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.

Contents

Style Guide: Structure Pages
1. General Guidelines
2. Editing Specific Sections

General Guidelines

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

red

The basic structure template is also used for unions that have pages in the wiki. For simplicity, the following guidelines for structures will also apply to unions unless a specific difference is noted.

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 (#pragma or #acl processing instructions, etc.) except:
- On CategoryCompat pages, place the following markup above the page title, below the processing instructions or red 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.

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.

If the page describes a union rather than a structure	Action: Use the alternate description (`A union that contains...`) and, if necessary, replace the word `structure` with the word `union` where appropriate throughout the page.
	Example: SDL_Event
If another API page is referenced in the description	Action: Be sure to hyperlink it and use () outside the link markup if it is a function.
	Example: `[[SDL_FunctionName]](), [[SDL_StructureName]]`
If a parameter on that page is referenced in the description	Action: Use bold for the parameter name.
	Note: This is a very rare occurrence.
	Note: If the reference is to the parameter as a concept (ie: the window to do something with) rather than directly to the parameter itself (ie: SDL_Function(window)) do not make it bold. Please don't just make the word bold every time it occurs on the page.

Return to 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||
...
||typeN||'''fieldN'''||description||

Markup: Use basic table markup and enclose each field name in bold markup.

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.
There are a few content-dependent conventions we have chosen for consistency across pages - see the tables below for details.

Example: SDL_JoyButtonEvent, SDL_HapticCondition

General (whole table)
If another API page is referenced	Action: Be sure to hyperlink it.
	Example: SDL_Event, SDL_AudioSpec
If there are important, distinct groups of fields within the structure	Action: Place a full-width row with a grey background and centered, italics title above each section.
	Markup: Begin the row with empty table cells equal to the number of columns in the table -1 (ie: 2 empty cells for a 3 column table). Place the following markup in the next cell `<bgcolor="#EDEDED">''Section Title''` Replace `Section Title` with appropriate text and close the last column.
	Example: this table, SDL_HapticConstant, SDL_HapticRamp
If the field is for internal use, deprecated, unused, or read-only	Action: Make the text in the row grey by including the following, verbatim, in the first cell of the row between the starting table markup and the text: `<rowstyle="color: #808080;">`
	Example: `\|\|<rowstyle="color: #808080;">\|\|type\|\|'''field'''\|\|description\|\|`
	Note: Although a rare case, any other table style markup should be included within the same set of angle brackets (`<>`) and separated from this markup by a space.
First Column (type)
If there is a pointer associated with the field	Action: Place the pointer symbol(s) at the end of the type with no space between.
	Example: SDL_Surface, SDL_assert_data
If	Action:
	Example:
Second Column (field)
Third Column (description)
If a field references another field on that same page	Action: Use bold for the field name.
	Note: This is a very rare occurrence.
	Note: If the reference is to the field as a concept rather than directly to the field itself do not make it bold. Please don't just make the word bold every time it occurs on the page.
	Example: SDL_AudioCVT()

large remarks SDL_RendererInfo

-  ⇤ ← Revision 5 as of 2011-09-27 20:53:53 → 
  Size: 6954
  Editor: SheenaSmith
  Comment: add content (very incomplete)
+   ← Revision 6 as of 2011-09-28 05:22:00 → ⇥
  Size: 9007
  Editor: SheenaSmith
  Comment: add content (very incomplete)
-Deletions are marked like this.
+Additions are marked like this.
 Line 26:
- * Do not remove, modify, or add to the markup (#pragma, etc.) above the page title.
+ * Do not remove, modify, or add to the markup above the page title (`#pragma` or `#acl` processing instructions, etc.) except:
  * On CategoryC``ompat pages, place the following markup above the page title, below the processing instructions or <<Color2(red,DRAFT)>> markup if present:
  . {{{||<tablewidth="100%" #000000 style="color: #FF8C00;" :> <<BR>>~+For Backward Compatibility Only+~<<BR>><<BR>> ||}}}
-Line 121:
+Line 123:
+||||<bgcolor="#EDEDED">''General (whole table)''||
||<( |2 30%>''If'' __another API page__ is referenced||''Action'': Be sure to [[http://wiki.libsdl.org/moin.cgi/SGWikiBasics#Hyperlinks|hyperlink]] it.||
||''Example'': [[SDL_Event]], [[SDL_AudioSpec]]||
||<( |3 30%>''If'' there are __important, distinct groups of fields__ within the structure||''Action'': Place a full-width row with a grey background and centered, italics title above each section.||
||''Markup'': Begin the row with empty table cells equal to the number of columns in the table -1 (ie: 2 empty cells for a 3 column table).  Place the following markup in the next cell<<BR>>   `<bgcolor="#EDEDED">''Section Title''`<<BR>>Replace `Section Title` with appropriate text and close the last column.||
||''Example'': this table, [[SDL_HapticConstant]], [[SDL_HapticRamp]]||
||<( |3 30%>''If'' the field is __for internal use, deprecated, unused, or read-only__||''Action'': Make the text in the row grey by including the following, verbatim, in the first cell of the row between the starting table markup and the text:<<BR>>{{{<rowstyle="color: #808080;">}}}||
||''Example'': {{{||<rowstyle="color: #808080;">||type||'''field'''||description||}}}||
||''Note'': Although a rare case, any other table style markup should be included within the same set of angle brackets (`<>`) and separated from this markup by a space.||
-Line 122:
+Line 133:
-||<( |2 30%>''If'' __another API page__ is referenced in the type column||''Action'': Be sure to [[http://wiki.libsdl.org/moin.cgi/SGWikiBasics#Hyperlinks|hyperlink]] it.||
||''Example'': [[SDL_Event]], [[SDL_AudioSpec]]||
-Line 125:
+Line 134:
-||''Example'': [[SDL_Surface]]||
+||''Example'': [[SDL_Surface]], [[SDL_assert_data]]||
||<( |2 30%>''If''||''Action'':||
||''Example'':||
-Line 129:
+Line 139:
+||<( |4 30%>''If'' __a field references another field__ on that same page||''Action'': Use '''[[http://wiki.libsdl.org/moin.cgi/SGWikiBasics#Text_Formatting|bold]]''' for the field name.||
||''Note'': This is a very rare occurrence.||
||''Note'': If the reference is to the field as a ''concept'' rather than ''directly'' to the field itself do not make it bold.<<BR>>~-Please don't just make the word bold every time it occurs on the page.-~||
||''Example'': [[SDL_AudioCVT]]()||

Wiki Navigation

Wiki Page Content

Style Guide: Structure Pages

General Guidelines

Editing Specific Sections

Title

Description

Table of Contents

Data Fields