Date:        Mon, 17 Jul 2000 13:05:32 -0700 (PDT)
    From:        Mike Cheponis <mac@Wireless.Com>
    Message-ID:  <Pine.BSI.4.05L.10007171257140.20975-100000@NameServer.Culver.Net>

  | The problem, of course, is that it's a single "flat file" type of man
  | database.

That's not the problem, that is the feature.

  | If the man pages were html, with links to deeper documentation levels (even 
  | automatically generated documentation), that would be better.

No, that would be the problem.   If all that happened was that the current
man pages gained some prettier formatting, and a few auto links (the way
tkman makes them appear, or using a man2html type converter) then aside
from unnecessary general bloat, there wouldn't be much of a problem.

But writing the doc in html would just lead to "deeper documentation levels"
making the whole thing almost impossible to fathom without jumping around
all over the place even when on line, and 100% impossible to follow when
the documentation is printed and in book form, instead of on-line form (which
is sometimes still a better method).

It is the same reason that "info" format doc is horrid to deal with.

  | I propose junking man pages as we know them, keeping all documentation in
  | html, and making the man command essentially a stripped-down lynx (or other
  | specialized text-based browser).

Definitely no.

  | p.s. As precedent for using html, the READMEs in pkgsrc are html.

The READMEs in pkgsrc are auto generated, and basically useless.  All the
info they contain is available elsewhere (the auto-generation has to come
from somewhere...) and those files are ordinary text.

If you want to auto generate html versions of the man pages, or even if
NetBSD wants to do that, or make it an option at least, that's fine - but
the man page source needs to stay as man page source, not html.

Incidentally, I took the reference to "go look in the source" to be a joke,
no-one is seriously suggesting that (or if they have, they have never attempted
to work out what errors the kernel can generate from reading the source - it
is not at all easy to do, even if you know the sources fairly well).

The real discussion that started this is whether or not each man page should
attempt to have a complete list of all the errors, or whether most of them
should be incorporated by reference to the intro(2) page, which contains all
of the errno values, and their standard meanings.   Clearly when a kernel
interface uses an error number in a non-standard way (almost the rule for
ENXIO) then it needs to be documented on that page - but there really is
no need to have EROFS mentioned in the pages for link(), open(), creat(),
mkdir(), rmdir(), unlink(), socket(),  ...  on and on, all those functions
return the error in the same circumstance, the definition of the error in
EROFS in intro(2) is just fine.   That read() can't rationally return EROFS
is really immaterial - anyone reading its description ("An attempt was made
to modify...") will see that since read() doesn't modify the file, that
error will not occur.

kre