As some people know I've been gradually working on fixing
/usr/share/doc; this has two parts. One is installing useful files
(text, html, pdf, etc.) instead of roff source. More on that later.
The other is reworking the organization, which in its current form is
between 20 and 30 years old and mostly pretty dated.
(Yes, I know, most of the documents are also that dated. They should
be removed or updated. But there's no motivation to do so when nobody
will ever see them, which is the current state.)
I'm intending to combine the installation changes and reorg into a
single batch of commits to reduce the impact on the set lists and
obsolete file database.
After looking through what we have (and don't have) I have the
following reorganization in mind:
- drop the USD/SMM/PSD categories.
- divide the docs by type (intros/guides, reference, papers, etc.)
- within the reference section, create nine subsections ref1-ref9
that correspond to the nine man page sections we know.
Nearly everything we have in /usr/share/doc (plus nearly all the
vintage 4.4 docs we don't have copies of in the tree) is reference
material. There are a few tutorials/introductions, and some papers.
(The key property of papers is that they're historical documents and
don't update, so they should be filed separately. Papers that aren't
worth including in their original form should just be dropped.)
It also seems like a good idea to get rid of the section numbers in
the article names, as the ordering isn't especially meaningful and
baking it into the set lists is an unnecessary nuisance.
I also propose to put all the roff-related material in a single
subdirectory of reference/ref1. If the docs for pic, eqn, refer, and
all that ever reappear this would include those.
I don't think it's a good idea to create separate hierarchies for
text, html, and ps/pdf, even though that's how man pages are
installed, so this is predicated on one dir per document that will
contain all output formats.
That gives the following contents for /usr/share/doc:
intro/beginners usd/01.begin
intro/ed usd/11.edit [1]
intro/vi usd/12.vi
papers/fastfs smm/05.fastfs
papers/fsck_ffs smm/03.fsck_ffs
papers/password smm/17.password
reference/ref1/atf (currently doc/atf)
reference/ref1/bzip2 (currently doc/html/bzip2)
reference/ref1/config smm/02.config
reference/ref1/csh usd/04.csh
reference/ref1/ex/reference usd/12.ex
reference/ref1/ex/summary usd/12.ex
reference/ref1/kyua-atf-compat (currently doc/kyua-atf-compat)
reference/ref1/kyua-cli (currently doc/kyua-cli)
reference/ref1/kyua-testers (currently doc/kyua-testers)
reference/ref1/mail usd/07.mail
reference/ref1/make psd/12.make
reference/ref1/roff/groff/mom (currently doc/html/groff/mom)
reference/ref1/roff/groff/mom_examples (currently doc/groff/mom)
reference/ref1/roff/memacros usd/19.memacros
reference/ref1/roff/meref usd/20.meref
reference/ref1/roff/msdiffs usd/18.msdiffs
reference/ref1/roff/msmacros usd/17.msmacros
reference/ref1/sh usd/03.shell
reference/ref1/vi/reference usd/13.viref
reference/ref1/vi/summary usd/12.vi
reference/ref3/curses psd/19.curses
reference/ref3/ipc psd/21.ipc [2]
reference/ref3/ipctut psd/20.ipctut [2]
reference/ref3/sysman psd/05.sysman [3]
reference/ref6/rogue usd/30.rogue
reference/ref6/trek usd/31.trek
reference/ref7/quotas smm/04.quotas
reference/ref8/bind (currently doc/html/bind9/arm)
reference/ref8/lpd smm/07.lpd
reference/ref8/ntp (currently doc/html/ntp)
reference/ref8/postfix (currently doc/html/postfix)
reference/ref8/timed smm/12.timed
reference/ref8/timedop smm/11.timedop
reference/ref9/net smm/18.net
reference/ref9/nfs smm/06.nfs
[delete] smm/01.setup
[1] This could also just be deleted.
[2] These should probably be renamed as they're about sockets; also
despite the name, ipctut doesn't appear to belong in the intro section.
[3] Where this should go isn't entirely clear; it's possible it should
be split up.
Right now there is a good bit of additional material for each of the
USD, PSD, and SMM sections that's left over from when O'Reilly printed
them for 4.4; there is no useful way to update this so my inclination
is to delete it, or leave it somewhere in the source tree and not
install it.
Each of the non-article dirs should get an index.html file, and
ideally text and ps/pdf equivalents of this; there is some material
for this in the tree right now.
In the long run I would also like to ship the Guide in
/usr/share/doc/guide, but that can't happen with the current toolset
and should be its own flamewar when the time comes; I'm mentioning it
because it's supposed to fit into the organizational scheme shown
above.
The usd/smm/psd docs that are currently missing all (as far as I can
deduce from their titles) fit into this scheme adequately, so if some
of them reappear in the future they won't end up homeless.
It would be nice also to figure out how to crossreference this with
the texinfo docs in /usr/share/info, but that's going to be fairly
difficult.
I am *not* proposing to move anything around in the source tree. We
can do that later if it looks like a good idea. Many of the articles
are installed from miscellaneous places (e.g. the csh article comes
from src/bin/csh/USD.doc) and leaving the usd/smm/psd doc trees that
are currently in src/share/doc is probably better than trying to
rename everything in CVS. I can add readme files to those trees to
explain what's going on.
If there are more docs that should be added, we can do that, modulo
the typesetting/tools issues, which I'll bring up when I post about
installing output rather than roff source.
--
David A. Holland
dholl...@netbsd.org
