Subject: Re: bin/7249
To: None <>
From: Richard Rauch <>
List: tech-kern
Date: 07/19/2000 03:16:24
(Sorry, no CC: list for previous posters; there are simply too many voices
to catch everyone.  (^&)

On the topic of replacing .0 files with HTML (or was that replacing *roff
sources with HTML?  Or both?  The topic got a little tangled, I
think): Lynx is not the only way to read HTML on a tty (and arguments
about needing X and needing a network connection to read HTML just don't
ring).  (FWIW, I don't believe that HTML is a desirable substitute for .0
files _or_ for *nroff sources.)

To add to's arguments, I think that we'd have a
hard time keeping coherent the use of HTML features.  For one thing, we
have a multiplicity of browsers, but most people probably have one
favorite.  The fact that HTML pages would by their nature shade into the
web in general would also make it easier for things (people) to slip a
bit.  The ultimate insult: ``This man-page is best viewed with Internet
Explorer.''  (^&

Some kind of linking mechanism would be nice, though.  See also's don't
really cut it: You don't want to skim to the end of a document to read
those references.  See also's don't bind tightly to anything in the main
text.  Something with a lot of cross refernces could have a really _long_
See also list.  See also's are a bit weak for finding specific places
_within_ a referenced document (imagine a large document cross-referencing
itself with See also's---kind of silly---but with a little structure for
references, it can be very convenient)

Of course, you could argue that documents large enough to benefit from
referencing themselves shouldn't be man-pages.  That begs the question of
where such vital information should be kept.  Going this way runs into the
question of what a man page should be (see below)...

Relatedly, someone mentioned using TeX instead.  While TeX is alright
(I've used it more than, and prefer it to, *roff---probably only because
of that familiarity, though), it is more monolithic than one expects in a
UNIX environment.  It also doesn't lend itself well to text consoles, and
has a pretty big footprint compared to most other options (for users that
want to typeset their own man pages).

On the topic of what a man page should be, I think that there is some
inconsistancy...some praise the selective sparseness, seeming to imply
that readers should all have copies of XPG or some other standard (_which_
standard does NetBSD always adhere to where not documented, anyway? I
never supposed that there was _any_ such standard).  A later message
lamented Borland's hypertext docs for a similar characteristic: They were
only useful (to paraphrase him) if you only wanted a reminder of something
that you already knew.  IMHO, that description is only a short hop from
what some seem to praise in the NetBSD man pages.  (Granted, however,
there isn't quite a contradiction.  But the two notions do not fit well in
one perspective for me.)

Perhaps instead of trying to force the man pages to support _all_ system
documentation, we could revive the PSD/USD/etc. documents (or create a
similar set of documents).  IMHO, even with the NetBSD Guide (which
doesn't ship with the system anyway, and _is_ in HTML), there's still lots
of ground that could stand to be covered.  Perhaps not by the NetBSD
project, but by someone.  In my mind's eye, if he would permit it, Chuck
Cranor's UVM paper would belong in such a set of documents.  An overview
of error _handling_ might be appropriate.  The shell man-pages are also a
bit out-sized for man-pages (IMHO); the man-pages could be made briefer,
with an in-depth document (for cover-to-cover reading) stuffed somewhere

Well, it's an idea.

My current thought is that *roff sources would probably be the best option
for these other docs, as well.  They serve the purpose well enough, and we
already have to carry the *roff family along for man pages.

  "I probably don't know what I'm talking about."