SDL documentation (volunteers?)

SDL Development
1

Hey guys, SDL is an important part of the strategy at Valve to promote
Linux development, and that means making SDL great on all platforms. One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great place
to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam

2

Hi.
I don’t seem to be able to create an account.
I fill out the forms at [
http://wiki.libsdl.org/moin.cgi/FrontPage?action=newaccount ], click on
"Create Profile" and wait. I’ve managed to finish a tea cup and a piece of
cake, but it was still loading. It is still loading as of now.
Google Chrome says: “waiting for wiki.libsdl.org…”. The console is empty.

Could anybody try on their own machine? If the issue persists with multiple
people, perhapes the problem is with SDL’s servers.
Thanks in advance!On Mon, Feb 11, 2013 at 6:56 PM, Sam Lantinga wrote:

Hey guys, SDL is an important part of the strategy at Valve to promote
Linux development, and that means making SDL great on all platforms. One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great
place to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

3

The wiki probably would be better off being remade from scratch. Not
only a large amount of functions are missing, but many of those that
are there either have barebones documentation, outdated information or
even draft leftovers.

Indicating how to build the doxygen files would help as well, I
wouldn’t have realized about how to do it if somebody hadn’t mentioned
it in the mailing list. Even better, make it part of the build script
(though maybe allow it to fail in case doxygen isn’t installed).

2013/2/11, Sam Lantinga :> Hey guys, SDL is an important part of the strategy at Valve to promote

Linux development, and that means making SDL great on all platforms. One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great place
to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam

4

I don’t see any reason why it would need to be reset - the idea of a wiki
is that you can just edit anything, whether that’s adding pages, or
removing them. There is some notes on
contributinghttp://wiki.libsdl.org/moin.cgi/APIContributionStyleGuideto
help keep things consistent. See a function not documented? Add a
link

  • even if the page doesn’t exist yet, it will prompt other wiki writers to
    get that page up quickly. A function is depreciated? Add a note on the
    page that this function has been removed/depreciated, and perhaps add a
    link to a more preferred function.

I don’t know that the wiki is the appropriate place to say how to build
doxygen; others may feel differently - maybe that needs to be a discussion
on a different thread? I wouldn’t be surprised (don’t have a copy of SDL2
source with me right now) if make docs or make doxygen already exists,
but if it doesn’t, that may be worth tossing in.

Otherwise, Sam, I’ll have some time to dedicate to the wiki this weekend -
I’ve been setup for that but just haven’t had motivation/a chance to get to
actually adding content.

-AlexOn Mon, Feb 11, 2013 at 12:11 PM, Sik the hedgehog < sik.the.hedgehog at gmail.com> wrote:

The wiki probably would be better off being remade from scratch. Not
only a large amount of functions are missing, but many of those that
are there either have barebones documentation, outdated information or
even draft leftovers.

Indicating how to build the doxygen files would help as well, I
wouldn’t have realized about how to do it if somebody hadn’t mentioned
it in the mailing list. Even better, make it part of the build script
(though maybe allow it to fail in case doxygen isn’t installed).

2013/2/11, Sam Lantinga :

Hey guys, SDL is an important part of the strategy at Valve to promote
Linux development, and that means making SDL great on all platforms. One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great
place
to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

5

About doxygen, I actually meant in the readme, it says nothing about
building the documentation, and in fact if I didn’t look into the
headers there’s no way I’d know it’s there in the first place.

2013/2/11, Alex Barry <alex.barry at gmail.com>:> I don’t see any reason why it would need to be reset - the idea of a wiki

is that you can just edit anything, whether that’s adding pages, or
removing them. There is some notes on
contributinghttp://wiki.libsdl.org/moin.cgi/APIContributionStyleGuideto
help keep things consistent. See a function not documented? Add a
link

  • even if the page doesn’t exist yet, it will prompt other wiki writers to
    get that page up quickly. A function is depreciated? Add a note on the
    page that this function has been removed/depreciated, and perhaps add a
    link to a more preferred function.

I don’t know that the wiki is the appropriate place to say how to build
doxygen; others may feel differently - maybe that needs to be a discussion
on a different thread? I wouldn’t be surprised (don’t have a copy of SDL2
source with me right now) if make docs or make doxygen already exists,
but if it doesn’t, that may be worth tossing in.

Otherwise, Sam, I’ll have some time to dedicate to the wiki this weekend -
I’ve been setup for that but just haven’t had motivation/a chance to get to
actually adding content.

-Alex

On Mon, Feb 11, 2013 at 12:11 PM, Sik the hedgehog < @Sik_the_hedgehog> wrote:

The wiki probably would be better off being remade from scratch. Not
only a large amount of functions are missing, but many of those that
are there either have barebones documentation, outdated information or
even draft leftovers.

Indicating how to build the doxygen files would help as well, I
wouldn’t have realized about how to do it if somebody hadn’t mentioned
it in the mailing list. Even better, make it part of the build script
(though maybe allow it to fail in case doxygen isn’t installed).

2013/2/11, Sam Lantinga :

Hey guys, SDL is an important part of the strategy at Valve to promote
Linux development, and that means making SDL great on all platforms.
One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great
place
to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

6

Use the feedback form and let the documentation contributors know which
functions are missing, which are barebones, which are outdated, and which
have draft leftovers. If you don’t have the time to make the changes
yourself, this will at least give everyone a heads up who is working on it.

I think adding some documentation about how to use the source distribution
(including building doxygen reference) is an important thing.

Jonny DOn Mon, Feb 11, 2013 at 12:11 PM, Sik the hedgehog < sik.the.hedgehog at gmail.com> wrote:

The wiki probably would be better off being remade from scratch. Not
only a large amount of functions are missing, but many of those that
are there either have barebones documentation, outdated information or
even draft leftovers.

Indicating how to build the doxygen files would help as well, I
wouldn’t have realized about how to do it if somebody hadn’t mentioned
it in the mailing list. Even better, make it part of the build script
(though maybe allow it to fail in case doxygen isn’t installed).

2013/2/11, Sam Lantinga :

Hey guys, SDL is an important part of the strategy at Valve to promote
Linux development, and that means making SDL great on all platforms. One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great
place
to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

7

I find the SDL*.h headers to be well-documented, nicely organized, and easy to
navigate, as are the man pages. The combination of headers and man pages has
served me well for many years. These are two of SDL’s strengths. The wikis and
doxygen api dump, not so much. I vote we focus on the strengths, and consider
that perhaps the wiki format isn’t a good fit for SDL core documentation, as
time has shown.On 02/11/2013 12:25 PM, Sik the hedgehog wrote:

About doxygen, I actually meant in the readme, it says nothing about
building the documentation, and in fact if I didn’t look into the
headers there’s no way I’d know it’s there in the first place.

2013/2/11, Alex Barry <alex.barry at gmail.com>:

I don’t see any reason why it would need to be reset - the idea of a wiki
is that you can just edit anything, whether that’s adding pages, or
removing them. There is some notes on
contributinghttp://wiki.libsdl.org/moin.cgi/APIContributionStyleGuideto
help keep things consistent. See a function not documented? Add a
link

  • even if the page doesn’t exist yet, it will prompt other wiki writers to
    get that page up quickly. A function is depreciated? Add a note on the
    page that this function has been removed/depreciated, and perhaps add a
    link to a more preferred function.

I don’t know that the wiki is the appropriate place to say how to build
doxygen; others may feel differently - maybe that needs to be a discussion
on a different thread? I wouldn’t be surprised (don’t have a copy of SDL2
source with me right now) if make docs or make doxygen already exists,
but if it doesn’t, that may be worth tossing in.

Otherwise, Sam, I’ll have some time to dedicate to the wiki this weekend -
I’ve been setup for that but just haven’t had motivation/a chance to get to
actually adding content.

-Alex

On Mon, Feb 11, 2013 at 12:11 PM, Sik the hedgehog < sik.the.hedgehog at gmail.com> wrote:

The wiki probably would be better off being remade from scratch. Not
only a large amount of functions are missing, but many of those that
are there either have barebones documentation, outdated information or
even draft leftovers.

Indicating how to build the doxygen files would help as well, I
wouldn’t have realized about how to do it if somebody hadn’t mentioned
it in the mailing list. Even better, make it part of the build script
(though maybe allow it to fail in case doxygen isn’t installed).

2013/2/11, Sam Lantinga :

Hey guys, SDL is an important part of the strategy at Valve to promote
Linux development, and that means making SDL great on all platforms.
One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great
place
to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

8

The problem with the headers is that there isn’t any list of functions
you can check to see if there’s something that looks like what you
need, so either you scroll through the entire header and hope you
don’t miss anything or you know the name of the function beforehand
(the latter isn’t useful if you’re looking to do something you didn’t
do before).

2013/2/11, John :> I find the SDL*.h headers to be well-documented, nicely organized, and easy

to
navigate, as are the man pages. The combination of headers and man pages has

served me well for many years. These are two of SDL’s strengths. The wikis
and
doxygen api dump, not so much. I vote we focus on the strengths, and
consider
that perhaps the wiki format isn’t a good fit for SDL core documentation, as

time has shown.

On 02/11/2013 12:25 PM, Sik the hedgehog wrote:

About doxygen, I actually meant in the readme, it says nothing about
building the documentation, and in fact if I didn’t look into the
headers there’s no way I’d know it’s there in the first place.

2013/2/11, Alex Barry <alex.barry at gmail.com>:

I don’t see any reason why it would need to be reset - the idea of a
wiki
is that you can just edit anything, whether that’s adding pages, or
removing them. There is some notes on
contributinghttp://wiki.libsdl.org/moin.cgi/APIContributionStyleGuideto
help keep things consistent. See a function not documented? Add a
link

  • even if the page doesn’t exist yet, it will prompt other wiki writers
    to
    get that page up quickly. A function is depreciated? Add a note on the
    page that this function has been removed/depreciated, and perhaps add a
    link to a more preferred function.

I don’t know that the wiki is the appropriate place to say how to build
doxygen; others may feel differently - maybe that needs to be a
discussion
on a different thread? I wouldn’t be surprised (don’t have a copy of
SDL2
source with me right now) if make docs or make doxygen already
exists,
but if it doesn’t, that may be worth tossing in.

Otherwise, Sam, I’ll have some time to dedicate to the wiki this weekend

I’ve been setup for that but just haven’t had motivation/a chance to get
to
actually adding content.

-Alex

On Mon, Feb 11, 2013 at 12:11 PM, Sik the hedgehog < @Sik_the_hedgehog> wrote:

The wiki probably would be better off being remade from scratch. Not
only a large amount of functions are missing, but many of those that
are there either have barebones documentation, outdated information or
even draft leftovers.

Indicating how to build the doxygen files would help as well, I
wouldn’t have realized about how to do it if somebody hadn’t mentioned
it in the mailing list. Even better, make it part of the build script
(though maybe allow it to fail in case doxygen isn’t installed).

2013/2/11, Sam Lantinga :

Hey guys, SDL is an important part of the strategy at Valve to promote
Linux development, and that means making SDL great on all platforms.
One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for
volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great
place
to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

9

SDL 2 isn’t even officially released yet. I would guess that’s why the
wiki doesn’t get as much love as the headers, which must be kept current.
Wikis are way better with more users. Those users are currently limited
to the developers who strongly want/need what SDL 2 provides for their own
projects, which means they likely don’t have the time to be contributing to
a wiki.

Jonny DOn Mon, Feb 11, 2013 at 12:54 PM, John wrote:

I find the SDL*.h headers to be well-documented, nicely organized, and
easy to navigate, as are the man pages. The combination of headers and man
pages has served me well for many years. These are two of SDL’s strengths.
The wikis and doxygen api dump, not so much. I vote we focus on the
strengths, and consider that perhaps the wiki format isn’t a good fit for
SDL core documentation, as time has shown.

On 02/11/2013 12:25 PM, Sik the hedgehog wrote:

About doxygen, I actually meant in the readme, it says nothing about
building the documentation, and in fact if I didn’t look into the
headers there’s no way I’d know it’s there in the first place.

2013/2/11, Alex Barry <alex.barry at gmail.com>:

I don’t see any reason why it would need to be reset - the idea of a wiki
is that you can just edit anything, whether that’s adding pages, or
removing them. There is some notes on
contributing<http://wiki.libsdl.org/moin.cgi/
APIContributionStyleGuidehttp://wiki.libsdl.org/moin.cgi/APIContributionStyleGuide

to
help keep things consistent. See a function not documented? Add a
link

  • even if the page doesn’t exist yet, it will prompt other wiki writers
    to
    get that page up quickly. A function is depreciated? Add a note on the
    page that this function has been removed/depreciated, and perhaps add a
    link to a more preferred function.

I don’t know that the wiki is the appropriate place to say how to build
doxygen; others may feel differently - maybe that needs to be a
discussion
on a different thread? I wouldn’t be surprised (don’t have a copy of
SDL2
source with me right now) if make docs or make doxygen already
exists,
but if it doesn’t, that may be worth tossing in.

Otherwise, Sam, I’ll have some time to dedicate to the wiki this weekend

I’ve been setup for that but just haven’t had motivation/a chance to get
to
actually adding content.

-Alex

On Mon, Feb 11, 2013 at 12:11 PM, Sik the hedgehog < sik.the.hedgehog at gmail.com> wrote:

The wiki probably would be better off being remade from scratch. Not

only a large amount of functions are missing, but many of those that
are there either have barebones documentation, outdated information or
even draft leftovers.

Indicating how to build the doxygen files would help as well, I
wouldn’t have realized about how to do it if somebody hadn’t mentioned
it in the mailing list. Even better, make it part of the build script
(though maybe allow it to fail in case doxygen isn’t installed).

2013/2/11, Sam Lantinga :

Hey guys, SDL is an important part of the strategy at Valve to promote
Linux development, and that means making SDL great on all platforms.
One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great

place

to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/**listinfo.cgi/docs-libsdl.orghttp://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/**private.cgi/docs-libsdl.org/http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam

_____________**
SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/**listinfo.cgi/sdl-libsdl.orghttp://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

_____________**
SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/**listinfo.cgi/sdl-libsdl.orghttp://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

_____________**
SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/**listinfo.cgi/sdl-libsdl.orghttp://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

10

Since you are talking about making the information easier to find for new
developers, and if Valve?s plans are successful, the SDL Development Forums
will be more crowded.
That said, most people here seems to follow this list, not the forums. And
the forum messages are not being redirected to the list correctly, so, some
newbies, maybe, will be lost in the void.

So, any plans to overhaul the forums, fix its problems and make it more
friendly for a big stream of users posting? create more sections? or even
close the forums and centralize everything in the list? Or even another
idea?

Cheers!
Rodrigo Rocha

2013/2/11 > Message: 5

Date: Mon, 11 Feb 2013 08:56:34 -0800
From: Sam Lantinga
To: “A list for developers using the SDL library. (includes
SDL-announce)” , Erich Fischer
, Jonathan Dearborn <
grimfang4 at gmail.com>,
Benoit Bardet <benoit.bardet at gmail.com>, Chris Bush
, Pallav Nawani ,
Jonas
Thiem <jonas.th at web.de>
Subject: [SDL] SDL documentation (volunteers?)
Message-ID:
<CACC3sbGuxe5hBJzoKeVUm0_LhBn=
mG388Zy+SSOKtHFTwXpQcA at mail.gmail.com>
Content-Type: text/plain; charset=“iso-8859-1”

Hey guys, SDL is an important part of the strategy at Valve to promote
Linux development, and that means making SDL great on all platforms. One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great place
to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam
-------------- next part --------------
An HTML attachment was scrubbed…
URL: <
http://lists.libsdl.org/pipermail/sdl-libsdl.org/attachments/20130211/738f3d3c/attachment-0001.htm

11

Jonathan Dearborn, thank you for jumping in and responding to a bunch of
the wiki feedback! :)On Mon, Feb 11, 2013 at 8:56 AM, Sam Lantinga <@slouken> wrote:

Hey guys, SDL is an important part of the strategy at Valve to promote
Linux development, and that means making SDL great on all platforms. One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great
place to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam

12

No problem, Sam. I’m glad I can finally help directly with something.

Jonny DOn Mon, Feb 11, 2013 at 8:03 PM, Sam Lantinga wrote:

Jonathan Dearborn, thank you for jumping in and responding to a bunch of
the wiki feedback! :slight_smile:

On Mon, Feb 11, 2013 at 8:56 AM, Sam Lantinga wrote:

Hey guys, SDL is an important part of the strategy at Valve to promote
Linux development, and that means making SDL great on all platforms. One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great
place to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam

13

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

I’ve tried again today to create a wiki account but it always fail (it
stays forever in “waiting for wiki.libsdl.org” when I click “create
profile” in the registration form), I’ve tried to create it several times
in the past weeks :)–
Bye,
Gabry

14

Yeah, the server really struggles when editing, too. I usually get a
timeout after submitting changes. I think that’s Ryan’s field for figuring
out how to improve it.

Jonny DOn Thu, Feb 14, 2013 at 9:34 AM, Gabriele Greco <gabriele.greco at darts.it>wrote:

The wiki is a great source of information, but there’s a backlog of

feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

I’ve tried again today to create a wiki account but it always fail (it
stays forever in “waiting for wiki.libsdl.org” when I click “create
profile” in the registration form), I’ve tried to create it several times
in the past weeks :slight_smile:

–
Bye,
Gabry

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

15

Yeah, the server really struggles when editing, too. I usually get a
timeout after submitting changes. I think that’s Ryan’s field for figuring
out how to improve it.

I do not know if Ryan can do anything about this,
because from the IP it seems it is hosted on a Dreamhost Webserver
and not on Ryan’s Server.

16

I was able to create an account. Even though it seemed like the
request timed out the account was still created. Did you try logging
in?On Mon, Feb 11, 2013 at 12:07 PM, Ivan Rubinson wrote:

Hi.
I don’t seem to be able to create an account.
I fill out the forms at [
http://wiki.libsdl.org/moin.cgi/FrontPage?action=newaccount ], click on
"Create Profile" and wait. I’ve managed to finish a tea cup and a piece of
cake, but it was still loading. It is still loading as of now.
Google Chrome says: “waiting for wiki.libsdl.org…”. The console is empty.

Could anybody try on their own machine? If the issue persists with multiple
people, perhapes the problem is with SDL’s servers.
Thanks in advance!

–
Todd Steinackle

17

Yeah, I tried just now.
I get an “Invalid username or password” error. Basically, it didn’t
register.On Fri, Feb 15, 2013 at 4:38 PM, Todd Steinackle wrote:

On Mon, Feb 11, 2013 at 12:07 PM, Ivan Rubinson <@Ivan_Rubinson> wrote:

Hi.
I don’t seem to be able to create an account.
I fill out the forms at [
http://wiki.libsdl.org/moin.cgi/FrontPage?action=newaccount ], click on
"Create Profile" and wait. I’ve managed to finish a tea cup and a piece
of
cake, but it was still loading. It is still loading as of now.
Google Chrome says: “waiting for wiki.libsdl.org…”. The console is
empty.

Could anybody try on their own machine? If the issue persists with
multiple
people, perhapes the problem is with SDL’s servers.
Thanks in advance!

I was able to create an account. Even though it seemed like the
request timed out the account was still created. Did you try logging
in?

–
Todd Steinackle

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

18

What can you tell us about Valve’s Linux strategy?

Back to the docs…

Folks, I’ve done this before. It should be done in stages with care being
made to separate the different types of documentation. What are the core
types of documentation:

  1. Functional -
    a) What you get from Doxygen
    b) Should be in the Source Code

  2. Educational -
    a) Examples
    b) Tutorials
    c) Educational materials

There are two phase that need to be worked on. They can be done in parallel
but only at risk of redoing work. The first is to up date the documentation
in the source code. As good as it always is, there are always mistakes in
it. There should be a group who does nothing but:

  1. Read the headers and sync up the doxygen with the source. There are
    often inconsistencies. Especially in formatting style. Often missing
    comments and or out of date or just plain wrong comments.

  2. Generate the Doxygen comments. Read them examine them… go back to 1)

This part requires someone who can check in code.

The comments in the source code should be the core of the "functional"
documentation.

The rest of the documentation can be written independent of the Doxygen
docs. But, the actual functional documentation in the wiki or anywhere else
should be mechanically pulled from the doxygen docs which are pulled from
the source. The source should always be the SOURCE of the functional docs.
The rest can stand on its own.

This time around I would really like to see every function in the wiki
reference a line of code in a program in the test directory so that people
can look at the docs, an example in context, and then link to an actual
program to see how the function is used.

To quote somebody else “I believe in working code”.

I would also like to see that the documentation in the wiki was written by
someone who had at least run the appropriate test program and understood
the output.

Bob PendletonOn Mon, Feb 11, 2013 at 10:56 AM, Sam Lantinga wrote:

Hey guys, SDL is an important part of the strategy at Valve to promote
Linux development, and that means making SDL great on all platforms. One
of the important pieces of any software development kit is the
documentation. It has to be clear, easy to understand, and complete.

The wiki is a great source of information, but there’s a backlog of
feedback that would be great to incorporate. I’m looking for volunteers
with SDL experience and writing skills to update the documentation and
improve it. If you’re interested in helping out, please create a wiki
account and let me know!
http://wiki.libsdl.org/

If you’re looking to help, the documentation list archives is a great
place to start. If you do, please send e-mail to the documentation list so
people can coordinate what they are working on:
http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org
http://lists.libsdl.org/private.cgi/docs-libsdl.org/

Cheers,
–Sam

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

–
±----------------------------------------------------------

19

Hello !

What can you tell us about Valve’s Linux strategy?

Please :slight_smile:

Back to the docs…

I agree 100% on what you wrote.

From the reading of your text, it seems to
me that publishing all this stuff in the end
as a wiki is a fine thing, but while doing the
work, it would be a lot easier doing this in simple
text files in a revision control system like Mercurial, SVN
or even CVS.

Updates to the docs could be automailed to the docs mailinglist,
like code changes to SDL to the commitlist, right now.

In the end when the text files are finished, it is just a matter
of Copy/Paste to add it to the wiki. Maybe the wiki has some Import/Export
Functions, i do not know.

CU

20

Message-ID:
<CAKabUS5jHPxtRUEcy9=zF-weSAUrK7K=MrgvgccVgnQhrncmSg at mail.gmail.com>
Content-Type: text/plain; charset=“iso-8859-1”

The rest of the documentation can be written independent of the Doxygen
docs. But, the actual functional documentation in the wiki or anywhere else
should be mechanically pulled from the doxygen docs which are pulled from
the source. The source should always be the SOURCE of the functional docs.
The rest can stand on its own.

Do you mean the wiki should be automatically populated and updated
from Doxygen? Since there’s actually a wiki in use, I think it makes
more sense to automatically generate the Doxygen docs, but have each
wiki page provide a link to the relevant Doxygen text instead of
automatically drawing content from it. This would allow the Doxygen
files to be automatically updated without auto-magically clobbering
any edits or additions that had been made to the wiki.

This time around I would really like to see every function in the wiki
reference a line of code in a program in the test directory so that people
can look at the docs, an example in context, and then link to an actual
program to see how the function is used.

That would be nice. For that matter, it would be nice if the pages all
had links to the relevant include & source files.> Date: Fri, 15 Feb 2013 13:26:40 -0600

From: Bob Pendleton
To: SDL Development List
Subject: Re: [SDL] SDL documentation (volunteers?)