Using fossil embedded documents

Question

I'm using fossil to manage some home projects and keeping notes in the wiki. After running like this for a few months, I'd like to at least try to use embedded documentation; mainly so as to be able easily to go back to previous versions.

I've studied the website page about managing project documentation which confirms that this is a technique I want to follow up, but I can't make out how to do it.

I've cut-and-pasted one of my wiki pages and added it to my fossil repo, but I can't work out where it should go in the directory structure to be accessible as described on the above page.

I've tried in a few places none of which worked. The document is currently %fossil-root%\doc\foo.wiki, (I'm on Windows), where %fossil-root% is the directory holding _ _FOSSIL__ (slighly mangled filename because of markdown), but having started a server with fossil ui, when I point my browser at http://localhost:8080/doc/foo.wiki, fossil presents me with a nicely formatted page saying it can't find index.html. I created /doc/index.html to see what would happen, but it made no difference.

Please can someone help me out, and/or point me to an example repository containing embedded documentation or another "how-to" document.

Answer 1

If your document is located in %fossil-root%\doc\foo.wiki, you can access it at the following URL:

http://localhost:8080/doc/trunk/doc/foo.wiki

This URL breaks down as follows:

• http://localhost:8080 is the root URL to access Fossil when you run fossil ui
• /doc signals that you want to access embedded documentation
• /trunk indicates the checkin containing the documentation you wish to access
• /doc/foo.wiki is the path of the document inside the repository

Instead of trunk, you can also specify a tag, or a branch name, or even a hexadecimal checkin identifier.

In the URL you were using, http://localhost:8080/doc/foo.wiki, foo.wiki is interpreted as the checkin name, and no document path is specified, which logically means Fossil won't find anything.

As for an example repository containing embedded documentation, the homepage of the Fossil website itself is a prime example:

https://www.fossil-scm.org/index.html/doc/trunk/www/index.wiki

where

• https://www.fossil-scm.org/index.html is Fossil's root URL
• /doc indicates a request for embedded documentation
• /trunk indicates we want to fetch files from the trunk
• /www/ is the path to the requested file inside the repository
• index.wiki is the name of the file inside the repository.

So, in the 'trunk' branch of the repository, the file www/index.wiki contains the home page of the Fossil website.

Answer 2

You simply need to put the documentation under the %fossil-root%\www\ directory (or any other directory under version control) in your repository and then you can, for example, add the following line to your header's mainmenu section to link to it:

html "<a href='$home/doc/trunk/www/foo.wiki'>Documentation</a>\n"

As I said, it can be any directory under version control. To test this, pick any file in the repository, let's say a README file at the top level, and go to http://localhost:8080/doc/trunk/README. You should see the README file load up in your browser in a raw text format. By putting wiki or html files under a particular directory such as www you make it easy to organize the files that you specifically want rendered as documentation, which makes it easier to link to them.

Answer 3

http://www.fossil-scm.org/index.html/doc/trunk/www/embeddeddoc.wiki

After fossil 1.33, just prepare your document in the repository. If the wiki file is put in

/doc/index.wiki

And use web browser to setup -> Admin -> Configuration. There is a "Index Page" field, fill in your main index.html. For example:

/doc/trunk/doc/index.wiki

Or if you just want the released version:

/doc/<version>/doc/index.wiki