Re: reorganizing /usr/share/doc

["James K. Lowden" <jklowden%schemamania.org@localhost>]

On Fri, 18 Oct 2013 07:52:58 +0000
David Holland <dholland-docs%netbsd.org@localhost> wrote:

> As some people know I've been gradually working on fixing
> /usr/share/doc; 

Thank you for working on this. 

> After looking through what we have (and don't have) I have the
> following reorganization in mind:
> 
>    - drop the USD/SMM/PSD categories.
>    - divide the docs by type (intros/guides, reference, papers, etc.)
>    - within the reference section, create nine subsections ref1-ref9
>      that correspond to the nine man page sections we know.

I think Ken Thomson may cast the evil eye on you.  

I would keep usd/smm/psd.  It seems to me that the user, the
programmer, and the administrator are different roles, even if they are
sometimes the same person.  User is section 1, programmer is 2, 3, & 4
(and sometimes 9), admin is 5 and 8.  I would say that taxonomy has
held up pretty well.  

I would say all material divides along those lines.  Whether you're
talking about an introduction ("beginner"), a tutorial, a guide, or
whatever, the overlap between user, programmer, and admin is pretty
slim.  That suggests usd/intro/intro.{ms,ps,pdf,html} is a userful
namespace.  

> It also seems like a good idea to get rid of the section numbers in
> the article names

Yes. 

> I also propose to put all the roff-related material in a single
> subdirectory of reference/ref1. 

"reference/ref1" doesn't say much.  Why not "usd/troff/" instead?  

> I don't think it's a good idea to create separate hierarchies for
> text, html, and ps/pdf, 

Agreed!  

> even though that's how man pages are
> installed, so this is predicated on one dir per document that will
> contain all output formats.

I would *really* like to see only the sources distributed, with a
Makefile at the top of the hierarchy that produces the preferred output
format.  Tradition suggests a "cat" directory to hold rendered
documents, but "out" (or "view") might make more sense in 2013.
Current groff produces pdf directly.  

> usd/19.memacros reference/ref1/roff/meref             usd/20.meref

I dislike calling reference documents "ref".  Like the whole manual
(i.e., /user/share/man), "reference" is implied unless the name
explicitly -- tut, guide, intro -- says otherwise.  The system should
be heavy with reference material; calling it all "ref" is akin to
appending "of Earth" to everyone's name.  

--jkl