17 Sep
2019
17 Sep
'19
4:10 a.m.
On Mon, 16 Sep 2019 14:54:49 -0700 Jon Steinhart <jon(a)fourwinds.com> wrote:
Larry McVoy writes:
A typical manpage had just the right length. Reading man pages
and experimenting is how I initially learned all about unix
commands.
Keeping a manpage short also limited what you as the
implementer would be tempted to add to the command. Manpages
work best for programs that follow the unix mantra of do one
thing and do it well. But not for kitchensink programs. When
you need a multipage reference manual (for *experts*) with a
TOC and program to "navigate", you're much more likely to give
into the temptation of adding more features than partition
functionality into separate programs that work well together.
Not to mention it is harder to get something right that has
many more features.
I think, someone correct me if I'm wrong, the info stuff was designed
to handle larger, more complex stuff, with a table of contents, etc.
Something like perl could fit in one info doc but the perl man page is
not a thing, it's just a series of pointers to more man pages.
Can't answer you directly on this one, but I prefer the old system of
having man pages and separate documents for longer things. I still
have old notebooks full of papers on lex, yacc, and so on.
One of the problems with using info for something like perl is that it
doesn't have a useful organization. There's a difference to me between
a reference manual and a user's guide. Most of the stuff referenced by
the main perl page is user's guide stuff to me, it's not a reference.
Probably someone knows more than me about all this. I have always been
under the impression that one read the user's guide to learn about
complicated stuff. The manual pages were there so that you could find
the right options when you forgot. Putting every detail about a complex
program into a manual page doesn't feel right to me.