Wiki Page Content

Revision 23 as of 2011-02-12 01:04:33

Clear message

DRAFT

Style Guide: Wiki Basics

Contents

  1. Style Guide: Wiki Basics
    1. Getting Started
      1. Opening An Editor
      2. Saving Your Changes
    2. Some Markup Basics
      1. Spacing
        1. Indenting
        2. Hard Line Break
      2. Text Formatting
        1. Bold
        2. Italics
        3. Monospace
        4. Code
        5. Colored Text
      3. Hyperlinks
        1. Anchors
      4. Lists
      5. Tables
      6. Headers
      7. Includes
    3. Miscellaneous Notes
      1. Style Guide Terminology
      2. Other Help
    4. Resources
    5. Disclaimer

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

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

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

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]

{i} Especially when using the text editor, use the blue

function in the left sidebar 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.

When you have finished adding your content and filling in the Comment field, and are satisfied with the formatting, use the blue

function in the left sidebar to save your changes.

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.

Return to Table of Contents

Some Markup Basics

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

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.

Spacing

Indenting

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

Hard Line Break

  • <<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 that you cannot change indent level immediately following a hard line break. (Seems like a hard break forces the next line into 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

      {i} A hard return (Enter key) is often not recognized as a line break.
      {i} 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

      • 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

    • To ensure that the next line is treated as a separate line (paragraph)

      1. use two consecutive hard returns (Enter key)

        • Note that this will leave a larger space between lines (usually a double-space)

      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

      5. indent less (farther left)

Return to Table of Contents

Text Formatting

{i} 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.

Bold

  • Bold

    • Place three apostrophes surrounding text to be bolded, without a space between markup and text.

      Example: '''bold text''' generates bold text

Italics

  • Italics

    • Place two apostrophes surrounding text to be italicized, without a space between markup and text.

      Example: ''italics text'' generates italics text

Monospace

  • Monospace

    • Place a backtick on either side of the text, without a space between markup and text. (Note: This may resemble inline code (see below) in many cases, but will not behave the same.)

      Example: `monospace text` generates monospace text

Code

  • Code (or Verbatim Text)

    • Use three curly brackets surrounding text to be rendered as code.
      • Place the brackets inline with the text to display the code formatting inline.

        Example: 

        {{{Verbatim text as it should be typed, or appear as code or with markup. If it is too long for the line it will not wrap.}}}

        • generates

        Verbatim text as it should be typed, or appear as code or with markup. If it is too long for the line it will not wrap.

      • Place the brackets above and below the text to display the code formatting inside a box.

        Example: 

        {{{
Verbatim text as it should be typed, or appear as code or with markup. This will word wrap if it is too long for one line.
}}}

        • generates 

        Verbatim text as it should be typed, or appear as code or with markup. This will word wrap if it is too long for one line.

Colored Text

  • red

    orange

    yellow

    green

    blue

    indigo

    violet

    brown

    pink

    grey

    purple

    • We have the Color2 macro installed. It will colorize text outside of tables using the following syntax:

      • <<Color2(colorname,text to be colorized)>>

      • colorname may be most any simple color name like blue or red or green

      • If text to be colorized must contain commas each section must be colorized separately. Place the comma at the end of each string and the space after between colorized sections to accomplish this.

        • Example:

          • Correct 

            <<Color2(purple,A sentence that contains commas,)>> <<Color2(purple,such as this one,)>> <<Color2(purple,must be broken into parts or the text before the first comma will not appear when parsed.)>>

            • generates

          • purple

            purple

            purple

          • Incorrect (note that the beginning of the sentence is missing) 

            <<Color2(purple,A sentence that contains commas, such as this one, must be broken into parts or the text before the first comma will not appear when parsed.)>>

            • generates

          • purple

      The Color2 macro will work within a table also! However, there are other options for colorizing text (and backgrounds) in tables. See Tables below for more info.

      <!> Please use colored text sparingly if at all. As a general convention we use blue to represent links (whether they actually behave as links or not), so please reserve that color for such purposes.

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

Return to Table of Contents

  • 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 it is important that you manually hyperlink these.

    • A hyperlink to another page (especially within the wiki) is created, in most cases, by enclosing the text to be linked in double brackets:
      [[linktarget]]

    • Example: Typing SDL_VideoInit will produce SDL_VideoInit, an incomplete hyperlink, because only the CamelCase portion of the name is automatically recognized by the wiki as a hyperlink. You will need to type [[SDL_VideoInit]] to include the SDL_ in the link (SDL_VideoInit).

    • If a hyperlink is automatically created where you don't want one, adding 2 backticks (``) to interrupt the linked phrase or an exclamation mark (!) at the beginning of the incorrect link will usually remove the automatic link without appearing in the displayed text.

    • Example: If typed verbatim, the data field BitsPerPixel is automatically linked, as shown here (BitsPerPixel). This is pointless because individual data fields will not have their own pages, making this a useless, dead link. Typing Bits``Per``Pixel or !BitsPerPixel will prevent it from becoming a link, as shown here (BitsPerPixel).

    • A hyperlink to an anchor (or any unique text on a page) is created, in most cases, by

      • [[#anchorname|description]]
        where anchorname is a previously created anchor or a unique bit of text on the page (but not a header) and description is the text that will actually appear as the link.

      Example: [[#hyperlinks|how to hyperlink]] creates how to hyperlink (try clicking the link to see it in action)

    • A hyperlink to an outside web or email address may be created by simply typing or pasting in the address.
      • To create a link with link text other than the address itself, enclose the address followed by a pipe and the alternate link text in double brackets.

        Example: [[link address|alternate text]] produces alternate text

    • Any link referencing the header files should replace the version number (12-digit alpha-numeric code) with tip in the address if the link should be to the most current version rather than to a specific version of the header file.

    More wiki markup for tables can be found at HelpOnLinking

Return to Table of Contents

Anchors

  • <<Anchor(anchorname)>>

    • Place the above markup in the location where you wish to create an anchor, replacing anchorname with a word (or phrase) that has meaning in that application.

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

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

Return to Table of Contents

Lists

  • Bullet Lists
    • 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
    • Begin a line with a space followed by the number 1 and a period (or the beginning of 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:

    • First line of numbered list
    • Second line of numbered list

    More wiki markup for lists can be found at HelpOnLists

{i} If a list is interrupted by another item (like a box of code) with less indent (farther left) than the previous line of the list, it may interfere with the correct parsing of the next line of the list after the interruption. (It seems to default to a first level indent after an interruption.)

  • One possible workaround is to place a blank line containing a space period space ( . ) between the interfering content and the next line. (See below for an example. In edit mode look for <<Anchor(example)>>.) This seems to allow the wiki parser to interpret the indent count correctly on the next line and effectively continue the list.

    • It may be necessary to indent to one level less (farther left) than the line that is not being parsed correctly. For example, if you need a line following an interruption to be at 3 indents, put the space-period-space immediately above it at 2 indents (ie: space space period space;  . ).

    • A numbered list may require that the correct start number be manually entered, however this may not always work. See HelpOnLists for details on forcing a start number/letter.

  • For more information about this 'bug' and another possible workaround see BlockElementsInListBreakIndent.

{i} A related issue is trying to use a mixed list where bullets follow numbers on the same indent level. This will likely parse as the next consecutive number regardless of your use of an asterisk to indicate the use of a bullet. The same workaround seems to resolve this issue as well.

Return to Table of Contents

Tables

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

    • It is important that there are 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
    To add color within a table use the following markup:

    • <style="color: #FF0000;">

      set text color

      <bgcolor="#XXXXXX">

      set cell background color

      <rowbgcolor="#XXXXXX">

      set row background color (only valid in first cell)

      <tablebgcolor="#XXXXXX">

      set table background color

    More wiki markup for tables can be found at HelpOnTables

Return to Table of Contents

Headers

  • Use one to five equals signs (=) surrounding header text, with a space between markup and text.
    • One equals sign is the highest level header (largest)

    • Example: = Title =

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

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

    Example: === Some Wiki Markup Basics ===
    Headers will appear in an automatically generated Table of Contents.

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

Return to Table of Contents

Includes

  • An include enables you to copy all or a portion of a page onto another page, allowing changes to one page to be automatically updated on another. This is especially useful for listing enumeration values for a function parameter on the function page, for example.
    To create an Include place the following markup in the location where you wish the data to begin on the recipient page.

    • For copying values from an enumeration:

      <<Include(SDL_Enumeration, , , from="== Values ==", to="== Code Examples ==")>>

      • where SDL_Enumeration is replaced by the Enumeration's name.

      For copying data fields from a structure:

      <<Include(SDL_Structure, , , from="== Data Fields ==", to="== Code Examples ==")>>

      • where SDL_Structure is replaced by the Structure's name.

      The basic format is 

      <<Include(pagename, heading, level, from="regex", to="regex", sort=ascending|descending, items=n, skipitems=n, titlesonly, editlink)>>

      {i} The from= and to= start markers are very literal! They will include everything following the end of the start marker and up to but not including the beginning of the end marker. (This is why the header markup is included in the above statements.) When creating an Include statement choose from= and to= parameters carefully.

Return to Table of Contents

Miscellaneous Notes

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.

  • If...

    • Found at the beginning of detailed style guide sections, this indicates options for you to choose from. Select the one(s) that best suit 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.

    • Action is almost always followed by Markup and may also be followed by Note, red

      , and/or Example (see below).

    • /!\ Please read any Note or red

      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.

  • Markup:

    • The instructions immediately following Markup: indicate the critical markup that would be used in the text editor to complete the Action above it.

  • Note:

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

  • red

    • Similar to a Note, but indicates that the noted information should be heeded by all contributors.

  • Example:

    • Points to a place in the wiki where the related Action and Markup can be observed.



Other Help

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

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.

  1. Post a question to the Mailing List

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

All content modifications are subject to review for consistency and quality. We reserve the right to remove or modify any content added to this wiki at any time. You may direct questions or concerns to <ANTI SPAM wiki AT libsdl DOT org>.

(Page Info.)
Feedback
Please include your contact information if you'd like to receive a reply.
Submit