--- data/markup.DocBook.orig 2001-09-09 01:46:40 UTC +++ data/markup.DocBook @@ -1,347 +1,411 @@ -
-

# Markdown

+# Markdown + +The usual way to write pages for this wiki is [pandoc]'s extended form +of [markdown]. You can start using markdown and later switch to +DocBook by using `pandoc` to convert your markdown page to DocBook for +more sophisticated formatting. To do so use the wiki's export option +(if enabled) or `pandoc -f markdown -t docbook -o page.xml page.md`. +Further down on this page there is some information about the DocBook +format. Here we continue with an introduction to markdown. +If you're not familiar with markdown, you should start by looking +at the [markdown "basics" page] and the [markdown syntax description]. +Consult the [pandoc User's Guide] for information about pandoc's syntax +for footnotes, tables, description lists, and other elements not present +in standard markdown. + +[pandoc]: http://pandoc.org +[pandoc User's Guide]: http://pandoc.org/README.html +[markdown]: http://daringfireball.net/projects/markdown +[markdown "basics" page]: http://daringfireball.net/projects/markdown/basics +[markdown syntax description]: http://daringfireball.net/projects/markdown/syntax + +Markdown is pretty intuitive, since it is based on email conventions. +Here are some examples to get you started: + ++--------------------------------------------------------+------------------------------------------------------------+ +| Markdown code | Result | ++========================================================+============================================================+ +| `*emphasized text*` | *emphasized text* | ++--------------------------------------------------------+------------------------------------------------------------+ +| `**strong emphasis**` | **strong emphasis** | ++--------------------------------------------------------+------------------------------------------------------------+ +| `` `literal text` `` | `literal text` | ++--------------------------------------------------------+------------------------------------------------------------+ +| `\*escaped special characters\*` | \*escaped special characters\* | ++--------------------------------------------------------+------------------------------------------------------------+ +| `[external link](http://google.com)` | [external link](http://google.com) | ++--------------------------------------------------------+------------------------------------------------------------+ +| `![folder](/img/icons/folder.png)` | ![folder](/img/icons/folder.png) | ++--------------------------------------------------------+------------------------------------------------------------+ +| Wikilink: `[Front Page]()` | Wikilink: [Front Page]() | ++--------------------------------------------------------+------------------------------------------------------------+ +| `H~2~O` | H~2~O | ++--------------------------------------------------------+------------------------------------------------------------+ +| `10^100^` | 10^100^ | ++--------------------------------------------------------+------------------------------------------------------------+ +| `~~strikeout~~` | ~~strikeout~~ | ++--------------------------------------------------------+------------------------------------------------------------+ +| `$x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}$` | $x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}$[^1] | +| | | +| | [^1]: If this looks like code, it\'s because MathJax is | +| | not installed on your system. Contact your administrator | +| | to request it. | ++--------------------------------------------------------+------------------------------------------------------------+ +| `A simple footnote.^[Or is it so simple?]` | A simple footnote.^[Or is it so simple?] | ++--------------------------------------------------------+------------------------------------------------------------+ +| \> an indented paragraph\ \ | > an indented paragraph, usually used for quotations | +| \> usually used for quotations | | ++--------------------------------------------------------+------------------------------------------------------------+ +| #!/bin/sh -e | #!/bin/sh -e | +| # code, indented four spaces | # code, indented four spaces | +| echo "Hello world" | echo "Hello world" | ++--------------------------------------------------------+------------------------------------------------------------+ +| * a bulleted list | - a bulleted list | +| * second item | - second item | +| - sublist | - sublist | +| - and more | - and more | +| * back to main list | - back to main list | +| 1. this item has an ordered | 1. this item has an ordered | +| 2. sublist | 2. sublist | +| a) you can also use letters | a. you can also use letters | +| b) another item | b. another item | ++--------------------------------------------------------+------------------------------------------------------------+ +| Fruit Quantity | Fruit Quantity | +| ------- --------- | ------- ---------- | +| apples 30,200 | apples 30,200 | +| oranges 1,998 | oranges 1,998 | +| pears 42 | pears 42 | +| | | +| Table: Our fruit inventory | : Our fruit inventory | ++--------------------------------------------------------+------------------------------------------------------------+ + +## Headings + +For headings, prefix a line with one or more `#` signs: one for a major heading, +two for a subheading, three for a subsubheading. Be sure to leave space before +and after the heading. + + # Markdown + + Text... + + ## Some examples... + + Text... + +## Wiki links + +Links to other wiki pages are formed this way: `[Page Name]()`. +(Gitit converts markdown links with empty targets into wikilinks.) + +To link to a wiki page using something else as the link text: +`[something else](Page Name)`. + +Note that page names may contain spaces and some special characters. +They need not be CamelCase. CamelCase words are *not* automatically +converted to wiki links. + +Wiki pages may be organized into directories. So, if you have +several pages on wine, you may wish to organize them like so: + + Wine/Pinot Noir + Wine/Burgundy + Wine/Cabernet Sauvignon + +Note that a wiki link `[Burgundy]()` that occurs inside the `Wine` +directory will link to `Wine/Burgundy`, and not to `Burgundy`. +To link to a top-level page called `Burgundy`, you'd have to use +`[Burgundy](/Burgundy)`. + +To link to a directory listing for a subdirectory, use a trailing +slash: `[Wine/]()` will link to a listing of the `Wine` subdirectory. + +# DocBook + +As DocBook is an XML format, opening and closing tags must match +(``...``). + ++--------------------------------------------------------+------------------------------------------------------------+ +| DocBook code | Result | ++========================================================+============================================================+ +| `emphasized text` | *emphasized text* | ++--------------------------------------------------------+------------------------------------------------------------+ +| `strong emphasis` | **strong emphasis** | ++--------------------------------------------------------+------------------------------------------------------------+ +| ``literal text`` | `literal text` | ++--------------------------------------------------------+------------------------------------------------------------+ +| XML character entities: `< > "` | `< > "` | ++--------------------------------------------------------+------------------------------------------------------------+ +| ` | [external link](https://en.wikipedia.org/wikiDocBook) | +| external link` | | ++--------------------------------------------------------+------------------------------------------------------------+ +| Inserting an image: | ![folder](/img/icons/folder.png) | +| | | +| | | +| folder | | +| | | +| | | +| | | +| | | ++--------------------------------------------------------+------------------------------------------------------------+ +| Wikilink: `Front Page` | Wikilink: [Front Page]() | ++--------------------------------------------------------+------------------------------------------------------------+ +| `H2O` | H~2~O | ++--------------------------------------------------------+------------------------------------------------------------+ +| `10100` | 10^100^ | ++--------------------------------------------------------+------------------------------------------------------------+ +| `strikeout` | ~~strikeout~~ | ++--------------------------------------------------------+------------------------------------------------------------+ +| `$x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}$` | $x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}$[^1] | +| | | +| | (Use pandoc's `--mathml` option to convert TeX math code.) | ++--------------------------------------------------------+------------------------------------------------------------+ +| `A simple footnote. Or | A simple footnote.^[Or is it so simple?] | +| is it so simple?` | | ++--------------------------------------------------------+------------------------------------------------------------+ +| `

> an indented paragraph, usually used | > an indented paragraph, usually used for quotations | +| for quotations

` | | ++--------------------------------------------------------+------------------------------------------------------------+ +|

                                       |     #!/bin/sh -e                                           |
    +|     #!/bin/sh -e`                                      |     echo "Hello world"                                     |
    +|     echo "Hello world"                                 |                                                            |
    +|

| | ++--------------------------------------------------------+------------------------------------------------------------+ +|

| - a bulleted list | +|
- | - second item | +|

  a bulleted list

  | - sublist | +|
| - and more | +|
- | - back to main list | +|

  second item

  | 1. this item has an ordered | +|
  | 2. sublist | +|
  - | a. you can also use letters | +|

    sublist

    | b. another item | +|
  | | +|
  - | | +|

    and more

    | | +|
  | | +|
  | | +|
| | +|
- | | +|

  back to main list

  | | +|
  | | +|
  1. | | +|

     this item has an ordered

     | | +|
  | | +|
  2. | | +|

     sublist

     | | +| <orderedlist spacing="compact" | | +| numeration="loweralpha"> | | +|
  3. | | +|

     you can also use letters

     | | +|
  | | +|
  4. | | +|

     another item

     | | +|
  | | +|
| | +| | | +| | | +| | | +|

| | ++--------------------------------------------------------+------------------------------------------------------------+ +|

| Fruit Quantity | +|

## Our fruit inventory

| ------- ---------- | +| | apples 30,200 | +| | oranges 1,998 | +| | pears 42 | +|
| | +|
| : Our fruit inventory | +|
| | +|
| | +|
Fruit | Quantity
--- | ---
| | +|
| | +|
| | +|
| | +|
| | +|
| | +|
apples | 30,200
| | +|
| | +|
| | +|
| | +|
oranges | 1,998
| | +|
| | +|
| | +|
| | +|
pears | 42
| | +|
| | +| | | +|

| | ++--------------------------------------------------------+------------------------------------------------------------+ + +## Headings + +A heading is given as the `

# ` element of a `
`: + +

    +<section>
    + <title>Heading</title>
    + <simpara>This is a top level section.</simpara>
    + <section>
    +  <title>Subheading</title>
    +  <simpara>This is a second level section.</simpara>
    + </section>
    +</section>
    +

+ +## Wiki links + +Links to other wiki pages are formed this way: +`Page Name` + +To link to a wiki page using something else as the link text: +`something else`. + +Note that page names may contain spaces and some special characters. +They need not be CamelCase. CamelCase words are *not* automatically +converted to wiki links. + +Wiki pages may be organized into directories. So, if you have +several pages on wine, you may wish to organize them like so: + + Wine/Pinot Noir + Wine/Burgundy + Wine/Cabernet Sauvignon + +Note that a wiki link `Burgundy` +that occurs inside the `Wine` directory will link to `Wine/Burgundy`, +and not to `Burgundy`. To link to a top-level page called `Burgundy`, +you'd have to use `Burgundy`. + +To link to a directory listing for a subdirectory, use a trailing +slash: `Wine` will link to a listing of +the `Wine` subdirectory. + +## Reference material + +Further reading: [DocBook 5: The Definitive Guide], which includes the +[List of DocBook elements]. + +[DocBook 5: The Definitive Guide]: https://tdg.docbook.org/tdg/5.0/docbook.html +[List of DocBook elements]: https://tdg.docbook.org/tdg/5.0/chunk-part-d64e8789.html + +## A sample document + +You might want to use the following document as a resource of DocBook +snippets (copy/paste). + +~~~~~~~~ + +
+

### Using DocBook

+

+ As DocBook is an XML format, opening and closing tags + must match (<tag>...</tag>). +

+
+

#### Text Formatting

+

+ A simple paragraph. +

- This wiki's pages are written in - pandoc's - extended form of - markdown. - If you're not familiar with markdown, you should start by looking at - the - markdown - "basics" page and the - markdown - syntax description. Consult the - pandoc - User's Guide for information about pandoc's syntax for - footnotes, tables, description lists, and other elements not present - in standard markdown. + A complex paragraph may contain blocks.

-

- Markdown is pretty intuitive, since it is based on email - conventions. Here are some examples to get you started: -

-

-
-
-
-
- `*emphasized text*` - | - emphasized text -
-
-
-
-
- `**strong emphasis**` - | - strong emphasis -
-
-
-
-
- ``literal text`` - | - `literal text` -
-
-
-
-
- `\*escaped special characters\*` - | - *escaped special characters* -
-
-
-
-
- `[external link](http://google.com)` - | - external link -
-
-
-
-
- `![folder](/img/icons/folder.png)` - | - + + italics: italics, + bold: bold, + strikeout: strikeout, + inline code snippets: `inline code`. + + + Links: + external, + internal Wiki Link. + + + Inserting an image: + - + - -
-
-
-
-
- Wikilink: `[Front Page]()` - | - Wikilink: Front Page -
-
-
-
-
- `H~2~O` - | - H2O -
-
-
-
-
- `10^100^` - | - 10100 -
-
-
-
-
- `~~strikeout~~` - | - strikeout -
-
-
-
-
- `$x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}$` - | - $x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}$ - - If this looks like code, it's because MathJax is not installed on - your system. Contact your administrator to request it. - - -
-
-
-
-
- `A simple footnote.^[Or is it so simple?]` - | - A simple footnote. - - Or is it so simple? - - -
-
-

-

    -  > an indented paragraph,
    -  > usually used for quotations
    -

-

-
-

> -

> - an indented paragraph, usually used for quotations -

> -

-

-
-

-

    -      #!/bin/sh -e
    -      # code, indented four spaces
    -      echo "Hello world"
    -

-

-
-

    +
    +
    +

+
+

#### Text Blocks

+

+ Quotation: +

> +

> + A quotation set off from the main text. +

> +

+ +

+ Code listing: +

     #!/bin/sh -e
    -# code, indented four spaces
     echo "Hello world"
    -

- - -
- -

    -  * a bulleted list
    -  * second item
    -      - sublist
    -      - and more
    -  * back to main list
    -      1. this item has an ordered
    -      2. sublist
    -          a) you can also use letters
    -          b) another item
    -

- - -

+ +

+
+
+

#### Lists

+

+ Simple list: +

- -

  - a bulleted list -

  +

  + first +

- -

  - second item -

  -
  -
  - -

    - sublist -

    -
  -
  - -

    - and more -

    -
  -
  -
+

+ second +

+ +

+ Numbered list: +

1. -

   - back to main list -

   -
   -
   1. -

      - this item has an ordered -

      -
   -
   2. -

      - sublist -

      -
      -
      1. -

         - you can also use letters -

         -
      -
      2. -

         - another item -

         -
      -
      -
   -
   +

   + first +

- - - -
- -

    -  Fruit        Quantity
    -  --------  -----------
    -  apples         30,200
    -  oranges         1,998
    -  pears              42
    -
    -  Table:  Our fruit inventory
    -

- - -

-

##### - Our fruit inventory -

- - - -
-
-
-
-
- Fruit - | - Quantity -
--- | ---
-
-
-
-
-
-
- apples - | - 30,200 -
-
-
-
-
- oranges - | - 1,998 -
-
-
-
-
- pears - | - 42 -
-
- -

- -
- -

- For headings, prefix a line with one or more `#` - signs: one for a major heading, two for a subheading, three for a - subsubheading. Be sure to leave space before and after the heading. +

2. +

   + second +

   +
+

+ Definition list: +

+ +
+ DocBook +
+
  +

  + A sophisticated XML format. +

  +
+ + +
+ orange +
+
  +

  + A healthy fruit. +

  +
+
  +

  + A warm colour. +

  +
+ +

-

    -# Markdown
    +

+

-Text... - -## Some examples... - -Text... - -
-

### Wiki links

-

- Links to other wiki pages are formed this way: - `[Page Name]()`. (Gitit converts markdown links - with empty targets into wikilinks.) -

-

- To link to a wiki page using something else as the link text: - `[something else](Page Name)`. -

-

- Note that page names may contain spaces and some special - characters. They need not be CamelCase. CamelCase words are - not automatically converted to wiki links. -

-

- Wiki pages may be organized into directories. So, if you have - several pages on wine, you may wish to organize them like so: -

-

    -Wine/Pinot Noir
    -Wine/Burgundy
    -Wine/Cabernet Sauvignon
    -

-

- Note that a wiki link `[Burgundy]()` that occurs - inside the `Wine` directory will link to - `Wine/Burgundy`, and not to - `Burgundy`. To link to a top-level page called - `Burgundy`, you'd have to use - `[Burgundy](/Burgundy)`. -

-

- To link to a directory listing for a subdirectory, use a trailing - slash: `[Wine/]()` will link to a listing of the - `Wine` subdirectory. -

-
-

+~~~~~~~~