Move all the reference manuals to subdirs of /usr/share/doc/reference.
We have subdirs ref1-ref9, corresponding to man page sections 1-9.
Everything that's the reference manual for a program (sections 1, 6,
8), C interface (sections 2, 3), driver or file system (section 4),
format or configuration (section 5), or kernel internal interface
(section 9) belongs in here.
Section 7 is a little less clear: some things that might go in section
7 if they were a man page aren't really reference manuals. So I'm only
putting things in reference section 7 that are (to me) clearly
reference material, rather than e.g. tutorials, guides, FAQs, etc.
This obviously leaves some room for debate, especially without first
editing the docs with this distinction in mind, but if people hate
what I've done things can always be moved again.
Note also that while roff macro man pages traditionally go in section
7, I have put all the roff documentation (macros, tools, etc.) in one
place in reference/ref1/roff. This will make it easier to find and
also easier to edit it into some kind of coherent form.
Update the <bsd.doc.mk> infrastructure, and update the docs to match
the new infrastructure.
- Build and install text, ps, pdf, and/or html, not roff sources.
- Don't wire the chapter numbers into the build system, or use them in
the installed pathnames. This didn't matter much when the docs were a
museum, but now that we're theoretically going to start maintaining
them again, we're going to add and remove documents periodically and
having the chapter numbers baked in creates a lot of thrashing for no
purpose.
- Specify the document name explicitly, rather than implicitly in a
path. Use this name (instead of other random strings) as the name
of the installed files.
- Specify the document section, which is the subdirectory of
/usr/share/doc to install into.
- Allow multiple subdocuments. (That is, multiple documents in one
output directory.)
- Enumerate the .png files groff emits along with html so they can be
installed.
- Remove assorted hand-rolled rules for running roff and roff widgetry
and add enough variable settings to make these unnecessary. This
includes support for
- explicit use of soelim
- refer
- tbl
- pic
- eqn
- Forcibly apply at least minimal amounts of sanity to certain
autogenerated roff files.
- Don't exclude USD.doc, SMM.doc, and PSD.doc directories from the
build, as they now actually do stuff.
Note: currently we can't generate pdf. This turns out to be a
nontrivial problem with no immediate solution forthcoming. So for now,
as a workaround, install compressed .ps as the printable form.
XXX: still not 100% "safe", except that we're in a protected directory.
XXX: arguably we should keep the fds open and fdopen(3) dup()s,
XXX: but we're in a protected directory so it shouldn't matter.
FORTIFY_SOURCE feature of libssp, thus checking the size of arguments to
various string and memory copy and set functions (as well as a few system
calls and other miscellany) where known at function entry. RedHat has
evidently built all "core system packages" with this option for some time.
This option should be used at the top of Makefiles (or Makefile.inc where
this is used for subdirectories) but after any setting of LIB.
This is only useful for userland code, and cannot be used in libc or in
any code which includes the libc internals, because it overrides certain
libc functions with macros. Some effort has been made to make USE_FORT=yes
work correctly for a full-system build by having the bsd.sys.mk logic
disable the feature where it should not be used (libc, libssp iteself,
the kernel) but no attempt has been made to build the entire system with
USE_FORT and doing so will doubtless expose numerous bugs and misfeatures.
Adjust the system build so that all programs and libraries that are setuid,
directly handle network data (including serial comm data), perform
authentication, or appear likely to have (or have a history of having)
data-driven bugs (e.g. file(1)) are built with USE_FORT=yes by default,
with the exception of libc, which cannot use USE_FORT and thus uses
only USE_SSP by default. Tested on i386 with no ill results; USE_FORT=no
per-directory or in a system build will disable if desired.
abhinav