Fossil: Project Documentation

Fossil SCM

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:

  1. 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.
  1. The documentation files can be edited using your favorite text editor instead of having to use the web-based wiki editor.
  1. 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".

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 either http://www.fossil-scm.org/fossil or http://www.hwaci.com/cgi-bin/fossil. If you launch the web server using the "fossil server" command line, then the <baseurl> is usually http://localhost:8080/.

The <version> is any unique prefix of the check-in ID for the check-in containing the documentation you want to access. Or <version> can be the name of a branch in order to show the documentation for the latest version of that branch. Or <version> can be one of the keywords "tip" or "ckout". The "tip" keyword means to use the most recent check-in. This is useful if you want to see the very latest version of the documentation. 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 normally only works when you start your server using the "fossil server" or "fossil ui" command line and is intended to show what the documentation you are currently editing looks like before you check it 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.

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 the text of the Index Of Fossil Documentation document.

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.

Server-Side Text Substitution

Fossil can do a few types of substitution of server-side information into the embedded document.

1. $ROOT

To allow for repositories served deeper than the root of the URL hierarchy, Fossil can substitute the repository's root in the URL scheme into HTML href and action attributes. For example:

        [$ROOT/doc.wiki | doc at project root]

might become this in the rendered HTML:

        <a href="/project/root/doc.wiki">doc at project root</a>

As you can see, this happens for all source document types that end up rendering as HTML, not just source documents in the HTML fossil-doc format described at the end of the prior section.

2. 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.

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://www.fossil-scm.org/index.html/doc/trunk/www/embeddeddoc.wiki.

The first part of this path, the "http://www.fossil-scm.org/index.html", is the base URL. You might have originally typed: http://www.fossil-scm.org/. The web server at the www.fossil-scm.org site automatically redirects such links by appending "index.html". The "index.html" file on www.fossil-scm.org is really a CGI script (do not be mislead by the name) which runs the fossil web service in CGI mode. The "index.html" 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:

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://www.fossil-scm.org/index.html/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.