4b826eed14 2008-05-19 drh: <h1>Managing Project Documentation</h1> 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: Fossil provides a built-in wiki which can be used to store the 4b826eed14 2008-05-19 drh: documentation for a project. This is sufficient for many projects. 4b826eed14 2008-05-19 drh: If your project is well-served by wiki documentation, then you 4b826eed14 2008-05-19 drh: need read no further. 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: But fossil also supports embedding project documentation as 4b826eed14 2008-05-19 drh: files in the source tree. There are several potential advantages 4b826eed14 2008-05-19 drh: to this approach: 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: 1. The documentation files are versioned together with the 4b826eed14 2008-05-19 drh: source code files so it is always clear what version of 4b826eed14 2008-05-19 drh: the documentation goes with a particular release. 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: 2. The documentation files can be edited using your favorite 4b826eed14 2008-05-19 drh: text editor instead of having to use the web-based wiki 4b826eed14 2008-05-19 drh: editor. 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: 3. Only people with check-in privileges can modify the documentation. 4b826eed14 2008-05-19 drh: (This might be either an advantage or disadvantage, depending 4b826eed14 2008-05-19 drh: on the nature of your project.) 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: We will call documentation is included as files in the source tree 4b826eed14 2008-05-19 drh: "embedded documentation". 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: <h2>Fossil Support For Embedded Documentation</h2> 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: The fossil web interface supports embedded documentation using 4b826eed14 2008-05-19 drh: the "/doc" page. To access embedded documentation, one points 4b826eed14 2008-05-19 drh: a web browser to a fossil URL of the following form: 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: <blockquote> 4b826eed14 2008-05-19 drh: <i><baseurl></i><big><b>/doc/</b></big><i><version></i><big><b>/</b></big><i><filename></i> 4b826eed14 2008-05-19 drh: </blockquote> 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: The <i><baseurl></i> is the main URL used to access the fossil web server. 4b826eed14 2008-05-19 drh: For example, the <i><baseurl></i> for the fossil project itself is 4b826eed14 2008-05-19 drh: either <b>http://www.fossil-scm.org/fossil</b> or 4b826eed14 2008-05-19 drh: <b>http://www.hwaci.com/cgi-bin/fossil</b>. 4b826eed14 2008-05-19 drh: If you launch the web server using the "<b>fossil server</b>" command line, 4b826eed14 2008-05-19 drh: then the <i><baseurl></i> is usually 4b826eed14 2008-05-19 drh: <b>http://localhost:8080/</b>. 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: The <i><version></i> is any unique UUID prefix of the baseline 4b826eed14 2008-05-19 drh: for the documentation you want to access. 4b826eed14 2008-05-19 drh: Or <i><version></i> can be one of the keywords "<b>tip</b>" or 4b826eed14 2008-05-19 drh: "<b>ckout</b>". The "<b>tip</b>" keyword means to use the most recently 4b826eed14 2008-05-19 drh: checked-in baseline. This is useful if you want to see the very latest 4b826eed14 2008-05-19 drh: version of the documentation. The "<b>ckout</b>" keywords means to 4b826eed14 2008-05-19 drh: pull the documentation file from the local source tree on disk, not 4b826eed14 2008-05-19 drh: from the any versioned baseline. The "<b>ckout</b>" keyword normally 4b826eed14 2008-05-19 drh: only works when you start your server using the "<b>fossil server</b>" 4b826eed14 2008-05-19 drh: command line and is intented to show what the documenation you are currently 4b826eed14 2008-05-19 drh: editing looks like before you check it in. 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: Finally, the <i><filename></i> element of the URL is the full 4b826eed14 2008-05-19 drh: pathname of the documentation file starting from the root of the source 4b826eed14 2008-05-19 drh: tree. 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: The mimetype (and thus the rendering) of documentation files is 4b826eed14 2008-05-19 drh: determined by the file suffix. Fossil currently understands the 4b826eed14 2008-05-19 drh: following file suffixes or embedded documents: 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: * .css 4b826eed14 2008-05-19 drh: * .gif 4b826eed14 2008-05-19 drh: * .htm 4b826eed14 2008-05-19 drh: * .html 4b826eed14 2008-05-19 drh: * .jpg 4b826eed14 2008-05-19 drh: * .jpeg 4b826eed14 2008-05-19 drh: * .png 4b826eed14 2008-05-19 drh: * .txt 4b826eed14 2008-05-19 drh: * .wiki 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: Documentation files whose names end in ".wiki" use the e65e669148 2008-05-24 drh: [/wiki_rules | same markup as wiki pages] - 4b826eed14 2008-05-19 drh: a safe subset of HTML together with some rules for paragraph 4b826eed14 2008-05-19 drh: breaks, lists, and hyperlinks. The ".wiki" and ".txt" pages 4b826eed14 2008-05-19 drh: are rendered with the standard fossil header and footer added. 4b826eed14 2008-05-19 drh: All other mimetimes are delivered directly to the requesting 4b826eed14 2008-05-19 drh: web browser with interpretation, additions, or changes. 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: The list of allowed suffixes for embedded documents is likely to 4b826eed14 2008-05-19 drh: grow and become user-configurable in future releases of fossil. 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: <h2>Examples</h2> 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: This file that you are currently reading is an example of 4b826eed14 2008-05-19 drh: embedded documentation. The name of this file in the fossil 4b826eed14 2008-05-19 drh: source tree is "<b>www/embeddeddoc.wiki</b>". 4b826eed14 2008-05-19 drh: You are perhaps looking at this 4b826eed14 2008-05-19 drh: file using the URL: 4b826eed14 2008-05-19 drh: [http://www.fossil-scm.org/index.html/doc/tip/www/embeddeddoc.wiki]. 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: The first part of this path, the "[http://www.fossil-scm.org/index.html]", 4b826eed14 2008-05-19 drh: is the base URL. You might have originally typed: 4b826eed14 2008-05-19 drh: [http://www.fossil-scm.org/]. The web server at the www.fossil-scm.org 4b826eed14 2008-05-19 drh: site automatically redirects such links by appending "index.html". The 4b826eed14 2008-05-19 drh: "index.html" file on www.fossil-scm.org is really a CGI script 4b826eed14 2008-05-19 drh: (do not be mislead by the name) which runs the fossil web service in 4b826eed14 2008-05-19 drh: CGI mode. The "index.html" CGI script looks like this: 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: <blockquote><pre> 4b826eed14 2008-05-19 drh: #!/usr/bin/fossil 4b826eed14 2008-05-19 drh: repository: /fossil/fossil.fossil 4b826eed14 2008-05-19 drh: </pre></blockquote> 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: This is one of three ways to set up a 4b826eed14 2008-05-19 drh: <a href="quickstart.wiki#serversetup">fossil web server</a>. 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: The "<b>/tip/</b>" part of the URL tells fossil to use 4b826eed14 2008-05-19 drh: the documentation files from the baseline that was checked in most 4b826eed14 2008-05-19 drh: recently. This file is stored in the fossil source tree under 4b826eed14 2008-05-19 drh: the name "<b>www/embeddeddoc.wiki</b>" and so that name forms the 4b826eed14 2008-05-19 drh: last part of the URL. 4b826eed14 2008-05-19 drh: 4b826eed14 2008-05-19 drh: As I sit writing this documentation file, I am testing my work by 4b826eed14 2008-05-19 drh: running the "<b>fossil server</b>" command line and viewing 4b826eed14 2008-05-19 drh: <b>http://localhost:8080/doc/ckout/www/embeddeddoc.wiki</b> in 4b826eed14 2008-05-19 drh: Firefox. I am doing this even though I have not yet checked in 4b826eed14 2008-05-19 drh: the "<b>www/embeddeddoc.wiki</b>" file for the first time. Using 4b826eed14 2008-05-19 drh: the special "<b>ckout</b>" version identifier on the "<b>/doc</b>" page 4b826eed14 2008-05-19 drh: it is easy to make multiple changes to multiple files and see how they all 4b826eed14 2008-05-19 drh: look together before committing anything to the repository.
File Annotation