SDL API Contribution Style Guide

This guide provides the instructions needed to add your own content to the Code Examples or Remarks sections of the Function, Enumeration, and Structure pages in this wiki.

Existing content, including markup, should not be modified or removed unless specifically noted.

If you would like to contribute to or edit other sections, more detailed instructions can be found at APIDocumentationStyleGuide.

You must have permission to make major edits or create new pages.
Please email docs@libsdl.org to request permission.

The Basics

Opening An Editor

If a page can be edited you will see two options in the left column to choose from:

1. blue

   • The Text editor provides more power/flexibility for editing than the GUI editor but requires that you know the wiki markup. Use the Text editor to see the content with raw markup. You will need to use the Preview feature to view the content as it will appear when saved (rendered?).

   Specific markup instructions on this page are for use with the Text editor but should also work in the GUI editor. For information on wiki markup not included here, or other MoinMoin-specific questions, please see the wiki help documentation.

2. blue

   • The GUI editor provides buttons, much like a simple word processor, to add formatting markup such as bolding text, making a table, or creating a numbered list. It is simpler to use than the Text editor but does not provide buttons for all the possible markup. Use the GUI editor to see the content appear roughly as it would on the screen as you edit or if you do not know or want to use the wiki markup.

   The GUI editor is fairly self-explanatory however, if you require further assistance, see the GUI editor help for more detailed instructions.

Saving Your Changes

Before you save your changes please include a note in the Comment field below the editing box that summarizes what you have done.

When you have completed adding your content and are satisfied with the formatting use the blue

link in the left column to save your changes.

Automatic Backup of Drafts
(copied from: Help On Editing)

• Every time you are in the editor and use the "Preview", "Spell Check", "Cancel" or "Save Changes" buttons, moin saves a draft copy of your work internally. Use preview often! If you hit "cancel" accidentally, your machine crashes, or the browser window was accidentally closed, then the automatic backup of your draft may be easily recovered.

  To recover that draft, you simply edit that page again. If there is a draft, an alert message will be in the message box and a "load draft" button will be present. Clicking the "load draft" will load your saved draft into the editor box replacing the current revision already loaded. You can continue editing the loaded draft, but this time try to save it at the end.

  Don't use the "preview", "spell check", "save changes" or "cancel" buttons on that page before "load draft" or you will overwrite your old draft with a new one. If you successfully save a page, the internal draft copy of it is not needed any more and will be deleted.

The Specifics

The following instructions apply to all Function, Enumeration, or Structure pages unless specifically noted. In most cases functions will be referenced for simplicity. This is not meant to exclude structures or enumerations.

Adding Code Examples

The Code Examples section provides real-world examples of how to use a function.

Please post code examples showing how you have used (implemented?) a function that may benefit other users.

• Do not post anything that you do not have permission to post publicly.

• If the Code Examples section is empty please replace
  You can add your code example here
  with your code.

• If there are existing examples please add yours to the end, or to a related section if there are many examples of various types.

• Example: SDL_Init()

• All content should be added within this markup.

  • {{{#!highlight cpp
     
    }}}

Do not remove or modify any existing code examples.

green

Adding Remarks

The Remarks section provides additional information about previous sections as well as a location for users to add relevant 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.

• If your remark is in reference to a specific function parameter use bold wherever the parameter's name is used.

  • '''parameter''' = parameter

• Example: SDL_ConvertAudio()

• Create hyperlinks if you reference an existing function, enumeration, or structure.

  • Note: Although the wiki will automatically create links in many cases, it does not recognize the SDL names correctly so you must manually hyperlink them.
    [[SDL_Function]]()
    

    • Include open and closed parentheses after a function name, outside of the hyperlink markup.
      

    [[SDL_Enumeration/Structure]]
    

    • Do not use parentheses for enumerations or structures.

• Example: SDL_BuildAudioCVT()

Do not remove or modify any existing remarks.