D. J. Bernstein
UNIX

The /doc hierarchy

Indices

/doc/commands.html is an index of available commands: 
     ...
     dnsq: query a DNS server
     dnstrace: search for all DNS servers relevant to a name
     ...
Each line is a link such as 
     <a name="dnstrace" href="host/cr.yp.to/djbdns/debugging.html#dnstrace">...</a>...<br>
in the general form 
     <a name="cmdname" href="url">cmdname</a>: description<br>
although future extensions may add more information after the href.

There are other indices similar to /doc/commands.html: /doc/packages.html is an index of packages; /doc/fileformats.html is an index of file formats; /doc/cfunctions.html is an index of C functions.

User interfaces

You can point your browser to /doc/commands.html to scan the list of commands.

You can point your browser to /doc/commands.html#dnstrace to look up the dnstrace command by name.

An experimental replacement for man -k foo | less is the slashdoc script, which uses the w3m browser. slashdoc foo starts w3m with a list of index links containing foo, in a sensible order. A big advantage over man -k is that you can very quickly follow the links.

The /doc/merge hierarchy

Each package supplies only its portion of /doc/commands.html. For example, the djbdns documentation includes /doc/merge/web/djbdns/commands.html, along with /doc/host/cr.yp.to/djbdns/*. Then slashdoc-merge, a simple shell script, incorporates /doc/merge/web/djbdns/commands.html into /doc/commands.html.

The /doc/host hierarchy

The directory /doc/host/h is controlled by the owner of Internet host h. For example, I own cr.yp.to; I decided that /doc/host/cr.yp.to/djbdns/tools.html would be a mirror of https://cr.yp.to/djbdns/tools.html.

Notes

Much more effort has gone into web browsers than into roff readers. We can take advantage of this by providing browser-compatible documentation.

We need browser-compatible documentation anyway: users want to read documentation on the web before they download a package. The only extra effort required for /doc is the effort of packaging the existing documentation with a few index links.