NOTE: This page exists temporarily for internal reference only and is not for public use. It has been superseded by the individual style guides that can be found on the Contributing page. Please refer to those style guides instead of this one as they are more up to date.

SDL API Documentation Style Guide

This guide provides the formatting instructions needed to make major edits or create new pages.

Getting Started

This section provides information on the following:

• How to create a new page

• Some of the most common markup used in this wiki including help with markup problems

• Conventions that apply to all API pages in the wiki

Once you are familiar with these you will find all the detailed editing information you will need in Editing Pages below.

If you have questions, problems, or suggestions for changes or additions to this document or any other portion of the wiki please don't hesitate to contact <ANTI SPAM docs AT libsdl DOT org> with your thoughts. We are happy to have the participation!

Creating A New Page

The convention in this wiki is that the name of the page is also the address of the page (usually a Function, Enumeration, or Structure name).

• Example: The address for the page SDL_BuildAudioCVT is
  

  • http://wiki.libsdl.org/moin.cgi/SDL_BuildAudioCVT

  Page addresses are case-sensitive. Be careful to name and spell accurately when creating a new page.

• Please use appropriate formatting (CAPS_CamelCase) when naming a new page.

New pages for Functions, Enumerations, and Structures should be created with the appropriate template, respectively:

• SDLFunctionTemplate

• SDLEnumTemplate

• SDLStructTemplate

Should these templates be un-linked so you can't get directly to them so easily?

• Please do not edit the templates themselves! Check the page address to be sure you are in the new page and not the template page before making changes.

To create a new page you may:

1. Type the address of the new page into the address bar and go to the page.
   

   • http://wiki.libsdl.org/moin.cgi/newpagename
     where newpagename is replaced by the actual name of the page following the above conventions.

   -OR-
   Create a hyperlink to a new page on an existing page and then click the link.

   • Example: Place [[SDL_NewStructure]] on an existing page, preview the change, and click on the link to SDL_NewStructure to create the new page.

     • If you use this method to create a new page please place the hyperlink in an appropriate location or delete it after use.
2. Choose the appropriate template and edit according to this guide.

   • A table will appear when you first go to the new page. All three SDL Templates are listed toward the lower-middle of the left column. Choosing a template will take you to the Edit (Text) screen for the new page with the template contents displayed.

     • If you would prefer to work with the GUI editor click GUI/Text Mode in the left sidebar to switch to GUI mode. For future edits use Edit (GUI) in the sidebar to enter the GUI editor.

Return to Table of Contents

Some Wiki Markup Basics

A good starting place for basic markup is HelpOnMoinWikiSyntax. Also see the Editor Hints in the left sidebar in Edit mode for some of the most common markup. Below is a summary of the most commonly used markup in this wiki and some hints and tricks for using it.

Spacing

Spacing

• Indenting: Place blank spaces at the beginning of a line of text. (this line has 1 space)

  • Use one space for each indent level desired. (this line has 2 spaces)
  • Use a period (.) after the spaces and before the text (usually separated by a space after but not necessary) to ensure that the indent does not become a bullet or numbered list. Note that this markup will sometimes resolve problems when the spacing from line to line is not what you expected. (this line has 2 spaces and a starting period)

    • Example:  . This line starts with a period    generates
      

      • This line starts with a period

• Hard Line Break: <<BR>>

  • Place the above markup wherever you want to force the following text onto the next line but keep it in the same paragraph.
    

  • Note that you cannot change indent level immediately following a hard line break.

    • Example: Typing the following in the text editor

          1 first line<<BR>>    2 this line typed on same line after hard line break markup, same indent<<BR>>     3 this line typed on same line after hard line break markup, +1 indent<<BR>>    4 this line typed on same line after hard line break markup, -1 indent<<BR>>    . 5 this line typed on same line after hard line break markup, same indent with period<<BR>>6 this line typed on same line after hard line break markup without any indent

      Generates:

      • 1 first line
        2 this line typed on same line after hard line break markup, same indent
        3 this line typed on same line after hard line break markup, +1 indent
        4 this line typed on same line after hard line break markup, -1 indent
        . 5 this line typed on same line after hard line break markup, same indent with period
        6 this line typed on same line after hard line break markup without any indent

  A hard return (Enter key) is not always recognized as a line break.
  Spaces between lines and paragraphs (which may be individual lines) are parsed with different spacing depending upon the context (especially relative indent level). It may take some playing around with the markup to get the spacing you want, or it may be that you will have to accept a certain amount of pre-determined spacing between lines.

  • Example: Typing the following in the text editor

    1 hard return followed by next line same indent
    2 hard return followed by next line +1 indent
     3 hard return followed by next line same indent using period
     . 4 hard return followed by next line same indent, no period
     5 hard return followed by next line -1 indent
    6 hard return after hard line break markup, followed by next line same indent<<BR>>
    7<<BR>>8 next line typed on same line after hard line break markup, same indent

    Generates:

  • 1 hard return followed by next line same indent 2 hard return followed by next line +1 indent
    • 3 hard return followed by next line same indent using period
    • 4 hard return followed by next line same indent, no period 5 hard return followed by next line -1 indent

    6 hard return after hard line break markup, followed by next line same indent
    7
    8 next line typed on same line after hard line break markup, same indent

• To ensure that the next line is treated as a separate line (paragraph)

  1. use two consecutive hard returns (Enter key)

     • Note that this will leave a larger space between lines (usually a double-space)

  2. use a hard line break

  3. indent more (farther right)

  4. use a period at the beginning of the line after indenting the same amount

  5. indent less (farther left)

Back to Markup Basics start

Headers

Headers

• Use one to five equals signs (=) surrounding header text, with a space between markup and text.

  • One equals sign is the highest level header (largest) Example: = Title =
    Five equals signs is the lowest level header (smallest) Example: ===== Minor =====
    

  Example: === Some Wiki Markup Basics ===
  Headers will appear in an automatically generated Table of Contents.

• More (but not much) wiki markup for headers can be found at HelpOnHeadlines.

Back to Markup Basics start

Text Formatting

Text Formatting

• Bold: Place three apostrophes surrounding text to be bolded, without a space between markup and text.

  • Example: '''bold text''' generates bold text

• Italics: Place two apostrophes surrounding text to be italicized, without a space between markup and text.

  • Example: ''italics text'' generates italics text

• Monospace: Place a backquote on either side of the text, without a space between markup and text. (Note: This may resemble inline code (see below) in many cases, but will not behave the same.)

  • Example: 'monospace text' generates monospace text

• Code (or Verbatim Text): Use three curly brackets surrounding text to be rendered as code.

  • Place the brackets inline with the text to display the code formatting inline.

    • Example:

      {{{Verbatim text as it should be typed, or appear as code or with markup. If it is too long for the line it will not wrap.}}}

      produces

      Verbatim text as it should be typed, or appear as code or with markup. If it is too long for the line it will not wrap.

  • Place the brackets above and below the text to display the code formatting inside a box.

    • Example:

      {{{
      Verbatim text as it should be typed, or appear as code or with markup. This will word wrap if it is too long for one line.
      }}}

      produces

      Verbatim text as it should be typed, or appear as code or with markup. This will word wrap if it is too long for one line.

• Note: Formatting markup can usually be nested/grouped, but the order it is used in may affect whether it works as desired. Try using multiple formatting tags in a different order or check the help if you have trouble.

  More wiki markup for text formatting can be found at HelpOnFormatting.

Back to Markup Basics start

Lists

Lists

• Bullet Lists: Begin a line with a space followed by an asterisk to create a bulleted line of text (space after asterisk is optional but seems to be preferred)

  Example:   * First line of bullet list
  

  • produces
    

  • First line of bullet list
    

• Numbered Lists: Begin a line with a space followed by the number 1 and a period (or the beginning of another number format such as i or a).
  • Note: Each line that should be part of the list begins with the same starting number. The wiki will generate sequential numbers in preview mode or after saving.

  • Example:

       1. First line of numbered list
       1. Second line of numbered list

    • produces
      

    1. First line of numbered list
    2. Second line of numbered list

  More wiki markup for lists can be found at HelpOnLists

If a list is interrupted by another item (like a box of code) with less indent (farther left) than the previous line of the list, it may interfere with the correct parsing of the next line of the list after the interruption. (It seems to default to a first level indent after an interruption.)

• One possible workaround is to place a blank line containing a space period space ( . ) between the interfering content and the next line. (See below for an example. In edit mode look for <<Anchor(example)>>.) This seems to allow the wiki parser to interpret the indent count correctly on the next line and effectively continue the list.

  • It may be necessary to indent to one level less (farther left) than the line that is not being parsed correctly. For example, if you need a line following an interruption to be at 3 indents, put the space-period-space immediately above it at 2 indents (ie: space space period space;  . ).

  • A numbered list may require that the correct start number be manually entered, however this may not always work. See HelpOnLists for details on forcing a start number/letter.

• For more information about this 'bug' and another possible workaround see BlockElementsInListBreakIndent.

A related issue is trying to use a mixed list where bullets follow numbers on the same indent level. This will likely parse as the next consecutive number regardless of your use of an asterisk to indicate the use of a bullet. The same workaround seems to resolve this issue as well.

• For more information about this 'bug' and another possible workaround see MixedNumberedAndUnorderedLists.

Back to Markup Basics start

Tables

Tables

• Two pipes (||) are used to begin and end a table row, with two pipes separating each cell in between.

  • It is important that there are no blank spaces or other characters after the closing pipes on a line.

  Example:

  • ||row 1 column 1||row 1 column 2||row 1 column 3||
    ||row 2 column 1||row 2 column 2||row 2 column 3||

    • produces

    row 1 column 1	row 1 column 2	row 1 column 3
    row 2 column1	row 2 column 2	row 2 column 3

  More wiki markup for tables can be found at HelpOnTables

Back to Markup Basics start

Anchors

Anchors

• <<Anchor(anchorname)>>
  Place the above markup in the location where you wish to create an anchor, replacing anchorname with a word (or phrase) that has meaning in that application.
  Example: <<Anchor(hyperlinks)>> would create an anchor called hyperlinks that would be located at the beginning of a section related to hyperlinks.
  More (but not much) wiki markup for anchors can be found at HelpOnLinking and HelpOnMacros.

Back to Markup Basics start

Hyperlinks

Hyperlinks

• Although this wiki automatically creates some hyperlinks, in most cases for the SDL functions, enumerations, and structures it is unable to interpret the text correctly so it is important that you manually hyperlink these.

  • A hyperlink to another page (especially within the wiki) is created, in most cases, by enclosing the text to be linked in double brackets:
    [[linktarget]]

    • Example: Typing SDL_VideoInit will produce SDL_VideoInit, an incomplete hyperlink, because only the CamelCase portion of the name is automatically recognized by the wiki as a hyperlink. You will need to type [[SDL_VideoInit]] to include the SDL_ in the link (SDL_VideoInit).

  • If a hyperlink is automatically created where you don't want one, adding 2 backticks (``) to interrupt the linked phrase or an exclamation mark at the beginning of the incorrect link will usually remove the automatic link without appearing in the displayed text.

    • Example: If typed verbatim, the data field BitsPerPixel is automatically linked, as shown here (BitsPerPixel). This is pointless because individual data fields will not have their own pages, making this a useless, dead link. Typing Bits``Per``Pixel or !BitsPerPixel will prevent it from becoming a link, as shown here (BitsPerPixel).

  • A hyperlink to an anchor (or any unique text on a page) is created, in most cases, by
    

    • [[#anchorname|description]]
      where anchorname is a previously created anchor or a unique bit of text on the page (but not a header) and description is the text that will actually appear as the link.
      Example: [[#hyperlinks|how to hyperlink]] creates how to hyperlink (try clicking the link to see it in action)

  • A hyperlink to an outside web or email address may be created by simply typing or pasting in the address.
    • To create a link with link text other than the address itself, enclose the address followed by a pipe and the alternate link text in double brackets.

      Example: [[link address|alternate text]] produces alternate text

  More wiki markup for tables can be found at HelpOnLinking

Back to Markup Basics start

Include

• An include enables you to copy all or a portion of a page onto another page, allowing changes to one page to be automatically updated on another. This is especially useful for listing enumeration values for a function parameter in the Remarks on the function page, for example.
  

To create an Include:

1. Place the following markup, with appropriate changes at CAPS, in the location where you wish the data to begin on the recipient page.

   • <<Include(PAGENAME, , , from="Start Include here.", to="##End Include here")>>

2. Place the following markup, with appropriate changes at CAPS, on the page where an include is being taken from.

   • Place this immediately before the beginning of the section you wish to include:

     ##The following is included on PAGE NAME(S).  Any changes between these comments will be reflected on THAT PAGE/THOSE PAGES.  Please use caution when editing.  Start Include here.

     Place this immmediately after the end of the section you wish to include:

     ##End Include here

     Note that "Start Include here" and "End Include here" are used as the tags to actually begin and end the Include so these should be placed carefully so that all of the intervening content will be copied to the recipient pages.

This section will be irrelevant when the above new method is implemented.

• For copying values from an enumeration:
  

  <<Include(SDL_Enumeration, , , from="== Values ==", to="== Code Examples ==")>>

  • where SDL_Enumeration is replaced by the Enumeration's name.
    

  For copying data fields from a structure:
  

  <<Include(SDL_Structure, , , from="== Data Fields ==", to="== Code Examples ==")>>

  • where SDL_Structure is replaced by the Structure's name.
    

End obsolete section.

• The basic format is

  <<Include(pagename, heading, level, from="regex", to="regex", sort=ascending|descending, items=n, skipitems=n, titlesonly, editlink)>>

  • See HelpOnMacros/Include for details if a different include becomes necessary.

  The from= and to= start markers are very literal! They will include everything following the end of the start marker and up to but not including the beginning of the end marker. (This is why the header markup is included in the above statements.) When creating an Include statement choose from= and to= parameters carefully.

Back to Markup Basics start

Return to Table of Contents

Global Conventions

The following rules apply to all three Templates (and their associated pages):

• All templates include meta-formatting that is not to be changed.

  • #pragma section-numbers off
    #pragma camelcase off
    <<TableOfContents()>>

    • The Table of Contents will auto-populate using headers

  The only exception to the 'don't change the meta-formatting rule' is the following:

  • Remove #acl All: read from the top of any new page being created from a template (NOT from the template itself or from any existing page you are trying to edit!) or you will not be able to save the new page.

• All templates include the basic subheadings specific to each type of page (Function, Enumeration, Structure) as well as some universal formatting and/or text. To maintain consistency throughout the wiki, these are not to be changed.

  • In rare cases subheadings may be added.

    • Example: SDL_Init()

• Text in italics is intended to be replaced and converted to standard text by also removing the double apostrophes ('') surrounding the text.
  

• If a section is completely empty because there is no relevant information and none is anticipated the section can be deleted, with the following exceptions which are to remain on all pages:

  • Code Examples
    

  • Remarks
    

  When in doubt, leave the section empty.

• Function Parameters and Data Fields that are specifically referenced should be bolded (surrounded by ''', see above) wherever they occur on that function or structure's page.

• When referencing function parameters or members of structures on another page (as with x->y) put the reference in monospace type (surrounded by `, see above)

• Every API page contains a footer below a separator line (thinnest horizontal rule; ----) that provides a link to Category pages.

  • All Enumeration, Structure, and Function pages contain a link to their associated Category Header list.

    • The Header Category is to be changed from the default on the Template (CategoryHeader) to match the category corresponding to the header that the enumeration, structure, or function came from (ie: CategoryVideo). See below or the API By Category page for a list of names corresponding to headers.

  • All Function pages contain a link to the CategoryAPI page.

  • All Enumeration pages contain a link to CategoryEnum.

  • All Structure pages contain a link to CategoryStruct.

    • These links are to remain unchanged.

• If a Function, Enumeration, or Structure that has it's own page is referenced on another page it must be hyperlinked except in the Title or Syntax sections. (Do not rely on the wiki to automatically create the link correctly.)

  • If a hyperlink to a function is created, follow the linking markup with empty parentheses except in the Related Functions section:
    [[SDL_FunctionName]]().

  • Do not use the () for structures or enumerations.
    

Return to Table of Contents

Editing Pages

The following instructions cover both modification of new pages based on a template and modification of existing page contents.

• First see Creating A New Page if the page you wish to edit does not already exist.

There are two options for editing pages - Text Mode and GUI Mode. Once on the page you wish to edit:

• Click Edit (Text) in the left sidebar to use the text editor.

• Click Edit (GUI) in the left sidebar to use the GUI editor.

  The specific markup instructions and examples provided here apply in the Text editor. For instructions on using the GUI editor see HelpOnGraphicalEditor. For information on wiki markup not included here, or other MoinMoin-specific questions, please see the wiki help documentation.

Saving Your Changes

There is a formatting issue with using Color2 inline and then transferring it using an Include. See Preview and Save Changes below. I will see what I can find out to fix it but most likely this section will need to be copied and pasted from the Contribution guide instead of being an Include.

Return to Table of Contents

Function Pages

Every function in the API has a page providing basic information about that function. The information provided is organized as follows and may be modified as described below.

Title & Description

Each page is headed by meta-formatting information followed by the name of the function (Title) and a brief description of what it does.

The meta-formatting must remain unchanged with the following exception:

• When creating a new page from a template, remove
  

  • #acl All: read
    

  from the top of the new page (NOT from the template itself or from any existing page you are trying to edit!) or you will not be able to save the new page.

The page title must be the name of the function described on the page and should match the page address (see above).

• Leave = SDL_ = and replace FunctionName

  • There must be a space between the = on either side of the title.

  • Match the case of the name to that used by the API. In most cases it is CamelCase.

• In order to avoid confusion with regard to the address-title relationship as described above, titles on existing pages should not be changed.

  • If you are concerned about an existing title or page address please contact <ANTI SPAM docs AT libsdl DOT org> to determine the most appropriate correction.

The description of each function should be clear and concise.

• Leave Use this function to and replace ''insert short function description here'', removing the apostrophes.

  • If you are taking information from the header file, the replaced text is usually the same as the text after \brief or is the first line/paragraph about that function, often after /** if the markup has been added to the header.

  • If you are writing your own description (or editing an existing description) it must retain the common beginning and should use hyperlinks if another function, structure, or enumeration is mentioned.

Return to Table of Contents

Syntax

The Syntax section shows the basic format and components of the function.

• Syntax information should replace value SDL_FunctionName(param) within the markup and maintain the same formatting.

  • Do not modify or remove the markup at the beginning or end of this section.

  • All content should be added within this markup on the line following cpp.

  • Closing markup ( }}} ) must be on its own line.

    {{{#!highlight cpp
    value SDL_FunctionName(param)
    }}}

  • Include a space between the value and the function name but do not include a space between the function name and the parenthesis.
  • If there is more than one parameter they are listed on separate lines and aligned vertically into two columns (type and name) using spaces.
    • The parameter types and names should each be left-aligned, using spaces. All names should align with the name following the longest type after a single space.
    • Occasionally types are two word phrases. These should be treated as one word for spacing and alignment purposes but the space between words in the type phrase should be preserved. (This applies to two word values as well.)

      Example:

        _____type_____   _name_
       |              | |      |
       SDL_Surface*     dst
       const SDL_Point* points,   <- 2 word phrase for type
            |
          space

  • If there are pointer indicators (* or **) they are attached to the preceding word and separated from the next by at least one space.
  • Each line ends with a comma except the last which ends with a closed parenthesis.

    Example: SDL_OpenAudioDevice()
    Example: (see box below)

{{{#!highlight cpp

           1 space      no space  spaces (as needed)
              |             \    |_________|
SDL_AudioSpec* SDL_LoadWAV_RW(SDL_RWops*     src,
                              int            freesrc,
                              SDL_AudioSpec* spec,     <- longest type
                              Uint8**        audio_buf,   sets alignment
                              Uint32*        audio_len)
||||||||||||||||||||||||||||||      \       |
      spaces (as needed)          no space  1 space
}}}

• Additional information such as typedef, extern, DECLSPEC, SDLCALL, or ending semi-colon (;) is not included in this section. (This information belongs in Code Examples.)

• Any existing syntax should not be altered except to reflect changes in the API that affect a specific function (such as if a parameter is renamed).
  • Please make any necessary alignment adjustments if an existing syntax section is modified.

  If you are taking information from the header file, the syntax is usually taken from the last line associated with that function's information, often immediately following */, and will require removal of the extra text and spacing adjustments as mentioned above.

Example: SDL_AddPaletteWatch()

Return to Table of Contents

Function Parameters

The Function Parameters section provides a basic description of each input parameter, if any.

Function Parameters are presented within a table and are listed in the order in which they are found in the function.

• The parameter name should replace param and a brief description of the parameter should replace description, maintaining the same formatting.

  You may find it useful to copy the existing line,
  

  • ||'''param'''||description||
    paste in as many copies as there are parameters to create a multi-row table, and then fill in the table rather than typing out the markup for each additional line.

  • The table markup should remain at the beginning and end of each line and between each cell.

    • It is important that there is nothing, including white spaces, at the end of each table line outside of the markup.

  • The first column lists the parameter name in bold.

  • The second column contains a brief description of the parameter as well as limited additional information when relevant. It may contain a link to further information in the Remarks section or on another page.

    • Descriptions should begin with a lower case letter (unless otherwise required for correct syntax) and end without a period. Use a semi-colon (;) to separate multiple concepts within a single description.

    • If a function, enumeration, or structure is mentioned in the description it must be hyperlinked if it has or will have a page. A link should always be included for parameters with enumerated or complex structure types.

    • For a parameter with a type that is a structure having a page of its own, use the SDL name followed by structure in the description rather than a descriptive word (eg: use "SDL_Rect structure" instead of "rectangle"). For a parameter with a type that is an enumeration having a page of its own, use only the SDL name (eg: SDL_ScaleMode). It is not necessary to specify that it is an enumeration.

    • If the structure (or enumeration) does/will not have a page of its own use the descriptive word rather than the SDL name (eg: use "window" instead of "SDL_Window").

      • If the parameter may be any one of many use "a"/"an" (ie: an SDL_Rect structure)

      • If the parameter is limiting use "the" (ie: the window to use).
    • If the parameter refers to an array of structures use the following, or similar, phrasing:

      • an array of SDL_name structures representing something

    • Use "filled in with" if a function fills a structure (or enumeration) with data.
    • Pointers (*) should not be mentioned in the description unless they are critical to the meaning or understanding of the parameter (eg: void* or for some enumerations).

    • Example: SDL_DirtyTexture(), SDL_GetTextureBlendMode()

  • Parameters reserved for future use, deprecated, or for internal use are listed for information purposes only and should be shown in gray.

    • Markup: use <style="color: #808080;"> at the beginning of each table cell to make the contents of the cell 50% gray. Cell text follows this markup on the outside of the >.

    • Example: SDL_PixelFormat (Note: There were no function examples at the time this was written.)

  • If a parameter list contains sections that require headers/titles within the table put the header/title text in italics and make the background color grey.

    • Markup:

      • a) Use empty table cells for all but the last column to create a row that spans all of the columns with centered text.
      • b) place the following at the beginning of the header/title row inside the table cell:

        <bgcolor="#EDEDED">

    • For a two-column table:

      • ||||<bgcolor="#EDEDED">''Header/Title Text in Italics''||
             ||first column text||second column text||

      • generates:

        Header/Title Text in Italics
        first column text	second column text

    • For a three-column table:

      • ||||||<bgcolor="#EDEDED">''Header/Title Text in Italics''||
             ||first column text||second column text||third column text||

      • generates:

        Header/Title Text in Italics
        first column text	second column text	third column text

  • Example: SDL_EventType

  If you are taking information from the header file, some of the more complex or specialized parameters will have description information listed following \param, but not all parameters will be described in the header file. It may be helpful (and enhance wiki consistency) to do a search for the parameter in question and use any existing descriptions as a reference when writing a parameter description on a new page.

• If more detailed information beyond the basic description is required it should be posted in the Remarks section and linked back to the parameter description.
  The following methods may be used to tie information in the Remarks section to a specific function parameter:

  • To link to the beginning of the Remarks section place the following at the end of the related parameter's description and place the relevant information in the Remarks. No other markup is required.

    • ; see [[#Remarks|Remarks]] for details

    • This would be applicable in the case of adding the first remark or if the section is small.
  • To link to a specific comment in the Remarks section you must:

    1. Create the comment in the Remarks section.

    2. Add an anchor to the beginning of the related comment in the Remarks section.

       • Example: <<Anchor(texture)>> might be used to link to extra information located in the Remarks section about the texture parameter. In most cases the anchorname should be the parameter name.

    3. Place the following at the end of the related parameter's description

       • ; see [[#anchorname|Remarks]] for details
         where anchorname is the anchorname you chose in step 2.
         Example: ; see [[#texture|Remarks]] for details

  • • This would be applicable if the Remarks section is large so it may be difficult to find the particular remark or if there are already multiple links to the section.

  • Example: SDL_OpenAudio()

• In some cases it is appropriate to include the possible values/data fields for a parameter that are derived from an enumeration or structure on the function's page rather than simply providing a link to another page. In this case they should be added to the Remarks section by

  1. Using Include markup in the Remarks section to import the data directly from the related page rather than retyping it. (This saves time, avoids typographical errors, and allows updates on the enumeration or structure page to automatically appear on the function page.)

  2. As described above, use the Remarks link in the Function Parameter description cell and Anchor markup in front of the Include markup to connect the two sections.

     • Example: SDL_CreateTexture()

• If creating a page for a function with no Function Parameters (ie: void) remove this entire section from the page.

Return to Table of Contents

Return Value

The Return Value section specifies the type of output from the function, if any.

• In general, positive or successful Return Values are listed first, followed by negative, unsuccessful, or error values.

  • If a parameter is specifically referenced in the return value it should be in bold.

    • Example: SDL_LoadWAV_RW()

• Many functions generate an int type return value. For these functions the Return Value entry should be the following, with only slight modifications as needed to fit the specific function:

  • Returns 0 on success or a negative error code on failure; call [[SDL_GetError]]() for more information.

  • In most cases the specific negative error code or a reason for the error (ie: function not possible) is the only modification to this phrase.

    • Example: SDL_GetDisplayBounds()

  • If there is a distinction between the meaning of a returned 1, 0, and -1 they should be specifically listed, but ;call [[SDL_GetError]]() for more information.
    should remain unchanged.

    • Example: SDL_GetWindowGrab()

  If you are taking information from the header file, the text for the return value usually follows \return.

• In most cases, existing Return Value entries should not be changed except to reflect a change in the API.
• If creating a page for a function with no Return Value (ie: void) remove this entire section from the page.

Return to Table of Contents

Code Examples

The Code Examples section provides real-world examples of how to use a function.

For the most part Code Examples will be user-generated and this section will remain as is until users input their examples.

• All content should be added within the markup at the beginning and end of this section. Do not modify or remove this markup.

• {{{#!highlight cpp
  
  }}}

• If you have a code example to include on a page without any examples, replace
  You can add your code example here
  with your code.

• If there are existing examples please add a new code box to the end of the examples section, or the end of a related group if there are many examples of various types.
  • To add a new code box insert the following into the spot where your example will be located:

    • {{{#!highlight cpp
       
      }}}

    • Example: SDL_Init()

  • All content should be added within this markup (on the blank line with the markup above and below your example content).
• Please remember to keep it simple and easy to understand.
• Do not post anything that you do not have permission to post publicly.

Do not remove this section, even if it is currently empty.

Return to Table of Contents

Remarks

The Remarks section provides additional information related to other sections on the page (see above) as well as a location for users to add comments related to real-world application of the API.

For the most part Remarks will be user-generated and this section will remain as is until users input their comments.

When adding comments:

• Do not post anything that you do not have permission to post publicly.
• If you have general comments or insights about the use of the function please post them in the Remarks section in a simple and easy to understand format.
  • If the section is empty replace

    • ''You can add useful comments here''
      with your content.

  • If the section contains other content, add your general remarks at the end, or in an otherwise appropriate place in the section if there is a large amount of information in the section.

    • Create hyperlinks if you reference an existing function, enumeration, or structure.

      • Example: SDL_BuildAudioCVT()

    • If your remark is in reference to a specific function parameter use bold wherever the parameter's name is used.

      • Example: SDL_ConvertAudio()

  On occasion the header file will contain additional information about a function. This information should be included in this section and linked back to a previous section if appropriate.

  • Example: SDL_AudioSpec()

Do not remove this section, even if it is currently empty.

Return to Table of Contents

Related Functions

The Related Functions section provides a list of other functions specifically referenced by that function or otherwise closely related.

• In general, a "Related Function" is one that is important to the use or understanding of the given function.

  • Example: Get and Set or Open and Close pairs would be listed here, but all other Window or all other Create functions would not.

  • This list should not include every function that might be considered "related" as there can be an argument made for a "relationship" between large numbers of functions, making these lists less valuable.

• Related Functions should be listed in alphabetical order.

• Replace OtherFunction in  .[[SDL_OtherFunction]] with the related function's name.

  • The single, blank space at the beginning of the line must remain.
  • The period (.) after the space must remain.

    If there are multiple related functions it may be easier to copy and paste this line from the template as many times as there are functions and then edit each name rather than typing out all of the markup for new lines.

  • Do not use () after the function names in this section.

  On occasion related functions will be listed in the header file, usually following \sa. Note that some items following \sa are not functions and should not be listed in Related Functions!

If a function does not currently have any related functions this section may be removed and added back at a later time.

You may find more broadly related functions listed by category via the Category links in the footer section or by relationship in a broader, functional sense (often cross-category) on the Function Groups page(s) (to be created).

Return to Table of Contents

Related Enumerations

Rarely, a function page may include an additional section listing enumerations that are directly related to that function. In most cases it will suffice to link to a structure or enumeration within the content rather than in a distinct section.

This section may be added if there is a related enumeration that should be prominently listed on the Function page.

• Include the following immediately above the Related Functions section:

  • == Related Enumerations ==

  • List the related enumeration(s) immediately below this line following the instructions above for Related Functions.

Example: SDL_RendererInfo (Note: There were no function examples at the time this was written.)

On occasion related enumerations will be listed in the header file, usually following \sa. Note that some items following \sa are not enumerations and should not be listed in Related Enumerations!

Return to Table of Contents

Related Structures

Rarely, a function page may include an additional section listing structures that are directly related to that function. In most cases it will suffice to link to a structure within the content rather than in a distinct section.

This section may be added if there is a related structure that should be prominently listed on the Function page.

• Include the following immediately above the Related Functions section (and below Related Enumerations, if present):

  • == Related Structures ==

  • List the related structure(s) immediately below this line following the instructions above for Related Functions.

Example: SDL_ScaleMode (Note: There were no function examples at the time this was written.)

On occasion related structures will be listed in the header file, usually following \sa. Note that some items following \sa are not structures and should not be listed in Related Structures!

Return to Table of Contents

Footer

The footer section, located below a dividing line(----), provides links to Category lists.

• All Function pages contain a link to the CategoryAPI list which includes all functions, enumerations, and structures in the API.

  • Do not remove or modify this link.

• All Function pages contain a link to the associated CategoryHeader list which includes all functions of a particular type such as video, audio, pixels, etc.(ie: CategoryVideo for a video function).

  • From the template, replace Header in [[CategoryHeader]] with one of the following that corresponds to the header file (SDL_*.h) where the function is located.

    • There is no space between the word Category and the Header name.

    • Note that the Header name does not always exactly match the actual header file name.

      Init	Atomic	Audio	CPU	Endian	Error
      Events	ForceFeedback	Joystick	Keyboard	SharedObject	Mouse
      Mutex	Pixels	Platform	Power	Rect	IO
      Surface	SWM	Thread	Timer	Version	Video
      Hints	Assertions	Clipboard	Compat	Touch	Shape

Return to Table of Contents

Enumerations Pages

Every enumeration in the API has a page providing basic information about the enumeration.

Enumerations pages are organized very similarly to function pages.

The information provided is organized as follows and may be modified as described below.

Title & Description

Each page is headed by meta-formatting information followed by the name of the enumeration (Title) and a brief description of what it enumerates.

The meta-formatting must remain unchanged with the following exception:

• When creating a new page from a template, remove
  

  • #acl All: read
    

  from the top of the new page (NOT from the template itself or from any existing page you are trying to edit!) or you will not be able to save the new page.

Enumerations pages are named/titled following the same rules as Function pages.

The description of each enumeration should be clear and concise.

• Leave An enumeration of and replace ''replace with description of the enum'', removing the apostrophes.

  • Use hyperlinks if another function, structure, or enumeration is mentioned.

Return to Table of Contents

Values

Similar to Function Parameters, the Values section provides a list of values that are used by the enumeration and a brief description of each.

Values are presented within a table and are listed in the order in which they are found in the enumeration.

• The value name should replace value and a brief description of the value should replace description, maintaining the same formatting.

  • ||value||description||

• Unlike parameters, values are not listed in bold.

• As with parameters, values that are deprecated, reserved, or for internal use are listed for information purposes only and are to be shown in gray.

  • Example: SDL_GLattr

• Guidelines for this section are otherwise the same as those for Function Parameters.

Return to Table of Contents

Code Examples

Guidelines for posting Code Examples for enumerations are essentially the same as those for functions. See Code Examples section above or SDL API Contribution Style Guide for details.

Return to Table of Contents

Remarks

Guidelines for posting Remarks for enumerations are essentially the same as those for functions. See Remarks section above or SDL API Contribution Style Guide for details.

Return to Table of Contents

Related Functions

This section lists functions that reference the enumeration.

Guidelines for posting related functions for enumerations are essentially the same as those for functions. See Related Functions section above for details.

Return to Table of Contents

Related Structures

This section lists structures that reference the enumeration.

Guidelines for posting related structures for enumerations are essentially the same as those for functions. See Related Structures section above for details.

If an enumeration does not have related structures this section may be removed.

Return to Table of Contents

Footer

The footer section, located below a dividing line (----), provides links to Category lists.

• All Enumeration pages contain a link to the CategoryEnum list, which includes all enumerations in the API.

  • Do not remove or modify this link.

• All Enumeration pages contain a link to the associated CategoryHeader list which includes all enumerations of a particular type such as video, audio, pixels, etc.(ie: CategoryVideo for a video enumeration).

  • From the template, replace Header in [[CategoryHeader]] with one of the following that corresponds to the header file (SDL_*.h) where the enumeration is located.

    • There is no space between the word Category and the Header name.

    • Note that the Header name does not always exactly match the actual header file name.

      Init	Atomic	Audio	CPU	Endian	Error
      Events	ForceFeedback	Joystick	Keyboard	SharedObject	Mouse
      Mutex	Pixels	Platform	Power	Rect	IO
      Surface	SWM	Thread	Timer	Version	Video

Return to Table of Contents

Structure Pages

Every structure in the API has a page providing basic information about the structure.

Structure pages are organized very similarly to function pages.

The information provided is organized as follows and may be modified as described below.

Title & Description

Each page is headed by meta-formatting information followed by the name of the structure (Title) and a brief description of what it contains.

The meta-formatting must remain unchanged with the following exception:

• When creating a new page from a template, remove
  

  • #acl All: read
    

  from the top of the new page (NOT from the template itself or from any existing page you are trying to edit!) or you will not be able to save the new page.

Structure pages are named/titled following the same rules as Function pages.

The description of each structure should be clear and concise.

• Leave A structure that contains and replace ''replace with brief description of the structure'', removing the apostrophes.

  • Use hyperlinks if another function, structure, or enumeration is mentioned.

Return to Table of Contents

Data Fields

Similar to Function Parameters, the Data Fields section provides a list of data fields used by a given structure and a brief description of each.

Data fields are presented within a table and are listed in order matching their sequence in the structure.

• The table has the following format:

  • ||type||'''field'''||description||

  • The first column lists the value type.
  • The second column lists the field name in bold (similar to function parameters).
  • The third column contains a brief description of the data field as well as limited additional information when relevant, and may contain links to other pages or to further information in the Remarks section.

  • As with parameters, data fields that are deprecated, reserved, or for internal use are listed for information purposes only and are to be shown in gray.

    • Example: SDL_AudioCVT

• Guidelines for this section are otherwise the same as those for Function Parameters.

• Example: SDL_RendererInfo

Return to Table of Contents

Code Examples

Guidelines for posting Code Examples for structures are essentially the same as those for functions. See Code Examples section above or SDL API Contribution Style Guide for details.

Return to Table of Contents

Remarks

Guidelines for posting Remarks for structures are essentially the same as those for functions. See Remarks section above or SDL API Contribution Style Guide for details.

Return to Table of Contents

Related Enumerations

This section lists enumerations that reference the structure.

Guidelines for posting related enumerations for structures are essentially the same as those for functions. See Related Structures section above for details.

If a structure does not have related enumerations this section may be removed.

Return to Table of Contents

Related Structures

This section should not be present on Structure pages.

Return to Table of Contents

Related Functions

This section lists functions that reference the structure.

Guidelines for posting related functions for structures are essentially the same as those for functions. See Related Functions section above for details.

If a structure does not have related functions this section may be removed. (unlikely)

Return to Table of Contents

Footer

The footer section, located below a dividing line (----), provides links to Category lists.

• All Structure pages contain a link to the CategoryStruct list, which includes all structures in the API.

  • Do not remove or modify this link.

• All Structure pages contain a link to the associated CategoryHeader list which includes all structures of a particular type such as video, audio, pixels, etc.(ie: CategoryVideo for a video structure).

  • From the template, replace Header in [[CategoryHeader]] with one of the following that corresponds to the header file (SDL_*.h) where the structure is located.

    • There is no space between the word Category and the Header name.

    • Note that the Header name does not always exactly match the actual header file name.

      Init	Atomic	Audio	CPU	Endian	Error
      Events	ForceFeedback	Joystick	Keyboard	SharedObject	Mouse
      Mutex	Pixels	Platform	Power	Rect	IO
      Surface	SWM	Thread	Timer	Version	Video
      Hints

Return to Table of Contents

Category Pages

Editing An Existing Category Page

Please do not change or remove any existing content on a Category page. It is especially critical that the search and footer markup remain unchanged. See Creating A Category Page below for the core content.

If you would like to contribute content to the Introduction section on an existing Category page please observe the following guidelines:

• In nearly every case all new content should be placed below the opening line(s) generally introducing each Category.
• The Introduction should contain only information relating to the entire Category as a whole or discussing how one Category relates to another where relevant. Specific details about structures, functions, etc. within a Category should be placed on the relevant page(s) for those items.
• In general the overall look and feel of the wiki should not be substantially changed due to the addition of your content.

• If you have a very large quantity of introduction information to share consider creating a new page and linking it in the Introduction or possibly creating a Tutorial instead.

  • NAMING: If you create a new page for introduction information please name the page IntroTopic where Topic is replaced by a word or phrase describing the topic of your introduction materials.

    • Example: IntroSurface would be the name of a page with content introducing concepts related to surfaces

      • IntroHaptic would be the name of a page with content introducing force feedback

    • TITLE: The title of a separate Introduction page should use the highest level header markup and may be longer and more descriptive than the page name.

Return to Table of Contents

Creating A Category Page

This section provides information necessary to correctly create a Category page.

• In the vast majority of cases all Category pages will have been previously created so please search thoroughly and double-check spelling prior to creating a new Category page.

If you are confident that a new page must be created (and have coordinated w/ <ANTI SPAM docs AT libsdl DOT org>):

• Follow the instructions above for Creating A New Page but in step 2 choose the template

  • CategoryTemplate

• from the beginning of the list in the left column of the table on the new page instead of choosing one of the API page templates.

• Replace everything between #language en and the dividing line (----) with the following:

  • An appropriate title for the page within level 1 header markup (see below).

    • In most cases this will be a very general description of the header file the page represents. (See existing pages for examples.)

  • '''Include File(s):''' followed by a link to the address of the associated header file, using tip to replace the alphanumeric version code in the address, and the include filename as the alternate text (see below).

  • Table of Contents markup (see below).
  • Level 2 header markup for an Introduction section, followed by whatever introductory information is relevant to the new Category.

    • At minimum this should begin with
      This category contains functions for
      followed by a basic description of what that part of the API does.

    • Sub-headings (level 3 or lower) may be added to this section as needed.

  • Level 2 header markup for an Enumeration, Structure, and Function section, each followed by FullSearch markup, as shown below, where Header in CategoryHeader is replaced by whatever the name of the new category page is (ie: CategoryVideo).

    If the enumeration, structure, and/or function pages to be listed on the new Category page have already all been created, it may be preferable to use a cached full search instead of a full search to reduce load time, etc. To do this add the word Cached immediately following Search (so it will read <<FullSearchCached... instead.

  Example:

  ##master-page:CategoryTemplate
  ##master-date:Unknown-Date
  #format wiki
  #language en
  ||<tablewidth="100%" style="color: #FF0000;" :> DRAFT||
  
  = Title of the Page =
  
  '''Include File(s):''' [[http://hg.libsdl.org/SDL/file/default/include/SDL_headername.h|SDL_headername.h]]
  
  <<TableOfContents()>>
  
  == Introduction ==
  This category contains functions for
  
  == Enumerations ==
  
  <<FullSearch(category:CategoryEnum CategoryHeader)>>
  
  == Structures ==
  
  <<FullSearch(category:CategoryStruct CategoryHeader)>>
  
  == Functions ==
  
  <<FullSearch(category:CategoryHeader -CategoryEnum -CategoryStruct)>>
  
  
  ----
  CategoryCategory

• Once the page is created and the basic format filled in, please follow the instructions in Editing An Existing Category Page for adding any additional content to the Introduction section.

• If a section is empty it should be removed from the page.
  • This will generally only apply to the Enumerations and/or Structures sections or else a Category page is not likely the appropriate page format to be creating.
• For future consistency, please retain the exclusion search terms (preceded by a - (minus)) in the Functions search even if there are no corresponding enumeration or structure pages at the time of page creation or editing.

Return to Table of Contents

Tutorial Pages

Linking To An External Tutorial

To add a link on the Tutorials page to an existing tutorial from another site:

1. Go to the Tutorials page: Tutorials

   • There is a link to the page in the left sidebar.

2. Edit the page (see Editing Pages above for details).

3. Add a link to your tutorial at the beginning of the appropriate SDL version's section.

   • Place a single space followed by an asterisk (and an optional space) before your link.

     • Use the following syntax for your link

         * [[link address|link text]]

       • It is preferred that you use alternate text for the link rather than the raw address.

       • Example: [[http://www.libsdl.org/cgi/docwiki.cgi/SDL_Guide|SDL Quick Guide]] produces SDL Quick Guide

   • See the Hyperlinks section for further instructions on creating a link.

   • See existing links for more examples.

4. Add a brief description of what the tutorial covers on the line below the link.

   • Place two blank spaces followed by a period (and an optional space) before your description text.

   • Example:

       . Description text

Overall the addition should appear as follows (existing header shown to illustrate spacing more clearly):

• == Video ==
   * [[link address|link text]]
    . Description text

Creating A Tutorial In The Wiki

If you wish to create a new tutorial from within the wiki, begin by creating a new page following the instructions above.

• Your tutorial page may have any formatting you feel suits the contents best. It is preferred that the general appearance remain consistent with the rest of the wiki as much as possible.

  • See Some Wiki Markup Basics for examples of available formatting markup.

Once your tutorial is created and the page saved, follow the instructions above for Linking To An External Tutorial, making the following adjustments:

• Use the following syntax for your link

   * [[page title portion of page address only|optional alternate link text]]

  • Example: For the internal page address http://wiki.libsdl.org/moin.cgi/Tutorials, simply creating a link [[Tutorials]] produces Tutorials instead.

  • You may provide alternate link text if the title of your page is especially short, long, cryptic, or otherwise not the best "title" for your page. Otherwise, omit |optional alternate link text from the above syntax.

Return to Table of Contents

Miscellaneous Notes

Some other wiki help that might be of interest or helpful to find quickly:

• HelpIndex

• HelpOnFormatting

• HelpOnEditing

• HelpOnSmileys

• HelpOnAdmonitions

We have the Color2 macro installed.

• It will colorize text outside of tables using the following syntax:
  

  • <<Color2(colorname,text to be colorized)>>
    

  • If text to be colorized must contain commas each section must be colorized separately. Place the comma at the end of each string and the space after between colorized sections to accomplish this.

    • Example:

      • Incorrect -

        <<Color2(purple,A sentence that contains commas, such as this one, must be broken into parts or the text before the first comma will not appear when parsed.)>>

        • generates

        such as this one, must be broken into parts or the text before the first comma will not appear when parsed.

      • Correct -

        <<Color2(purple,A sentence that contains commas,)>> <<Color2(purple,such as this one,)>> <<Color2(purple,must be broken into parts or the text before the first comma will not appear when parsed.)>>

        • generates

        A sentence that contains commas, such as this one, must be broken into parts or the text before the first comma will not appear when parsed.

  • colorname may be most any simple color name like blue or red or green

Any link referencing the header files should replace the version number (12-digit alpha-numeric code) with tip in the address if the link should be to the most current version rather than to a specific version of the header file.

Return to Table of Contents

Style Guide Formatting:

• Formatting scenarios - use one each separated by a space when there are multiple conditions that may or may not apply (not necessary when only 1 option).

When your remark includes a reference to...

||<width="30%" bgcolor="#EDEDED">If...||<bgcolor="#EDEDED">Then...||
||<|3>'''context'''||Use formatting||
||''Markup'': <<BR>>{{{markup}}} = result||
||''Example'': ||

For more information on markup see the Wiki Basics Style Guide.

Disclaimer