|
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. (For historical reasons, these must |
|
10
|
currently be in fossil-wiki text format.) |
|
11
|
* [./embeddeddoc.wiki | Embedded documentation] files whose |
|
12
|
name ends in ".wiki" or ".md" or ".markdown". |
|
13
|
* [./event.wiki | Technical notes]. |
|
14
|
* [./forum.wiki | Forum messages]. |
|
15
|
* Auxiliary notes on check-ins and branches. |
|
16
|
|
|
17
|
The [/wiki_rules | formatting rules for fossil wiki] |
|
18
|
are designed to be simple and intuitive. The idea is that wiki provides |
|
19
|
paragraph breaks, numbered and bulleted lists, and hyperlinking for |
|
20
|
simple documents together with a safe subset of HTML for more complex |
|
21
|
formatting tasks. |
|
22
|
|
|
23
|
The [/md_rules | Markdown formatting rules] are more complex, but |
|
24
|
are also more widely known, and are thus provided as an alternative. |
|
25
|
|
|
26
|
<h2>Stand-alone Wiki Pages</h2> |
|
27
|
|
|
28
|
Each wiki page has its own revision history which is independent of |
|
29
|
the sequence of check-ins (check-ins). Wiki pages can branch and merge |
|
30
|
just like check-ins, though as of this writing (2008-07-29) there is |
|
31
|
no mechanism in the user interface to support branching and merging. |
|
32
|
The current implementation of the wiki shows the version of the wiki |
|
33
|
page that has the most recent time stamp. |
|
34
|
|
|
35
|
In other words, if two users make unrelated changes to the same wiki |
|
36
|
page on separate repositories and those repositories are synced, |
|
37
|
the wiki page will fork. The web interface will display whichever edit |
|
38
|
was checked in last. The other edit can be found in the history. The |
|
39
|
file format will support merging the branches back together, but there |
|
40
|
is no mechanism in the user interface (yet) to perform the merge. |
|
41
|
|
|
42
|
Every change to a wiki page is a separate |
|
43
|
[./fileformat.wiki | control artifact] |
|
44
|
of type [./fileformat.wiki#wikichng | "Wiki Page"]. |
|
45
|
|
|
46
|
<h2>Embedded Documentation</h2> |
|
47
|
|
|
48
|
Files in the source tree that use the ".wiki", ".md", or ".markdown" suffixes |
|
49
|
can be accessed and displayed using special URLs to the fossil server. |
|
50
|
This allows |
|
51
|
project documentation to be stored in the source tree and accessed |
|
52
|
online. (Details are described [./embeddeddoc.wiki | separately].) |
|
53
|
|
|
54
|
Some projects prefer to store their documentation in wiki. There is nothing |
|
55
|
wrong with that. But other projects prefer to keep documentation as part |
|
56
|
of the source tree, so that it is versioned along with the source tree and |
|
57
|
so that only developers with check-in privileges can change it. |
|
58
|
Embedded documentation serves this latter purpose. Both forms of documentation |
|
59
|
use the exact same markup. Some projects may choose to |
|
60
|
use both forms of documentation at the same time. Because the same |
|
61
|
format is used, it is trivial to move a file from wiki to embedded documentation |
|
62
|
or back again as the project evolves. |
|
63
|
|
|
64
|
<h2>Bug-reports and check-in comments and Forum messages</h2> |
|
65
|
|
|
66
|
The comments on check-ins, forum posts, and the text in the |
|
67
|
descriptions of bug reports both use wiki formatting. Exactly the |
|
68
|
same set of formatting rules apply. There is never a need to learn |
|
69
|
one formatting language for documentation and a different markup for |
|
70
|
bugs or for check-in comments. |
|
71
|
|
|
72
|
Minor caveat: check-in messages are currently limited to the |
|
73
|
fossil-wiki format. |
|
74
|
|
|
75
|
<h2 id="assocwiki">Auxiliary notes attached to check-ins or branches</h2> |
|
76
|
|
|
77
|
Stand-alone wiki pages with special names "branch/<i>BRANCHNAME</i>" |
|
78
|
or "checkin/<i>HASH</i>" are associated with the corresponding |
|
79
|
branch or check-in. The wiki text appears in an "About" section of |
|
80
|
timelines and info screens. Examples: |
|
81
|
|
|
82
|
* [/timeline?r=graph-test-branch] shows the text of the |
|
83
|
[/wiki?name=branch/graph-test-branch&p|branch/graph-test-branch] |
|
84
|
wiki page at the top of the timeline |
|
85
|
* [/info/19c60b7fc9e2] shows the text of the |
|
86
|
[/wiki?name=checkin/19c60b7fc9e2400e56a6f938bbad0e34ca746ca2eabdecac10945539f1f5e8c6&p|checkin/19c60b7fc9e2...] |
|
87
|
wiki page in the "About" section. |
|
88
|
|
|
89
|
These special wiki pages are very useful for recording historical |
|
90
|
notes. |
|
91
|
|