On Tue, 18 Jul 2000, matthew green wrote:

>    
>    So it looks like I've shot down the "performance" argument...
> 
> 
> 
> except that netbsd ships with pre-formatted man pages and has for
> some years now, so this rarely happen anymore.

Except with newly-installed packages from /usr/pkgsrc/, like emacs.


> html is f*cking *horrible* format to create documentation in.  as
> an author of many pages of netbsd documentation, i *totally* do not
> want to go to html documentation.  i would probably support something
> else that wasn't so broken (such as docbook) and lacking in features
> that i currently use often, but i'm honestly quite happy with the
> way man pages work today.  writing `mandoc' man pages is *really*
> nice to do, on the scale of documentation writing.  they format nicely,
> particularly into postscript for printing, unlike html in the general
> case.
> 
> 
> please, take this html idea away and shoot it in the head before it
> spreads.

Then, for consistency, we must remove all hmtl from eveywhere in NetBSD,
and, in particular, we must rid ourselves of that vile and disgusting
html crap in /usr/pkgsrc; it is difficult to believe that the entire
NetBSD distribution has not been completely and utterly polluted by 
association with html, ewwwwwu!  Grab the Lysol!

Screw it that the rest of the world is going to html and xml, we're NetBSD!
We're the old guard!  We keep using crap that should have been discarded
decades ago, because Ken and Dennis like it!

(Sorry, that's a bit over the top, I know, I know... it's called "humor"
in some circles...)


But here's the short of it:

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?

Then consensus seems to be to -not- put all the error codes into the man
pages, because it clutters it up.

I pointed out that it clutters the man page because man pages are a simple
flat-file documentation style.

Therefore, some hierarchical documentation approach would both allow
uncluttered "front pages" of documentation, -and- would allow, for example,
a "link" to more detail (in those cases where you actually -did- want to
see all the error codes).

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.

-Mike