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.
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 appropriate remarks that may benefit other users.
~-Return to Table of Contents-~
1. Begin by going to the page you wish to edit and selecting
Edit (Text)
or
Edit (GUI)
in the left column to begin editing.
{i} ~-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 heading following the conventions in this style guide.
1. Find information relevant to your content in the style guide sections
below
and apply the appropriate formatting as you create your content.
1. Preview your work as you go by clicking
Preview
in the left column. Preview often and any time you are unsure of formatting.
1. Save your work by clicking
Save Changes
in the left column after you are satisfied with your content and have filled in the Comment field under the editing box.
For additional assistance with editing, saving, or wiki-appropriate markup see the Wiki Basics Style Guide.
~-Return to Table of Contents-~
<( |2 30%>If your remark is the __first on the page__ |
Action: Replace the following text and markup with your remarks: |
Example: SDL_StopTextInput() |
|
<( |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. |
Important! Do not change or remove any of the existing content. |
|
Example: SDL_MixAudio() |
~-Return to Table of Contents-~
When your remark includes a reference to a function 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. |
|
Example: SDL_ConvertAudio() |
|
<( |3>If you are referencing a parameter __from another page__ |
Action: Use |
Markup: Use a single backtick on either side of the text for monospace. |
|
Example: SDL_OpenAudio() |
~-Return to Table of Contents-~
If your remark includes a reference to a structure data field:
Action: Use the same formatting as for function parameters above.
Example: SDL_AudioSpec
~-Return to Table of Contents-~
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
~-Return to Table of Contents-~
If your remark is describing a callback function:
Action: See the special section on callback functions in the Function Pages Style Guide.
Note: Callback functions do not get their own pages.
Example: SDL_AddEventWatch(), SDL_AddTimer()
~-Return to Table of Contents-~
If your remark uses an Include to copy content from another page into the Remarks section, see the guidelines below.
<( 30%>If your Include is copying __stand-alone content__ into the Remarks |
Action: A tie-in statement is not likely necessary. In that case, simply follow the instructions for creating an Include in Wiki Basics |
<( |2 30%>If your Include is used to copy __values from a related enumeration__ that was mentioned in the Function Parameters section (most common use) |
Action: See the following table for tie-in text options to precede the Include. |
Note: In these examples, replace |
|
<( 30%>If your Include is for __some other purpose__ |
Action: Please apply the closest appropriate match from the other two options (above) with minimal modifications, or contact us if you are unsure what to do. |
Action: If required (see table above), select from the following introductory phrases to explain the relationship of the included material to the page:
<( |2 30%>If the Include contains a list from which __only one option__ may be selected |
Action: Place the following phrase on the line above the Include markup |
Example: SDL_CreateTexture(), SDL_SetThreadPriority() |
|
<( |2 30%>If the Include contains a list from which __more than one option__ may be selected |
Action: Place the following phrase on the line above the Include markup |
Example: SDL_CreateRenderer() |
|
<( |2 30%>If the Include contains a list from which __only one value will be used to fill a parameter__ |
Action: Place the following phrase on the line above the Include markup |
Example: SDL_GetTextureBlendMode() |
|
<( |2 30%>If the Include contains a list from which __more than one option may be selected or the value may be 0__ |
Action: Place the following phrase on the line above the Include markup |
Example: SDL_RendererInfo |
|
<( |2 30%>If the Include contains a list from which __one or more than one__ option may be selected |
Action: Place the following phrase on the line above the Include markup |
Example: SDL_RendererInfo, SDL_SetRenderDrawBlendMode() |
~-Return to Table of Contents-~
If your remark includes a reference to an SDL function, enumeration, or structure:
Action: Create a hyperlink to its page.
Markup: Use two brackets surrounding the page name (``````) to create 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() |
~-Return to Table of Contents-~
<<Include(SGWikiBasics, , , from="Start SG Include here.", to="##End SG Include here.")>>