Artifact 0522d4b67268ba68ed3195adaf9262734d364129
File
www/embeddeddoc.wiki
part of check-in
[5523218023a]
- Add <title> markup to several of the embedded documentation pages.
by
drh on
2009-08-24 17:54:24.
<title>Managing Project Documentation</title>
<h1 align="center">Managing Project Documentation</h1>
Fossil provides a built-in <a href="wikitheory.wiki">wiki</a>
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.
2. The documentation files can be edited using your favorite
text editor instead of having to use the web-based wiki
editor.
3. 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".
<h2>Fossil Support For Embedded Documentation</h2>
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:
<blockquote>
<i><baseurl></i><big><b>/doc/</b></big><i><version></i><big><b>/</b></big><i><filename></i>
</blockquote>
The <i><baseurl></i> is the main URL used to access the fossil web server.
For example, the <i><baseurl></i> for the fossil project itself is
either <b>http://www.fossil-scm.org/fossil</b> or
<b>http://www.hwaci.com/cgi-bin/fossil</b>.
If you launch the web server using the "<b>fossil server</b>" command line,
then the <i><baseurl></i> is usually
<b>http://localhost:8080/</b>.
The <i><version></i> is any unique prefix of the check-in ID for
the check-in containing the documentation you want to access.
Or <i><version></i> can be the name of a
[./branching.wiki | branch] in order to show
the documentation for the latest version of that branch.
Or <i><version></i> can be one of the keywords "<b>tip</b>" or
"<b>ckout</b>". The "<b>tip</b>" keyword means to use the most recently
checked-in. This is useful if you want to see the very latest
version of the documentation. The "<b>ckout</b>" keywords means to
pull the documentation file from the local source tree on disk, not
from the any check-in. The "<b>ckout</b>" keyword normally
only works when you start your server using the "<b>fossil server</b>"
or "<b>fossil ui</b>"
command line and is intended to show what the documentation you are currently
editing looks like before you check it in.
Finally, the <i><filename></i> 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 192
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
[/wiki_rules | 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 mimetypes are delivered directly to the requesting
web browser without interpretation, additions, or changes.
<h2>Examples</h2>
This file that you are currently reading is an example of
embedded documentation. The name of this file in the fossil
source tree is "<b>www/embeddeddoc.wiki</b>".
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:
<blockquote><pre>
#!/usr/bin/fossil
repository: /fossil/fossil.fossil
</pre></blockquote>
This is one of three ways to set up a
<a href="quickstart.wiki#serversetup">fossil web server</a>.
The "<b>/tip/</b>" part of the URL tells fossil to use
the documentation files from the check-in that was checked in most
recently. If you wanted to see an historical version of this document,
you could substitute the name of a check-in for "<b>/tip/</b>".
For example, to see the version of this document associated with
check-in [9be1b00392], simply replace the "<b>/tip/</b>" with
"<b>/9be1b00392/</b>". You can also substitute the symbolic name
for a particular version or branch. For example, you might
replace "<b>/tip/</b>" with "<b>/trunk/</b>" to get the latest
version of this document in the "trunk" branch. (As of this writing,
the self-hosting fossil repository only has a single branch "trunk" and
so "trunk" and "tip" amount to the same thing, but they would be different
in a project with multiple branches.)
The file that encodes this document is stored in the fossil source tree under
the name "<b>www/embeddeddoc.wiki</b>" 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 "<b>fossil server</b>" command line and viewing
<b>http://localhost:8080/doc/ckout/www/embeddeddoc.wiki</b> in
Firefox. I am doing this even though I have not yet checked in
the "<b>www/embeddeddoc.wiki</b>" file for the first time. Using
the special "<b>ckout</b>" version identifier on the "<b>/doc</b>" page
it is easy to make multiple changes to multiple files and see how they all
look together before committing anything to the repository.