NAME
dwww - access documentation via WWW
SYNOPSIS
http://localhost/dwww/index.html
DESCRIPTION
A typical Linux system has documentation in many formats (manual pages,
Info files, READMEs, and so on). dwww makes it possible to access all
of these via the same interface, a WWW browser. This makes it easier
to use the documentation.
dwww consists of several programs:
cgi-bin/dwww
Run by the WWW server when user requests document via dwww.
Parses the request and runs dwww-convert(8) or dwww-find(8) with
suitable arguments. Installed in the server’s cgi-bin
directory.
dwww-convert(8)
Converts any document to HTML.
dwww-format-man(8)
Auxiliary program to convert man pages or text files to HTML.
dwww-find(8)
Searches for documentation.
dwww-quickfind(8)
Used by dwww-find(8) to quickly find which package a program
belongs to.
dwww-cache(8)
Manages the cache of converted documents.
dwww-refresh-cache(8)
Cleans outdated documents from the cache.
dwww-build(8)
Builds static lists of manual pages. Needs to be re-run
whenever documents are installed or removed. (In default
configuration is called by the dwww daily cron job).
dwww-build-menu(8)
Builds the Debian Documentation Menu pages. Needs to be re-run
whenever documents are installed or removed. (In default
configuration is called by the install-docs(8) or by the dwww
daily cron job).
dwww-index++(8)
Uses index++(1) to build index of the documentation registered
with doc-base. In default configuration is called be the dwww
weekly cron job.
For speed reasons, the converted documents are stored in
/var/cache/dwww. The cache is cleaned by dwww-refresh-cache(8) of old
documents to keep it from growing too large.
CONFIGURATION
dwww is configured via the /etc/dwww/dwww.conf file. That file is a
Bourne shell (/bin/sh) script that defines some or all the following
variables (defaults are used if the file doesn’t exist, or doesn’t
define the variable).
Basic configuration variables
These variables can be also configured by debconf script. You can
change them using the following command:
dpkg-reconfigure dwww
DWWW_SERVERNAME
Name of the www server. Default is localhost.
DWWW_SERVERPORT
Port on which the www server listen to. Default is 80.
DWWW_USEHTTPS
If enabled, dwww(1) will connect to
DWWW_SERVERNAME:DWWW_SERVERPORT through the HTTPS protocol.
Default is no.
DWWW_DOCROOTDIR
The document root for web server. Default is /var/www.
DWWW_CGIDIR
The directory which contains the CGI scripts for your web
server. Default is /usr/lib/cgi-bin.
DWWW_CGIUSER
Name of the user that the web server uses to execute CGI
scripts. Default is www-data.
Browser variables
DWWW_BROWSER
Web-browser used by dwww(1) to load dwww main page.
DWWW_X11_BROWSER
Web-browser used by dwww(1) to load dwww main page when in X11.
Path variables
DWWW_DOCPATH
Colon-delimited list of directories from which dwww-convert(8)
supplies files. For security reasons, it will refuse to convert
files outside the directories named by this variable. Default
is /usr/share/doc : /usr/doc : /usr/share/info : /usr/info :
/usr/share/man : /usr/man : /usr/X11R6/man : /usr/local/man :
/usr/local/doc : /usr/local/info : /usr/share/common-licenses.
DWWW_ALLOWEDLINKPATH
Colon-delimited list of directories which can be targets of
symlinks from files from directories inside DWWW_DOCPATH.
Default value is /usr/share:/usr/lib:/var/www.
For example, /usr/share/doc/package/foo.html may be symlinked to
a file /usr/share/package/foo.html, and this file can be
displayed by dwww.
Cache files locations
DWWW_QUICKFIND_DB
Location of the installed packages and programs cache file,
generated by dwww-refresh-cache(8) with the help of
dwww-quickfind(8). Default is /var/cache/dwww/quickfind.dat.
DWWW_DOCBASE2PKG_DB
Location of the cache file, which maps installed doc-base files
to packages names, used by the dwww-build-menu(8). Default is
/var/cache/dwww/docbase2pkg.dat.
DWWW_REGDOCS_DB
Location of doc-base registered documents contents cache. The
cache is generated by dwww-build-menu(8) and read by
dwww-find(8) Default is /var/cache/dwww/regdocs.dat.
Documentation indexing variables
DWWW_INDEX_DOCUMENTATION
If this variable is set to yes (default), and the swish++
package is installed, then dwww-index++(8) will generate index
of registered documentation.
DWWW_INDEX_FULL_TIME_INTERVAL
Specifies how often (in days) dwww-index++(8) will generate full
index of documentation. The default value is 28.
DWWW_INDEX_INCREMENTAL_TIME_INTERVAL
Specifies how often (in days) dwww-index++(8) will run
incremental indexing of new documentation files. The default
value is 7.
DWWW_MERGE_MAN2HTML_INDEX
If this variable is set to yes, then while generating index of
registered documents, dwww-index++(8) will use man pages index
generated by man2html package, if it’s available.
Other variables
DWWW_KEEPDAYS
How many days should dwww-refresh-cache(8) keep documents that
have not been accessed? Default is 10 days.
DWWW_TMPDIR
Directory used by dwww-build(8) and dwww-build-menu(8) to
temporally store the web pages it generates. Default is
/var/lib/dwww. For security reason any public writable
directory like /tmp should not be used.
DWWW_USEFILEURL
If this variable is set, dwww will use file:/ style URLs to
access html files - bypassing the CGI script. This is faster on
slow machines. Of course, you will not be able to read the html
documentation on a non-local machine. Default is to not enable
this feature.
DWWW_TITLE
Title to appear on dwww generated files. Default is dwww:
$(hostname)
DWWW_USE_CACHE
If this variable is set to yes (default), dwww will cache
accessed documents in /var/cache/dwww/db. See dwww-cache(8).
Deprecated variables
Since version 1.10, dwww no longer uses the following variables:
DWWW_HTMLDIR, DWWW_MAN2HTML, DWWW_TEXT2HTML, DWWW_DIR2HTML.
CUSTOMISING DWWW PAGES LAYOUT
dwww uses a CSS file for managing the layout of the pages it generates.
The file is built from two other files, namely
/usr/share/dwww/dwww.css, which is a global one, provided by the
package, and /etc/dwww/dwww-user.css, a local one, that can be provided
by the user to override settings from the former file. The latter file
does not exist by default, but when it exists, dwww-build(8) will
append its contents at the end of generated file. Since web browsers
tend to use the last one setting defined for a given CSS element, this
has the expected effect of customisation.
Example
To use some image as a background for dwww pages, please put something
like this in /etc/dwww/dwww-user.css:
body { background: url('http://host/path/to/background.png')
repeat; }
table,pre,code,tt { opacity: 0.7; }
Please make sure to run dwww-build(8) afterwards.
FILES
/etc/dwww/dwww.conf
Configuration file for dwww. It’s not necessary for this file
to exist, there are sensible defaults for everything.
/etc/dwww/apache.conf
Default configuration file for various apache-based web servers.
The dwww package post-installation script creates symlinks from
/etc/apache*/conf.d/dwww to this file.
/etc/dwww/dwww-user.css
If such a file exists, its contents will be appended to the
dwww.css file. This allows local administrators to customise
dwww pages layout.
/etc/cron.daily/dwww
Dwww daily cron job, which rebuilds cache directory and dwww
HTML pages.
/etc/cron.weekly/dwww
Dwww weekly cron job. Uses dwww-index++(8) to rebuild registered
documentation index.
/var/cache/dwww
Directory, where are placed various cache files generated and
used by dwww.
/var/cache/dwww/db
Cache for the converted documents.
/usr/share/dwww
Templates for the dwww web pages (used by dwww-build(8) and
others).
/var/lib/dwww
The dwww pages. The server’s document root directory should
have a link to this directory.
SEE ALSO
dwww(1), dwww-build(8), dwww-build-menu(8), dwww-cache(8),
dwww-convert(8), dwww-find(8), dwww-format-man(8), dwww-index++(8),
dwww-quickfind(8), dwww-refresh-cache(8), dwww-txt2html(8).
AUTHOR
Originally by Lars Wirzenius <liw@iki.fi>. Modified by Jim Pick
<jim@jimpick.com> and Robert Luberda <robert@debian.org>. Bugs should
be reported via the normal Debian bug reporting system, see
/usr/share/doc/debian/bug-reporting.txt file or reportbug(1) man page.
dwww is licensed via the GNU General Public License. While it has been
written for Debian, porting it to other systems is strongly encouraged.
