On Fri, 18 Oct 2013 07:52:58 +0000
David Holland <dholland-d...@netbsd.org> 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
