On Mon, Jul 17, 2000 at 06:56:25PM -0700, Mike Cheponis wrote:
> 
> The problem presented was: are all the error codes put into man pages, or
> are man pages kept "as is" where some of the more common error codes are
> documented, and you then grovel through the source code when you come
> up against an error not mentioned in the man page?
> 
You're being silly.  The point you're missing is that the average
NetBSD user who _uses_ man pages is not dumb.  I would find it
confusing to have each possible error, no matter how obvious, listed
for each function in man.2.  I would be deeply offended if I discovered
this to be an attempt at insulting my intelligence and that of my peers,
one of the reasons I dislike the Microslob documentation you seem hell-
bent on emulating.

There is sense in HTML, but it is a dreadfully disturbing format to
code text in, and mere <pre>s, as you suggest, are more than inadequate,
I presume that was you shooting from the hip, rather than a considerate
response.

Now go look at Plan 9's doc <http://plan9.bell-labs.com/sys/doc/> and
see what we can all learn (and possibly improve on) from there.

> Why html?  Because it's everywhere and it has the required propertities, 
> and because it allows updates over the net, or indeed, the entire doc tree
> to be off your machine in an easy-to-access way.
> 
> If there is something superior to html, please, suggest it.
> 
You're lost :-)  "man" and "ms" are superior, and, as greywolf
suggested, they are at a lower level, which makes it possible, not
just easier, to convert them to other styles.  TeX may be another
option, but I suspect it is not sufficiently better to warrant
migrating to.

man2html and similar friends are the tools you're after, not
hotmetal (consider producing html documentation without a graphic
tool).

Just for curiosity's sake (a) have you ever looked at html2ps as
an indication of html's shortcomings, and (b) how do you propose
to track html's continued evolution in NetBSD's information page
display program - something I, at least, consider critical to
the operating system deployment?

++L