Documentation

Kenneth_Bull · September 9, 2009, 10:01pm

2009/9/9 GMScribe <ali_lowe at sky.com>:

Lack of documentation has been miffing me off, especially in regards to
knowing what features I have to use to plan projects based on SDL 1.3. As
such I’ve updated the API documentation to include 99% of functions and have
subcatagorised these to better show how they work together (for example
display devices vs display modes vs windows etc). I have added a contents to
comensate for the increased documentation size. We now just need to start
populating these links with data, a lot of which can be copied and pasted
from 1.2 of course. I think the biggest changes not indicated by the new API
would be the text input in events.

I’ve edited some of the pages you posted (small changes mostly), and
filled out the remaining links on the SDL-1.3 page.
If you want to review what I’ve done, check the RecentChanges list on
the SDL wiki.

GMScribe · September 9, 2009, 10:22pm

No problems, sorry about adding a new API list, I’m teaching C++ to a group
of college students and wanted to introduce them to SDL 1.3 and so quickly
needed an overview of functionality. I’m going to add some of the basic
tutorials too as for 1.2, hopefully then that’ll make it clearer to
newcomers the primary changes in the API. I think 1.3 is at the point now
where people need to become interested and help spur along the development
to that final hurdle… It’s about time it gets polished off and released =P

Many thanks

Kenneth Bull wrote:>

2009/9/9 GMScribe <@GMScribe>:

Lack of documentation has been miffing me off, especially in regards to
knowing what features I have to use to plan projects based on SDL 1.3. As
such I’ve updated the API documentation to include 99% of functions and
have
subcatagorised these to better show how they work together (for example
display devices vs display modes vs windows etc). I have added a contents
to
comensate for the increased documentation size. We now just need to start
populating these links with data, a lot of which can be copied and pasted
from 1.2 of course. I think the biggest changes not indicated by the new
API
would be the text input in events.

I’ve edited some of the pages you posted (small changes mostly), and
filled out the remaining links on the SDL-1.3 page.
If you want to review what I’ve done, check the RecentChanges list on
the SDL wiki.

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

–
View this message in context: http://www.nabble.com/Documentation-tp24675616p25374152.html
Sent from the SDL mailing list archive at Nabble.com.

Kenneth_Bull · September 9, 2009, 10:57pm

You should probably also mention SDL_INIT_EVERYTHING in
SDL-1.3/Initializing_SDL.

There are no “default subsystems”.
SDL_Init(0) (no flags) initializes the pth library, installs a signal
handler and starts a helper window for DirectInput events. If you
call SDL_Init(SDL_INIT_NOPARACHUTE) on linux and you’re not using pth,
it does nothing.

I’ll leave this for you to change or not though.

slouken · September 10, 2009, 2:02pm

Thank you guys for adding info to the wiki!

We’re actually starting a fresh Wiki for SDL 1.3 documentation, and
Lauren is coordinating that. If you have suggestions, please send
them to me and I’ll forward them along.

http://wiki.libsdl.org/On Wed, Sep 9, 2009 at 1:16 PM, Kenneth Bull wrote:

2009/9/9 GMScribe <ali_lowe at sky.com>:

Lack of documentation has been miffing me off, especially in regards to
knowing what features I have to use to plan projects based on SDL 1.3. As
such I’ve updated the API documentation to include 99% of functions and have
subcatagorised these to better show how they work together (for example
display devices vs display modes vs windows etc). I have added a contents to
comensate for the increased documentation size. We now just need to start
populating these links with data, a lot of which can be copied and pasted
from 1.2 of course. I think the biggest changes not indicated by the new API
would be the text input in events.

I had this set up to work automatically as features were documented…
To add a function to that list, all you need to do is make a new page
with the appropriate categories (and maybe add another category to
indicate it was undocumented if you don’t feel like filling it in
yourself). ?The list itself requires no maintenance except
DeleteCache.

You can still find this page at
http://www.libsdl.org/cgi/docwiki.cgi/SDL-1.3/API
I see no reason to remove it and it’s easier to maintain than a manual list.

I still need to enter information regarding haptic, however noticed that the
only source code was not in a major header. Are there haptic commands
available as official SDL API calls? If so in what source file, just so that
I don’t start posting nonsense.

The file you’re looking for is SDL/include/haptic.h

Also I’ve made no attempt to include compatability information, I believe
this should be on a completely different page, if not just added to the SDL
1.2 documentation to specify if it still works in 1.3.

You could put this information on SDL-1.3/Changes
http://www.libsdl.org/cgi/docwiki.cgi/SDL-1.3/Changes

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

–
-Sam Lantinga, Founder and President, Galaxy Gameworks LLC

Kenneth_Bull · September 10, 2009, 9:57pm

2009/9/10 Sam Lantinga :

Thank you guys for adding info to the wiki!

We’re actually starting a fresh Wiki for SDL 1.3 documentation, and
Lauren is coordinating that. ?If you have suggestions, please send
them to me and I’ll forward them along.

http://wiki.libsdl.org/

Is this still a work in progress or safe to start using?

Kenneth_Bull · September 10, 2009, 10:48pm

2009/9/10 Kenneth Bull <@Kenneth_Bull>:

2009/9/10 Sam Lantinga :

Thank you guys for adding info to the wiki!

We’re actually starting a fresh Wiki for SDL 1.3 documentation, and
Lauren is coordinating that. ?If you have suggestions, please send
them to me and I’ll forward them along.

http://wiki.libsdl.org/

Is this still a work in progress or safe to start using?

Actually, if you’re switching anyway, Trac ( http://trac.edgewall.org/
) is probably a better bet.
Wiki syntax is the same as MoinMoin, so it’s easier to copy content
from the old wiki, and it has a built in source browser and bug
tracker for SVN. Also, you can get a Trac wiki through sourceforge if
you don’t want to set it up yourself.

GMScribe · September 12, 2009, 10:25am

I’m glad you’ve chosen MediaWiki as it’s what I use personally and have
gotten along quite well with.

I guess from my point of view what would be most useful is to be given
Lauren’s intended layout of the wiki and any examples of format/layout so
that we can begin contributing in the form that they wish and conflict as
little as possible.

Many thanks.

Sam Lantinga-4 wrote:>

Thank you guys for adding info to the wiki!

We’re actually starting a fresh Wiki for SDL 1.3 documentation, and
Lauren is coordinating that. If you have suggestions, please send
them to me and I’ll forward them along.

http://wiki.libsdl.org/

On Wed, Sep 9, 2009 at 1:16 PM, Kenneth Bull wrote:

2009/9/9 GMScribe <@GMScribe>:

Lack of documentation has been miffing me off, especially in regards to
knowing what features I have to use to plan projects based on SDL 1.3.
As
such I’ve updated the API documentation to include 99% of functions and
have
subcatagorised these to better show how they work together (for example
display devices vs display modes vs windows etc). I have added a
contents to
comensate for the increased documentation size. We now just need to
start
populating these links with data, a lot of which can be copied and
pasted
from 1.2 of course. I think the biggest changes not indicated by the new
API
would be the text input in events.

I had this set up to work automatically as features were documented…
To add a function to that list, all you need to do is make a new page
with the appropriate categories (and maybe add another category to
indicate it was undocumented if you don’t feel like filling it in
yourself). ?The list itself requires no maintenance except
DeleteCache.

You can still find this page at
http://www.libsdl.org/cgi/docwiki.cgi/SDL-1.3/API
I see no reason to remove it and it’s easier to maintain than a manual
list.

I still need to enter information regarding haptic, however noticed that
the
only source code was not in a major header. Are there haptic commands
available as official SDL API calls? If so in what source file, just so
that
I don’t start posting nonsense.

The file you’re looking for is SDL/include/haptic.h

Also I’ve made no attempt to include compatability information, I
believe
this should be on a completely different page, if not just added to the
SDL
1.2 documentation to specify if it still works in 1.3.

You could put this information on SDL-1.3/Changes
http://www.libsdl.org/cgi/docwiki.cgi/SDL-1.3/Changes

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

–
-Sam Lantinga, Founder and President, Galaxy Gameworks LLC

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

–
View this message in context: http://www.nabble.com/Documentation-tp24675616p25413241.html
Sent from the SDL mailing list archive at Nabble.com.

GMScribe · September 23, 2009, 9:02pm

I’ve now moved the API by category list over to the new wiki.

Many thanks.

GMScribe wrote:>

I’m glad you’ve chosen MediaWiki as it’s what I use personally and have
gotten along quite well with.

I guess from my point of view what would be most useful is to be given
Lauren’s intended layout of the wiki and any examples of format/layout so
that we can begin contributing in the form that they wish and conflict as
little as possible.

Many thanks.

Sam Lantinga-4 wrote:

Thank you guys for adding info to the wiki!

We’re actually starting a fresh Wiki for SDL 1.3 documentation, and
Lauren is coordinating that. If you have suggestions, please send
them to me and I’ll forward them along.

http://wiki.libsdl.org/

On Wed, Sep 9, 2009 at 1:16 PM, Kenneth Bull wrote:

2009/9/9 GMScribe <@GMScribe>:

Lack of documentation has been miffing me off, especially in regards to
knowing what features I have to use to plan projects based on SDL 1.3.
As
such I’ve updated the API documentation to include 99% of functions and
have
subcatagorised these to better show how they work together (for example
display devices vs display modes vs windows etc). I have added a
contents to
comensate for the increased documentation size. We now just need to
start
populating these links with data, a lot of which can be copied and
pasted
from 1.2 of course. I think the biggest changes not indicated by the
new API
would be the text input in events.

I had this set up to work automatically as features were documented…
To add a function to that list, all you need to do is make a new page
with the appropriate categories (and maybe add another category to
indicate it was undocumented if you don’t feel like filling it in
yourself). ?The list itself requires no maintenance except
DeleteCache.

You can still find this page at
http://www.libsdl.org/cgi/docwiki.cgi/SDL-1.3/API
I see no reason to remove it and it’s easier to maintain than a manual
list.

I still need to enter information regarding haptic, however noticed
that the
only source code was not in a major header. Are there haptic commands
available as official SDL API calls? If so in what source file, just so
that
I don’t start posting nonsense.

The file you’re looking for is SDL/include/haptic.h

Also I’ve made no attempt to include compatability information, I
believe
this should be on a completely different page, if not just added to the
SDL
1.2 documentation to specify if it still works in 1.3.

You could put this information on SDL-1.3/Changes
http://www.libsdl.org/cgi/docwiki.cgi/SDL-1.3/Changes

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

–
-Sam Lantinga, Founder and President, Galaxy Gameworks LLC

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

–
View this message in context: http://www.nabble.com/Documentation-tp24675616p25531296.html
Sent from the SDL mailing list archive at Nabble.com.

Kenneth_Bull · September 24, 2009, 2:13am

2009/9/23 GMScribe <ali_lowe at sky.com>:

I’ve now moved the API by category list over to the new wiki.

A few notes:

tables are a pain in the ass in mediawiki
In moinmoin you have this:
||cell1_1||cell1_2||
||cell2_1||cell2_2||
or this:
{{{#!csv
cell1_1;cell1_2
cell2_1;cell2_2
}}}
and it actually looks decent when rendered.
In mediawiki you have this:

{

cell1_1

cell1_2

-

cell2_1

cell2_2

}
no syntax highlighting except through extensions
In moinmoin you do this for preformatted text:
{{{
my
preformatted
text
}}}
and this for C or C++ code:
{{{#!cplusplus
#include "SDL.h"
int main(int, char**) {
if (SDL_Init(SDL_INIT_VIDEO|SDL_INIT_TIMER) != 0) {
fprintf(stderr, “\nUnable to initialize SDL: %s\n”, SDL_GetError());
return 1;
}
atexit(SDL_Quit);
/* … /
}
}}}
or this with newer versions of moinmoin:
{{{#!highlight cpp
#include "SDL.h"
int main(int, char*) {
if (SDL_Init(SDL_INIT_VIDEO|SDL_INIT_TIMER) != 0) {
fprintf(stderr, “\nUnable to initialize SDL: %s\n”, SDL_GetError());
return 1;
}
atexit(SDL_Quit);
/* … */
}
}}}
In mediawiki, preformatted text looks like this:
```
 my
   preformatted
     text
 
```

and source code is unsupported except through extensions.
Through the GeSHi extension source code looks like this:

#include "SDL.h"
int main(int, char**) {
if (SDL_Init(SDL_INIT_VIDEO|SDL_INIT_TIMER) != 0) {
fprintf(stderr, “\nUnable to initialize SDL: %s\n”, SDL_GetError());
return 1;
}
atexit(SDL_Quit);
/* … */
}

but there are other extensions with different syntax.
3. no underscores in page titles
Page titles like SDL_Init are rendered as SDL Init instead in mediawiki.
4. page titles are capitalized
You cannot have a page title beginning with a lower case character
in mediawiki.

Points 3 and 4 especially make it unsuitable for documenting code.
Basically, mediawiki was designed for wikipedia, not programming
projects…

slouken · September 24, 2009, 7:05am

I threw up a new MoinMoin wiki, we’ll be trying some experimental
stuff on there over the next few days.

See ya!On Wed, Sep 23, 2009 at 7:13 PM, Kenneth Bull wrote:

2009/9/23 GMScribe <ali_lowe at sky.com>:

I’ve now moved the API by category list over to the new wiki.

A few notes:
tables are a pain in the ass in mediawiki
?In moinmoin you have this:
? ?||cell1_1||cell1_2||
? ?||cell2_1||cell2_2||
?or this:
? ?{{{#!csv
? ?cell1_1;cell1_2
? ?cell2_1;cell2_2
? ?}}}
?and it actually looks decent when rendered.
?In mediawiki you have this:
? ?{|
? ?|-
? ?|cell1_1
? ?|cell1_2
? ?|-
? ?|cell2_1
? ?|cell2_2
? ?|}
no syntax highlighting except through extensions
?In moinmoin you do this for preformatted text:
? ?{{{
? ?my
? ? ?preformatted
? ? ? ?text
? ?}}}
?and this for C or C++ code:
? ?{{{#!cplusplus
? ? ?#include “SDL.h”
? ? ?int main(int, char**) ?{
? ? ? ?if (SDL_Init(SDL_INIT_VIDEO|SDL_INIT_TIMER) != 0) {
? ? ? ? ?fprintf(stderr, “\nUnable to initialize SDL: ?%s\n”, SDL_GetError());
? ? ? ? ?return 1;
? ? ? ?}
? ? ? ?atexit(SDL_Quit);
? ? ? ?/* … /
? ? ?}
? ?}}}
?or this with newer versions of moinmoin:
? ?{{{#!highlight cpp
? ? ?#include “SDL.h”
? ? ?int main(int, char*) ?{
? ? ? ?if (SDL_Init(SDL_INIT_VIDEO|SDL_INIT_TIMER) != 0) {
? ? ? ? ?fprintf(stderr, “\nUnable to initialize SDL: ?%s\n”, SDL_GetError());
? ? ? ? ?return 1;
? ? ? ?}
? ? ? ?atexit(SDL_Quit);
? ? ? ?/* … /
? ? ?}
? ?}}}
?In mediawiki, preformatted text looks like this:
? ?

? ?my
? ? ?preformatted
? ? ? ?text
? ?

?and source code is unsupported except through extensions.
?Through the GeSHi extension source code looks like this:
? ?
? ? ?#include “SDL.h”
? ? ?int main(int, char*) ?{
? ? ? ?if (SDL_Init(SDL_INIT_VIDEO|SDL_INIT_TIMER) != 0) {
? ? ? ? ?fprintf(stderr, “\nUnable to initialize SDL: ?%s\n”, SDL_GetError());
? ? ? ? ?return 1;
? ? ? ?}
? ? ? ?atexit(SDL_Quit);
? ? ? ?/* … */
? ? ?}
? ?
?but there are other extensions with different syntax.
no underscores in page titles
? ?Page titles like SDL_Init are rendered as SDL Init instead in mediawiki.

page titles are capitalized
? ?You cannot have a page title beginning with a lower case character
in mediawiki.
Points 3 and 4 especially make it unsuitable for documenting code.
Basically, mediawiki was designed for wikipedia, not programming
projects…

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

–
-Sam Lantinga, Founder and President, Galaxy Gameworks LLC

Kenneth_Bull · September 24, 2009, 11:28pm

2009/9/24 Sam Lantinga :

I threw up a new MoinMoin wiki, we’ll be trying some experimental
stuff on there over the next few days.

See ya!

If you’re using apache, I can help get rid of the /moin.cgi/ part of the URL.

slouken · September 26, 2009, 6:45am

I’m using Dreamhost, so I don’t have direct access to the web server.
Is it something I can do from user files?On Thu, Sep 24, 2009 at 4:28 PM, Kenneth Bull wrote:

2009/9/24 Sam Lantinga <@slouken>:

I threw up a new MoinMoin wiki, we’ll be trying some experimental
stuff on there over the next few days.

See ya!

If you’re using apache, I can help get rid of the /moin.cgi/ part of the URL.

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

–
-Sam Lantinga, Founder and President, Galaxy Gameworks LLC

Steven_Noonan · September 26, 2009, 8:13am

You probably want something similar to this in .htaccess.

RewriteEngine On
RewriteCond $1 !.(gif|jpe?g|png|ico)$ [NC]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ /moin.cgi/$1 [L]On Fri, Sep 25, 2009 at 11:45 PM, Sam Lantinga wrote:

I’m using Dreamhost, so I don’t have direct access to the web server.
Is it something I can do from user files?

On Thu, Sep 24, 2009 at 4:28 PM, Kenneth Bull wrote:

2009/9/24 Sam Lantinga :

I threw up a new MoinMoin wiki, we’ll be trying some experimental
stuff on there over the next few days.

See ya!

If you’re using apache, I can help get rid of the /moin.cgi/ part of the URL.

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

–
? ? ? ?-Sam Lantinga, Founder and President, Galaxy Gameworks LLC

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

Kenneth_Bull · September 26, 2009, 2:26pm

2009/9/26 Sam Lantinga :

I’m using Dreamhost, so I don’t have direct access to the web server.
Is it something I can do from user files?

RewriteEngine works for this (see Noonan’s post), but you may be able
to get it working with just ScriptAlias instead.
The way I’ve done it in the past is to edit the site configuration
file in /etc/apache2/sites-available.
There used to be a tutorial on this on moinmo.in, but it seems to have
vanished (but see
http://moinmo.in/HowTo/WindowsWithApacheServer#Configuring_Apache_httpd.conf
).

I’ll look through my old config files later today (my other computer
is rather loud and my roommates are still sleeping).

Kenneth_Bull · September 28, 2009, 7:52am

2009/9/26 Kenneth Bull <@Kenneth_Bull>:

I’ll look through my old config files later today (my other computer
is rather loud and my roommates are still sleeping).

Here’s my configuration file:
<VirtualHost *:80>
ServerAdmin @Kenneth_Bull

    DocumentRoot /var/www/
    <Directory />
            Options FollowSymLinks
            AllowOverride None
    </Directory>
    <Directory /var/www/>
            Options Indexes FollowSymLinks MultiViews
            AllowOverride None
            Order allow,deny
            allow from all
    </Directory>

    Alias /moin_static "/var/wiki/common/htdocs/"
    <Directory "/var/wiki/common/htdocs/">
       Order deny,allow
       Allow from all
    </Directory>

ScriptAlias /wiki “/var/wiki/cgi-bin/moin.cgi”

    <Directory "/var/wiki/cgi-bin">
       Order deny,allow
       Allow from all
    </Directory>

    WSGIScriptAlias /wiki "/var/wiki/cgi-bin/moin.wsgi"
    WSGIDaemonProcess moin user=www-data group=www-data

home=/home/www-data processes=5 threads=10 maximum-requests=1000
umask=0007
WSGIProcessGroup moin

    ErrorLog /var/log/apache2/error.log

    # Possible values include: debug, info, notice, warn, error, crit,
    # alert, emerg.
    LogLevel warn

    CustomLog /var/log/apache2/access.log combined

The important bits are:

    WSGIScriptAlias /wiki "/var/wiki/cgi-bin/moin.wsgi"
    WSGIDaemonProcess moin user=www-data group=www-data

home=/home/www-data processes=5 threads=10 maximum-requests=1000
umask=0007
WSGIProcessGroup moin

(I’ve used WSGI for performance reasons. See here: http://wsgi.org/wsgi/ )

If you want this on http://wiki.libsdl.org/ instead of
http://wiki.libsdl.org/wiki/ do this instead:

    WSGIScriptAlias / "/var/wiki/cgi-bin/moin.wsgi"
    WSGIDaemonProcess moin user=www-data group=www-data

home=/home/www-data processes=5 threads=10 maximum-requests=1000
umask=0007
WSGIProcessGroup moin

You need to replace /var/wiki/cgi-bin/moin.wsgi with the local path to
your moin.wsgi script (as in not over the internet).

You may need to edit the WSGIDaemonProcess line (specifically user,
group and home). There are brief instructions in the moin.wsgi file
packed with moinmoin.

You will need to add the path to your wiki data to moin.wsgi. For my
wiki this is:

sys.path.insert(0, ‘/var/wiki/’)

since that is where I put my wikiconfig.py.

{
cell1_1
cell1_2
-
cell2_1
cell2_2
}