Subject: Re: port-i386/4651: Man page describing booting NetBSD from Wind
To: None <tech-userlevel@NetBSD.ORG>
From: Greg A. Woods <firstname.lastname@example.org>
Date: 12/12/1997 22:52:28
[ On Fri, December 12, 1997 at 14:38:16 (-0600), Ty Sarna wrote: ]
> Subject: Re: port-i386/4651: Man page describing booting NetBSD from Wind
> My whole point is that's not where they should go -- the documentation
> should be together. That's also why I'm proposing new sections for that
> kind of stuff to live in. It's volume two, so what? If I buy a two book
> set, I don't want the first one in 5x9 format and the other in 8.5x11 in
> a different layout. I'd expect the two volumes to look similar, and be
> organized in a similar manner. I'd also expect to find the two volumes
> next to each other on the bookshelf.
The point is that manual pages and /usr/share/doc have vastly different
purposes and vastly differnt styles of *usage*. The former is like a
desk reference set, and the latter is more like a novel.
Even the Encyclopaedia Britannica was smart enough to introduce a
two-section format with their "MicroPaedia" and "MacroPaedia".
> If we want those features (and I do), we should have them for man pages
Absolutely. But right now we have more features for manual pages
because *reference* documents need more features and better UIs. That
doesn't mean in-depth documents that read more like books can't use the
same features -- it only identifies why things are the way they are.
Necessity is the mother of invention.
> And it'd be a lot easier to implement that kind of thing if there
> was a single mechanism for documentation.
Perhaps. However the *style* differences between manual pages and the
other documentation is critically important and I feel it must be
Greg A. Woods
+1 416 443-1734 VE3TCP robohack!woods
Planix, Inc. <email@example.com>; Secrets Of The Weird <firstname.lastname@example.org>