[ 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
> too!

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
maintained.

-- 
							Greg A. Woods

+1 416 443-1734			VE3TCP			robohack!woods
Planix, Inc. <woods@planix.com>; Secrets Of The Weird <woods@weird.com>