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 and then return here.

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. When you are satisfied with your content and have filled in the Comment field under the editing box, save your work 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 sub-topic should be grouped together within each major section.

• Markup: see Format below for specific instructions

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

     . 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

1. Action: Create an address for your tutorial.

   How: Type the following into the address bar and replace PageName with the name of your page. Press Enter to begin creating the page.

   • http://wiki.libsdl.org/moin.cgi/PageName

   • Note: There are several ways to create a new page address. You may choose another if you prefer.

   Note: The convention in this wiki is that the name of the page is also the address of the page and that CamelCase is preferable to blank spaces.

   Example: The address for the page SDL_BuildAudioCVT() is
   http://wiki.libsdl.org/moin.cgi/SDL_BuildAudioCVT

   red Page addresses are case-sensitive. Be careful to name and spell accurately when creating a new page!

   If you discover a typo in the address prior to saving the page	Action: Copy all of your contents, cancel the page, and start over. Paste your contents into the new page and continue editing.
   	Note: Your old page and address will not be saved.
   If you discover a typo in the address after you saved the page	Action: Send a message via Feedback or to <ANTI SPAM wiki AT libsdl DOT org> requesting a correction.
   	Note: You will not be able to correct it yourself.

   Note: If you type in an address and land on an existing page you will need to select a new address.

2. Action: Create a blank page to fill with your tutorial.

   How: If you have chosen a unique address in step 1 above then you will arrive at a page that has the following at the top followed by a table with 2 columns.

   • This page does not exist yet. You can create a new empty page, or use one of the page templates. blue

   Click on blue

   , which will take you to a nearly blank editing page (using the text editor) that says, Describe PageName here.

   • Note: You will need to delete the text in the editing box to start with a truly blank page.

   • If you prefer to use the GUI editor click blue in the left column to switch to the GUI editor.

3. Action: Create your tutorial! Your tutorial page may have any formatting you feel suits the contents best. It is preferred that the general appearance remain consistent (or at least compatible) with the rest of the wiki as much as possible.

   Note: For information on markup see http://wiki.libsdl.org/moin.cgi/SGWikiBasics

• Note: It is not necessary to create your entire tutorial in one sitting. You are free to save the page, keep track of the address, and go to the next step when it is complete and ready for prime time.

Once your tutorial is complete and the page saved, follow the instructions above for Adding An Existing Tutorial to link your tutorial into the Tutorials page.

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