Documentation de Gambas - /doc/markdown

/doc/markdown

# Gambas Markdown Syntax

- Paragraphs

- Headers

  - Indexed headers

- Blockquotes

- Lists

- Code blocks

- Horizontal rules

- Links

  - Inline links

  - Reference links

- Emphasis

- Underlining

- Code

- Automatic Escaping for Special Characters

- Backslash Escapes

- Inline HTML

- Tables

- Special commands

  - `@{index}`

  - `@{index <prefix>}`

The Gambas Markdown Syntax is a customized version of the Markdown syntax. It allows to write most of HTML without having to use all these HTML markups.

Here is a quick documentation of the syntax:

## Paragraphs

A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. Normal paragraphs should not be indented with spaces or tabs, except in the context of lists.

If a line ends with a slash `\` character, then a line break (`<br>`) is inserted.

### Example

    This is a simple paragraph.

    This is another paragraph, that is
    written on two lines.

    This is a paragraph that is written on two lines,\
    but with a line-break after the word `lines`

will print:

This is a simple paragraph.

This is another paragraph, that is written on two lines.

This is a paragraph that is written on two lines,
but with a line-break after the word `lines`

## Headers

You can write first-level headers by underlining the header text that way:

    This is an H1
    =============

Any number of underlining `=` will work.

The other syntax is prefixing the header text with `#`:

    # This is an H1

    ## This is an H2

    ###### This is an H6

Optionally, you may close the headers. This is purely cosmetic - you can use this if you think it looks better.

    # This is an H1 #

    ## This is an H2 ##

    ###### This is an H6 ######

### Example

    This is an H1
    =============

    ## This is an H2

    ### This is an H3 ###

will print:

# This is an H1

## This is an H2

### This is an H3

### Indexed headers

Indexed headers are headers that will be visible in the index generated by the `@{index}` special command (see below).

To make an indexed header, just write the header title between `[` and `]` characters.

For example:

    ## This header will not be indexed

    ## [But this header will!]

## Blockquotes

The syntax uses email-style `>` characters for blockquoting. If you’re familiar with quoting passages of text in an email message, then you know how to create a blockquote.

    > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
    > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
    > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
    >
    > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
    > id sem consectetuer libero luctus adipiscing.

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of `>`:

    > This is the first level of quoting.
    >
    > > This is nested blockquote.
    >
    > Back to the first level.

Blockquotes can contain other elements, including headers, lists, and code blocks:

    > ## This is a header.
    >
    > 1.   This is the first list item.
    > 2.   This is the second list item.
    >
    > Here's some example code:
    >
    >     return shell_exec("echo $input | $script");

You can put blockquotes into lists too.

## Lists

Unordered lists use asterisks, and hyphens - interchangeably - as list markers:

    * Red
    * Green
    * Blue

is equivalent to:

    - Red
    - Green
    - Blue

Ordered list items use the plus character `+` as list markers:

    + One
    + Two
    + Three

List markers typically start at the left margin, but may be indented by any number of spaces.

    *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
        Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
        viverra nec, fringilla in, laoreet vitae, risus.
    *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
        Suspendisse id sem consectetuer libero luctus adipiscing.

If a list item follows a blank line, then the item will be wrapped in `<p>` tags. For example, this input:

    * Bird
    * Magic

will turn into:

- Bird

- Magic

But this:

    * Bird

    * Magic

will turn into:

- Bird

- Magic

List items may consist of multiple paragraphs.

    * This is a list item with two paragraphs. Lorem ipsum dolor
      sit amet, consectetuer adipiscing elit. Aliquam hendrerit
      mi posuere lectus.

      Vestibulum enim wisi, viverra nec, fringilla in, laoreet
      vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
      sit amet velit.

    * Suspendisse id sem consectetuer libero luctus adipiscing.

To put a blockquote within a list item, the blockquote’s `>` delimiters need to be indented:

    * A list item with a blockquote:
      > This is a blockquote
      > inside a list item.

Which gives:

- A list item with a blockquote:

  > This is a blockquote

  > inside a list item.

To put a code block within a list item, the code block indentation must be added to the list indentation:

    *   A list item with a code block:

            <code goes here>

## Code blocks

Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Code blocks are wrapped in both `<pre>` and `<code>` tags.

To produce a code block, simply indent every line of the block by at least 4 spaces or 1 tab. For example, given this input:

    This is a normal paragraph:

        This is a code block.

The following will be generated:

This is a normal paragraph:

    This is a code block.

A code block continues until it reaches a line that is not indented (or the end of the article).

Within a code block, ampersands (`&`) and angle brackets (`<` and `>`) are automatically converted into HTML entities. This makes it very easy to include example HTML source code - just paste it and indent it.

For example, this:

        <div class="footer">
            &copy; 2004 Foo Corporation
        </div>

will turn into:

    <div class="footer">
        &copy; 2004 Foo Corporation
    </div>

The markup syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block.

## Horizontal rules

You can produce a horizontal rule tag (`<hr/>`) by placing three or more hyphens, or asterisks on a line by themselves.

Each of the following lines will produce a horizontal rule:

    ***

    *****

    ---

    ---------------------------------------

## Links

Two style of links are supported: inline and reference.

In both styles, the link text is delimited by square brackets.

### Inline links

To create an inline link, use a set of regular parentheses immediately after the link text’s closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes. For example:

    This is [an example](http://example.com/ "Title") inline link.

    [This link](http://example.net/) has no title attribute.

Will produce:

    <p>This is <a href="http://example.com/" title="Title">
    an example</a> inline link.</p>

    <p><a href="http://example.net/">This link</a> has no
    title attribute.</p>

Note that a "void link" (i.e. `[]`) will not be interpreted and the two brackets will be emitted as is.

If the link between braces is not specified, then it is assumed to be the same as the link title between brackets:

    [http://gambas.sourceforge.net]

Will produce:

    <a href="http://gambas.sourceforge.net target="_blank">gambas.sourceforge.net</a>

Note that external links are automatically opened in a new window.

### Reference links

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:

    This is [an example][id] reference-style link.

Then, anywhere in the document, you define your link label like this, on a line by itself:

That is:

- Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);

- followed by a colon;

- followed by one or more spaces (or tabs);

- followed by the URL for the link;

- optionally followed by a title attribute for the link, enclosed in double quotes.

Link definitions are stripped from your document in the HTML output.

Link definition names may consist of letters, numbers, spaces, and punctuation - but they are not case sensitive. E.g. these two links:

    [link text][a]
    [link text][A]

are equivalent.

The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets - e.g., to link the word “Google” to the google.com web site, you could simply write:

    [Google][]

And then define the link:

Because link names may contain spaces, this shortcut even works for multiple words in the link text:

    Visit [Daring Fireball][] for more information.

And then define the link:

Link definitions can be placed anywhere in your document.

Here’s an example of reference links in action:

    I get 10 times more traffic from [Google] [1] than from
    [Yahoo] [2] or [MSN] [3].

Using the implicit link name shortcut, you could instead write:

    I get 10 times more traffic from [Google][] than from
    [Yahoo][] or [MSN][].

Both of the above examples will produce the following HTML output:

    <p>I get 10 times more traffic from <a href="http://google.com/"
    title="Google">Google</a> than from
    <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
    or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>

For comparison, here is the same paragraph written using inline link style:

    I get 10 times more traffic from [Google](http://google.com/ "Google")
    than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
    [MSN](http://search.msn.com/ "MSN Search").

## Emphasis

Emphasis is indicated by asterisks (`*`). Text wrapped with one `*` will be wrapped with an HTML `<em>` tag; double `*`s will be wrapped with an HTML `<strong>` tag. E.g., this input:

    *single asterisks*
    **double asterisks**

will produce:

    <em>single asterisks</em>
    <strong>double asterisks</strong>

Emphasis cannot be used in the middle of a word, nor alone in a word.

    un*frigging*believable

It will be treated as a literal asterisk.

To produce a literal asterisk at a position where it would otherwise be used as an emphasis delimiter, you must escape it with a backslash (see below).

## Underlining

Underlining is indicated by the tilde character (`~`). Text wrapped with `~` will be wrapped with an HTML `<u>` tag. E.g., this input:

    ~underlined~

will produce:

    <u>underlined</u>

Underlining cannot be used in the middle of a word, nor alone in a word.

    un~flaming~believable

It will be treated as a literal tilde.

To produce a literal tilde at a position where it would otherwise be used as an underlining delimiter, you must escape it with a backslash (see below).

## Code

To indicate a span of code, wrap it with single quotes (`'`) or backtick quotes (```).

Unlike a pre-formatted code block, a code span indicates code within a normal paragraph. For example:

    Use the `printf()` function.

will produce:

    <p>Use the <code>printf()</code> function.</p>

With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to include example HTML tags. This:

    Please don't use any `<blink>` tags.

will be turned into:

    <p>Please don't use any <code><blink></code> tags.</p>

You can write this:

    `&#8212;` is the decimal-encoded equivalent of `&mdash;`.

to produce:

    <p><code>&amp;#8212;</code> is the decimal-encoded
    equivalent of <code>&amp;mdash;</code>.</p>

The difference between the backquote and the single quote is that HTML tags and HTML entities are interpreted between single quotes, whereas they are automatically escaped between backquotes.

    `<b>Not Bold</b>` '<b>Bold</b>'

Gives you:

`<b>Not Bold</b>` `Bold`

## Automatic Escaping for Special Characters

In HTML, there are two characters that demand special treatment: `<` and `&`.

Left angle brackets are used to start tags; ampersands are used to denote HTML entities. If you want to use them as literal characters, you must escape them as entities, e.g. `&lt;`, and `&amp;`.

You even need to escape ampersands within URLs.

The markup syntax allows you to use these characters naturally, taking care of all the necessary escaping for you. If you use an ampersand as part of an HTML entity, it remains unchanged; otherwise it will be translated into `&amp;`.

So, if you want to include a copyright symbol in your article, you can write:

    &copy;

and it will be left alone. But if you write:

    AT&T

it will be translated to:

    AT&amp;T

## Backslash Escapes

Any special character can be escaped with a backslash `\` to be interpreted literally and prevent them to be interpreted.

    \*This text is surrounded by literal asterisks.\*

Gives you:

*This text is surrounded by literal asterisks.*

## Inline HTML

Finally, you can write any HTML code anywhere. HTML markup are automatically detected.

    This is a regular paragraph.

    <table>
        <tr>
            <td>Foo</td>
        </tr>
    </table>

    This is another regular paragraph.

Beware that the markup syntax is interpreted between HTML tags.

## Tables

Table can be created by using the following syntax:

    [[
    Header 1
    --
    Header 2
    ...
    ==
    Row 1, Cell 1
    --
    Row 1, Cell 2
    ...
    ==
    Row 2, Cell 1
    --
    Row 2, Cell 2
    ...
    ]]

Which gives you:

Header 1 | Header 2 ...
--- | ---
Row 1, Cell 1 | Row 1, Cell 2 ...
Row 2, Cell 1 | Row 2, Cell 2 ...
Row 3, Cell 1 | Row 3, Cell 2 ...

The header is optional:

    [[
    ==
    a
    --
    b
    ==
    c
    --
    d
    ]]

Gives you:

a | b
c | d

If a table has only one cell, then a simple `<div>` markup will be used instead of a `<table>`.

Note that the css class of the table can be inserted just after the initial `[[`.

## Special commands

Special commands generate some dynamic part of the page.

The syntax of a special command is:

    @{command}

where `command` is the name of the command.

A command can take arguments: they follow the command name and are separated by space characters.

    @{command arg1 arg2}

A command is always put at the beginning of a line.

At the moment only one command is implemented, `@{index}`:

### `@{index}`

Insert an index of all indexed headers.

### `@{index <prefix>}`

Insert an alphabetic index of all pages whose path begins with `<prefix>`.