Style Guide: Wiki Basics

Getting Started

In general, existing content, including markup, should not be modified or removed.

Opening An Editor

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

1. Edit (Text)

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

   Specific markup instructions in this guide 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. Edit (GUI)

   • 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 HelpOnGraphicalEditor for more detailed instructions.

Note that some formatting will appear slightly different in preview mode than on the finished screen.

Automatic Backup of Drafts

(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 [at the top] and a "load draft" button will be present [in the left column]. 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.

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.

• Sample comments:

  • added comment to end of remarks
  • added code example to C++ section
  • remarked on use of function with [sound card model]

Especially when using the text editor, use the Preview function in the left sidebar often and before saving your changes to ensure that the markup you have included is producing the desired result as well as to scan for errors in a different view.

• (Keep in mind that a few things (like Color2 text) don't preview exactly as they parse.)

When you have finished adding your content and filling in the Comment field, and are satisfied with the formatting, use the Save Changes function in the left sidebar to save your changes.

Return to Table of Contents

Style Guide Terminology

Some terms used in the style guides are intended to have specific meanings or purposes that may or may not be as intuitively clear as we hope. Explanations are provided here to avoid any potential confusion.

• API Page

  • Refers to any Function, Structure, or Enumeration page.

• Category Page

  • Refers to the front page of each major category found in the API by Category list.

• Draft Page

  • Any page with DRAFT at the top is incomplete. It should not be used as a formatting example until DRAFT is removed. There may be missing or extra information, unusual formatting, colors, markup, notes, etc. on these pages. They will all be cleaned up by the time DRAFT is removed. Please bear with us while they are in place as they help to speed up the final editing process. Thank you!

• If...

  • Found in some detailed style guide sections, this indicates options for you to choose from. Select the one(s) that best suits your content given the context on the page you are editing and follow the related instructions. (See Action through Example below.)

  • In some cases a portion of the statement following If will be underlined to help you quickly scan for the option(s) that you need.

• Action:

  • The instructions immediately following Action indicate what you should do to apply the style guide guidelines. In some cases you will select an Action that is relevant to your particular content (usually from a table of options). In many cases everyone making a certain type of edit should follow the same Action in which case no options will be given.

  • Sometimes Action will include a number (ie: Action 2) to indicate that there is more than one way to achieve the same result or that more than one step is required. Read carefully to determine which apply to your circumstance.

  • Action is occasionally followed by Markup or How and may also be followed by any of the other markers (see below).

  • Please read any Note or Important! comment related to the Action(s) you choose. If you are otherwise familiar with the wiki and it's markup the other sections can usually be skipped unless you are having trouble.

• Markup:

  • The instructions immediately following Markup indicate the critical markup that would be used in the text editor to complete the Action above it. If you prefer another way to achieve the same result, or prefer to use the GUI editor this information should be used to clarify the correct formatting for you to match.

  • Sometimes Markup will include a number (ie: Markup 2) to indicate that there is more than one way to achieve the same result. You should choose whichever option suits you best for the circumstances.

• How:

  • Usually used instead of Markup, the information immediately following How describes specific actions to be taken outside of the editing window in order to complete the Action above it. (This is somewhat rare.)

• Note:

  • The instructions immediately following Note: should be taken into consideration as necessary.

• Important!

  • Similar to a Note, but indicates that the noted information is especially important and should be heeded by all Contributors.

• Example:

  • Provides a direct example of the markup or points to a place in the wiki where the related Action and Markup can be observed.

Return to Table of Contents

General Guidelines

This section contains general information that applies to nearly every page in the wiki. Please review this section periodically for updates.

Important! Do not change the Category links at the bottom of any page.

Please do not remove DRAFT from any page!

The top of (nearly) every page begins with the following, which should not be edited:

• #pragma section-numbers off
  #pragma camelcase off

• Any new or in progress page will also include:

  ||<tablewidth="100%" style="color: #FF0000;" :> DRAFT||

Important! If you encounter the following comments while editing a page, please ensure that any changes to the <intervening content> are appropriate to all pages listed in the first comment. If not, please make your changes outside of the comments or contact us for assistance.
DO NOT change these comments except to update included <PageName>s if necessary.

• ##The following content is included on <PageName>.  Any changes between these comments will be reflected there as well.  Please use caution when editing.  Start Include here.
     <intervening content>
  ##End Include here.

• See Includes for more information.

Return to Table of Contents

Some Markup Basics

Below is a summary of the most commonly used markup in this wiki, as well as some very rarely used, and some hints and tricks for using it.

The following is provided for your convenience and is meant to be general information. The other Style Guides describe where this formatting should be applied and where exceptions may exist.

A good place to look for additional information on MoinMoin wiki markup is HelpOnMoinWikiSyntax. Also see the Editor Hints in the left sidebar when in Edit mode for some of the most common markup.

Text Formatting

Note: Formatting markup can usually be nested/grouped, but the order it is used in may affect whether it works as desired. Try using multiple formatting tags in a different order or check the help if you have trouble.

Important! The wiki's default font type, font colors, and font sizes should be used in almost all cases.

• Example 1:

  • {{{Verbatim text as it should be typed, appear as code, or show markup. If it is too long for the line it will not wrap when parsed (this is more of an issue for smaller monitors) but will also not appear in a box.}}}

    • Generates

    Verbatim text as it should be typed, appear as code, or show markup. If it is too long for the line it will not wrap when parsed (this is more of an issue for smaller monitors) but will also not appear in a box.

• Example 2:

  • {{{
    Verbatim text as it should be typed, appear as code, or show markup. This will word-wrap if it is too long for one line but it will also appear in a box.
    }}}

    • Generates

    Verbatim text as it should be typed, appear as code, or show markup. This will word-wrap if it is too long for one line but it will also appear in a box.

• Example 3:

  • Correct

    <<Color2("A sentence that contains commas, such as this one, must be quoted in order for the commas to appear correctly.",purple)>>

    • Generates

  • A sentence that contains commas, such as this one, must be quoted in order for the commas to appear correctly.

More wiki markup for text formatting can be found at HelpOnFormatting.

Return to Table of Contents

Spacing

Both vertical and horizontal spacing can be rendered differently depending upon the combination of formatting markup that is used. If your formatting is not working out the way you want check the style guide information on other formatting that you have used nearby, especially the Lists section, that may be affecting how the local formatting is interpreted.

• Example: If you try to pick up a numbered list down the page after using indents/unnumbered lines at the same indent level, the next number in the numbered list may count the unnumbered lines or change format.

• See Some Known Problems and Solutions below for notes on known markup misbehavior and ways to try to circumvent it.

Hard Line Break

Markup: <<BR>>

• Place the above markup wherever you want to force the following text onto the next line but keep it in the same paragraph.
  

• Note: You cannot change indent level immediately following a hard line break. (The next line is still part of the same paragraph.)

Example: Typing the following in the text editor

•   1 first line<<BR>>  2 this line typed on same line after hard line break markup, same indent<<BR>>   3 this line typed on same line after hard line break markup, +1 indent<<BR>>  4 this line typed on same line after hard line break markup, -1 indent<<BR>>  . 5 this line typed on same line after hard line break markup, same indent with period<<BR>>6 this line typed on same line after hard line break markup without any indent

  • generates

• 1 first line
  2 this line typed on same line after hard line break markup, same indent
  3 this line typed on same line after hard line break markup, +1 indent
  4 this line typed on same line after hard line break markup, -1 indent
  . 5 this line typed on same line after hard line break markup, same indent with period
  6 this line typed on same line after hard line break markup without any indent

Indenting

Important! Indenting often leads to inadvertent creation of an unnumbered list. Lists follow very limiting, sometimes difficult to figure out, rules. See Lists below if your indenting is not working the way you think it should.

Markup: Place blank spaces at the beginning of a line of text to create indents. (this line has 1 space)

• Use one space for each indent level desired. (this line has 2 spaces)

Note: Use a period (.) after the spaces and before the text (usually separated by a space after but not necessary) to ensure that the indent does not become a bullet or numbered list. Note that this markup will sometimes resolve problems when the spacing from line to line is not what you expected. (this line has 2 spaces and a starting period)

Example:  . This line starts with a period   

• generates
  

• This line starts with a period

Note: Paragraph breaks and spaces between lines and paragraphs (which may be individual lines) are parsed with different spacing depending upon the context (especially relative indent level). It may take some playing around with the markup to get the spacing you want, or it may be that you will have to accept a certain amount of pre-determined spacing between lines.

Example: Typing the following in the text editor

•  1 hard return followed by next line same indent
   2 hard return followed by next line +1 indent
    3 hard return followed by next line same indent using period
    . 4 hard return followed by next line same indent, no period
    5 hard return followed by next line -1 indent
   6 hard return after hard line break markup, followed by next line same indent<<BR>>
   7<<BR>> 8 next line typed on same line after hard line break markup, same indent
  
   9 next line typed after double Enter (1 blank line), same indent, no starting period
  
   . 10 last line typed after double Enter (1 blank line), same indent, with starting period

  • generates

• 1 hard return followed by next line same indent 2 hard return followed by next line +1 indent
  • 3 hard return followed by next line same indent using period
  • 4 hard return followed by next line same indent, no period 5 hard return followed by next line -1 indent

  6 hard return after hard line break markup, followed by next line same indent
  7
  8 next line typed on same line after hard line break markup, same indent 9 next line typed after double Enter (1 blank line), same indent, no starting period

• 10 last line typed after double Enter (1 blank line), same indent, with starting period

Note: To ensure that the next line is treated as a separate line (not necessarily a separate paragraph!) try the following:

1. use two consecutive hard returns (Enter key)

   • Note: this will leave a larger space between lines (usually a double-space) but it is treated as a new paragraph

2. use a hard line break

3. indent more (farther right)

4. use a period at the beginning of the line after indenting the same amount or less

5. indent less (farther left)

Return to Table of Contents

Lists

Important! Anything that interrupts a list, except a list item indented further right, will potentially end the list! This may affect the indenting, count, or symbols if you try to restart the list below the interruption. This may or may not be able to be overcome, so be careful with adding anything that interrupts a list!

If you have trouble with lists see Some Known Problems and Solutions below.

Unnumbered Lists

See Indenting above.

Bullet Lists

• Markup: Begin a line with a space followed by an asterisk to create a bulleted line of text (space after asterisk is optional but seems to be preferred)

• Example:   * First line of bullet list
  

  • Generates:

  • First line of bullet list
    

Numbered Lists

• Markup: Begin a line with a space followed by the number 1 and a period (or choose another number format such as i or a).

  Note: Each line that should be part of the list begins with the same starting number. The wiki will generate sequential numbers in preview mode or after saving.

  Example:

  •  1. First line of numbered list
     1. Second line of numbered list

  • Generates:

• 1. First line of numbered list
  2. Second line of numbered list

More wiki markup for lists can be found at HelpOnLists

Hyperlinks

Important! Although this wiki automatically creates some hyperlinks, in most cases for the SDL functions, enumerations, and structures it is unable to interpret the text correctly so we have disabled automatic linking via CamelCase recognition using the following markup at the top of every page:

• #pragma camelcase off

Therefore, it is necessary for you to manually create most hyperlinks!

• Note: If a hyperlink is automatically created where you don't want one check to ensure that this #pragma markup is correct at the top of the page. If it is not, please correct or add it. This should resolve the issue if it is related to CamelCase text.

Action:

More wiki markup for tables can be found at HelpOnLinking

Return to Table of Contents

Anchors

Markup: <<Anchor(anchorname)>>

• Place the above markup in the location where you wish to create an anchor, replacing anchorname with a word (or phrase) of your choosing that has meaning in that application. Short but clear names are usually best.

• Anchors will not appear on the saved page or take space on the page but can be referenced in hyperlinks.

Example: <<Anchor(hyperlinks)>> creates an anchor called hyperlinks that could be located at the beginning of a section related to hyperlinks.

Note: In some cases you cannot place anchor markup on the same line as other text, such as headings, without affecting the formatting following the anchor. It is preferable to place the anchor markup on its own line to avoid these conflicts.

Note: It is best to place your anchor on the line above the beginning of the section you are marking with the anchor. This is because the next line after the anchor will be aligned with the top of the viewing window when it is used. If the anchor is below something like a heading the heading will be off screen when the anchor is used. The exception to this is if the anchor is very close to the bottom of the page, in which case it will be moved as close to the top of the screen as possible.

Note: Anchors can be used in tables but must follow any table formatting markup in order to not disturb the table format. Also, the anchor jump point will align with the parsed formatting so put it at the highest point in a row if you wish the whole row to appear on the screen when the anchor is used. See the 2nd and 3rd Ifs of the Function Parameters section of the Function Pages Style Guide for an example. (If the anchor was in the left column it would jump to the top of the vertically centered text when used, leaving half of the content off the top of the screen.)

More (but not much) wiki markup for anchors can be found at HelpOnLinking and HelpOnMacros.

Return to Table of Contents

Tables

Action: To create a basic table with default spacing and styling.

Markup: Two pipes (||) are used to begin and end a table row, with two pipes separating each cell in between.

• Important! There can be no blank spaces or other characters after the closing pipes on a line.

Example:

• ||row 1 column 1||row 1 column 2||row 1 column 3||
  ||row 2 column 1||row 2 column 2||row 2 column 3||

  • Generates:

  row 1 column 1	row 1 column 2	row 1 column 3
  row 2 column1	row 2 column 2	row 2 column 3

Action: To create non-default formatting in tables place any of the following markup within <> at the beginning of the cell, row, column, or table to be formatted.

• All formatting markup can be placed within the same <>, separated by spaces.

• If markup conflicts the last option in the list wins.

Markup 1:

• If you know CSS formatted style markup you can append most any common formatting into the <style="..."> markup to create table formatting. You can also use class markup to some extent.

  • See Help On Tables for details.

Markup 2:

• If you would prefer to use the wiki markup or do not know CSS styles see the table below.

More wiki markup for tables can be found at HelpOnTables

Return to Table of Contents

Section Headings

Markup: Use 1 to 5 equals signs (=) surrounding header text, with a space between markup and text.

• One equals sign is the highest level heading (largest)

• Example: = Title =
  

• Note: In this wiki a level 1 heading is reserved for the title of the page

• Five equals signs is the lowest level heading (smallest)

• Example: ===== Minor =====

Important! Heading lines must stand alone with no other markup on the same line or within the heading.

Example: == Some Wiki Markup Basics ==

Note: All level 2 and lower headings will appear in an automatically generated Table of Contents.

More (but not much) wiki markup for headings can be found at HelpOnHeadlines.

Return to Table of Contents

Table of Contents

Markup: <<TableOfContents()>>

• Place this markup on the page where you want a Table of Contents to appear. There should be no other markup on the same line.

Note: All level 2 and lower headings will be included by default. The numbering scheme is set by a #pragma and, in most cases, should not be changed.

Includes

An include enables you to dynamically copy all or a portion of a page onto another page, allowing changes to one page (source) to be automatically updated on another page (recipient). This is especially useful for listing enumeration values for a function parameter on the function page, for example.

Important! While very few pages have includes, it is important to scan over the source page for existing include markup before creating a new include. More than one set of include markup on a source page will cause conflicts on all pages using that source. See the table below to determine the best course of action.

Important! Includes should be used sparingly in this wiki. It is only appropriate to copy page content using an Include if it is critical that the content remain up to date on the recipient page if the source page changes. In many cases it is better to do a one time copy and paste operation instead.

Note: Please choose the source page carefully. It should reflect the most primary version of the copied information. (For example, you should use the actual enumeration page as the source rather than another function page that also references the enumeration details.)

Markup: To create an Include is a 3 step process:

• Action 1: On the recipient page place the following markup, verbatim, in the location where you wish the copied content to begin.

  • Replace <PageName> with the name of the page to copy from (the source page where the original content is located).

    <<Include(<PageName>, , , from="Start Include here.", to="##End Include here.")>>

  • Example: To copy content from SDL_GLattr

    • <<Include(SDL_GLattr, , , from="Start Include here.", to="##End Include here.")>>

  • Example: See the Remarks section of SDL_GetRevision() or the Return Value section of SDL_MasksToPixelFormatEnum() in the text editor.

  Action 2: On the source page place the following markup, verbatim, on the line immediately before the point where you wish to begin the include (to start copying content).

  • Replace <PageName> with the name of the page to receive the Include (recipient). If this include will be used on more than one page add additional page names. Hyperlink markup and () after functions should be left out.

    ##The following content is included on `<PageName>`.  Any changes between these comments will be reflected there as well.  Please use caution when editing.  Start Include here.

  • Example: If this include will be used on SDL_GL_GetAttribute() and SDL_GL_SetAttribute() the comment on the source page should read:

    • ##The following content is included on SDL_GL_GetAttribute and SDL_GL_SetAttribute. Any changes between these comments will be reflected there as well. Please use caution when editing. Start Include here.

  • Example: See the Remarks section of SDL_REVISION or Pixel Format Values on SDL_PixelFormatEnum in the text editor.

  Action 3: On the source page place the following markup, verbatim, on the line immediately after the point where you want to end the include (to stop copying content).

  • ##End Include here.

  • Example: See the Remarks section of SDL_REVISION or Pixel Format Values on SDL_PixelFormatEnum in the text editor.

Note: Includes are very literal. All content between the two ##comments, beginning with the character immediately following "Start Include here." and ending with the character immediately before "##End...", will be copied onto the recipient page, so be careful that you intend to include all content!

Alternative Markup: For pages needing more than one Include use the following:

• Action A: On the recipient page place the following markup, verbatim, in the location where you wish the copied content to begin.

  • Replace <PageName> with the name of the page to copy from (the source page where the original content is located).

  • Replace X (at the end of the from= parameter) with a number.

    • The second include on a page should use the number 2 for all occurrences of X. Increment the number as necessary if more includes are used on a single source page. (This should not occur often if at all!)

    <<Include(<PageName>, , , from="Start Include here.X", to="##XEnd Include here.")>>

  • Example: To copy a second block of content from SDL_GLattr

    • <<Include(SDL_GLattr, , , from="Start Include here.2", to="##2End Include here.")>>

  Action B: On the source page place the following markup, verbatim, on the line immediately before the point where you wish to begin the additional include (to define the start of a different block of content).

  • Replace <PageName> with the name of the page to receive the Include (recipient). If this include will be used on more than one page add additional page names. Hyperlink markup should be left out.

  • Replace X (at the end) with a number.

    • The second include on a page should use the number 2 for all occurrences of X. Increment the number as necessary if more includes are used on a single source page. (This should not occur often if at all!)

    ##The following content is included on `<PageName>`.  Any changes between these comments will be reflected there as well.  Please use caution when editing.  Start Include here.X

  • Example: If this is the 2nd include on the source page and will be used on SDL_GL_GetAttribute() and SDL_GL_SetAttribute() recipient pages the comment on the source page should read:

    • ##The following content is included on SDL_GL_GetAttribute and SDL_GL_SetAttribute. Any changes between these comments will be reflected there as well. Please use caution when editing. Start Include here.2

  Action C: On the source page place the following markup, verbatim, on the line immediately after the point where you want to end the include (to stop copying content).

  • Replace X (at the beginning) with a number.

    • The second include on a page should use the number 2 for all occurrences of X. Increment the number as necessary if more includes are used on a single source page. (This should not occur often if at all!)

    ##XEnd Include here.

  • Example: If this is the 2nd include on the source page it should read:

    • ##2End Include here.

Important! Please send Feedback or email us at <ANTI SPAM wiki AT libsdl DOT org> with the names of the source and recipient page(s) so we can keep track of where the includes in the wiki are.

• Note: The use of hidden comments to create include tags is deliberate. This include markup has been carefully crafted to not only be reliable if used correctly (per these instructions), but also to enhance traceability for maintenance purposes and to make it easier for others to edit without causing problems on pages without realizing it. If you are going to create an include, please follow these guidelines precisely and write to us if you have any trouble. We'd greatly appreciate it.

See HelpOnMacros/Include for details if a different include becomes necessary.

Return to Table of Contents

Some Known Problems and Solutions

While creating this wiki we encountered several formatting challenges. This section reflects some of the solutions that we discovered in the process. Hopefully you will find them helpful if you encounter these same difficulties. Please note that updates to the wiki or various add-ons may change these at any time.

Important! Some list breaks cannot currently be fixed without major formatting compromises so you should be very careful when interrupting a list as it may force formatting you will not want.

See Mixed Lists for some discussion and examples of problems.
Note: The contents at this link may change at any time and this link may not always be up to date.

Return to Table of Contents

---

Miscellaneous Notes

Other Help

Some other wiki help that might be of interest or helpful to find quickly:

• Help Index

• Help On Moin Wiki Syntax

• Help On Formatting

• Help On Editing

• Help On Smileys

• Help On Admonitions

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