#
1.4 |
|
05-Jul-2014 |
dholland |
Reorg docs, part 1: 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.
|
#
1.3 |
|
05-Jul-2014 |
dholland |
Rework /usr/share/doc.
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.
|