Documentation build things

Firstly, it would be advantageous for several reasons if we *not*
tar.gz'ed the HTML and man documentation bundles in the distribution.
One, gzip is redundant because the main tarball is already gzipped.  Two,
users could be able to read the documentation before installing.  But most
importantly, it would allow us to make incremental diffs between releases
(or at least subreleases), which has so far always failed because of this.

Seemingly, it should be no problem if we instead placed the files like
{root}/doc/admin/*.html, {root}/doc/man/man1/*.1, etc. or perhaps under
{root}/doc/src/admin/*.html, etc.


Secondly, I'd like to "autoconfiscate" the documentation build some more
(or at all).  I've already written Autoconf macros to detect jade, nsgmls,
docbook, and stylesheets.  Docbook2man is in the works, although that
package has no defined installation layout, so it would probably be a thin
wrapper around a manual override until something better arises.

The build of the HTML docs seems solid enough that it could be run at
distribution time without manual intervention.  (Of course there is manual
intervention when a release is made, so no *extra* intervention.)

The same should be true of the man pages as well, or at least it would be
something to aim for.  Is there currently manual voodoo involved in this?


The issue of man page sections was not resolved yet.  'l' (ell) doesn't
work at all on some systems.  Some systems have '7' for miscellaneous,
some have '5'.  (The other one of 5 or 7 is usually device drivers.)
Some systems don't have any appropriate section for this, expect a perhaps
to be created '1sql'.  What should we do about this, besides possibly not
caring :-) ?


Other concerns, questions, comments?

--
Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/