Project Documentation
Fossil provides a built-in wiki that can be used to store the documentation for a project. This is sufficient for many projects. If your project is well-served by wiki documentation, then you need read no further.
But fossil also supports embedding project documentation as files in the source tree. There are several potential advantages to this approach:
- The documentation files are versioned together with the source code files so it is always clear what version of the documentation goes with a particular release.
- The documentation files can be edited using your favorite text editor instead of having to use the web-based wiki editor.
- Only people with check-in privileges can modify the documentation. (This might be either an advantage or disadvantage, depending on the nature of your project.)
We will call documentation that is included as files in the source tree "embedded documentation".
1.0 Fossil Support For Embedded Documentation
The fossil web interface supports embedded documentation using the "/doc" page. To access embedded documentation, one points a web browser to a fossil URL of the following form:
<baseurl>/doc/<version>/<filename>
The <baseurl> is the main URL used to access the fossil web server. For example, the <baseurl> for the fossil project itself is https://fossil-scm.org/home. If you launch the web server using the "fossil ui" command line, then the <baseurl> is usually http://localhost:8080/.
The <version> is the name of a check-in that contains the embedded document. This might be a hash prefix for the check-in, or it might be the name of a branch or tag, or it might be a timestamp. See the prior link for more possibilities and examples.
The <version> can also be the special identifier "ckout". The "ckout" keywords means to pull the documentation file from the local source tree on disk, not from the any check-in. The "ckout" keyword only works when you start your server using the "fossil server" or "fossil ui" commands. The "/doc/ckout" URL is intended to show a preview of the documentation you are currently editing but have not yet checked in.
The original designed purpose of the "ckout" feature is to allow the user to preview local changes to documentation before committing the change. This is an important facility, since unlike other document languages like HTML, there is still a lot of variation among rendering engines for Fossil's markup languages, Markdown and Fossil Wiki. Your changes may look fine in your whizzy GUI Markdown editor, but what actually matters is how Fossil will interpret your Markdown text. Therefore, you should always preview your edits before committing them.
To help make "ckout" easier to use, the "fossil ui" command has the "--ckout-alias NAME" option that makes NAME an alias for "ckout". If you are editing a collection of documents that have hardcoded links to one another in the form of "/doc/trunk/...", for example, you can test your changes by running "fossil ui --ckout-alias trunk" and all of the links will point to your uncommitted edits rather than to the latest trunk check-in.
Finally, the <filename> element of the URL is the pathname of the documentation file relative to the root of the source tree.
The mimetype (and thus the rendering) of documentation files is determined by the file suffix. Fossil currently understands 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 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 Markdown markup language. 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. Most other mimetypes are delivered directly to the requesting web browser without interpretation, additions, or changes.
1.1 HTML Rendering With Fossil Headers And Footers
Files with the mimetype "text/html" (the .html or .htm suffix) are usually rendered directly to the browser without interpretation. However, if the file begins with a <div> element like this:
<div class='fossil-doc' data-title='Title Text'>
Then the standard Fossil header and footer are added to the document prior to being displayed. The "class='fossil-doc'" attribute is required for this to occur. The "data-title='...'" attribute is optional, but if it is present the text will become the title displayed in the Fossil header. An example of this can be seen in Fossil Documentation Index www/permutedindex.html:
Beware that such HTML files render in the same browser security context as all other embedded documentation served from Fossil; they are not fully-independent web pages. One practical consequence of this is that embedded <script> tags will cause a Content Security Policy error in your browser with the default CSP as served by Fossil. See the documentation on Header and Footer Processing and The Default CSP.
2.0 Server-Side Text Substitution
Fossil can do a few types of substitution of server-side information into the embedded document.
2.1 "$ROOT" In HTML and Markdown Hyperlinks
Hyperlinks in Markdown and HTML embedded documents can reference the root of the Fossil repository using the special text "$ROOT" at the beginning of a URL. For example, a Markdown hyperlink to the Markdown formatting rules might be written in the embedded document like this:
[Markdown formatting rules]($ROOT/wiki_rules)
Depending on how the how the Fossil server is configured, that hyperlink might be renderer like one of the following:
<a href="/wiki_rules">Wiki formatting rules</a>
<a href="/cgi-bin/fossil/wiki_rules">Wiki formatting rules</a>
So, in other words, the "$ROOT" text is converted into whatever the "<baseurl>" is for the document.
This substitution works for HTML and Markdown documents. It does not work for Wiki embedded documents, since with Wiki you can just begin a URL with "/" and it automatically knows to prepend the $ROOT.
2.2 "$CURRENT" In "/doc/" Hyperlinks
Similarly, URLs of the form "/doc/$CURRENT/..." have the check-in hash of the check-in currently being viewed substituted in place of the "$CURRENT" text. This feature, in combination with the "$ROOT" substitution above, allows an absolute path to be used for hyperlinks.
For example, if an embedded document documented wanted to reference some other document in a separate file named "www/otherdoc.md", it could use a URL like this:
[Other Document]($ROOT/doc/$CURRENT/www/otherdoc.md)
As with "$ROOT", this substitution only works for Markdown and HTML documents. For Wiki documents, you would need to use a relative URL.
2.3 TH1 Documents
Fossil will substitute the value of TH1 expressions within { curly braces } into the output HTML if you have configured it with the --with-th1-docs option, which is disabled by default.
Since TH1 is a full scripting language, this feature essential grants the ability to execute code on the server to anyone with check-in privilege for the project. This is a security risk that needs to be carefully managed. The feature is off by default. Administrators should understand and carefully assess the risks before enabling the use of TH1 within embedded documentation.
3.0 Examples
This file that you are currently reading is an example of embedded documentation. The name of this file in the fossil source tree is "www/embeddeddoc.wiki". You are perhaps looking at this file using the URL:
http://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki.
The first part of this path, the "http://fossil-scm.org/home", is the base URL. You might have originally typed: http://fossil-scm.org/. The web server at the fossil-scm.org site automatically redirects such links by appending "home". The "home" file on fossil-scm.org is really a CGI script which runs the fossil web service in CGI mode. The "home" CGI script looks like this:
#!/usr/bin/fossil repository: /fossil/fossil.fossil
This is one of the many ways to set up a Fossil server.
The "/trunk/" part of the URL tells fossil to use the documentation files from the most recent trunk check-in. If you wanted to see an historical version of this document, you could substitute the name of a check-in for "/trunk/". For example, to see the version of this document associated with check-in [9be1b00392], simply replace the "/trunk/" with "/9be1b00392/". You can also substitute the symbolic name for a particular version or branch. For example, you might replace "/trunk/" with "/experimental/" to get the latest version of this document in the "experimental" branch. The symbolic name can also be a date and time string in any of the following formats:
- YYYY-MM-DD
- YYYY-MM-DDTHH:MM
- YYYY-MM-DDTHH:MM:SS
When the symbolic name is a date and time, fossil shows the version of the document that was most recently checked in as of the date and time specified. So, for example, to see what the fossil website looked like at the beginning of 2010, enter:
http://fossil-scm.org/home/doc/2010-01-01/www/index.wiki
The file that encodes this document is stored in the fossil source tree under the name "www/embeddeddoc.wiki" and so that name forms the last part of the URL for this document.
As I sit writing this documentation file, I am testing my work by running the "fossil ui" command line and viewing http://localhost:8080/doc/ckout/www/embeddeddoc.wiki in Firefox. I am doing this even though I have not yet checked in the "www/embeddeddoc.wiki" file for the first time. Using the special "ckout" version identifier on the "/doc" page it is easy to make multiple changes to multiple files and see how they all look together before committing anything to the repository.