Re: PSD, SMM and USD manuals [was: Re: Shell tutorial added]

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

On Mon, May 07, 2012 at 06:15:46PM -0400, James K. Lowden wrote:
 > > On Wed, 25 Aug 2010 21:56:51 +0200
 > > Kristaps Dzonsons <kristaps%kth.se@localhost> wrote:
 > > 
 > > > >> Finally, I question that anyone will find particularly relevant
 > > > >> documentation about the NetBSD operating system in the year 2010
 > > > >> from /usr/src/share/doc/{psd,smm,usd}. That said, kudos to Perry
 > > > >> E. for updating some of these.
 > > > > 
 > > > > I semi-regularly use these documents for reference purposes.
 > > > 
 > > > I'm curious: who else uses these?  Can there be a bit of show of
 > > > hands?
 > 
 > On Thu, 26 Aug 2010 05:09:10 -0400
 > Matthew Mondor <mm_lists%pulsar-zone.net@localhost> wrote:
 > >
 > > I can't say I used them regularily, but I was surprised to find those
 > > there when I started using NetBSD (as they were not installed), and
 > > read some of those which interested me.  At some point I also fell on
 > > a partial collection of postscript-converted old BSD documents which
 > > were also a pleasure to read.
 > 
 > That was my experience, too.  NetBSD is a place to learn,
 > and /usr/share/doc is one place to do it.  There should be more, not
 > less, there.  

Yes, as I've said before, /usr/share/doc should be where one goes for
major documentation. One of these days I will find time to get around
to fixing the infrastructure for it.

(the full mission is, roughly:
   1. what's installed in /usr/share/doc should be typeset (text,
      html, pdf), not troff source;
   2. the numbering scheme for the PSD/SMM/USD chapters needs to be
      reworked so adding and removing chapters doesn't make a mess;
   3. pointing a web browser at file:///usr/share/doc/index.html
      should produce broadly useful results;
   4. the chapters that are papers (that is, historical documents
      fixed in time) rather than documentation (which should be kept
      up to date) should be moved to their own area;
   5. the chapters that are of no current or future value should be
      dropped;
   6. the missing chapters should be scraped up from wherever they've
      run away from;
   7. any new chapters that should exist should be scoped out and
      written;
   8. severely outdated chapters, which is many of them, should be
      revised.
Points 1-4 are infrastructure; the rest is writing/editing.)

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