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