Overview
| SHA1 Hash: | 5c65487c5f5cfc8970a4fdd8ad6b2d400faefe7c |
|---|---|
| Date: | 2009-01-25 23:30:07 |
| User: | drh |
| Comment: | Add documentation (advocacy-type documentation) on the fossil web interface. Created links from the homepage. |
| Timelines: | ancestors | descendants | both | trunk |
| Other Links: | files | ZIP archive | manifest |
Tags And Properties
- branch=trunk inherited from [a28c83647d]
- sym-trunk inherited from [a28c83647d]
Changes
[hide diffs]Modified www/embeddeddoc.wiki from [b0c6d59681] to [f65cddb5e8].
@@ -1,6 +1,6 @@ -<h1>Managing Project Documentation</h1> +<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 @@ -99,17 +99,29 @@ 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. This file is stored in the fossil source tree under +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. +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.
Modified www/index.wiki from [2046c07523] to [786913c0b4].
@@ -28,14 +28,13 @@
<a href="http://subversion.tigris.org/">subversion</a>,
<li>Or, operations on local repositories,
<li>Or, all of the above at the same time</ul>
* Integrated, [./bugtheory.wiki | distributed bug tracking] and
[./wikitheory.wiki | distributed wiki].
- * Built-in web interface that supports deep archaeological digs through
- the project history.
- * All network communication via
- [http://en.wikipedia.org/wiki/HTTP | HTTP] with
+ * Built-in [./webui.wiki | web interface] that supports deep
+ archaeological digs through the project history.
+ * All network communication via HTTP with
[./quickstart.wiki#proxy | proxy support]
so that everything works from behind restrictive firewalls.
* Everything (client, server, and utilities) is included in a
single self-contained executable - trivial to install
* Server runs as [./quickstart.wiki#cgiserver | CGI], using
@@ -55,12 +54,14 @@
<b>User Links:</b>
* [./faq.wiki | FAQ]
* The [./concepts.wiki | concepts] behind fossil
- * [./build.wiki | Building And Installing]
* [./quickstart.wiki | Quick Start] guide to using fossil
+ * [./reviews.wiki | Testimonials] from fossil users.
+ * [./qandc.wiki | Questions & Criticisms] directed at fossil.
+ * [./build.wiki | Building And Installing]
* Fossil supports [./embeddeddoc.wiki | embedded documentation]
that is versioned along with project source code.
* A tutorial on [./branching.wiki | branching], what it means and how
to do it using fossil.
* The [./selfcheck.wiki | automatic self-check] mechanism
@@ -67,12 +68,10 @@
helps insure project integrity.
* Fossil contains a [./wikitheory.wiki | built-in wiki].
* There is a
[http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users | mailing list]
available for discussing fossil issues.
- * [./qandc.wiki | Questions & Criticisms] directed at fossil.
- * [./reviews.wiki | Testimonials] from fossil users.
* Some (unfinished but expanding) extended
[./reference.wiki | reference documentation] for the fossil command line.
<b>Developer Links:</b>
Added www/webui.wiki version [5308e376e1]
@@ -1,1 +1,165 @@ +<h1 align="center">The Fossil Web Interface</h1> + +One of the innovative features of fossil is its built-in web interface. +This web interface provides everything you need to run a software +development project: + + * [./bugtheory.wiki | Ticketing and bug tracking] + * [./wikitheory.wiki | Wiki] + * [./embeddeddoc.wiki | On-line documentation] + * Status information + * Timelines + * File and version lists and differences + * Historical change data + * Links to download historical versions as ZIP archives + +You get all of this, and more, for free when you use fossil. +There are no extra programs to install or setup. +Everything you need is already pre-configured and built into the +self-contained, stand-alone fossil executable. + +As an example of how useful this web interface can be, +the entire [./index.wiki | fossil website] (except for the +[http://www.fossil-scm.org/download.html | precompiled binary download page]), +including the document you are now reading, +is rendered using the stock fossil web interface, with no enhancements, +and little customization. + +Note also that because fossil is a distribute system, you can run +the web interface on your local machine while off network (for example, +while on an airplane) including +making changes to wiki pages and/or trouble ticket, then synchronize with your +co-workers after you reconnect. + +<h2>Drop-Dead Simple Startup</h2> + +To start using the built-in fossil web interface on an existing fossil +repository, simply type this: + + <b>fossil ui existing-repository.fossil</b> + +Substitute the name of your repository, of course. +The "ui" command will start a webserver running (it figures out an +available TCP port to use on its own) and then automatically launches +your web browser to point at that server. If you run the "ui" command +from within an open check-out, you can omit the repository name: + + <b>fossil ui</b> + +The latter case is a very useful short-cut when you are working on a +fossil project and what to quickly do some work with the interface. +Notice that fossil automatically finds an unused TCP port to run the +server own and automatically points your web browser to the correct +URL. So there is never any fumbling around trying to find an open +port or to type arcane strings into your browser URL entry box. +The interface just pops right up, ready to run. + +The fossil web interface is also very easy to setup and run on a +network server, as either a CGI program or from inetd. Details on how +to do that are described further below. + +<h2>Things To Do Using The Web Interface</h2> + +You can view <b>timelines</b> of changes to the project. The default +"Timeline" link on the menu bar takes you to a page that shows the 20 +most recent check-ins, wiki page edits, and ticket/bug-report changes. +This gives a very useful snapshot of what has been happening lately on the +project. You can click to go further back in time, if needed. Or +follow hyperlinks to see details, including diffs and annotated diffs, +of individual check-ins, wiki page edits, or ticket changes. + +You can view and edit <b>tickets and bug reports</b> by following the +"Tickets" link on the menu bar. +Fossil is backed by an SQL database, so users with appropriate permissions +can write new ticket report formats based on SQL query statements. +Fossil is careful to prevent ticket report formats from doing any mischief +on the database (it only allows SELECT statements to run) and it restricts +access to sensitive data such as user passwords. So it is actually safe +to let anonymous users on the internet write their own ticket formats if +you like. In addition to viewing and/or creating report formats, you can +also create new tickets or look at summaries or complete histories of +existing tickets. Any changes you make will automatically merge with +changes from your co-workers the next time your repository is synchronized. + +You can view and edit <b>wiki</b> by following the "Wiki" link on the +menu bar. Fossil uses simple and easy-to-remember +[/wiki_rules | wiki formatting rules] so you won't have to spend a lot +of time learning a new markup language. And, as with tickets, all of +your edits will automatically merge with those of your co-workers when +your repository synchronizes. + +You can view summary reports of <b>leaves and branches</b> in the +check-in graph by visiting the "Leaves" or "Branches" links on the +menu bar. From those pages you can follow hyperlinks to get additional +details. These screens allow you to easily keep track of what is going +on with separate subteams within your project team. + +The "Files" link on the menu allows you to browse though the <b>file +hierarchy</b> of the project and to view complete changes histories on +individual files, with hyperlinks to the check-ins that made those +changes, and with diffs and annotated diffs between versions. + +The web interface supports [./embeddeddoc.wiki | embedded documentation]. +Embedded documentation is documentation files (usually in wiki format) +that are checked into project as part of the source tree. Such files +can be viewed as if they were ordinary web pages. This document that +you are now reading is an example of embedded documentation. + +<h2>Customizing The Web Interface Appearance</h2> + +Users with appropriate permissions can customize the look and feel of +the web interface using the "Admin" link on the main menu of the web +interface. Templates +for the header and footer of each page can be edited, as can the CSS +for the entire page. You can even change around the main menu. +Timeline display preferences can be edited. The page that is brought +up as the "Home" page can be changed. It is often useful to set the +"Home" page to be a wiki page or an embedded document. + +<h2>Installing On A Network Server</h2> + +When you create a new fossil project and after you have configured it +like you want it using the web interface, you can make the project +available to a distributed team by simply copying the single +repository file up to a web server that supports CGI. Just put the +<b>sample-project.fossil</b> file in a directory where CGI scripts +have both read and write permission on the file and the directory that +contains the file, then add a CGI script that looks something like this: + + <verbatim> + #!/usr/local/bin/fossil + repository: /home/www/sample-project.fossil + </verbatim> + +Adjust the script above so that the paths are correct for your system, +of course, and also make sure the fossil binary is installed on the server. +But that is <u>all</u> you have to do. You now have everything you need to host +a distributed software development project in less than five minutes using a +two-line CGI script. + +You don't have a CGI-capable web server running on your server machine? +Not a problem. The fossil interface can also be launched via inetd or +xinetd. An inetd configuration line sufficient to launch the fossil +web interface looks like this: + + <verbatim> + 80 stream tcp nowait.1000 root /usr/local/bin/fossil \ + /usr/local/bin/fossil http /home/www/sample-project.fossil + </verbatim> + +As always, you'll want to adjust the pathnames to whatever is appropriate +for your system. The xinetd setup uses a different syntax but follows +the same idea. + +Once you have your new repository running on the network server, delete +the original repository from your local machine, then clone the repository +off of the server: + + <b>fossil clone http://user:password@myserver.org/cgi-bin/my-project</b> +(As always, adjust the URL as appropriate for your installation.) +After copying a repository, it is important to reclone it onto new machines. +Each repository has a random "repository ID" and repositories will not +sync with another repository having the same ID (to avoid sync loops). +Cloning the repository will give you a new repository ID in your local +copy and allow you to sync with the server.