xenial (7) dwww.7.gz

Provided by: dwww_1.13.1_amd64 bug

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/share/info:/usr/share/man:
              /usr/local/share/doc:/usr/local/share/info:/usr/local/share/man: /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:/usr/local/share:/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.