Artifact 97f93908600bdd2dc3f0b52ecf2f81b80c1b2d4d
File www/embeddeddoc.wiki part of check-in [4b826eed14] - Add a page describing how to do embedded documentation. by drh on 2008-05-19 15:10:55.
Managing Project Documentation
Fossil provides a built-in wiki which 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 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 UUID prefix of the baseline for the documentation you want to access. Or <version> can be one of the keywords "tip" or "ckout". The "tip" keyword means to use the most recently checked-in baseline. 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 versioned baseline. The "ckout" keyword normally only works when you start your server using the "fossil server" command line and is intented to show what the documenation you are currently editing looks like before you check it in.
Finally, the <filename> element of the URL is the full pathname of the documentation file starting from the root of the source tree.
The mimetype (and thus the rendering) of documentation files is determined by the file suffix. Fossil currently understands the following file suffixes or embedded documents:
- .css
- .gif
- .htm
- .html
- .jpg
- .jpeg
- .png
- .txt
- .wiki
Documentation files whose names end in ".wiki" use the same markup as wiki pages - a safe subset of HTML together with some rules for paragraph breaks, lists, and hyperlinks. The ".wiki" and ".txt" pages are rendered with the standard fossil header and footer added. All other mimetimes are delivered directly to the requesting web browser with interpretation, additions, or changes.
The list of allowed suffixes for embedded documents is likely to grow and become user-configurable in future releases of fossil.
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/tip/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 three ways to set up a fossil web server.
The "/tip/" part of the URL tells fossil to use the documentation files from the baseline that was checked in most recently. This file is stored in the fossil source tree under the name "www/embeddeddoc.wiki" and so that name forms the last part of the URL.
As I sit writing this documentation file, I am testing my work by running the "fossil server" 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.