initial commitHEADmaster

1 files changed, 181 insertions, 0 deletions

diff --git a/www/webui.wiki b/www/webui.wiki
new file mode 100644
index 0000000..f0126d7
--- /dev/null
+++ b/www/webui.wiki
@@ -0,0 +1,181 @@
+<title>The Fossil Web Interface</title>
+
+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]
+  *  [./event.wiki | Technical notes]
+  *  [./forum.wiki | Forum]
+  *  [./chat.md | Chatroom]
+  *  Timelines
+  *  Full text search over all of the above
+  *  Status information
+  *  Graphs of revision and branching history
+  *  File and version lists and differences
+  *  Download historical versions as ZIP archives
+  *  Historical change data
+  *  Add and remove tags on check-ins
+  *  Move check-ins between branches
+  *  Revise check-in comments
+  *  Manage user credentials and access permissions
+  *  And so forth... (some [./webpage-ex.md|examples])
+
+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],
+including the document you are now reading,
+is rendered using the Fossil web interface, with no enhancements,
+and little customization.
+
+<div class="indent">
+<b>Key point:</b> <i>The Fossil website is just a running instance
+of Fossil!
+</div>
+
+Note also that because Fossil is a distributed 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.  When you clone a Fossil repository, you
+don't just get the project source code, you get the entire project
+management website.
+
+<h2>Very Simple Startup</h2>
+
+To start using the built-in Fossil web interface on an existing Fossil
+repository, simply type this:
+
+<pre>fossil ui existing-repository.fossil</pre>
+
+Substitute the name of your repository, of course.
+The "ui" command will start a web server 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:
+
+<pre>fossil ui</pre>
+
+The latter case is a very useful short-cut when you are working on a
+Fossil project and you want to quickly do some work with the web interface.
+Notice that Fossil automatically finds an unused TCP port to run the
+server on 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, or as an
+SCGI server.  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, ticket/bug-report changes,
+and/or blog entries.
+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, ticket changes, and
+blog edits.
+
+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 has its own easy-to-remember
+[/wiki_rules | markup rules], or if you prefer,  it also
+supports [/md_rules | Markdown]. 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>branches</b> in the
+check-in graph by visiting the "Branches" link 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 sub-teams within your project team.
+
+The "Files" link on the menu allows you to browse through 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]
+files (usually in wiki format) that are checked into the 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. The built-in
+pages <b>/home</b> and <b>/index</b> can be used as the "Home" page.
+They have identical effect, which is to instruct Fossil to find and
+display a wiki page with the same name as the project, or if that
+does not exist, <b>/README.md</b> or <b>/index.wiki</b>.
+
+An embedded document link such as <b>doc/trunk/README.md</b> can be
+used for the "Home" page. If you specify one of the built-in keywords
+<b>/home</b> or <b>/index</b>, the page will not be treated as 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 or SCGI.  To
+run Fossil as 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.
+
+Instructions for setting up an SCGI server are
+[./scgi.wiki | available separately].
+
+You don't have a CGI- or SCGI-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.