Fossil

Check-in [5fcc1d5c]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Improved Markdown documentation.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 5fcc1d5c59ea28ff67cdbdafe4774143358d2b59
User & Date: drh 2016-05-29 22:59:32
Context
2016-05-29
23:57
Minor documentation updates. check-in: ac8aa0c6 user: drh tags: trunk
22:59
Improved Markdown documentation. check-in: 5fcc1d5c user: drh tags: trunk
20:58
Improved linkages between the various status pages. check-in: ba4a9ca8 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/markdown.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

67
68
69
70
71
72
73
74


75
76
77
78


79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100




101
102




103
104
105
106

107
108
109





110
111


112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137




138
139

140
141

142
143
144
145
146
147
148
149
150
151
152

153
154
155

156
157

158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241






# Markdown formatting rules

In addition to its native Wiki formatting syntax, Fossil supports Markdown syntax as specified by
[John Gruber's original Markdown implementation](http://daringfireball.net/projects/markdown/).
For lots of examples - not repeated here - please refer to its
[syntax description](http://daringfireball.net/projects/markdown/syntax), of which the page you
are reading is an extract.

This page itself uses Markdown formatting.

## Summary

  - Block elements

      * A **paragraph** is a group of consecutive lines. Paragraphs are separated by blank lines.

      * A **Header** is a line of text underlined with equal signs or hyphens, or prefixed by a
        number of hash marks.

      * **Block quotes** are blocks of text prefixed by '>'.

      * **Ordered list** items are prefixed by a number and a period. **Unordered list** items
        are prefixed by a hyphen, asterisk or plus sign. Prefix and item text are separated by
        whitespace.

      * **Code blocks** are formed by lines of text (possibly including empty lines) prefixed by
        at least 4 spaces or a tab.

      * A **horizontal rule** is a line consisting of 3 or more asterisks, hyphens or underscores,
        with optional whitespace between them.

  - Span elements

      * 3 types of **links** exist:

        - **automatic links** are URLs or email addresses enclosed in angle brackets
          ('<' and '>'), and are displayed as such.

        - **inline links** consist of the displayed link text in square brackets ('[' and ']'),
          followed by the link target in parentheses.

        - **reference links** separate _link instance_ from _link definition_. A link instance
          consists of the displayed link text in square brackets, followed by a link definition name
          in square brackets.
          The corresponding link definition can occur anywhere on the page, and consists
          of the link definition name in square brackets followed by a colon, whitespace and the
          link target.

      * **Emphasis** can be given by wrapping text in one or two asterisks or underscores - use
        one for HTML `<em>`, and two for `<strong>` emphasis.

      * A **code span** is text wrapped in backticks ('`').

      * **Images** use a syntax much like inline or reference links, but with alt attribute text
        ('img alt=...') instead of link text, and the first pair of square
        brackets in an image instance prefixed by an exclamation mark.

  - **Inline HTML** is mostly interpreted automatically.

  - **Escaping** Markdown punctuation characters is done by prefixing them by a backslash ('\\').

## Details

### Paragraphs

To cause an explicit line break within a paragraph, use 2 or more spaces at the end of a line.


Any line containing only whitespace (space or tab characters) is considered a blank line.

### Headers

#### 'Setext' style headers (underlined)

The number of underlining equal signs or hyphens used has no impact on the resulting header.



Underlining using equal sign(s) creates a top level header (corresponding to HTML `<h1>`),
while hyphen(s) create a second level header (HTML `<h2>`). Thus, only 2 levels of headers
can be made this way.



#### 'Atx' style headers (hash prefixed)

1 to 6 hash characters can be used to indicate header levels 1 (HTML `<h1>`) to 6 (`<h6>`).

Headers may optionally be 'closed' for cosmetic reasons, by appending a whitespace and hash
characters to the header. The number of trailing hash characters has no impact on the header
level.

### Block quotes

Not every line in a paragraph needs to be prefixed by '>' in order to make it a block quote,
only the first line.

Block quoted paragraphs can be nested by using multiple '>' characters as prefix.

Within a block quote, Markdown formatting (e.g. lists, emphasis) still works as normal.

### Lists

A list item prefix need not occur first on its line; up to 3 leading spaces are allowed
(4 spaces would make a code block out of the following text).





For unordered lists, asterisks, hyphens and plus signs can be used interchangeably.





For ordered lists, arbitrary numbers can be used as part of an item prefix; the items will be
renumbered during rendering. However, future implementations may demand that the number used
for the first item in a list indicates an offset to be used for subsequent items.


For list items spanning multiple lines, subsequent lines can be indented using an arbitrary amount
of whitespace.






List items will be wrapped in HTML `<p>` tags if they are separated by blank lines.



A list item may span multiple paragraphs. At least the first line of each such paragraph must
be indented using at least 4 spaces or a tab character.

Block quotes within list items must have their '>' delimiters indented using 4 up to 7 spaces.

Code blocks within list items need to be indented _twice_, that is, using 8 spaces or 2 tab
characters.

### Code blocks

Lines within a code block are rendered verbatim using HTML `<pre>` and `<code>` tags, except that
HTML punctuation characters like '<' and '&' are automatically converted to HTML entities. Thus,
there is no need to explicitly escape HTML syntax within a code block.

A code block runs until the first non blank line with indent less than 4 spaces or 1 tab character.


Regular Markdown syntax is not processed within code blocks.

### Links

#### Automatic links

When rendering automatic links to email addresses, HTML encoding obfuscation is used to
prevent some spambots from harvesting.





#### Inline links


Links to resources on the same server can use relative paths (i.e. can start with a '/').


An optional title for the link (e.g. to have mouseover text in the browser) may be given behind
the link target but within the parentheses, in single and double quotes, and separated from the
link target by whitespace.

#### Reference links

> Each reference link consists of
>
>   - one or more _link instances_ at appropriate locations in the page text
>   - a single _link definition_ at an arbitrary location on the page

>
> During rendering, each link instance is resolved, and the corresponding definition is
> filled in. No separate link definition clauses occur in the rendered output.

>
> There are 3 fields involved in link instances and definitions:

>
>   - link text (i.e. the text that is displayed at the resulting link)
>   - link definition name (i.e. an unique ID binding link instances to link definition)
>   - link target (a target URL for the link)

Multiple link instances may reference the same link definition using its link definition
name.

Link definition names are case insensitive, and may contain letters, numbers, spaces and
punctuation.

##### Link instance

A space may be inserted between the bracket pairs for link text and link definition name.

A link instance can use an _implicit link definition name_ shortcut, in which case the link
text is used as the link definition name. The second set of brackets then remains empty, e.g.
'[Google][]' ('Google' being used as both link text and link definition name).

##### Link definition

The first bracket pair containing the link definition name may be indented using up to 3 spaces.

The link target may optionally be surrounded by angle brackets ('<' and '>').

A link target may be followed by an optional title (e.g. to have mouseover text in the browser).
This title may be enclosed in parentheses, single or double quotes.

Link definitions may be split into 2 lines, with the title on the second line, arbitrarily
indented. This may be more visually pleasing when using long link targets.

### Emphasis

The same character(s) used for starting the emphasis must be used to end it; don't mix
asterisks and underscores.

Emphasis can be used in the middle of a word. That is, there need not be whitespace on either
side of emphasis start or end punctuation characters.

### Code spans

To include a literal backtick character in a code span, use multiple backticks as opening and
closing delimiters.

Whitespace may exist immediately after the opening delimiter and before the closing delimiter
of a code span, to allow for code fragments starting or ending with a backtick.

Within a code span - like within a code block - angle brackets and ampersands are automatically encoded to make including
HTML fragments easier.

### Images

If necessary, HTML must be used to specify image dimensions. Markdown has no provision for this.

### Inline HTML

Start and end tags of
a HTML block level construct (`<div>`, `<table>` etc) must be separated from surrounding
context using blank lines, and must both occur at the start of a line.

No extra unwanted `<p>` HTML tags are added around HTML block level tags.

Markdown formatting within HTML block level tags is not processed; however, formatting within
span level tags (e.g. `<mark>`) is processed normally.

### Escaping Markdown punctuation

The following punctuation characters can be escaped using backslash:

  - \\   backslash
  - `   backtick
  - *   asterisk
  - _   underscore
  - {}  curly braces
  - []  square brackets
  - ()  parentheses
  - #   hash mark
  - +   plus sign
  - -   minus sign (hyphen)
  - .   dot
  - !   exclamation mark

To render a literal backslash, use 2 backslashes ('\\\\').







|

<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|

<
>

<
<
|

<
|
<
>
>
|
<
<
<
>
>

<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|

<
<
>
>
>
>

<
>
>
>
>

<
<
<
>

<
<
>
>
>
>
>

<
>
>

<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|

<
|
<
<
>
>
>
>

<
>

<
>

<
<
<
<
<
<
<
|
<
<
>
|
<
<
>
|
<
>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
>
>
>
>
>
>
1
2





























































3
4

5
6


7
8

9

10
11
12



13
14
15

















16
17


18
19
20
21
22

23
24
25
26
27



28
29


30
31
32
33
34
35

36
37
38



















39
40

41


42
43
44
45
46

47
48

49
50







51


52
53


54
55

56
57



















































































58
59
60
61
62
63
# Markdown Overview #






























































## Paragraphs ##


> Paragraphs are divided by blank lines.



## Headings ##


>

    # Top-level Heading                         Alternative Top Level Heading
                                                =============================
>



    ## Second-level Heading                     Alternative 2nd Level Heading
                                                -----------------------------


















## Links ##



> 1.  **\[display text\]\(URL\)**
> 2.  **\[display text\]\(URL "Title"\)**
> 3.  **\<URL\>**
> 4.  **\[display text\]\[label\]**


> With link format 4 ("reference links") the label must be resolved by
> including a line of the form **\[label\]:&nbsp;URL** or
> **\[label\]:&nbsp;URL&nbsp;"Title"** somewhere else
> in the document.




## Fonts ##



> *   _\*italic\*_
> *   *\_italic\_*
> *   __\*\*bold\*\*__
> *   **\_\_bold\_\_**
> *   `` `code` ``


> Note that the \`...\` construct disables HTML markup, so one can write,
> for example, **\``<html>`\`** to yield **`<html>`**.




















## Lists ##


>


     *   bullet item
     +   bullet item
     -   bullet item
     1.  numbered item


## Block Quotes ##


> Begin each line of a paragraph with ">" to block quote that paragraph.








> >


    > This paragraph is indented
> >


    > > Double-indented paragraph


## Miscellaneous ##




















































































> *   In-line images using **\!\[alt-text\]\(image-URL\)**
> *   Use HTML for complex formatting issues.
> *   Escape special characters (ex: "\[", "\(", "\*")
>     using backslash (ex: "\\\[", "\\\(", "\\\*").
> *   See [daringfireball.net](http://daringfireball.net/projects/markdown/syntax)
>     for additional information.

Changes to www/embeddeddoc.wiki.

67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
The mimetype (and thus the rendering) of documentation files is 
determined by the file suffix.  Fossil currently understands 
[/mimetype_list|many different file suffixes],
including all the popular ones such as ".css", ".gif", ".htm",
".html", ".jpg", ".jpeg", ".png", and ".txt".

Documentation files whose names end in ".wiki" use the 
[/wiki_rules | same markup as wiki pages] -
a safe subset of HTML together with some wiki rules for paragraph
breaks, lists, and hyperlinks. 
Documentation files ending in ".md" or ".markdown" use the
[/md_rules  | Markdown markup langauge].
Documentation files ending in ".txt" are plain text.
Wiki, markdown, and plain text documentation files
are rendered with the standard fossil header and footer added.







|







67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
The mimetype (and thus the rendering) of documentation files is 
determined by the file suffix.  Fossil currently understands 
[/mimetype_list|many different file suffixes],
including all the popular ones such as ".css", ".gif", ".htm",
".html", ".jpg", ".jpeg", ".png", and ".txt".

Documentation files whose names end in ".wiki" use the 
[/wiki_rules | fossil wiki markup] -
a safe subset of HTML together with some wiki rules for paragraph
breaks, lists, and hyperlinks. 
Documentation files ending in ".md" or ".markdown" use the
[/md_rules  | Markdown markup langauge].
Documentation files ending in ".txt" are plain text.
Wiki, markdown, and plain text documentation files
are rendered with the standard fossil header and footer added.

Changes to www/wikitheory.wiki.

1
2
3
4

5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
..
56
57
58
59
60
61
62
63
64

65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
<title>Wiki In Fossil</title>
<h2>Introduction</h2>

Fossil uses [/wiki_rules | wiki markup] for many things:


   *  Stand-alone wiki pages.
   *  Description and comments in [./bugtheory.wiki | bug reports].
   *  Check-in comments.
   *  [./embeddeddoc.wiki | Embedded documentation] files whose
      name ends in ".wiki".
   *  [./event.wiki | Technical notes].

The [/wiki_rules | formatting rules] for fossil wiki
are designed to be simple and intuitive.  The idea is that wiki provides
paragraph breaks, numbered and bulleted lists, and hyperlinking for
simple documents together with a safe subset of HTML for more complex
formatting tasks.

Some commentators feel that the use of HTML is a mistake and that
fossil should use the markup language of the
<i>fill-in-your-favorite</i> wiki engine instead.  That approach
was considered but was rejected for the following reasons:

  1.  There is no standard wiki markup language.  Every wiki engine does
      it a little differently.

  2.  The wiki markup used by fossil, though limited, is common to most
      other wiki engines, is intuitive, and is sufficient for 90% of
      all formatting tasks.

  3.  Where the fossil wiki markup language is insufficient, HTML is
      used.  HTML is a standard language familiar to most programmers so
      there is nothing new to learn.  And, though cumbersome, the HTML
      does not need to be used very often so is not a burden.

UPDATE: Since 2012, Fossil also contains a [/md_rules | Markdown]
rendering engine.  Markdown can optionally be used to format 
[./embeddeddoc.wiki | embedded documents], wiki pages, 
[./event.wiki | technical notes], and bug report text.

<h2>Stand-alone Wiki Pages</h2>

Each wiki page has its own revision history which is independent of
the sequence of check-ins (check-ins).  Wiki pages can branch and merge
just like check-ins, though as of this writing (2008-07-29) there is
no mechanism in the user interface to support branching and merging.
................................................................................

Every change to a wiki page is a separate 
[./fileformat.wiki | control artifact]
of type [./fileformat.wiki#wikichng | "Wiki Page"].

<h2>Embedded Documentation</h2>

Files in the source tree that use the ".wiki" suffix can be accessed
and displayed using special URLs to the fossil server.  This allows

project documentation to be stored in the source tree and accessed 
online.  (Details are described [./embeddeddoc.wiki | separately].)

Some projects prefer to store their documentation in wiki.  There is nothing
wrong with that.  But other projects prefer to keep documentation as part
of the source tree, so that it is versioned along with the source tree and
so that only developers with check-in privileges can change it.  
Embedded documentation serves this latter purpose.  Both forms of documentation
use the exact same wiki markup language.  Some projects may choose to
use both forms of documentation at the same time.  Because the same
format is used, it is trivial to move a file from wiki to embedded documentation
or back again as the project evolves.

<h2>Bug-reports and check-in comments</h2>

The comments on check-ins and the text in the descriptions of bug reports
both use wiki formatting.  Exactly the same set of formatting rules apply.
There is never a need to learn one formatting language for documentation
and a different markup for bugs or for check-in comments.



|
>





|


|





|
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







 







|
|
>








|










1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21



















22
23
24
25
26
27
28
..
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
<title>Wiki In Fossil</title>
<h2>Introduction</h2>

Fossil uses [/wiki_rules | Fossil wiki markup] and/or
[/md_rules | Markdown markup] for many things:

   *  Stand-alone wiki pages.
   *  Description and comments in [./bugtheory.wiki | bug reports].
   *  Check-in comments.
   *  [./embeddeddoc.wiki | Embedded documentation] files whose
      name ends in ".wiki" or ".md" or ".markdown".
   *  [./event.wiki | Technical notes].

The [/wiki_rules | formatting rules for fossil wiki]
are designed to be simple and intuitive.  The idea is that wiki provides
paragraph breaks, numbered and bulleted lists, and hyperlinking for
simple documents together with a safe subset of HTML for more complex
formatting tasks.

The [/md_rules | Markdown formatting rules] are more complex, but
are also more widely know, and are thus provided as an alternative.




















<h2>Stand-alone Wiki Pages</h2>

Each wiki page has its own revision history which is independent of
the sequence of check-ins (check-ins).  Wiki pages can branch and merge
just like check-ins, though as of this writing (2008-07-29) there is
no mechanism in the user interface to support branching and merging.
................................................................................

Every change to a wiki page is a separate 
[./fileformat.wiki | control artifact]
of type [./fileformat.wiki#wikichng | "Wiki Page"].

<h2>Embedded Documentation</h2>

Files in the source tree that use the ".wiki", ".md", or ".markdown" suffixes
can be accessed and displayed using special URLs to the fossil server.  
This allows
project documentation to be stored in the source tree and accessed 
online.  (Details are described [./embeddeddoc.wiki | separately].)

Some projects prefer to store their documentation in wiki.  There is nothing
wrong with that.  But other projects prefer to keep documentation as part
of the source tree, so that it is versioned along with the source tree and
so that only developers with check-in privileges can change it.  
Embedded documentation serves this latter purpose.  Both forms of documentation
use the exact same markup.  Some projects may choose to
use both forms of documentation at the same time.  Because the same
format is used, it is trivial to move a file from wiki to embedded documentation
or back again as the project evolves.

<h2>Bug-reports and check-in comments</h2>

The comments on check-ins and the text in the descriptions of bug reports
both use wiki formatting.  Exactly the same set of formatting rules apply.
There is never a need to learn one formatting language for documentation
and a different markup for bugs or for check-in comments.