SDL API Documentation Style Guide: Getting Started

Before You Start

Together this Style Guide and the SDL API Contribution Style Guide provide the basic information needed to get started making the most common edits to this wiki - Code Examples and Remarks.

If you would like to make other contributions beyond Code Examples or Remarks we welcome your contribution! If you haven't already, please email <ANTI SPAM docs AT libsdl DOT org> to receive additional Style Guides and to coordinate efforts.

Some Wiki Markup Basics

Below is a summary of the most commonly used markup in this wiki and some hints and tricks for using it.

A good place to look for additional information on MoinMoin wiki markup is HelpOnMoinWikiSyntax. Also see the Editor Hints in the left sidebar in Edit mode for some of the most common markup.

Spacing

Indenting

• Place blank spaces at the beginning of a line of text to create indents. (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. (Seems like a hard break forces the next line into the same paragraph.)

    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)

Return to Table of Contents

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.}}}

      • generates

      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.
      }}}

      • generates

      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.

  red

  orange

  yellow

  green

  blue

  indigo

  violet

  brown

  • We have the Color2 macro installed. It will colorize text outside of tables using the following syntax:
    

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

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

    • 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 purple

        • 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 purple

          purple

          purple

    Please use colored text sparingly if at all. As a general convention we use blue to represent links (whether they actually behave as links or not), so please reserve that color for such purposes.

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.

Return to Table of Contents

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

Return to Table of Contents

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.

Return to Table of Contents

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
    

    • Generates:

    • 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

    Generates:

  • First line of numbered list
  • 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.

Return to Table of Contents

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||

    Generates:

    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

Return to Table of Contents

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.

Return to Table of Contents

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 on the function page, for example.
  To create an Include place the following markup in the location where you wish the data to begin on the recipient page.

  • 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.
      

    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.

Return to Table of Contents

Miscellaneous Notes

green

Some terms used in the Style Guides:

• API Pages: Refer to Function, Structure, and Enumeration pages.

• Category Pages: Each major category found in the blue list contains a page which includes a basic introduction to that category and an alphabetical list of all API pages in that category, separated by type.

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

• HelpIndex

• HelpOnFormatting

• HelpOnEditing

• HelpOnSmileys

• HelpOnAdmonitions

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

Disclaimer