Re: Generating pdf in base

[David Holland <dholland-docs%netbsd.org@localhost>]

On Sat, Jul 05, 2014 at 08:08:02PM +0000, David Holland wrote:
 > The problem with generating PDFs in base is as follows:
 > [snip]

btw, to head off the argument that these docs should just be deleted:
currently about 2/3 of the docs in /usr/share/doc are in fairly decent
shape: several have been updated, and quite a few (e.g. csh) document
things that haven't changed much in the last 20-odd years. Many need
only minor editing.

I count three that need total or near-total rewriting (the make and
config references and the network stack internals), two that should
probably be nuked, and a couple more that need review.

In reference/ref1:
   atf - 3rd party and hopefully current
   bzip2 - 3rd party and hopefully current
   config - 1993; I've begun edits but only scratched the surface
   csh - says 4.3BSD; but, csh doesn't change much
   ex - probably current, what was the last time ex changed?
   gprof - doesn't have a date, probably reasonably current though 
   kyua - 3rd party and hopefully current
   mail - lies about the date, needs review
   make - hopelessly outdated, needs complete rewrite
   roff - what's here is probably current as -me/-ms are ancient
   sh - 2010 (perry revised it then)
   vi - lies about the date, currency unclear and needs review

In reference/ref3:
   curses - probably needs only minor updating
   sockets - no date but old, needs reworking for tone and perspective
   sockets-advanced - similar but not as dated-sounding
   sysman - needs complete rework

In reference/ref5:
   timed - mostly current, should get a note that timed is a legacy protocol

In reference/ref6:
   rogue - should need at most minor edits
   trek - ditto

In reference/ref7:
   quotas - current (updated by yours truly last year)

In reference/ref8:
   bind9 - 3rd party and hopefully current
   lpd - probably mostly current but needs editing
   ntp - 3rd party and hopefully current
   postfix - 3rd party and hopefully current
   timed - mostly current, should get a note that timed is a legacy service

In reference/ref9:
   net - 1993, needs serious updating
   nfs - no date, probably needs serious updating

In usd:
   begin - needs complete rewrite
   edit - should probably be purged as nobody uses ed(1) any more
   vi - probably needs only minor updates

In smm:
   setup - totally obsolete and should probably just be purged

In psd:
   (nothing here currently)


A bigger issue is what's *not* here; basically we don't have anything
documenting any current or recent concerns (parallelism, desktops,
graphics, input devices, audio, removable storage media, bluetooth,
802.11, ...), a lot of things that should have reference manuals don't
(lua, pthreads, modules, proplib, ...) and there are sysadmin topics
that ought to be addressed (most notably backups)  ...  some of this
material belongs in the Guide, but that just means we need to be able
to share material between htdocs and /usr/share/doc, and currently we
can't.

-- 
David A. Holland
dholland%netbsd.org@localhost