dwww-convert(8) [debian man page]
DWWW-CONVERT(8) Debian DWWW-CONVERT(8) NAME
dwww-convert - convert files to HTML for dwww SYNOPSIS
dwww-convert [--no-path-info] type location DESCRIPTION
dwww-convert is part of the dwww package, which provides access to on-line documentation on a Debian system via WWW. dwww-convert converts documentation to HTML so that it can be viewed with a WWW browser. dwww-convert is usually run by the WWW server, but can also be run by hand. The type argument gives the type of the file, one of: file An arbitrary file; the type is guessed using simple heuristics based on the filename. dir A directory. If the directory contains the file index.html or index.htm that file will be returned. Otherwise, A listing of the files in the directory is generated. html An HTML file. The file is returned as is. man A manual page. The location is the pathname of the nroff source file. runman A manual page. The location is the name of the manual page and its section, separated by a slash. For example, the location would be intro/1 to refer to the intro(1) manual page. info An Info file. text A plain text file (using the ISO-8859-1 character set). An unknown file type is treated as text. The location argument gives the filename of the file. The name must be complete, i.e., it must start at the root directory (/). The name must not contain any symbolic links (cf. realpath(1)). The file must be located in or below a directory that has been allowed by the sys- tem administrator; see dwww(7) for more info. The file may be compressed with gzip(1) or bzip2(1). It is uncompressed automatically and invisibly. Compression is indicated by a file- name that ends in `.gz' or `.bz2'. OPTIONS
--no-path-info Internal option used by the dwww's CGI script to let dwww-convert know, that the arguments following the option do not come from the PATH_INFO variable, but from the QUERY_STRING. FILES
/etc/dwww/dwww.conf Configuration file for dwww. See dwww(7) for more information. SEE ALSO
dwww(7), dwww-txt2html(8), dwww-build(8), dwww-cache(8). AUTHOR
Lars Wirzenius. Modified by Robert Luberda. See dwww(7) for copyrights and stuff. dwww 1.11.1 February 15th, 2009 DWWW-CONVERT(8)
Check Out this Related Man Page
DWWW(7) Debian DWWW(7) 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 suit- able 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 configura- tion 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 regis- tered 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 gener- ated 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-quick- find(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 encour- aged. dwww 1.11.6 June 26th, 2011 DWWW(7)