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 as well as detail how to create a new tutorial from within the wiki if you prefer.

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 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 Entry

Location

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

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

• Markup: see Format for details

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 surrounding the link address and link text, separated by a pipe with no spaces, by double brackets:

    * [[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 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 as much as possible.

If your tutorial does not fit into any of the existing headings you may create a new heading for it. The headings should roughly match those found on the API by Category page.

To create a new heading:

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

  • == Heading ==

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

• 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