[ On Sat, December 13, 1997 at 01:52:02 (-0600), Ty Sarna wrote: ]
> Subject: Re: port-i386/4651: Man page describing booting NetBSD from Wind
>
> So why is "man something" the appropriate method of reading reference
> material, and "more /usr/share/doc/something" more approriate for
> "volume 2" stuff? Why can't I use man to read either one?

Well that is a different question when you put it that way.

I think the traditional answer would be that doing so would add too much
clutter and confusion.

The 'man' command reads the reference manaul.  The other documents are
traditionally only read in their final typeset form (on paper, though
with a good hi-res screen the medium is less important).

I don't think re-vamping 'man' to add new capabilities like these in
particular is a good idea here, but another more comprehensive tool that
can be used in place of both 'man' and a typeset previewer would not be
a bad thing -- far from it.

The ultimate hack might be a backend to groff that produces "info" (as
in GNU-tekinfo's "makinfo" output form) from "-mdoc" documents.  Then
the normal GNU 'info' tool could read manual pages, texinfo manuals, and
-mdoc manuals.  Converting from "info" to "html" is already a done deal
too, so there you go, problem solved for everyone all in one fell swoop
with a traditional unix tools approach.  One wee innovation provides a
whole new world of possibilities.

> Maybe we're talking about different things.  I'm not suggesting
> rewriting the /usr/share/doc stuff in a different _writing_ style; All
> I'm suggesting is converting them to a slightly different _typographic_
> style, and putting them under /usr/share/man/{cat,man}X with some
> yet-to-be-determined X.

But as I'm sure most folks with professional experience at documentation
will tell you, presentation is a critical part of a document's style.
Would you read a fictional novel with 'man chap1; man chap2; man chap3'?

Have you ever tried in a hurry to get any specific useful thing out of
the typical monolithic manual pages that have tended to come with big
and baroque packages such as rn/trn/strn, or perl, or similar?  It's
nearly impossible.  Why is the flex(1) manual *page* 54 nroff pages long
while the traditional unix lex(1) manual page is but 3 nroff pages long?
There aren't *that* many new features in it to describe.  I'd much
rather have a manual page and at least two in-depth documents, one
describing how to use the tool in various situations, and one describing
the implementation and innards of the tool.  I don't think I'd ever want
to type 'man' to read the latter documents though.

Have you ever wondered why they're called "manual *pages*"?  They're
supposed to be short, concise, and succinct with few, or no, examples,
no verbiage about how the tool they describe takes its place in the
bigger picture, no un-necessary implementation details, etc.

The manual pages are for the details when you already know what you're
doing.  The /usr/share/doc contents are for background information,
in-depth guidebooks (i.e. "how-to's"), dissertations about
implementation, etc.

It seems that in NetBSD at least /usr/share/examples is where reference
card like things go, and maybe where templates that don't belong in
/usr/share/skel go, etc.  Perhaps these need "browser" support too, but
I think 'grep' and 'more' are sufficient for them, esp. when in an ideal
world there'll be a related guidebook in /usr/share/doc for them too.

Clear and definite division between these different kinds of
documentation is quite beneficial, however as I've said it wouldn't be a
bad thing to have a hypertext browser that could connect them all
together in a virtual manner for those who maybe don't know what they're
doing.

Lastly I wonder if this task isn't better left to someone outside of an
OS specific forum such as NetBSD.  Unix brought us new typsetting tools
and a tools oriented philosophy of documentation, but Unix is no longer
just one thing.

-- 
							Greg A. Woods

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