README for dwww
                              ``To boldly go where no doc has gone before''
---------------------------------------------------------------------------

dwww is a web interface to all on-line documentation on a
Debian system.  It builds some web pages that list all installed
documents, and converts all documents to HTML. The conversion
is done when the user requests the document.  A future version
will support several ways of searching for documents.

dwww requires running a web server. Sorry.

For more information, read the manual page dwww(8), and the other
manual pages it refers to.


  Automatic fancy index of documents
--------------------------------------

[NOTE: Debian now has a "doc-base" package that provides a uniform way of
registering documenation; it supports other documentation systems besides dwww;
please consider using rather than this dwww-specific approach.]

dwww can build a fancy document index. The index is built from files
installed as </usr/doc/*/.dwww-index>. (Support for locale-dependent
and locally installed indexes will follow shortly.) The index file
should contain one or more entries in the following format:

	#section SECTION
	<dt><a href="RELATIVEHREF">TITLE</a>
	<dd>DESCRIPTION

The "#section" must be at the beginning of the line, and be
in lower case. "SECTION" is one word giving the section in the
index for the document; allowed values are

	admin		system administration info
	programming	programming info
	general		other info

These names are symbolic; the user will see a more descriptive name.

More sections will be added later. If unsure about which section
to put a document in, or if you want a new section, discuss on
debian-devel@lists.debian.org.

"RELATIVEHREF" is a link to the first file in the document,
relative to /usr/doc. For example, if the document is
in /usr/doc/hello/hello.html, RELATIVEHREF would be
"hello/hello.html".

"TITLE" should be the title of the document. If the title is very long,
it should be shortened.

"DESCRIPTION" is a few words describing the document. It is not necessary
to name the authors. The description should be short and to the point,
so that the index won't grow too big. Remember: a full Debian installation
has hundreds of packages.

dwww also builds a shorter index, which only has the titles.

If a directory below /usr/doc does not have a .dwww-index file (or
even if it does), then documentation in it can be accessed using
the "File listings" link from the dwww front page.

	 _				      _
	| 				       |
	    dwww is still under development!
	|_   				      _|


dwww is already quite usable, however.  Please use it, and report
bugs via the Debian bug tracking system so that they can be fixed.