DWWW(7)

💖 dwww — access documentation via WWW 💖

okay bestie, this is the DWWW(7) manual page and it's literally your girl explaining how to read every single piece of docs on your system through a browser. no cap. sit down, grab a snack 🍓, we're doing this.

---

✨ SYNOPSIS ✨

http://localhost/dwww/index.html

like. that's it. that's the whole vibe. 🦋

---

🌸 DESCRIPTION 🌸

so a normal Linux system has documentation scattered everywhere in a million formats — manual pages, Info files, READMEs, and so on and so on. dwww makes it possible to reach all of them through one single interface: a WWW browser. which makes the docs so much easier to actually use, and honestly? iconic. 👑

dwww is made up of several programs, and here's the whole roster, no one gets left out:

• cgi-bin/dwww — this one gets run by the WWW server when a user requests a document via dwww. it parses the request and runs dwww-convert(8) or dwww-find(8) with suitable arguments. installed in the server's cgi-bin directory. it's giving receptionist energy fr.
• dwww-convert(8) — converts any document to HTML. any. document. 💅
• dwww-format-man(8) — the auxiliary program that converts man pages or text files to HTML.
• dwww-find(8) — searches for documentation. the little detective 🕵️
• 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 out of the cache. the cleaner 🧹
• 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.

and why do we do all this? speed, bestie. 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. she stays skinny. 💃

---

⚙️ 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). so if you're scared of config files, she's got you — no file = defaults = fine. 🫶

🎀 Basic configuration variables 🎀

these variables can be also configured by debconf script. you can change them using the following command:

dpkg-reconfigure dwww

look at you being all official. ✨

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

for real though, that "for security reasons" part is not a vibe, it's a boundary. she will NOT convert files outside those directories. periodt.

• 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_SLEEP_TIME — In order to not impede regular server operation, dwww-index++(8) sleeps for the specified amount of time (in seconds) before feeding the next file path to index to index++(1). The default value is 0.15.
• 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.

bestie. do not use these. they're retired. they said goodbye. put them down gently and walk away. 🙈

---

💅 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. and since web browsers tend to use the last one setting defined for a given CSS element, this has the expected effect of customisation. it's the "last word wins" rule and we are using it to our advantage. 👑

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

not me reminding you twice — run dwww-build(8) after you touch the CSS, or nothing changes and you'll be sitting there confused. 😭

---

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

the whole squad. go read them. 🫶

---

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

found a bug? don't just scream into the void — report it through the normal Debian bug reporting system. the maintainers are listening and they're rooting for you. 💜

---

and that's the whole page bestie!! 🎀 this one's from dwww version 1.13.5, dated November 2nd, 2019 (the manual page is DWWW(7), in case the header up top got lost in all the sparkle). now go read some docs. you've got this. slay. 💖✨🦋