Style Guide: Structure Pages

This guide provides specific instructions for editing or adding your own content to each section of a Structure page in this wiki.

Structure pages should provide basic information about the SDL structures to allow users to most effectively utilize them in their projects.

General Guidelines

Please observe the following for all structure pages:

• Do not post anything that you do not have permission to post publicly.
• Sections should have adequate details to make them clear and useful while remaining brief wherever possible. Code Examples and Remarks may be more extensive than other sections if necessary.
• Please remember to keep it accurate, simple, and easy to understand.

• Do not remove, modify, or add to the markup above the page title (processing instructions (ie: #pragma, #acl), red markup, etc.) except:

  • On CategoryCompat pages, place the following markup above the page title and below the processing instructions or DRAFT markup, if present:

  • ||<tablewidth="100%" #000000 style="color: #FF8C00;" :> <<BR>>~+For Backward Compatibility Only+~<<BR>><<BR>> ||

• Do not remove, modify, or add section headings unless specifically mentioned below.
• In general, we prefer that you do not remove or modify existing content unless it is clearly incorrect or out of date.

• Pages with red at the top are in progress and will often contain unusual content, formatting, or notes. Please do not remove or modify these. That will all be corrected/removed upon final edit.

Return to Table of Contents

Getting Started

1. Begin by going to the page you wish to edit and selecting blue or blue in the left column to begin editing.

   • Markup info provided here is specifically for use in the Text editor but should work in both.

2. Scroll down in the edit window to the section(s) you want to edit. Add your content following the conventions in this style guide.

3. Find information relevant to your content in the style guide sections below and apply the appropriate formatting as you edit.

4. Preview your work as you go by clicking blue in the left column. Preview often and any time you are unsure of formatting.

   • (Keep in mind that a few things (like Color2 text) don't preview exactly as they parse.)

5. Save your work by clicking blue in the left column after you are satisfied with your content and have filled in the Comment field under the editing box.

For assistance with editing, saving, or wiki-appropriate markup see the Wiki Basics Style Guide or contact us at <ANTI SPAM wiki AT libsdl DOT org>.

Return to Table of Contents

Editing Specific Sections

Title

Do not edit the Title.

The Title section consists of the page heading and its markup:

• = SDL_StructureName =

For structure pages this is the name of the structure being described on the page and should match the address of the page.

Example: The page address http://wiki.libsdl.org/moin.cgi/SDL_PixelFormat should have matching title SDL_PixelFormat and describe the SDL_PixelFormat structure.

If you believe a change is necessary please submit Feedback from that page or contact us at <ANTI SPAM wiki AT libsdl DOT org>.

Return to Table of Contents

Description

The Description section immediately follows the page title and does not have it's own heading.

Structure descriptions begin with:

• A structure that contains

  • or very rarely

  A union that contains

• followed by a clear and concise description of what the structure contains.

Note: Information presented in this section is meant to be limited. Extended description information for more complicated structures should be placed in the Remarks section instead.

• The Description should not contain a link to the Remarks section even if additional information is located there.

Note: Exceptions to the basic description are very unusual. Follow established patterns in the wiki (based on similar pages which may be found by text search) whenever possible if an exception seems appropriate.

Return to Table of Contents

Table of Contents

Do not edit the Table of Contents.

The Table of Contents consists of the following markup and is generated automatically on the parsed page.

• <<TableOfContents()>>

If you believe a change is necessary please submit Feedback from that page or contact us at <ANTI SPAM wiki AT libsdl DOT org>.

Return to Table of Contents

Data Fields

The Data Fields section provides basic information about each field in the structure and is presented in table format.

The basic format is as follows:

||type1||'''field1'''||description||
||type2*||'''field2'''||description||
||[[type3]]||'''field3'''||description||
...
||typeN||'''fieldN'''||description||

Markup: Use basic table markup and enclose each field name in bold markup. All text in the table is left-justified.

• The first column contains the field type and any pointers if applicable.

• The second column contains the field name, without types or pointers, in bold.

• The third column contains a simple description of each field using some specific formatting conventions.

  • red All descriptions begin with a lower case letter, end without a period, and are generally not complete sentences.

Example: SDL_Surface, SDL_JoyButtonEvent, SDL_Palette, SDL_HapticCondition

Action: There are a few content-dependent conventions we have chosen for consistency across pages. See the tables below for details.

Return to Table of Contents

Code Examples

The Code Examples section is meant to contain simple, meaningful examples of how to use the structure in a program.

• Unlike other sections, which should rarely require editing once DRAFT is removed, this section is expected to change over time.

This is one of the few sections that is intended to grow and adjust as users discover more information about a structure that would be helpful to share with other users.

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

Please see the Code Examples Style Guide for details on editing this section.

Return to Table of Contents

Remarks

The Remarks section is meant to contain additional information that did not fit in the other sections as well as comments regarding the behavior and use of the structure in real-world applications.

• Unlike other sections, which should rarely require editing once DRAFT is removed, this section is expected to change over time.

This is one of the few sections that is intended to grow and adjust as users discover more information about how a structure behaves under different circumstances.

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

Note: This is not an appropriate place to post questions, suggestions, bugs, or commentary. Please use the other communication channels available to you, especially the forums and Feedback form, for these types of remarks.

Please see the Remarks Style Guide for details on editing this section.

Return to Table of Contents

Related Enumerations

The Related Enumerations section provides a list of enumerations specifically referenced by the structure or otherwise closely related to it.

This list should include:

• enumerations that are specifically referenced in the structure
• enumerations that are indirectly referenced by but still closely related to the structure

  • (ie: the enum is not a field type but its values are used to fill in a field as with SDL_EventType for the type field in many event structures)

This list should not include:

• every enumeration that might be considered "related" to the structure or any other listed enumerations

  • Including too many would make these lists much less valuable.

• all enumerations of similar type
• all enumerations of a related category
• enumerations that are indirectly related

  • (ie: it might be common to use them together)

• enumerations that do not have a page in the wiki
• non-enumerations

  • (ie: do not include functions or structures in this list)

Markup: Each line should begin with a single blank space and a period followed by the enumeration name enclosed in double brackets to create a hyperlink.

• Note: Do not include empty parentheses after the name.

• The basic format for the Related Enumerations list is:

== Related Enumerations ==
 .[[SDL_EnumerationName]]
 .[[SDL_EnumerationName]]

• Note: The heading was included to more clearly illustrate the blank space before the period at the beginning of each list line. Without this markup the format will not parse correctly.

Example: SDL_Event, SDL_Keysym, SDL_WindowEvent

Return to Table of Contents

Related Structures

The Related Structures section provides a list of other structures (or unions) specifically referenced by the structure or otherwise closely related to it.

This list should include:

• other structures that are specifically referenced in the structure
• other structures that are indirectly referenced by but closely related to the structure

  • This is uncommon.

This list should not include:

• the primary structure on that page
• every other structure that might be considered "related"

  • Including too many would make these lists much less valuable.

• all structures of similar type
• all structures of a related category
• structures that are indirectly related

  • (ie: it might be common to use them together)

• structures that do not have a page in the wiki
• non-structures

  • (ie: do not include functions or enumerations in this list)

Markup: Each line should begin with a single blank space and a period followed by the structure name enclosed in double brackets to create a hyperlink.

• Note: Do not include empty parentheses after the name.

• The basic format for the Related Structures list is:

== Related Structures ==
 .[[SDL_StructureName]]
 .[[SDL_StructureName]]

• Note: The heading was included to more clearly illustrate the blank space before the period at the beginning of each list line. Without this markup the format will not parse correctly.

Example: SDL_Event, SDL_Color, SDL_HapticDirection

Return to Table of Contents

Related Macros

This is a custom section that should not be used except in the most specific circumstances. Example: SDL_version The Related Macros section provides a list of functions specifically associated with that structure or otherwise closely related to it.

Return to Table of Contents

Related Functions

The Related Functions section provides a list of functions specifically associated with that structure or otherwise closely related to it.

• In general, a "Related Function" is one that uses the given structure.

This list should include:

• functions that use or are otherwise very closely related to the structure

This list should not include:

• every other function that might be considered "related"

  • Including too many would make these lists much less valuable.

• all functions of similar type or action
• all functions of a related category
• functions that are indirectly related (ie: a similar function that does not use the structure)
• functions that do not have a page in the wiki
• non-functions (ie: do not include structures or enumerations in this list)

Markup: Each line should begin with a single blank space and a period followed by the function name enclosed in double brackets to create a hyperlink.

• Note: Do not include empty parentheses after the function names in this section. They are all functions so it should be understood/unnecessary.

• The basic format for the Related Functions list is:

== Related Functions ==
 .[[SDL_FunctionName]]
 .[[SDL_FunctionName]]

• Note: The heading was included to more clearly illustrate the blank space before the period at the beginning of each list line. Without this markup the format will not parse correctly.

Example: SDL_TextInputEvent, SDL_SysWMinfo

Return to Table of Contents

Footer

The Footer section consists of a horizontal rule followed by two links separated by a comma.

Markup:

----
[[CategoryStruct]], [[CategoryHeader]]

• where CategoryStruct is the same for every structure page and CategoryHeader is structure-specific with Header varying based on the header file containing the structure (see below).

red Category names do not always match the header file name. Please consult the following table for the correct name to use so the structure will appear in the correct list(s).

Action 1: Do not edit the CategoryStruct link!

Action 2: The CategoryHeader link may be edited if the page still says [[CategoryHeader]] (as on a new page) or if the structure has been relocated to another header (very rare).

red There are a few exceptions to this rule (pages with a category name that does not match their header file). These have been determined by the SDL team. Please do not change an existing page's category name simply because it does not match its header file. If you are concerned that a name is incorrect please submit Feedback from that page or contact us at <ANTI SPAM wiki AT libsdl DOT org> to confirm the change first.

Markup: Replace CategoryHeader with the appropriate category name from the table that follows, or contact us at <ANTI SPAM wiki AT libsdl DOT org> to find out what category name to use if you are unsure or if the category appears to be missing.

Return to Table of Contents

Special

This section contains details for special formatting circumstances that are best described separately from the average structure page. In general these guidelines should be used in conjunction with the above.

Callback Functions

Although having a callback function associated with a structure is rare, it does occasionally occur. Documenting this will affect two (2) sections of the structure's page - Data Fields and Remarks.

• Note: Because callback functions are so rare with structures most of the examples listed here will be on function pages. This is for illustrative purposes only. As of this writing the only callback associated with a structure is the audio callback, found with SDL_AudioSpec. Because of this rarity many of the guidelines below will not currently apply to a structure-based callback, but this is being written with the future possibilities in mind.

Action 1: Use the following formatting specifics in addition to those listed above for the structure whenever a callback function is included on a structure page:

Action 2: Detail the syntax and parameters of the callback function in the Remarks section using the following basic format with the changes listed in the table below:

• The function prototype for '''callback''' is:
   {{{#!highlight cpp
  callback syntax
  }}}
   . where its parameters are:
   ||`callback parameter`||description||
   . optional return value info...
   . optional remarks or details...

  • to display

The function prototype for callback is:

• callback syntax
  

• where its parameters are:

  callback parameter

  description

• optional return value info...
• optional remarks or details...

Compatibility Structures

Compatibility Structures are present in the API for backward compatibility only and thus are treated slightly differently than structures from the current version. Use the following formatting specifics in addition to those listed above for all CategoryCompat pages::

Action 1: The top of every compatibility structure page should include the following, verbatim, to be placed below the pragma markup, below red if present, and above the page title:

• ||<tablewidth="100%" #000000 style="color: #FF8C00;" :> <<BR>>~+For Backward Compatibility Only+~<<BR>><<BR>> ||

Action 2:

• If only one SDL 1.3 structure replaces the compatibility structure	Action: See Markup A below.
  If more than one SDL 1.3 structure has replaced the compatibility structure	Action: See Markup B below.
  	Note: This should occur only very rarely, if at all. Please avoid making the list any larger than necessary. This is NOT a related structures list!
  If there are no equivalent structures in SDL 1.3	Action: See Markup C below.
  Example: SDL_ActiveEvent, SDL_Overlay, SDL_VideoInfo

• Markup A: Add the following section to the end of the page above the footer. Replace SDL_Structure with the name of the appropriate SDL 1.3 structure:

  • == SDL 1.3 Replacement(s) ==
    ||<tablewidth="100%" #000000 style="color: #FF8C00;">'''This structure has been replaced by the following in SDL 1.3:  [[SDL_Structure]]'''||

• Markup B: Add the following section to the end of the page above the footer. Create a list of structures by repeating the [[SDL_Structure]] markup, separating each member of the list with a comma, and placing the most direct counterpart first, alphabetizing any additional structures after that.

  • == SDL 1.3 Replacement(s) ==
    ||<tablewidth="100%" #000000 style="color: #FF8C00;">'''This structure has been replaced by the following in SDL 1.3:  [[SDL_Structure]], [[SDL_Structure]]'''||

• Markup C: Add the following section to the end of the page above the footer. Replace Other options here with text describing other options in SDL 1.3 that could be used to accomplish the same goal, or remove it if there is no applicable text:

  • == SDL 1.3 Replacement(s) ==
    ||<tablewidth="100%" #000000 style="color: #FF8C00;">'''There are currently no equivalent structures in SDL 1.3.'''||
    Other options here

Example: See other CategoryCompat pages for examples

Return to Table of Contents