Fossil SCM
Improved Markdown documentation.
Commit
5fcc1d5c59ea28ff67cdbdafe4774143358d2b59
Parent
ba4a9ca84dc1958…
3 files changed
+63
-241
+1
-1
+10
-27
+63
-241
| --- src/markdown.md | ||
| +++ src/markdown.md | ||
| @@ -1,241 +1,63 @@ | ||
| 1 | -# Markdown formatting rules | |
| 2 | - | |
| 3 | -In addition to its native Wiki formatting syntax, Fossil supports Markdown syntax as specified by | |
| 4 | -[John Gruber's original Markdown implementation](http://daringfireball.net/projects/markdown/). | |
| 5 | -For lots of examples - not repeated here - please refer to its | |
| 6 | -[syntax description](http://daringfireball.net/projects/markdown/syntax), of which the page you | |
| 7 | -are reading is an extract. | |
| 8 | - | |
| 9 | -This page itself uses Markdown formatting. | |
| 10 | - | |
| 11 | -## Summary | |
| 12 | - | |
| 13 | - - Block elements | |
| 14 | - | |
| 15 | - * A **paragraph** is a group of consecutive lines. Paragraphs are separated by blank lines. | |
| 16 | - | |
| 17 | - * A **Header** is a line of text underlined with equal signs or hyphens, or prefixed by a | |
| 18 | - number of hash marks. | |
| 19 | - | |
| 20 | - * **Block quotes** are blocks of text prefixed by '>'. | |
| 21 | - | |
| 22 | - * **Ordered list** items are prefixed by a number and a period. **Unordered list** items | |
| 23 | - are prefixed by a hyphen, asterisk or plus sign. Prefix and item text are separated by | |
| 24 | - whitespace. | |
| 25 | - | |
| 26 | - * **Code blocks** are formed by lines of text (possibly including empty lines) prefixed by | |
| 27 | - at least 4 spaces or a tab. | |
| 28 | - | |
| 29 | - * A **horizontal rule** is a line consisting of 3 or more asterisks, hyphens or underscores, | |
| 30 | - with optional whitespace between them. | |
| 31 | - | |
| 32 | - - Span elements | |
| 33 | - | |
| 34 | - * 3 types of **links** exist: | |
| 35 | - | |
| 36 | - - **automatic links** are URLs or email addresses enclosed in angle brackets | |
| 37 | - ('<' and '>'), and are displayed as such. | |
| 38 | - | |
| 39 | - - **inline links** consist of the displayed link text in square brackets ('[' and ']'), | |
| 40 | - followed by the link target in parentheses. | |
| 41 | - | |
| 42 | - - **reference links** separate _link instance_ from _link definition_. A link instance | |
| 43 | - consists of the displayed link text in square brackets, followed by a link definition name | |
| 44 | - in square brackets. | |
| 45 | - The corresponding link definition can occur anywhere on the page, and consists | |
| 46 | - of the link definition name in square brackets followed by a colon, whitespace and the | |
| 47 | - link target. | |
| 48 | - | |
| 49 | - * **Emphasis** can be given by wrapping text in one or two asterisks or underscores - use | |
| 50 | - one for HTML `<em>`, and two for `<strong>` emphasis. | |
| 51 | - | |
| 52 | - * A **code span** is text wrapped in backticks ('`'). | |
| 53 | - | |
| 54 | - * **Images** use a syntax much like inline or reference links, but with alt attribute text | |
| 55 | - ('img alt=...') instead of link text, and the first pair of square | |
| 56 | - brackets in an image instance prefixed by an exclamation mark. | |
| 57 | - | |
| 58 | - - **Inline HTML** is mostly interpreted automatically. | |
| 59 | - | |
| 60 | - - **Escaping** Markdown punctuation characters is done by prefixing them by a backslash ('\\'). | |
| 61 | - | |
| 62 | -## Details | |
| 63 | - | |
| 64 | -### Paragraphs | |
| 65 | - | |
| 66 | -To cause an explicit line break within a paragraph, use 2 or more spaces at the end of a line. | |
| 67 | - | |
| 68 | -Any line containing only whitespace (space or tab characters) is considered a blank line. | |
| 69 | - | |
| 70 | -### Headers | |
| 71 | - | |
| 72 | -#### 'Setext' style headers (underlined) | |
| 73 | - | |
| 74 | -The number of underlining equal signs or hyphens used has no impact on the resulting header. | |
| 75 | - | |
| 76 | -Underlining using equal sign(s) creates a top level header (corresponding to HTML `<h1>`), | |
| 77 | -while hyphen(s) create a second level header (HTML `<h2>`). Thus, only 2 levels of headers | |
| 78 | -can be made this way. | |
| 79 | - | |
| 80 | -#### 'Atx' style headers (hash prefixed) | |
| 81 | - | |
| 82 | -1 to 6 hash characters can be used to indicate header levels 1 (HTML `<h1>`) to 6 (`<h6>`). | |
| 83 | - | |
| 84 | -Headers may optionally be 'closed' for cosmetic reasons, by appending a whitespace and hash | |
| 85 | -characters to the header. The number of trailing hash characters has no impact on the header | |
| 86 | -level. | |
| 87 | - | |
| 88 | -### Block quotes | |
| 89 | - | |
| 90 | -Not every line in a paragraph needs to be prefixed by '>' in order to make it a block quote, | |
| 91 | -only the first line. | |
| 92 | - | |
| 93 | -Block quoted paragraphs can be nested by using multiple '>' characters as prefix. | |
| 94 | - | |
| 95 | -Within a block quote, Markdown formatting (e.g. lists, emphasis) still works as normal. | |
| 96 | - | |
| 97 | -### Lists | |
| 98 | - | |
| 99 | -A list item prefix need not occur first on its line; up to 3 leading spaces are allowed | |
| 100 | -(4 spaces would make a code block out of the following text). | |
| 101 | - | |
| 102 | -For unordered lists, asterisks, hyphens and plus signs can be used interchangeably. | |
| 103 | - | |
| 104 | -For ordered lists, arbitrary numbers can be used as part of an item prefix; the items will be | |
| 105 | -renumbered during rendering. However, future implementations may demand that the number used | |
| 106 | -for the first item in a list indicates an offset to be used for subsequent items. | |
| 107 | - | |
| 108 | -For list items spanning multiple lines, subsequent lines can be indented using an arbitrary amount | |
| 109 | -of whitespace. | |
| 110 | - | |
| 111 | -List items will be wrapped in HTML `<p>` tags if they are separated by blank lines. | |
| 112 | - | |
| 113 | -A list item may span multiple paragraphs. At least the first line of each such paragraph must | |
| 114 | -be indented using at least 4 spaces or a tab character. | |
| 115 | - | |
| 116 | -Block quotes within list items must have their '>' delimiters indented using 4 up to 7 spaces. | |
| 117 | - | |
| 118 | -Code blocks within list items need to be indented _twice_, that is, using 8 spaces or 2 tab | |
| 119 | -characters. | |
| 120 | - | |
| 121 | -### Code blocks | |
| 122 | - | |
| 123 | -Lines within a code block are rendered verbatim using HTML `<pre>` and `<code>` tags, except that | |
| 124 | -HTML punctuation characters like '<' and '&' are automatically converted to HTML entities. Thus, | |
| 125 | -there is no need to explicitly escape HTML syntax within a code block. | |
| 126 | - | |
| 127 | -A code block runs until the first non blank line with indent less than 4 spaces or 1 tab character. | |
| 128 | - | |
| 129 | - | |
| 130 | -Regular Markdown syntax is not processed within code blocks. | |
| 131 | - | |
| 132 | -### Links | |
| 133 | - | |
| 134 | -#### Automatic links | |
| 135 | - | |
| 136 | -When rendering automatic links to email addresses, HTML encoding obfuscation is used to | |
| 137 | -prevent some spambots from harvesting. | |
| 138 | - | |
| 139 | -#### Inline links | |
| 140 | - | |
| 141 | -Links to resources on the same server can use relative paths (i.e. can start with a '/'). | |
| 142 | - | |
| 143 | -An optional title for the link (e.g. to have mouseover text in the browser) may be given behind | |
| 144 | -the link target but within the parentheses, in single and double quotes, and separated from the | |
| 145 | -link target by whitespace. | |
| 146 | - | |
| 147 | -#### Reference links | |
| 148 | - | |
| 149 | -> Each reference link consists of | |
| 150 | -> | |
| 151 | -> - one or more _link instances_ at appropriate locations in the page text | |
| 152 | -> - a single _link definition_ at an arbitrary location on the page | |
| 153 | -> | |
| 154 | -> During rendering, each link instance is resolved, and the corresponding definition is | |
| 155 | -> filled in. No separate link definition clauses occur in the rendered output. | |
| 156 | -> | |
| 157 | -> There are 3 fields involved in link instances and definitions: | |
| 158 | -> | |
| 159 | -> - link text (i.e. the text that is displayed at the resulting link) | |
| 160 | -> - link definition name (i.e. an unique ID binding link instances to link definition) | |
| 161 | -> - link target (a target URL for the link) | |
| 162 | - | |
| 163 | -Multiple link instances may reference the same link definition using its link definition | |
| 164 | -name. | |
| 165 | - | |
| 166 | -Link definition names are case insensitive, and may contain letters, numbers, spaces and | |
| 167 | -punctuation. | |
| 168 | - | |
| 169 | -##### Link instance | |
| 170 | - | |
| 171 | -A space may be inserted between the bracket pairs for link text and link definition name. | |
| 172 | - | |
| 173 | -A link instance can use an _implicit link definition name_ shortcut, in which case the link | |
| 174 | -text is used as the link definition name. The second set of brackets then remains empty, e.g. | |
| 175 | -'[Google][]' ('Google' being used as both link text and link definition name). | |
| 176 | - | |
| 177 | -##### Link definition | |
| 178 | - | |
| 179 | -The first bracket pair containing the link definition name may be indented using up to 3 spaces. | |
| 180 | - | |
| 181 | -The link target may optionally be surrounded by angle brackets ('<' and '>'). | |
| 182 | - | |
| 183 | -A link target may be followed by an optional title (e.g. to have mouseover text in the browser). | |
| 184 | -This title may be enclosed in parentheses, single or double quotes. | |
| 185 | - | |
| 186 | -Link definitions may be split into 2 lines, with the title on the second line, arbitrarily | |
| 187 | -indented. This may be more visually pleasing when using long link targets. | |
| 188 | - | |
| 189 | -### Emphasis | |
| 190 | - | |
| 191 | -The same character(s) used for starting the emphasis must be used to end it; don't mix | |
| 192 | -asterisks and underscores. | |
| 193 | - | |
| 194 | -Emphasis can be used in the middle of a word. That is, there need not be whitespace on either | |
| 195 | -side of emphasis start or end punctuation characters. | |
| 196 | - | |
| 197 | -### Code spans | |
| 198 | - | |
| 199 | -To include a literal backtick character in a code span, use multiple backticks as opening and | |
| 200 | -closing delimiters. | |
| 201 | - | |
| 202 | -Whitespace may exist immediately after the opening delimiter and before the closing delimiter | |
| 203 | -of a code span, to allow for code fragments starting or ending with a backtick. | |
| 204 | - | |
| 205 | -Within a code span - like within a code block - angle brackets and ampersands are automatically encoded to make including | |
| 206 | -HTML fragments easier. | |
| 207 | - | |
| 208 | -### Images | |
| 209 | - | |
| 210 | -If necessary, HTML must be used to specify image dimensions. Markdown has no provision for this. | |
| 211 | - | |
| 212 | -### Inline HTML | |
| 213 | - | |
| 214 | -Start and end tags of | |
| 215 | -a HTML block level construct (`<div>`, `<table>` etc) must be separated from surrounding | |
| 216 | -context using blank lines, and must both occur at the start of a line. | |
| 217 | - | |
| 218 | -No extra unwanted `<p>` HTML tags are added around HTML block level tags. | |
| 219 | - | |
| 220 | -Markdown formatting within HTML block level tags is not processed; however, formatting within | |
| 221 | -span level tags (e.g. `<mark>`) is processed normally. | |
| 222 | - | |
| 223 | -### Escaping Markdown punctuation | |
| 224 | - | |
| 225 | -The following punctuation characters can be escaped using backslash: | |
| 226 | - | |
| 227 | - - \\ backslash | |
| 228 | - - ` backtick | |
| 229 | - - * asterisk | |
| 230 | - - _ underscore | |
| 231 | - - {} curly braces | |
| 232 | - - [] square brackets | |
| 233 | - - () parentheses | |
| 234 | - - # hash mark | |
| 235 | - - + plus sign | |
| 236 | - - - minus sign (hyphen) | |
| 237 | - - . dot | |
| 238 | - - ! exclamation mark | |
| 239 | - | |
| 240 | -To render a literal backslash, use 2 backslashes ('\\\\'). | |
| 241 | - | |
| 1 | +# Markdown Overview # | |
| 2 | + | |
| 3 | +## Paragraphs ## | |
| 4 | + | |
| 5 | +> Paragraphs are divided by blank lines. | |
| 6 | + | |
| 7 | +## Headings ## | |
| 8 | + | |
| 9 | +> | |
| 10 | + # Top-level Heading Alternative Top Level Heading | |
| 11 | + ============================= | |
| 12 | +> | |
| 13 | + ## Second-level Heading Alternative 2nd Level Heading | |
| 14 | + ----------------------------- | |
| 15 | + | |
| 16 | +## Links ## | |
| 17 | + | |
| 18 | +> 1. **\[display text\]\(URL\)** | |
| 19 | +> 2. **\[display text\]\(URL "Title"\)** | |
| 20 | +> 3. **\<URL\>** | |
| 21 | +> 4. **\[display text\]\[label\]** | |
| 22 | + | |
| 23 | +> With link format 4 ("reference links") the label must be resolved by | |
| 24 | +> including a line of the form **\[label\]: URL** or | |
| 25 | +> **\[label\]: URL "Title"** somewhere else | |
| 26 | +> in the document. | |
| 27 | + | |
| 28 | +## Fonts ## | |
| 29 | + | |
| 30 | +> * _\*italic\*_ | |
| 31 | +> * *\_italic\_* | |
| 32 | +> * __\*\*bold\*\*__ | |
| 33 | +> * **\_\_bold\_\_** | |
| 34 | +> * `` `code` `` | |
| 35 | + | |
| 36 | +> Note that the \`...\` construct disables HTML markup, so one can write, | |
| 37 | +> for example, **\``<html>`\`** to yield **`<html>`**. | |
| 38 | + | |
| 39 | +## Lists ## | |
| 40 | + | |
| 41 | +> | |
| 42 | + * bullet item | |
| 43 | + + bullet item | |
| 44 | + - bullet item | |
| 45 | + 1. numbered item | |
| 46 | + | |
| 47 | +## Block Quotes ## | |
| 48 | + | |
| 49 | +> Begin each line of a paragraph with ">" to block quote that paragraph. | |
| 50 | + | |
| 51 | +> > | |
| 52 | + > This paragraph is indented | |
| 53 | +> > | |
| 54 | + > > Double-indented paragraph | |
| 55 | + | |
| 56 | +## Miscellaneous ## | |
| 57 | + | |
| 58 | +> * In-line images using **\!\[alt-text\]\(image-URL\)** | |
| 59 | +> * Use HTML for complex formatting issues. | |
| 60 | +> * Escape special characters (ex: "\[", "\(", "\*") | |
| 61 | +> using backslash (ex: "\\\[", "\\\(", "\\\*"). | |
| 62 | +> * See [daringfireball.net](http://daringfireball.net/projects/markdown/syntax) | |
| 63 | +> for additional information. | |
| 242 | 64 |
| --- src/markdown.md | |
| +++ src/markdown.md | |
| @@ -1,241 +1,63 @@ | |
| 1 | # Markdown formatting rules |
| 2 | |
| 3 | In addition to its native Wiki formatting syntax, Fossil supports Markdown syntax as specified by |
| 4 | [John Gruber's original Markdown implementation](http://daringfireball.net/projects/markdown/). |
| 5 | For lots of examples - not repeated here - please refer to its |
| 6 | [syntax description](http://daringfireball.net/projects/markdown/syntax), of which the page you |
| 7 | are reading is an extract. |
| 8 | |
| 9 | This page itself uses Markdown formatting. |
| 10 | |
| 11 | ## Summary |
| 12 | |
| 13 | - Block elements |
| 14 | |
| 15 | * A **paragraph** is a group of consecutive lines. Paragraphs are separated by blank lines. |
| 16 | |
| 17 | * A **Header** is a line of text underlined with equal signs or hyphens, or prefixed by a |
| 18 | number of hash marks. |
| 19 | |
| 20 | * **Block quotes** are blocks of text prefixed by '>'. |
| 21 | |
| 22 | * **Ordered list** items are prefixed by a number and a period. **Unordered list** items |
| 23 | are prefixed by a hyphen, asterisk or plus sign. Prefix and item text are separated by |
| 24 | whitespace. |
| 25 | |
| 26 | * **Code blocks** are formed by lines of text (possibly including empty lines) prefixed by |
| 27 | at least 4 spaces or a tab. |
| 28 | |
| 29 | * A **horizontal rule** is a line consisting of 3 or more asterisks, hyphens or underscores, |
| 30 | with optional whitespace between them. |
| 31 | |
| 32 | - Span elements |
| 33 | |
| 34 | * 3 types of **links** exist: |
| 35 | |
| 36 | - **automatic links** are URLs or email addresses enclosed in angle brackets |
| 37 | ('<' and '>'), and are displayed as such. |
| 38 | |
| 39 | - **inline links** consist of the displayed link text in square brackets ('[' and ']'), |
| 40 | followed by the link target in parentheses. |
| 41 | |
| 42 | - **reference links** separate _link instance_ from _link definition_. A link instance |
| 43 | consists of the displayed link text in square brackets, followed by a link definition name |
| 44 | in square brackets. |
| 45 | The corresponding link definition can occur anywhere on the page, and consists |
| 46 | of the link definition name in square brackets followed by a colon, whitespace and the |
| 47 | link target. |
| 48 | |
| 49 | * **Emphasis** can be given by wrapping text in one or two asterisks or underscores - use |
| 50 | one for HTML `<em>`, and two for `<strong>` emphasis. |
| 51 | |
| 52 | * A **code span** is text wrapped in backticks ('`'). |
| 53 | |
| 54 | * **Images** use a syntax much like inline or reference links, but with alt attribute text |
| 55 | ('img alt=...') instead of link text, and the first pair of square |
| 56 | brackets in an image instance prefixed by an exclamation mark. |
| 57 | |
| 58 | - **Inline HTML** is mostly interpreted automatically. |
| 59 | |
| 60 | - **Escaping** Markdown punctuation characters is done by prefixing them by a backslash ('\\'). |
| 61 | |
| 62 | ## Details |
| 63 | |
| 64 | ### Paragraphs |
| 65 | |
| 66 | To cause an explicit line break within a paragraph, use 2 or more spaces at the end of a line. |
| 67 | |
| 68 | Any line containing only whitespace (space or tab characters) is considered a blank line. |
| 69 | |
| 70 | ### Headers |
| 71 | |
| 72 | #### 'Setext' style headers (underlined) |
| 73 | |
| 74 | The number of underlining equal signs or hyphens used has no impact on the resulting header. |
| 75 | |
| 76 | Underlining using equal sign(s) creates a top level header (corresponding to HTML `<h1>`), |
| 77 | while hyphen(s) create a second level header (HTML `<h2>`). Thus, only 2 levels of headers |
| 78 | can be made this way. |
| 79 | |
| 80 | #### 'Atx' style headers (hash prefixed) |
| 81 | |
| 82 | 1 to 6 hash characters can be used to indicate header levels 1 (HTML `<h1>`) to 6 (`<h6>`). |
| 83 | |
| 84 | Headers may optionally be 'closed' for cosmetic reasons, by appending a whitespace and hash |
| 85 | characters to the header. The number of trailing hash characters has no impact on the header |
| 86 | level. |
| 87 | |
| 88 | ### Block quotes |
| 89 | |
| 90 | Not every line in a paragraph needs to be prefixed by '>' in order to make it a block quote, |
| 91 | only the first line. |
| 92 | |
| 93 | Block quoted paragraphs can be nested by using multiple '>' characters as prefix. |
| 94 | |
| 95 | Within a block quote, Markdown formatting (e.g. lists, emphasis) still works as normal. |
| 96 | |
| 97 | ### Lists |
| 98 | |
| 99 | A list item prefix need not occur first on its line; up to 3 leading spaces are allowed |
| 100 | (4 spaces would make a code block out of the following text). |
| 101 | |
| 102 | For unordered lists, asterisks, hyphens and plus signs can be used interchangeably. |
| 103 | |
| 104 | For ordered lists, arbitrary numbers can be used as part of an item prefix; the items will be |
| 105 | renumbered during rendering. However, future implementations may demand that the number used |
| 106 | for the first item in a list indicates an offset to be used for subsequent items. |
| 107 | |
| 108 | For list items spanning multiple lines, subsequent lines can be indented using an arbitrary amount |
| 109 | of whitespace. |
| 110 | |
| 111 | List items will be wrapped in HTML `<p>` tags if they are separated by blank lines. |
| 112 | |
| 113 | A list item may span multiple paragraphs. At least the first line of each such paragraph must |
| 114 | be indented using at least 4 spaces or a tab character. |
| 115 | |
| 116 | Block quotes within list items must have their '>' delimiters indented using 4 up to 7 spaces. |
| 117 | |
| 118 | Code blocks within list items need to be indented _twice_, that is, using 8 spaces or 2 tab |
| 119 | characters. |
| 120 | |
| 121 | ### Code blocks |
| 122 | |
| 123 | Lines within a code block are rendered verbatim using HTML `<pre>` and `<code>` tags, except that |
| 124 | HTML punctuation characters like '<' and '&' are automatically converted to HTML entities. Thus, |
| 125 | there is no need to explicitly escape HTML syntax within a code block. |
| 126 | |
| 127 | A code block runs until the first non blank line with indent less than 4 spaces or 1 tab character. |
| 128 | |
| 129 | |
| 130 | Regular Markdown syntax is not processed within code blocks. |
| 131 | |
| 132 | ### Links |
| 133 | |
| 134 | #### Automatic links |
| 135 | |
| 136 | When rendering automatic links to email addresses, HTML encoding obfuscation is used to |
| 137 | prevent some spambots from harvesting. |
| 138 | |
| 139 | #### Inline links |
| 140 | |
| 141 | Links to resources on the same server can use relative paths (i.e. can start with a '/'). |
| 142 | |
| 143 | An optional title for the link (e.g. to have mouseover text in the browser) may be given behind |
| 144 | the link target but within the parentheses, in single and double quotes, and separated from the |
| 145 | link target by whitespace. |
| 146 | |
| 147 | #### Reference links |
| 148 | |
| 149 | > Each reference link consists of |
| 150 | > |
| 151 | > - one or more _link instances_ at appropriate locations in the page text |
| 152 | > - a single _link definition_ at an arbitrary location on the page |
| 153 | > |
| 154 | > During rendering, each link instance is resolved, and the corresponding definition is |
| 155 | > filled in. No separate link definition clauses occur in the rendered output. |
| 156 | > |
| 157 | > There are 3 fields involved in link instances and definitions: |
| 158 | > |
| 159 | > - link text (i.e. the text that is displayed at the resulting link) |
| 160 | > - link definition name (i.e. an unique ID binding link instances to link definition) |
| 161 | > - link target (a target URL for the link) |
| 162 | |
| 163 | Multiple link instances may reference the same link definition using its link definition |
| 164 | name. |
| 165 | |
| 166 | Link definition names are case insensitive, and may contain letters, numbers, spaces and |
| 167 | punctuation. |
| 168 | |
| 169 | ##### Link instance |
| 170 | |
| 171 | A space may be inserted between the bracket pairs for link text and link definition name. |
| 172 | |
| 173 | A link instance can use an _implicit link definition name_ shortcut, in which case the link |
| 174 | text is used as the link definition name. The second set of brackets then remains empty, e.g. |
| 175 | '[Google][]' ('Google' being used as both link text and link definition name). |
| 176 | |
| 177 | ##### Link definition |
| 178 | |
| 179 | The first bracket pair containing the link definition name may be indented using up to 3 spaces. |
| 180 | |
| 181 | The link target may optionally be surrounded by angle brackets ('<' and '>'). |
| 182 | |
| 183 | A link target may be followed by an optional title (e.g. to have mouseover text in the browser). |
| 184 | This title may be enclosed in parentheses, single or double quotes. |
| 185 | |
| 186 | Link definitions may be split into 2 lines, with the title on the second line, arbitrarily |
| 187 | indented. This may be more visually pleasing when using long link targets. |
| 188 | |
| 189 | ### Emphasis |
| 190 | |
| 191 | The same character(s) used for starting the emphasis must be used to end it; don't mix |
| 192 | asterisks and underscores. |
| 193 | |
| 194 | Emphasis can be used in the middle of a word. That is, there need not be whitespace on either |
| 195 | side of emphasis start or end punctuation characters. |
| 196 | |
| 197 | ### Code spans |
| 198 | |
| 199 | To include a literal backtick character in a code span, use multiple backticks as opening and |
| 200 | closing delimiters. |
| 201 | |
| 202 | Whitespace may exist immediately after the opening delimiter and before the closing delimiter |
| 203 | of a code span, to allow for code fragments starting or ending with a backtick. |
| 204 | |
| 205 | Within a code span - like within a code block - angle brackets and ampersands are automatically encoded to make including |
| 206 | HTML fragments easier. |
| 207 | |
| 208 | ### Images |
| 209 | |
| 210 | If necessary, HTML must be used to specify image dimensions. Markdown has no provision for this. |
| 211 | |
| 212 | ### Inline HTML |
| 213 | |
| 214 | Start and end tags of |
| 215 | a HTML block level construct (`<div>`, `<table>` etc) must be separated from surrounding |
| 216 | context using blank lines, and must both occur at the start of a line. |
| 217 | |
| 218 | No extra unwanted `<p>` HTML tags are added around HTML block level tags. |
| 219 | |
| 220 | Markdown formatting within HTML block level tags is not processed; however, formatting within |
| 221 | span level tags (e.g. `<mark>`) is processed normally. |
| 222 | |
| 223 | ### Escaping Markdown punctuation |
| 224 | |
| 225 | The following punctuation characters can be escaped using backslash: |
| 226 | |
| 227 | - \\ backslash |
| 228 | - ` backtick |
| 229 | - * asterisk |
| 230 | - _ underscore |
| 231 | - {} curly braces |
| 232 | - [] square brackets |
| 233 | - () parentheses |
| 234 | - # hash mark |
| 235 | - + plus sign |
| 236 | - - minus sign (hyphen) |
| 237 | - . dot |
| 238 | - ! exclamation mark |
| 239 | |
| 240 | To render a literal backslash, use 2 backslashes ('\\\\'). |
| 241 | |
| 242 |
| --- src/markdown.md | |
| +++ src/markdown.md | |
| @@ -1,241 +1,63 @@ | |
| 1 | # Markdown Overview # |
| 2 | |
| 3 | ## Paragraphs ## |
| 4 | |
| 5 | > Paragraphs are divided by blank lines. |
| 6 | |
| 7 | ## Headings ## |
| 8 | |
| 9 | > |
| 10 | # Top-level Heading Alternative Top Level Heading |
| 11 | ============================= |
| 12 | > |
| 13 | ## Second-level Heading Alternative 2nd Level Heading |
| 14 | ----------------------------- |
| 15 | |
| 16 | ## Links ## |
| 17 | |
| 18 | > 1. **\[display text\]\(URL\)** |
| 19 | > 2. **\[display text\]\(URL "Title"\)** |
| 20 | > 3. **\<URL\>** |
| 21 | > 4. **\[display text\]\[label\]** |
| 22 | |
| 23 | > With link format 4 ("reference links") the label must be resolved by |
| 24 | > including a line of the form **\[label\]: URL** or |
| 25 | > **\[label\]: URL "Title"** somewhere else |
| 26 | > in the document. |
| 27 | |
| 28 | ## Fonts ## |
| 29 | |
| 30 | > * _\*italic\*_ |
| 31 | > * *\_italic\_* |
| 32 | > * __\*\*bold\*\*__ |
| 33 | > * **\_\_bold\_\_** |
| 34 | > * `` `code` `` |
| 35 | |
| 36 | > Note that the \`...\` construct disables HTML markup, so one can write, |
| 37 | > for example, **\``<html>`\`** to yield **`<html>`**. |
| 38 | |
| 39 | ## Lists ## |
| 40 | |
| 41 | > |
| 42 | * bullet item |
| 43 | + bullet item |
| 44 | - bullet item |
| 45 | 1. numbered item |
| 46 | |
| 47 | ## Block Quotes ## |
| 48 | |
| 49 | > Begin each line of a paragraph with ">" to block quote that paragraph. |
| 50 | |
| 51 | > > |
| 52 | > This paragraph is indented |
| 53 | > > |
| 54 | > > Double-indented paragraph |
| 55 | |
| 56 | ## Miscellaneous ## |
| 57 | |
| 58 | > * In-line images using **\!\[alt-text\]\(image-URL\)** |
| 59 | > * Use HTML for complex formatting issues. |
| 60 | > * Escape special characters (ex: "\[", "\(", "\*") |
| 61 | > using backslash (ex: "\\\[", "\\\(", "\\\*"). |
| 62 | > * See [daringfireball.net](http://daringfireball.net/projects/markdown/syntax) |
| 63 | > for additional information. |
| 64 |
+1
-1
| --- www/embeddeddoc.wiki | ||
| +++ www/embeddeddoc.wiki | ||
| @@ -69,11 +69,11 @@ | ||
| 69 | 69 | [/mimetype_list|many different file suffixes], |
| 70 | 70 | including all the popular ones such as ".css", ".gif", ".htm", |
| 71 | 71 | ".html", ".jpg", ".jpeg", ".png", and ".txt". |
| 72 | 72 | |
| 73 | 73 | Documentation files whose names end in ".wiki" use the |
| 74 | -[/wiki_rules | same markup as wiki pages] - | |
| 74 | +[/wiki_rules | fossil wiki markup] - | |
| 75 | 75 | a safe subset of HTML together with some wiki rules for paragraph |
| 76 | 76 | breaks, lists, and hyperlinks. |
| 77 | 77 | Documentation files ending in ".md" or ".markdown" use the |
| 78 | 78 | [/md_rules | Markdown markup langauge]. |
| 79 | 79 | Documentation files ending in ".txt" are plain text. |
| 80 | 80 |
| --- www/embeddeddoc.wiki | |
| +++ www/embeddeddoc.wiki | |
| @@ -69,11 +69,11 @@ | |
| 69 | [/mimetype_list|many different file suffixes], |
| 70 | including all the popular ones such as ".css", ".gif", ".htm", |
| 71 | ".html", ".jpg", ".jpeg", ".png", and ".txt". |
| 72 | |
| 73 | Documentation files whose names end in ".wiki" use the |
| 74 | [/wiki_rules | same markup as wiki pages] - |
| 75 | a safe subset of HTML together with some wiki rules for paragraph |
| 76 | breaks, lists, and hyperlinks. |
| 77 | Documentation files ending in ".md" or ".markdown" use the |
| 78 | [/md_rules | Markdown markup langauge]. |
| 79 | Documentation files ending in ".txt" are plain text. |
| 80 |
| --- www/embeddeddoc.wiki | |
| +++ www/embeddeddoc.wiki | |
| @@ -69,11 +69,11 @@ | |
| 69 | [/mimetype_list|many different file suffixes], |
| 70 | including all the popular ones such as ".css", ".gif", ".htm", |
| 71 | ".html", ".jpg", ".jpeg", ".png", and ".txt". |
| 72 | |
| 73 | Documentation files whose names end in ".wiki" use the |
| 74 | [/wiki_rules | fossil wiki markup] - |
| 75 | a safe subset of HTML together with some wiki rules for paragraph |
| 76 | breaks, lists, and hyperlinks. |
| 77 | Documentation files ending in ".md" or ".markdown" use the |
| 78 | [/md_rules | Markdown markup langauge]. |
| 79 | Documentation files ending in ".txt" are plain text. |
| 80 |
+10
-27
| --- www/wikitheory.wiki | ||
| +++ www/wikitheory.wiki | ||
| @@ -1,44 +1,26 @@ | ||
| 1 | 1 | <title>Wiki In Fossil</title> |
| 2 | 2 | <h2>Introduction</h2> |
| 3 | 3 | |
| 4 | -Fossil uses [/wiki_rules | wiki markup] for many things: | |
| 4 | +Fossil uses [/wiki_rules | Fossil wiki markup] and/or | |
| 5 | +[/md_rules | Markdown markup] for many things: | |
| 5 | 6 | |
| 6 | 7 | * Stand-alone wiki pages. |
| 7 | 8 | * Description and comments in [./bugtheory.wiki | bug reports]. |
| 8 | 9 | * Check-in comments. |
| 9 | 10 | * [./embeddeddoc.wiki | Embedded documentation] files whose |
| 10 | - name ends in ".wiki". | |
| 11 | + name ends in ".wiki" or ".md" or ".markdown". | |
| 11 | 12 | * [./event.wiki | Technical notes]. |
| 12 | 13 | |
| 13 | -The [/wiki_rules | formatting rules] for fossil wiki | |
| 14 | +The [/wiki_rules | formatting rules for fossil wiki] | |
| 14 | 15 | are designed to be simple and intuitive. The idea is that wiki provides |
| 15 | 16 | paragraph breaks, numbered and bulleted lists, and hyperlinking for |
| 16 | 17 | simple documents together with a safe subset of HTML for more complex |
| 17 | 18 | formatting tasks. |
| 18 | 19 | |
| 19 | -Some commentators feel that the use of HTML is a mistake and that | |
| 20 | -fossil should use the markup language of the | |
| 21 | -<i>fill-in-your-favorite</i> wiki engine instead. That approach | |
| 22 | -was considered but was rejected for the following reasons: | |
| 23 | - | |
| 24 | - 1. There is no standard wiki markup language. Every wiki engine does | |
| 25 | - it a little differently. | |
| 26 | - | |
| 27 | - 2. The wiki markup used by fossil, though limited, is common to most | |
| 28 | - other wiki engines, is intuitive, and is sufficient for 90% of | |
| 29 | - all formatting tasks. | |
| 30 | - | |
| 31 | - 3. Where the fossil wiki markup language is insufficient, HTML is | |
| 32 | - used. HTML is a standard language familiar to most programmers so | |
| 33 | - there is nothing new to learn. And, though cumbersome, the HTML | |
| 34 | - does not need to be used very often so is not a burden. | |
| 35 | - | |
| 36 | -UPDATE: Since 2012, Fossil also contains a [/md_rules | Markdown] | |
| 37 | -rendering engine. Markdown can optionally be used to format | |
| 38 | -[./embeddeddoc.wiki | embedded documents], wiki pages, | |
| 39 | -[./event.wiki | technical notes], and bug report text. | |
| 20 | +The [/md_rules | Markdown formatting rules] are more complex, but | |
| 21 | +are also more widely know, and are thus provided as an alternative. | |
| 40 | 22 | |
| 41 | 23 | <h2>Stand-alone Wiki Pages</h2> |
| 42 | 24 | |
| 43 | 25 | Each wiki page has its own revision history which is independent of |
| 44 | 26 | the sequence of check-ins (check-ins). Wiki pages can branch and merge |
| @@ -58,21 +40,22 @@ | ||
| 58 | 40 | [./fileformat.wiki | control artifact] |
| 59 | 41 | of type [./fileformat.wiki#wikichng | "Wiki Page"]. |
| 60 | 42 | |
| 61 | 43 | <h2>Embedded Documentation</h2> |
| 62 | 44 | |
| 63 | -Files in the source tree that use the ".wiki" suffix can be accessed | |
| 64 | -and displayed using special URLs to the fossil server. This allows | |
| 45 | +Files in the source tree that use the ".wiki", ".md", or ".markdown" suffixes | |
| 46 | +can be accessed and displayed using special URLs to the fossil server. | |
| 47 | +This allows | |
| 65 | 48 | project documentation to be stored in the source tree and accessed |
| 66 | 49 | online. (Details are described [./embeddeddoc.wiki | separately].) |
| 67 | 50 | |
| 68 | 51 | Some projects prefer to store their documentation in wiki. There is nothing |
| 69 | 52 | wrong with that. But other projects prefer to keep documentation as part |
| 70 | 53 | of the source tree, so that it is versioned along with the source tree and |
| 71 | 54 | so that only developers with check-in privileges can change it. |
| 72 | 55 | Embedded documentation serves this latter purpose. Both forms of documentation |
| 73 | -use the exact same wiki markup language. Some projects may choose to | |
| 56 | +use the exact same markup. Some projects may choose to | |
| 74 | 57 | use both forms of documentation at the same time. Because the same |
| 75 | 58 | format is used, it is trivial to move a file from wiki to embedded documentation |
| 76 | 59 | or back again as the project evolves. |
| 77 | 60 | |
| 78 | 61 | <h2>Bug-reports and check-in comments</h2> |
| 79 | 62 |
| --- www/wikitheory.wiki | |
| +++ www/wikitheory.wiki | |
| @@ -1,44 +1,26 @@ | |
| 1 | <title>Wiki In Fossil</title> |
| 2 | <h2>Introduction</h2> |
| 3 | |
| 4 | Fossil uses [/wiki_rules | wiki markup] for many things: |
| 5 | |
| 6 | * Stand-alone wiki pages. |
| 7 | * Description and comments in [./bugtheory.wiki | bug reports]. |
| 8 | * Check-in comments. |
| 9 | * [./embeddeddoc.wiki | Embedded documentation] files whose |
| 10 | name ends in ".wiki". |
| 11 | * [./event.wiki | Technical notes]. |
| 12 | |
| 13 | The [/wiki_rules | formatting rules] for fossil wiki |
| 14 | are designed to be simple and intuitive. The idea is that wiki provides |
| 15 | paragraph breaks, numbered and bulleted lists, and hyperlinking for |
| 16 | simple documents together with a safe subset of HTML for more complex |
| 17 | formatting tasks. |
| 18 | |
| 19 | Some commentators feel that the use of HTML is a mistake and that |
| 20 | fossil should use the markup language of the |
| 21 | <i>fill-in-your-favorite</i> wiki engine instead. That approach |
| 22 | was considered but was rejected for the following reasons: |
| 23 | |
| 24 | 1. There is no standard wiki markup language. Every wiki engine does |
| 25 | it a little differently. |
| 26 | |
| 27 | 2. The wiki markup used by fossil, though limited, is common to most |
| 28 | other wiki engines, is intuitive, and is sufficient for 90% of |
| 29 | all formatting tasks. |
| 30 | |
| 31 | 3. Where the fossil wiki markup language is insufficient, HTML is |
| 32 | used. HTML is a standard language familiar to most programmers so |
| 33 | there is nothing new to learn. And, though cumbersome, the HTML |
| 34 | does not need to be used very often so is not a burden. |
| 35 | |
| 36 | UPDATE: Since 2012, Fossil also contains a [/md_rules | Markdown] |
| 37 | rendering engine. Markdown can optionally be used to format |
| 38 | [./embeddeddoc.wiki | embedded documents], wiki pages, |
| 39 | [./event.wiki | technical notes], and bug report text. |
| 40 | |
| 41 | <h2>Stand-alone Wiki Pages</h2> |
| 42 | |
| 43 | Each wiki page has its own revision history which is independent of |
| 44 | the sequence of check-ins (check-ins). Wiki pages can branch and merge |
| @@ -58,21 +40,22 @@ | |
| 58 | [./fileformat.wiki | control artifact] |
| 59 | of type [./fileformat.wiki#wikichng | "Wiki Page"]. |
| 60 | |
| 61 | <h2>Embedded Documentation</h2> |
| 62 | |
| 63 | Files in the source tree that use the ".wiki" suffix can be accessed |
| 64 | and displayed using special URLs to the fossil server. This allows |
| 65 | project documentation to be stored in the source tree and accessed |
| 66 | online. (Details are described [./embeddeddoc.wiki | separately].) |
| 67 | |
| 68 | Some projects prefer to store their documentation in wiki. There is nothing |
| 69 | wrong with that. But other projects prefer to keep documentation as part |
| 70 | of the source tree, so that it is versioned along with the source tree and |
| 71 | so that only developers with check-in privileges can change it. |
| 72 | Embedded documentation serves this latter purpose. Both forms of documentation |
| 73 | use the exact same wiki markup language. Some projects may choose to |
| 74 | use both forms of documentation at the same time. Because the same |
| 75 | format is used, it is trivial to move a file from wiki to embedded documentation |
| 76 | or back again as the project evolves. |
| 77 | |
| 78 | <h2>Bug-reports and check-in comments</h2> |
| 79 |
| --- www/wikitheory.wiki | |
| +++ www/wikitheory.wiki | |
| @@ -1,44 +1,26 @@ | |
| 1 | <title>Wiki In Fossil</title> |
| 2 | <h2>Introduction</h2> |
| 3 | |
| 4 | Fossil uses [/wiki_rules | Fossil wiki markup] and/or |
| 5 | [/md_rules | Markdown markup] for many things: |
| 6 | |
| 7 | * Stand-alone wiki pages. |
| 8 | * Description and comments in [./bugtheory.wiki | bug reports]. |
| 9 | * Check-in comments. |
| 10 | * [./embeddeddoc.wiki | Embedded documentation] files whose |
| 11 | name ends in ".wiki" or ".md" or ".markdown". |
| 12 | * [./event.wiki | Technical notes]. |
| 13 | |
| 14 | The [/wiki_rules | formatting rules for fossil wiki] |
| 15 | are designed to be simple and intuitive. The idea is that wiki provides |
| 16 | paragraph breaks, numbered and bulleted lists, and hyperlinking for |
| 17 | simple documents together with a safe subset of HTML for more complex |
| 18 | formatting tasks. |
| 19 | |
| 20 | The [/md_rules | Markdown formatting rules] are more complex, but |
| 21 | are also more widely know, and are thus provided as an alternative. |
| 22 | |
| 23 | <h2>Stand-alone Wiki Pages</h2> |
| 24 | |
| 25 | Each wiki page has its own revision history which is independent of |
| 26 | the sequence of check-ins (check-ins). Wiki pages can branch and merge |
| @@ -58,21 +40,22 @@ | |
| 40 | [./fileformat.wiki | control artifact] |
| 41 | of type [./fileformat.wiki#wikichng | "Wiki Page"]. |
| 42 | |
| 43 | <h2>Embedded Documentation</h2> |
| 44 | |
| 45 | Files in the source tree that use the ".wiki", ".md", or ".markdown" suffixes |
| 46 | can be accessed and displayed using special URLs to the fossil server. |
| 47 | This allows |
| 48 | project documentation to be stored in the source tree and accessed |
| 49 | online. (Details are described [./embeddeddoc.wiki | separately].) |
| 50 | |
| 51 | Some projects prefer to store their documentation in wiki. There is nothing |
| 52 | wrong with that. But other projects prefer to keep documentation as part |
| 53 | of the source tree, so that it is versioned along with the source tree and |
| 54 | so that only developers with check-in privileges can change it. |
| 55 | Embedded documentation serves this latter purpose. Both forms of documentation |
| 56 | use the exact same markup. Some projects may choose to |
| 57 | use both forms of documentation at the same time. Because the same |
| 58 | format is used, it is trivial to move a file from wiki to embedded documentation |
| 59 | or back again as the project evolves. |
| 60 | |
| 61 | <h2>Bug-reports and check-in comments</h2> |
| 62 |