--- 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 | | +| | | +| | | +| this item has an ordered | | +| | | +| | | +| sublist | | +| | | +| | | +| you can also use letters | | +| | | +| | | +| 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>`: + +<pre> +<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> +</pre> + +## Wiki links + +Links to other wiki pages are formed this way: +`<ulink url="Page Name">Page Name</ulink>` + +To link to a wiki page using something else as the link text: +`<ulink url="Page Name">something else</ulink>`. + +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 `<ulink url="Burgundy">Burgundy</ulink>` +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 `<ulink url="/Burgundy">Burgundy</ulink>`. + +To link to a directory listing for a subdirectory, use a trailing +slash: `<ulink url="Wine/">Wine</ulink>` 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). + +~~~~~~~~ + +<section id="docbook"> + <title>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: + - - back to main list - - - - - this item has an ordered - - - - - sublist - - - - - you can also use letters - - - - - 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. + + + 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. - - - +~~~~~~~~