DWWW(8)

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) with suitable arguments. Installed in the server's cgi-bin directory.

dwww-convert(8)
    Converts any document to HTML.

dwww-cache(8)
    Manages the cache of converted documents.

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 update-menus(1) program or by the dwww daily 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_DOCROOTDIR
    The document root for web server.

DWWW_CGIDIR
    The directory which contains the CGI scripts for your web server.

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.

  Converters

DWWW_MAN2HTML
    Command to convert a manual page to HTML. Default is builtin_man2html, which uses dwww-txt2html(8) to convert man pages.
    If you have man2html(1) installed and would prefer to use it, please add the following code to dwww's configuration file:
    if [ -x /usr/lib/cgi-bin/man/man2html ] ; then
        man2html_cmd () {
            /usr/lib/cgi-bin/man/man2html "$1"
        }
        DWWW_MAN2HTML=man2html_cmd
    elif [ -x /usr/lib/cgi-bin/man2html ] ; then
        man2html_cmd () {
            /usr/lib/cgi-bin/man2html "$1"
        }
        DWWW_MAN2HTML=man2html_cmd
    fi

DWWW_TEXT2HTML
    Command to convert a plain text file to HTML. Default is builtin_text2html.

DWWW_DIR2HTML
    Command to show contents of a directory as HTML. Default is builtin_dir2html.

The converters get the filename as their argument, and should output the converted document to stdout.

  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.

  Other variables

DWWW_KEEPDAYS
    How many days should dwww-refresh-cache(8) keep documents that have not been accessed? Default is 10 days.

DWWW_HTMLDIR
    Directory where dwww-build(8) stores the web pages it generates. Default is /var/lib/dwww.

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).

DWWW_INDEX_DOCUMENTATION
    If this variable is set to yes (default), and the swish++ package is installed, then dwww-index++ will generate index of registered documentation.

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.

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 postinstalation script creates symlinks from /etc/apache*/conf.d/dwww to this file.

/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.