Wiki Page Content

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.

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

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

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

Style

Details

Bold

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

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

Italics

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

Example: ''italics text'' generates italics text

Monospace

Markup: 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 usually behave the same. It may, however, interfere with word wrapping, especially in tables. It may be necessary to break up a long monospace string using extra markup to allow proper word wrapping.

Example: `monospace text` generates monospace text

Code (or Verbatim Text)

Markup: Use three curly brackets surrounding text to be rendered as code.

Markup 1: Place the brackets inline with the text to display the code formatting inline.

See Example 1 below the table.

Markup 2: Place the brackets above and below the text to display the code formatting inside a box.

See Example 2 below the table.

Note: Add #!highlight cpp immediately following the opening braces on the first line to automatically colorize as cpp code.

Example: see SDL_Event

C

o

l

o

r

e

d

T

e

x

t

(Color2 macro)

Important!

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.

Note: We have the Color2 macro installed. It will colorize text inside or outside of tables.

Markup:<<Color2(text to be colorized,colorname)>> where colorname may be most any simple color name like blue or red or green

Note: If text to be colorized must contain commas each section must be colorized separately, breaking at each comma.

See Example 3 below table.

Note: There are other options for colorizing text (and backgrounds) within tables. See Tables below for more info.

  • 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

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:

If you reference something that has a page in the wiki

Action: With extremely rare exception, always create a hyperlink to any existing API page. It is preferable to create a link to any page in the wiki that is referenced whether an API page or not.

Note: Include () after a function name, outside the link, except in the Related Functions section of a page. Do not use parens for structures or enumerations.

See the next table for how to create different links.

If you reference something that does not have a page in the wiki

Action: Do not create hyperlinks to pages that do not already exist unless you are 100% sure the page will exist very soon after creating the link.

Hint: If you are unsure whether a page exists check the API By Name page or try typing it into the browser.

If you reference an outside page or email address

Action: In most cases the wiki will automatically create the link for you.

Note: See the next table for options.

Type of link

How to create it

Link to another page within the wiki

Markup: Enclose the page name in double brackets:
[[pagename]]

Note: It is not necessary to include the wiki address http://wiki.libsdl.org/moin.cgi/ for intra-wiki pages.

Example: [[SDL_VideoInit]]() generates SDL_VideoInit()

Link to an outside page or email address

Markup: Type or paste in the address. The wiki should auto-recognize and link these standard forms.

Link with alternate link text

Markup: Enclose the standard address (as above) followed by a pipe and the alternate link text in double brackets to create linked text that is different from the actual address.

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

Note: Alternate link text is generally optional but preferred in most cases other than API page links to make the link cleaner, shorter, and/or to make it more desirable grammatically than the actual address.

Link referencing the header files

Important!

Replace the version number (12-digit alpha-numeric code) with default in the address if the link should be to the most current version rather than to a specific version of the header file.

Example: http://hg.libsdl.org/SDL/file/ef1db08c40ac/include/SDL_atomic.h should be changed to http://hg.libsdl.org/SDL/file/default/include/SDL_atomic.h so the link always points to the most current file.

Link to an anchor (or most any unique text) on the same page

Markup: [[#anchorname|link text]] where anchorname is a previously created anchor or a unique bit of text on the page (but not a header) and link text 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)

Note: In the case of anchors it is important to use the alternate text, even if it is identical to the anchor name, to make the link look nice. Without it the # appears in the link.

Link to an anchor on another page

Markup: Insert the page address before the # in the address section of an anchor link.
[[address#anchor|optional alternate text]]

Example: [[Contributing#guides|Style Guides]] creates the following link with alternate text and that takes you to that anchor on the other page:
Style Guides

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.

Markup 2:

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

Colors

To colorize text in a cell

Markup 1: use C

o

l

o

r

e

d

T

e

x

t

described above

Markup 2: style="color: #XXXXXX;"
where XXXXXX is a hexadecimal color code

Example: this cells began with <style="color:#339933;">

Note: Markup 2 can only be used to colorize all of the text within a cell. See Markup 1 to colorize only some text in a cell.

To set cell background color

Markup: bgcolor="#XXXXXX"
where XXXXXX is a hexadecimal color code

To set row background color

Markup: rowbgcolor="#XXXXXX"
where XXXXXX is a hexadecimal color code

Note: This is only valid in the first cell of a row

To set table background color

Markup: tablebgcolor="#XXXXXX"
where XXXXXX is a hexadecimal color code

Note: This is valid in the first cell of the table

Alignment

To control horizontal text alignment

Markup:
left = (
centered = :
right = )

Example: The first column in this table uses (

To control vertical text alignment

Markup:
top = ^
bottom = v

Note: middle is the default so there is no markup for it.

Sizes

To control table width

Markup: tablewidth="x%" where 0 < x < 100

Note: This is only valid in the first cell of the table.

To control column width

Markup: In the column you wish to control, use x% or width="x%" where 0 < x < 100.

Note: The remaining columns will auto-balance using the remaining percentage of table width and the size of the cell contents. (It may be the case that setting the column width in one cell will affect the whole table. I have not tested this extensively.)

Example: This table uses 30% in the first column

Spanning

To cause a cell to span multiple rows

Markup: |x where x is the number of rows to span including the first

Note: When creating the table, the cell(s) in the first row to span should be included on the same line as the spanning cell as usual. Each additional row should be on it's own table line, omitting the spanning cell.

Example: Go into Edit (Text)

mode and look at most any of the tables in this document.

To cause a cell to span multiple columns

Markup 1: Create empty cells at the beginning of the row equaling the number of cells to skip/span, then place your text in the last cell of that row.

Example: ||||||cell spanning 3 columns||; grey "Sizes" cell in this table

Note: Total number of columns should equal that of the table.

Note: Centers text in the spanning row by default.

Markup 2: Use -x where x is the number of columns to span including the first

Example: ||<-3>text spanning 3 columns||; grey "Spanning" cell in this table

Note: Left justifies text in the spanning row by default.

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

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!

If a source page does not already have an include on it

Action 1: Follow the instructions above to create a new include.

If a source page has an existing Include that already contains the content that you need to include on another page

Action: Use Action 1 above, add the name of the new recipient page to the existing markup on the source page (see Action 2 above), and skip Action 3.

If a source page has an existing Include that does not contain the content that you need to include on another page

Action: See Alternative Markup: Action A-C below.

Note: It is exceedingly rare to need more than one include on a page and should be avoided if at all possible.

If you want to create an include using more than one continuous section on the source page (copying separate blocks)

Action: See Alternative Markup: Action A-C below.

Note: It is exceedingly rare to need more than one include on a page and should be avoided if at all possible.

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.

Problem Category: Vertical spacing isn't working properly

Problem: My text is on another line in the editor but grouped with the previous line in the preview/saved version

Cause: Using a hard return (Enter key) at the end of a line is often not parsed as a line break.

Solution 1: Press the Enter key twice to put a space between paragraphs

Solution 2: Use a Hard Line Break.

Problem: There is too much/little space between lines of text

Cause: Most of the vertical spacing in this wiki is fixed and is determined based on other formatting choices.

Solution: You can force additional space between lines of text using Hard Line Breaks.

Note: You cannot force less space between lines of text in separate paragraphs. The only option for keeping lines of text close together is to use Hard Line Breaks to keep lines within a paragraph.

Important!

There are limits to how you can change formatting within a paragraph.

Note: Indenting can affect vertical spacing. See Note above for details.

Problem Category: My list isn't working properly

Problem: The numbering in my list started over

Cause: Most likely your numbering restarted because something broke the list into two parts.

Solution 1: Remove the interfering item or change it's indent to be subordinate in the list (add more spaces to indent more).

Note: This is the most successful solution.

Solution 2: Try forcing a new starting number/letter.

Markup: place #value, where # is the hash symbol and value is a number (like 2, 3, 4...; not the character you want), immediately after the starting numbering markup.

Example:  1.#4 text should force the list item to begin with the number 4.
a.#4 text should force the list item to begin with the letter d.

Important!

This fix does not always work!!!

Solution 3: Put a blank line (Enter key) between list items and then force a number (or other sequential) value by using the Markup from Solution 2 above.

Example: See the Basic Format section of SGTutorials then go into edit mode to see the markup.

Problem: The indenting of my next list item is wrong

Cause: The list is interrupted by another item (like a box of code) with less indent (farther left) than the previous line of the list

Result: The interfering block forces the end of a list so the list begun after it is treated as a new list. It also seems to default to a first level indent after an interruption of this type regardless of the number of spaces you actually put before your next line.

Solution: One possible workaround is to place a blank line containing a space(s) period space ( . ) between the interfering content and the next line.
Note: This seems to allow the wiki parser to interpret the indent count on the next line correctly but likely won't continue the list. It does not always work!

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

Problem: I want to use a mixed list where bullets follow numbers on the same indent level (or similar) but it just keeps numbering

Cause: This wiki seems to parse lists based on how they start and where they end. If they are not broken/ended it seems to ignore the actual intervening markup (except usually lines starting with a period).

Solution: The same workarounds as above may or may not be able to resolve this issue as well. Your goal is to end one list and begin the next with new formatting. You may have to try several tricks to make this happen.

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:

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

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

None: SGWikiBasics (last edited 2014-06-25 09:54:01 by Sam Lantinga)

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