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.

Tutorials should provide basic instruction regarding the use and application of some aspect of SDL (specific to v1.3 in this wiki). Tutorials may cover as little as a single function or as much as whole conceptual topics (ie: audio, video, etc.).

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.
• Please remember to keep it accurate, simple, and easy to understand.

Return to Table of Contents

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. See Formatting Your Entry below to find information relevant to your tutorial and apply the appropriate formatting as you create your entry.

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

Return to Table of Contents

Formatting Your Entry

Basic Format

• Action 1: Create a linked title for your tutorial.

  • It should be located under the appropriate section heading.

  • If there are other tutorials you may add yours anywhere in the section (top, middle, bottom) where it logically fits in.

  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 address should be the complete web address for the tutorial.

  • link text should be a short, simple title for your tutorial. It does not need to exactly match the address and may have blank spaces so it is grammatically correct.

   * [[link address|link text]]

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

• Action 2: 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.

Return to Table of Contents

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.

Return to Table of Contents

Creating A New Tutorial

• Action 1: 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. Page addresses are case-sensitive.

  Example: The address for the page SDL_BuildAudioCVT() is

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

  red Be careful to name and spell accurately when creating a new page! You cannot delete a page or edit a page address after the page is created and saved.

  If you discover a typo in the address prior to saving the page	Action: Copy all of your contents, cancel or close 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.

• Action 2: 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.

• Action 3: 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 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