|
Size: 5152
Comment: minor change
|
Size: 6251
Comment: update formatting
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 7: | Line 7: |
| Line 13: | Line 14: |
| '''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.''' | ''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.'' |
| Line 15: | Line 16: |
| Please post your appropriate remarks that may benefit other users. | '''Please post your appropriate remarks that may benefit other users. |
| Line 18: | Line 19: |
| * Please remember to keep it simple and easy to understand. |
* Please remember to keep it simple and easy to understand.''' <<BR>> <<BR>> <<BR>> == Adding Your Remarks == 1. Begin by going to the page you wish to edit and selecting <<Color2(blue,Edit (Text))>> or <<Color2(blue,Edit (GUI))>> in the left column to begin editing. ~-Reminder: Markup info provided here is specifically for use in the Text editor but should work in both.-~ 1. Scroll down in the edit window to the section that begins with {{{== Remarks ==}}}. Add your content below this header following the conventions in this style guide. 1. Find information relevant to your content in the style guide sections [[#formatting|below]] and apply the appropriate formatting as you create your content. 1. Preview your work as you go by clicking <<Color2(blue,Preview)>> in the left column. 1. Save your work when you are satisfied with your edits by clicking <<Color2(blue,Save Changes)>> in the left column. |
| Line 24: | Line 34: |
| == Adding Your Remarks == Place your remark in the {{{== Remarks ==}}} section: ||<30%>''If'' your remark is the __first on the page__||''Action'': Replace the following with your remarks<<BR>>{{{''You can add useful comments here''}}}|| ||''If'' there are __existing remarks__ on the page||''Action'': 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]]()|| ~-[[#ToC|Return to Table of Contents]]-~ <<BR>> <<BR>> <<BR>> |
<<Anchor(formatting)>> |
| Line 36: | Line 37: |
| === Location === ||<( |2 30%>''If'' your remark is the __first on the page__||''Action'': Replace the following text and markup with your remarks:<<BR>>{{{''You can add useful comments here''}}}|| ||''Example'': [[SDL_StopTextInput]]()<<BR>>~-(Remarks were empty at the time this was selected.-~)|| ||<( |3>''If'' there are __existing remarks__ on the page||''Action'': Add your remarks to the end of the Remarks section, or to a related grouping if there are existing remarks covering the same topic.|| ||''Note'': Do not change or remove any of the existing content.|| ||''Example'': [[SDL_MixAudio]]()|| <<Anchor(params)>> |
|
| Line 38: | Line 47: |
| ||<|3 30%>''If'' you are referencing a parameter __on the same page__||''Action'': Use '''bold''' wherever the name is used in the remark|| ||''Markup'': 3 apostrophes surrounding the text for bold<<BR>>{{{'''parameter'''}}} = '''parameter'''|| |
||<( |3 30%>''If'' you are referencing a parameter __on the same page__||''Action'': Use '''bold''' wherever the name is used in the remark.|| ||''Markup'': Use 3 apostrophes on either side of the text for bold.<<BR>>{{{'''parameter'''}}} = '''parameter'''|| |
| Line 41: | Line 50: |
| ||<|3>''If'' you are referencing a parameter __from another page__||''Action'': Use `monospace` wherever the name is used in the remark|| ||''Markup'': a single backtick surrounding the text for monospace<<BR>>{{{`member`}}} = `member`|| |
||<( |3>''If'' you are referencing a parameter __from another page__||''Action'': Use `monospace` wherever the name is used in the remark.|| ||''Markup'': Use a single backtick on either side of the text for monospace.<<BR>>{{{`member`}}} = `member`|| |
| Line 47: | Line 56: |
| When your remark includes a reference to a structure data field: * Use the same formatting as for function parameters above. . ''Example'': [[SDL_AudioSpec]] |
''If'' your remark includes a reference to a structure data field: . ''Action'': Use the same formatting as for [[#params|function parameters]] above. . ''Example'': [[SDL_AudioSpec]] |
| Line 53: | Line 62: |
| When your remark includes a reference to an enumeration value: . ''Action'': no special formatting is required since these are generally already in ALL CAPS. . ''Example'': [[SDL_GLattr]] |
''If'' your remark includes a reference to an enumeration value: . ''Action'': No special formatting is required since these are generally already in ALL CAPS. . ''Example'': [[SDL_GLattr]] |
| Line 59: | Line 68: |
| When your remark includes a reference to an existing function, enumeration, or structure: * ''Action'': Create a hyperlink to its page |
''If'' your remark includes a reference to an SDL function, enumeration, or structure: . ''Action'': 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.-~<<BR>> |
| Line 62: | Line 72: |
| {i} ~-''Although the wiki will automatically create links in many cases, it does not recognize the SDL names correctly so you must manually hyperlink them.''-~<<BR>> | . ''Markup'': Use two brackets surrounding the page name ({{{[[ ]]}}}) to create a link. . ~-Using the full page address is not necessary. The page name portion (end of address) is sufficient but must be exact.-~ |
| Line 64: | Line 75: |
| . ''Markup'': use two brackets surrounding the page name (must be exact) for a link. | ||<( |2 30%>''If'' you reference a __function__||''Action'': Include open and closed parentheses outside of the hyperlink markup.|| ||''Markup'': {{{[[SDL_Function]]()}}} = [[SDL_Function]]()|| ||<( |2>''If'' you reference a __structure__ or __enumeration__||''Action'': Do not use parentheses.|| ||''Markup'': {{{[[SDL_Enumeration/Structure]]}}} = [[SDL_Enumeration/Structure]]|| ||||<(>''Example'': [[SDL_SetTextureScaleMode]]()|| |
| Line 66: | Line 81: |
| ||<|2 30%>''If'' it is a __function__||''Action'': Include open and closed parentheses outside of the hyperlink markup|| ||''Markup'': {{{[[SDL_Function]]()}}} = [[SDL_Function]]()|| ||<|2>''If'' it is a __structure__ or __enumeration__||''Action'': Do not use parentheses|| ||''Markup'': {{{[[SDL_Enumeration/Structure]]}}}|| ||||<(>''Example'': [[SDL_SetTextureScaleMode]]()|| For more information on markup see the [[http://wiki.libsdl.org/moin.cgi/SGWikiBasics|Wiki Basics]] Style Guide. |
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. Please remember to keep it simple and easy to understand.
Adding Your Remarks
Begin by going to the page you wish to edit and selecting blue
or blue in the left column to begin editing.
Reminder: Markup info provided here is specifically for use in the Text editor but should work in both.
Scroll down in the edit window to the section that begins with == Remarks ==. Add your content below this header following the conventions in this style guide.
Find information relevant to your content in the style guide sections below and apply the appropriate formatting as you create your content.
Preview your work as you go by clicking blue in the left column.
Save your work when you are satisfied with your edits by clicking blue in the left column.
For additional assistance with editing, saving, or wiki-appropriate markup see the Wiki Basics Style Guide.
Formatting Your Remarks
Location
If your remark is the first on the page |
Action: Replace the following text and markup with your remarks: |
Example: SDL_StopTextInput() |
|
If there are existing remarks on the page |
Action: Add your remarks to the end of the Remarks section, or to a related grouping if there are existing remarks covering the same topic. |
Note: Do not change or remove any of the existing content. |
|
Example: SDL_MixAudio() |
Referencing Function Parameters
When your remark includes a reference to a function parameter:
If you are referencing a parameter on the same page |
Action: Use bold wherever the name is used in the remark. |
Markup: Use 3 apostrophes on either side of the text for bold. |
|
Example: SDL_ConvertAudio() |
|
If you are referencing a parameter from another page |
Action: Use monospace wherever the name is used in the remark. |
Markup: Use a single backtick on either side of the text for monospace. |
|
Example: SDL_OpenAudio() |
Referencing Structure Data Fields
If your remark includes a reference to a structure data field:
Action: Use the same formatting as for function parameters above.
Example: SDL_AudioSpec
Referencing Enumeration Values
If your remark includes a reference to an enumeration value:
Action: No special formatting is required since these are generally already in ALL CAPS.
Example: SDL_GLattr
Referencing Other API Components
If your remark includes a reference to an SDL function, enumeration, or structure:
Action: 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 ([[ ]]) to create a link.
Using the full page address is not necessary. The page name portion (end of address) is sufficient but must be exact.
If you reference a function
Action: Include open and closed parentheses outside of the hyperlink markup.
Markup: [[SDL_Function]]() = SDL_Function()
If you reference a structure or enumeration
Action: Do not use parentheses.
Markup: [[SDL_Enumeration/Structure]] = SDL_Enumeration/Structure
Example: SDL_SetTextureScaleMode()
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>.
