|
Size: 4505
Comment: alt formatting test
|
Size: 5140
Comment: update formatting
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 20: | Line 20: |
| For assistance with editing, saving, or wiki-appropriate markup see the [[http://wiki.libsdl.org/moin.cgi/SGWikiBasics|Wiki Basics]] Style Guide. | For additional assistance with editing, saving, or wiki-appropriate markup see the [[http://wiki.libsdl.org/moin.cgi/SGWikiBasics|Wiki Basics]] Style Guide. |
| Line 23: | Line 23: |
| == Adding the First Remark == Replace the following with your remarks: {{{''You can add useful comments here''}}} == Adding Additional Remarks == Add your remarks to the end of the Remarks section, or to a related grouping if there are existing remarks covering the same topic. ''Example'': [[SDL_MixAudio]]() |
== Adding Your Remarks == Place your remark between the {{{== Remarks ==}}} and {{{== Code Examples ==}}} headings: ||<width="30%" bgcolor="#EDEDED">If...||<bgcolor="#EDEDED">Then...|| ||your remark is the __first on the page__||replace the following with your remarks<<BR>>{{{''You can add useful comments here''}}}|| ||there are __existing remarks__ on the page||add your remarks to the ''end'' of the Remarks section,<<BR>>or to a related grouping if there are existing remarks covering the same topic|| ||||''Example'': [[SDL_MixAudio]]()|| |
| Line 36: | Line 33: |
| == Formatting Remarks == | == Formatting Your Remarks == |
| Line 39: | Line 36: |
| ||<|3>If a parameter '''on that page''' is referenced||Use '''bold''' wherever the name is used in the remark|| | When your remark includes a reference to a function parameter: ||<width="30%" bgcolor="#EDEDED">If...||<bgcolor="#EDEDED">Then...|| ||<|3>a parameter __on the same page__ is referenced||use '''bold''' wherever the name is used in the remark|| |
| Line 42: | Line 41: |
||<|3>If a parameter '''from another function''' is referenced||Use `monospace` wherever the name is used in the remark|| |
||<|3>a parameter __from another page__ is referenced||use `monospace` wherever the name is used in the remark|| |
| Line 49: | Line 47: |
| Same as for function parameters above. . ''Example'': [[SDL_AudioSpec]] |
When your remark includes a reference to a structure data field: * use the same formatting as for function parameters above. . ''Example'': [[SDL_AudioSpec]] |
| Line 54: | Line 53: |
| These are generally in ALL CAPS anyway and do not require special formatting. . ''Example'': [[SDL_GLattr]] |
When your remark includes a reference to an enumeration value: * no special formatting is required since these are generally already in ALL CAPS. . ''Example'': [[SDL_GLattr]] |
| Line 59: | Line 59: |
| If you reference an existing function, enumeration, or structure: | When your remark includes a reference to an existing function, enumeration, or structure: |
| Line 65: | Line 65: |
| . Include open and closed parentheses outside of the hyperlink markup after a function name. {{{[[SDL_Function]]()}}} = [[SDL_Function]]() . Do not use parentheses for enumerations or structures. .{{{[[SDL_Enumeration/Structure]]}}} . ''Example'': [[SDL_SetTextureScaleMode]]() |
||<width="30%" bgcolor="#EDEDED">If...||<bgcolor="#EDEDED">Then...|| ||<|2>it is a __function__||include open and closed parentheses outside of the hyperlink markup|| ||{{{[[SDL_Function]]()}}} = [[SDL_Function]]()|| ||<|2>it is a __structure__ or __enumeration__||do not use parentheses|| ||{{{[[SDL_Enumeration/Structure]]}}}|| ||||''Example'': [[SDL_SetTextureScaleMode]]()|| |
DRAFT |
Style Guide: Remarks
All API pages in this wiki contain a section for remarks. This guide provides instructions for adding your own content to the Remarks section of these pages.
Contents
General Guidelines
The Remarks section provides additional information related to other sections on the page as well as a location for users to add comments related to real-world application of the API.
Please post your appropriate remarks that may benefit other users.
- Do not post anything that you do not have permission to post publicly.
- Remarks should have adequate references to make them clear and useful.
- Please remember to keep it simple and easy to understand.
For additional assistance with editing, saving, or wiki-appropriate markup see the Wiki Basics Style Guide.
Adding Your Remarks
Place your remark between the == Remarks == and == Code Examples == headings:
If... |
Then... |
your remark is the first on the page |
replace the following with your remarks |
there are existing remarks on the page |
add your remarks to the end of the Remarks section, |
Example: SDL_MixAudio() |
|
Formatting Your Remarks
Referencing Function Parameters
When your remark includes a reference to a function parameter:
If... |
Then... |
a parameter on the same page is referenced |
use bold wherever the name is used in the remark |
Markup: 3 apostrophes surrounding the text for bold |
|
Example: SDL_ConvertAudio() |
|
a parameter from another page is referenced |
use monospace wherever the name is used in the remark |
Markup: a single backtick surrounding the text for monospace |
|
Example: SDL_OpenAudio() |
Referencing Structure Data Fields
When your remark includes a reference to a structure data field:
- use the same formatting as for function parameters above.
Example: SDL_AudioSpec
Referencing Enumeration Values
When your remark includes a reference to an enumeration value:
- no special formatting is required since these are generally already in ALL CAPS.
Example: SDL_GLattr
Referencing Other API Components
When your remark includes a reference to an existing function, enumeration, or structure:
- Create a hyperlink to its page
Although the wiki will automatically create links in many cases, it does not recognize the SDL names correctly so you must manually hyperlink them.
Markup: use two brackets surrounding the page name (must be exact) for a link.
If... |
Then... |
it is a function |
include open and closed parentheses outside of the hyperlink markup |
[[SDL_Function]]() = SDL_Function() |
|
it is a structure or enumeration |
do not use parentheses |
[[SDL_Enumeration/Structure]] |
|
Example: SDL_SetTextureScaleMode() |
|
For more information on markup see http://wiki.libsdl.org/moin.cgi/SGWikiBasics
Resources
Our goal is to create accurate, consistent, helpful, user-friendly documentation. We appreciate your efforts to make your additions fit into the existing framework and retain the same look and feel as much as possible.
If you have questions that aren't addressed here:
- Search for another page that contains something similar to what you want to do and copy all the basics as much as applicable.
Check the other SDL Style Guides.
Post a question to Feedback and
include a way to contact you.
Post a question to the Mailing List
Send a comment or question to <ANTI SPAM wiki AT libsdl DOT org> for clarification.
If you have suggestions for changes or additions to this document or any other portion of the wiki please don't hesitate to contact us with your thoughts. We are happy to have the participation!
Disclaimer
All content modifications are subject to review for consistency and quality. We reserve the right to remove or modify any content added to this wiki at any time. You may direct questions or concerns to <ANTI SPAM wiki AT libsdl DOT org>.
