Style Guide: Tutorials

The Tutorials page provides links to many different resources for help with using SDL. This guide provides instructions for adding your tutorial to the Tutorials page.

General Guidelines

Most tutorials on the Tutorials page are external resources. This guide will help you add an external tutorial to the list.
If you do not have an outside location for your tutorial, this guide also details how to create a tutorial from within the wiki and add it to the list when it is ready.

Please post appropriate tutorials that may benefit other users.

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

Adding An Existing Tutorial

The following instructions apply if you have already created your tutorial. If you still need to create your tutorial see Creating A New Tutorial below first.

1. Begin by going to the Tutorials page 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.

2. Scroll down in the edit window to the section that best fits your tutorial (eg: == Video ==, == Audio ==, etc.).
   See Creating A New Heading if one does not exist.

3. Find information relevant to your tutorial 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.

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.

Formatting Your Entry

Location

• Action: Place your tutorial listing anywhere within the relevant section.

  • Tutorials discussing the same specific sub-topic should be grouped together within each major section.

• Markup: see Format for details

• Note: It is preferable to have a blank line above and below your entry, separating it from any other entries or markup.

Format

1. Action: Create a linked title for your tutorial.
   Markup: Place a single space followed by an asterisk (and an optional space) before your link.

   • A link is created by placing double brackets ([[ ]]) on either side of the link address and link text, which are separated by a pipe (|) with no spaces.

   • link text should be a short, simple title for your tutorial.

    * [[link address|link text]]

2. Action: Add a brief description of what the tutorial covers on the line below the link.
   Markup: Place two blank spaces followed by a period (and an optional space) before your description text.

3.   . Description text

The total addition should appear as follows (existing header shown to illustrate spacing more clearly):

• == Audio ==
  
   * [[http://your.tutorial.html|Using Audio in SDL]]
    . This tutorial discusses how to set up audio playback using SDL 1.3.

  Example: See other entries on the Tutorials page for examples.

Creating A New Heading

Please use existing headings whenever possible.

Assuming your tutorial does not fit into any of the existing headings:

• Action: Create a new heading for it.

  • The headings should roughly match those found on the API by Category page.

• Markup: Place the following markup at the location for the new heading.

  • == Heading ==

  • Replace Heading with the new heading name (ie: Initialization, Events, etc.)

  • It is preferable to have a blank space above and below a heading.

• Return to Adding An Existing Tutorial to complete the process.

Creating A New Tutorial

When your remark includes a reference to a function parameter:

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

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