Wiki Page Content

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.

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.

General Guidelines

Please post 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 accurate, simple, and easy to understand.
  • red The Remarks section is not a discussion board. This is not an appropriate place to post questions, unrelated comments, or general commentary. Only constructive information is to be posted in the Remarks section.

    • Please use the forums, mailing lists, Feedback form (upper right corner), or email (<ANTI SPAM wiki AT libsdl DOT org>) if you have questions or need to discuss some aspect of the API.

Return to Table of Contents

Adding Your Remarks

  1. Begin by going to the page you wish to edit and selecting blue or blue 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.

  2. 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.

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

  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 additional assistance with editing, saving, or wiki-appropriate markup see the Wiki Basics Style Guide.

Return to Table of Contents

Formatting Your Remarks

Location

If your remark is the first on the page

Action: Replace the following text and markup with your remarks:
''You can add useful comments here''

Example: SDL_StopTextInput()
(Remarks were empty at the time this was selected.)

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.

red Do not change or remove any of the existing content.

Example: SDL_MixAudio()

Return to Table of Contents

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.
'''parameter''' = parameter

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.
`member` = member

Example: SDL_OpenAudio()

Return to Table of Contents

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

Return to Table of Contents

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

Return to Table of Contents

Referencing A Callback Function

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

Using an Include

If your remark uses an Include to copy content from another page into the Remarks section, see the guidelines below.

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

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 <parameter> with the relevant parameter name and replace <enumeration> with the name of the enumeration or other page being referenced.

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:

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
'''<parameter>'''may be one of the following:

Example: SDL_CreateTexture(), SDL_SetThreadPriority()

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
'''<parameter>''' may be any of the following OR'd together:

Example: SDL_CreateRenderer()

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
'''parameter''' will be filled in with one of the following:

Example: SDL_GetTextureBlendMode()

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
'''parameter''' may be 0 or a mask of any of the following SDL_<enumeration> values OR'd together:

Example: SDL_RendererInfo

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
'''parameter''' may be <option that cannot be OR'd (ie: SDL_x_NONE)> or a mask of any of the other SDL_<enumeration> values OR'd together:

Example: SDL_RendererInfo, SDL_SetRenderDrawBlendMode()

Return to Table of Contents

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()

Return to Table of Contents


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:

  1. Search for another page that contains something similar to what you want to do and copy all the basics as much as applicable.
  2. Check the other SDL Style Guides.

  3. Post a question to Feedback and include a way to contact you.

  4. Post a question to the Mailing List.

  5. 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>.

None: SGRemarks (last edited 2011-12-15 22:32:39 by SheenaSmith)

Feedback
Please include your contact information if you'd like to receive a reply.
Submit