|
1
|
<title>Project Documentation</title> |
|
2
|
|
|
3
|
Fossil provides a built-in <a href="wikitheory.wiki">wiki</a> |
|
4
|
that can be used to store the |
|
5
|
documentation for a project. This is sufficient for many projects. |
|
6
|
If your project is well-served by wiki documentation, then you |
|
7
|
need read no further. |
|
8
|
|
|
9
|
But fossil also supports embedding project documentation as |
|
10
|
files in the source tree. There are several potential advantages |
|
11
|
to this approach: |
|
12
|
|
|
13
|
1. The documentation files are versioned together with the |
|
14
|
source code files so it is always clear what version of |
|
15
|
the documentation goes with a particular release. |
|
16
|
|
|
17
|
2. The documentation files can be edited using your favorite |
|
18
|
text editor instead of having to use the web-based wiki |
|
19
|
editor. |
|
20
|
|
|
21
|
3. Only people with check-in privileges can modify the documentation. |
|
22
|
(This might be either an advantage or disadvantage, depending |
|
23
|
on the nature of your project.) |
|
24
|
|
|
25
|
We will call documentation that is included as files in the source tree |
|
26
|
"embedded documentation". |
|
27
|
|
|
28
|
<h1>1.0 Fossil Support For Embedded Documentation</h1> |
|
29
|
|
|
30
|
The fossil web interface supports embedded documentation using |
|
31
|
the "/doc" page. To access embedded documentation, one points |
|
32
|
a web browser to a fossil URL of the following form: |
|
33
|
|
|
34
|
<pre> |
|
35
|
<i><baseurl></i><big><b>/doc/</b></big><i><version></i><big><b>/</b></big><i><filename></i> |
|
36
|
</pre> |
|
37
|
|
|
38
|
The <i><baseurl></i> is the main URL used to access the fossil web server. |
|
39
|
For example, the <i><baseurl></i> for the fossil project itself is |
|
40
|
[https://fossil-scm.org/home]. |
|
41
|
If you launch the web server using the "[/help/ui|fossil ui]" command line, |
|
42
|
then the <i><baseurl></i> is usually |
|
43
|
<b>http://localhost:8080/</b>. |
|
44
|
|
|
45
|
The <i><version></i> is the |
|
46
|
[./checkin_names.wiki|name of a check-in] |
|
47
|
that contains the embedded document. This might be a hash prefix for |
|
48
|
the check-in, or it might be the name of a branch or tag, or it might |
|
49
|
be a timestamp. See the prior link |
|
50
|
for more possibilities and examples. |
|
51
|
|
|
52
|
The <i id="ckout"><version></i> can |
|
53
|
also be the special identifier "<b>ckout</b>". |
|
54
|
The "<b>ckout</b>" keywords means to |
|
55
|
pull the documentation file from the local source tree on disk, not |
|
56
|
from the any check-in. The "<b>ckout</b>" keyword |
|
57
|
only works when you start your server using the |
|
58
|
"[/help/server|fossil server]" or "[/help?cmd=ui|fossil ui]" |
|
59
|
commands. The "/doc/ckout" URL is intended to show a preview of |
|
60
|
the documentation you are currently editing but have not yet checked in. |
|
61
|
|
|
62
|
The original designed purpose of the "ckout" feature is to allow the |
|
63
|
user to preview local changes to documentation before committing the |
|
64
|
change. This is an important facility, since unlike other document |
|
65
|
languages like HTML, there is still a lot of variation among rendering |
|
66
|
engines for Fossil's markup languages, Markdown and Fossil Wiki. Your |
|
67
|
changes may look fine in your whizzy GUI Markdown editor, but what |
|
68
|
actually matters is how <i>Fossil</i> will interpret your Markdown text. |
|
69
|
Therefore, you should always preview your edits before committing them. |
|
70
|
|
|
71
|
To help make "ckout" easier to use, the "[/help?cmd=ui|fossil ui]" |
|
72
|
command has the "--ckout-alias NAME" option that makes NAME an |
|
73
|
alias for "ckout". If you are editing a collection of documents |
|
74
|
that have hardcoded links to one another in the form of |
|
75
|
"/doc/trunk/...", for example, you can test your changes by |
|
76
|
running "fossil ui --ckout-alias trunk" and all of the links will |
|
77
|
point to your uncommitted edits rather than to the latest trunk |
|
78
|
check-in. |
|
79
|
|
|
80
|
Finally, the <i><filename></i> element of the URL is the |
|
81
|
pathname of the documentation file relative to the root of the source |
|
82
|
tree. |
|
83
|
|
|
84
|
The mimetype (and thus the rendering) of documentation files is |
|
85
|
determined by the file suffix. Fossil currently understands |
|
86
|
[/mimetype_list|many different file suffixes], |
|
87
|
including all the popular ones such as ".css", ".gif", ".htm", |
|
88
|
".html", ".jpg", ".jpeg", ".png", and ".txt". |
|
89
|
|
|
90
|
Documentation files whose names end in ".wiki" use the |
|
91
|
[/wiki_rules | fossil wiki markup] - |
|
92
|
a safe subset of HTML together with some wiki rules for paragraph |
|
93
|
breaks, lists, and hyperlinks. |
|
94
|
Documentation files ending in ".md" or ".markdown" use the |
|
95
|
[/md_rules | Markdown markup language]. |
|
96
|
Documentation files ending in ".txt" are plain text. |
|
97
|
Wiki, markdown, and plain text documentation files |
|
98
|
are rendered with the standard fossil header and footer added. |
|
99
|
Most other mimetypes are delivered directly to the requesting |
|
100
|
web browser without interpretation, additions, or changes. |
|
101
|
|
|
102
|
<h2 id="html">1.1 HTML Rendering With Fossil Headers And Footers</h2> |
|
103
|
|
|
104
|
Files with the mimetype "text/html" (the .html or .htm suffix) are |
|
105
|
usually rendered directly to the browser without interpretation. |
|
106
|
However, if the file begins with a <div> element like this: |
|
107
|
|
|
108
|
<b><div class='fossil-doc' data-title='<i>Title Text</i>'></b> |
|
109
|
|
|
110
|
Then the standard Fossil header and footer are added to the document |
|
111
|
prior to being displayed. The "class='fossil-doc'" attribute is |
|
112
|
required for this to occur. The "data-title='...'" attribute is |
|
113
|
optional, but if it is present the text will become the title displayed |
|
114
|
in the Fossil header. An example of this can be seen in Fossil |
|
115
|
Documentation Index www/permutedindex.html: |
|
116
|
|
|
117
|
* [/file/www/permutedindex.html?txt|source text for <b>www/permutedindex.html</b>] |
|
118
|
* [/doc/trunk/www/permutedindex.html|<b>www/permutedindex.html</b> rendered as HTML] |
|
119
|
|
|
120
|
Beware that such HTML files render in the same browser security context |
|
121
|
as all other embedded documentation served from Fossil; they are not |
|
122
|
fully-independent web pages. One practical consequence of this is that |
|
123
|
embedded <tt><script></tt> tags will cause a |
|
124
|
[https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP | Content |
|
125
|
Security Policy] error in your browser with the default CSP as served by |
|
126
|
Fossil. See the documentation on [./customskin.md#headfoot | Header and |
|
127
|
Footer Processing] and [./defcsp.md | The Default CSP]. |
|
128
|
|
|
129
|
|
|
130
|
<h1>2.0 Server-Side Text Substitution</h1> |
|
131
|
|
|
132
|
Fossil can do a few types of substitution of server-side information |
|
133
|
into the embedded document. |
|
134
|
|
|
135
|
<h2>2.1 "$ROOT" In HTML and Markdown Hyperlinks</h2> |
|
136
|
|
|
137
|
Hyperlinks in Markdown and HTML embedded documents can reference |
|
138
|
the root of the Fossil repository using the special text "$ROOT" |
|
139
|
at the beginning of a URL. For example, a Markdown hyperlink to |
|
140
|
the Markdown formatting rules might be |
|
141
|
written in the embedded document like this: |
|
142
|
|
|
143
|
<verbatim> |
|
144
|
[Markdown formatting rules]($ROOT/wiki_rules) |
|
145
|
</verbatim> |
|
146
|
|
|
147
|
Depending on how the how the Fossil server is configured, that hyperlink |
|
148
|
might be renderer like one of the following: |
|
149
|
|
|
150
|
<verbatim> |
|
151
|
<a href="/wiki_rules">Wiki formatting rule</a> |
|
152
|
<a href="/cgi-bin/fossil/wiki_rules">Wiki formatting rules</a> |
|
153
|
</verbatim> |
|
154
|
|
|
155
|
So, in other words, the "$ROOT" text is converted into whatever |
|
156
|
the "<baseurl>" is for the document. |
|
157
|
|
|
158
|
This substitution works for HTML and Markdown documents. |
|
159
|
It does not work for Wiki embedded documents, since with |
|
160
|
Wiki you can just begin a URL with "/" and it automatically knows |
|
161
|
to prepend the $ROOT. |
|
162
|
|
|
163
|
<h2>2.2 "$CURRENT" In "/doc/" Hyperlinks</h2> |
|
164
|
|
|
165
|
Similarly, URLs of the form "/doc/$CURRENT/..." have the check-in |
|
166
|
hash of the check-in currently being viewed substituted in place of |
|
167
|
the "$CURRENT" text. This feature, in combination with the "$ROOT" |
|
168
|
substitution above, allows an absolute path to be used for hyperlinks. |
|
169
|
|
|
170
|
For example, if an embedded document documented wanted to reference |
|
171
|
some other document in a separate file named "www/otherdoc.md", |
|
172
|
it could use a URL like this: |
|
173
|
|
|
174
|
<verbatim> |
|
175
|
[Other Document]($ROOT/doc/$CURRENT/www/otherdoc.md) |
|
176
|
</verbatim> |
|
177
|
|
|
178
|
As with "$ROOT", this substitution only works for Markdown and HTML |
|
179
|
documents. For Wiki documents, you would need to use a relative URL. |
|
180
|
|
|
181
|
<h2 id="th1">2.3 TH1 Documents</h2> |
|
182
|
|
|
183
|
Enabling TH1 document support requires the following: |
|
184
|
|
|
185
|
* Configure the build with the <code>--with-th1-docs</code> flag. |
|
186
|
* Enable the <code>th1-docs</code> setting, which is only available |
|
187
|
after building with <code>--with-th1-docs</code>. |
|
188
|
* Affected files must have a <code>.th1</code> file extension. |
|
189
|
* The code to run must be embedded in blocks of |
|
190
|
<code><th1>...</th1></code>. |
|
191
|
|
|
192
|
Fossil will substitute the value of [./th1.md | TH1 expressions] |
|
193
|
within the <code><th1>...</th1></code> blocks into |
|
194
|
the output HTML. |
|
195
|
|
|
196
|
Since TH1 is a full scripting language, this feature essential grants |
|
197
|
the ability to execute code on the server to anyone with check-in |
|
198
|
privilege for the project. |
|
199
|
This is a security risk that needs to be carefully managed. |
|
200
|
The feature is off by default. |
|
201
|
Administrators should understand and carefully assess the risks |
|
202
|
before enabling the use of TH1 within embedded documentation. |
|
203
|
|
|
204
|
|
|
205
|
<h1>3.0 Examples</h1> |
|
206
|
|
|
207
|
This file that you are currently reading is an example of |
|
208
|
embedded documentation. The name of this file in the fossil |
|
209
|
source tree is "<b>www/embeddeddoc.wiki</b>". |
|
210
|
You are perhaps looking at this |
|
211
|
file using the URL: |
|
212
|
|
|
213
|
<pre>[https://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki]</pre> |
|
214
|
|
|
215
|
The first part of this path, the "[https://fossil-scm.org/home]", |
|
216
|
is the base URL. You might have originally typed: |
|
217
|
[https://fossil-scm.org/]. The web server at the fossil-scm.org |
|
218
|
site automatically redirects such links by appending "home". The |
|
219
|
"home" file on fossil-scm.org is really a [./server/any/cgi.md|CGI script] |
|
220
|
which runs the fossil web service in CGI mode. |
|
221
|
The "home" CGI script looks like this: |
|
222
|
|
|
223
|
<pre> |
|
224
|
#!/usr/bin/fossil |
|
225
|
repository: /fossil/fossil.fossil |
|
226
|
</pre> |
|
227
|
|
|
228
|
This is one of the many ways to set up a |
|
229
|
<a href="./server/">Fossil server</a>. |
|
230
|
|
|
231
|
The "<b>/trunk/</b>" part of the URL tells fossil to use |
|
232
|
the documentation files from the most recent trunk check-in. |
|
233
|
If you wanted to see an historical version of this document, |
|
234
|
you could substitute the name of a check-in for "<b>/trunk/</b>". |
|
235
|
For example, to see the version of this document associated with |
|
236
|
check-in [9be1b00392], simply replace the "<b>/trunk/</b>" with |
|
237
|
"<b>/9be1b00392/</b>". You can also substitute the symbolic name |
|
238
|
for a particular version or branch. For example, you might |
|
239
|
replace "<b>/trunk/</b>" with "<b>/experimental/</b>" to get the latest |
|
240
|
version of this document in the "experimental" branch. The symbolic name |
|
241
|
can also be a date and time string in any of the following formats:</p> |
|
242
|
|
|
243
|
<ul> |
|
244
|
<li> <i>YYYY-MM-DD</i> |
|
245
|
<li> <i>YYYY-MM-DD<b>T</b>HH:MM</i> |
|
246
|
<li> <i>YYYY-MM-DD<b>T</b>HH:MM:SS</i> |
|
247
|
</ul> |
|
248
|
|
|
249
|
When the symbolic name is a date and time, fossil shows the version |
|
250
|
of the document that was most recently checked in as of the date |
|
251
|
and time specified. So, for example, to see what the fossil website |
|
252
|
looked like at the beginning of 2010, enter: |
|
253
|
|
|
254
|
<pre><a href="https://fossil-scm.org/home/doc/2010-01-01/www/index.wiki">https://fossil-scm.org/home/doc/<b>2010-01-01</b>/www/index.wiki |
|
255
|
</a></pre> |
|
256
|
|
|
257
|
The file that encodes this document is stored in the fossil source tree under |
|
258
|
the name "<b>www/embeddeddoc.wiki</b>" and so that name forms the |
|
259
|
last part of the URL for this document. |
|
260
|
|
|
261
|
As I sit writing this documentation file, I am testing my work by |
|
262
|
running the "<b>fossil ui</b>" command line and viewing |
|
263
|
<b>http://localhost:8080/doc/ckout/www/embeddeddoc.wiki</b> in |
|
264
|
Firefox. I am doing this even though I have not yet checked in |
|
265
|
the "<b>www/embeddeddoc.wiki</b>" file for the first time. Using |
|
266
|
the special "<b>ckout</b>" version identifier on the "<b>/doc</b>" page |
|
267
|
it is easy to make multiple changes to multiple files and see how they all |
|
268
|
look together before committing anything to the repository. |
|
269
|
|