Post by Jan NieuwenhuizenPost by Wouter VerhelstI never said that; I only said that good on-line documentation should
concise and to-the-point information. Full, extensive documentation
should be put in a HOWTO, a book, or on a website -- not in the primary
on-line documentation tool.
Why do you want (at least) two documentation tools?
Are you suggesting that "foo --help" should contain everything,
including underlying concepts and references to other documentation? If
not, then you, yourself, are also suggesting more than one source of
documentation.
My point is: there are different types of documentation sources for
different purposes. --help output should not try to be complete;
similarly, on-line documentation does not have to contain information on
underlying concepts if they are rather complex.
Post by Jan NieuwenhuizenI really dislike having to travel down the path of possible sources of
documentation.
I much prefer different sources of documentation with different
purposes: --help output for answering quick "how was it again" type of
questions; on-line documentation (such as manpages, or on-line help)
documenting options and features; and books, HOWTOs, manpages from
section 7 (although those aren't used that often on (GNU/)Linux), or
other similar things documenting the "bigger picture".
If those purposes get messed up, then having to travel down the path of
possible sources is, indeed, painful; if that's not the case (and I
often find it isn't), there is no problem, and it in fact helps you
(because you don't get information you're not looking for).
Post by Jan NieuwenhuizenIn general, I like info pages a lot, I can live with man pages,
Well, we disagree here, but that isn't new, right?
Post by Jan Nieuwenhuizenfind .txt.gz files in /usr/share/doc/* a bit clumsy.
It depends.
Post by Jan NieuwenhuizenBut sometimes it gets worse, and there aro only .html pages or .ps.gz.
That's really annoying because there is no good search function or
index.
Can't agree more here.
Post by Jan NieuwenhuizenPost by Wouter VerhelstThis requirement allows a user to log on to a system, type "man foo",
and get documentation; such consistency is good.
Yes, consistency is good. However, I'm quite happy with the the
python info pages, but think that `man perl' is broken beyond repair;
I don't really like "man perl" either.
Post by Jan Nieuwenhuizenit illustrates why `man 2 open' is fine, but `must have man' does not
guarantee sanity or bring enlightenment.
Hm. I never intended to say that; if I have, apologies.
What I meant to say is that, IME, info pages tend to lean towards
over-documentation, so that one does not easily find the documentation
one needs anymore. Since manual pages need to be put everything on one
page, you don't see the same thing there.
I'm not suggesting that all manpages are great, or that all info pages
are crap. What i'm suggesting is that due to the difference in format,
manpages usually contain documentation better suited for on-line
documentation than info pages do.
Post by Jan NieuwenhuizenPost by Wouter VerhelstSince there's much more software that has manpages but no texinfo
documentation than the other way around, it's far easier to require
manpages than it is to require texinfo.
Yes, that's easier for the developer, but it's a lot less useful for
the user. I prefer better usability, if possible.
Requiring developers to write extensive info pages on software they want
to package before they get it uploaded will probably result in less
inclination to package software (and, thus, to document them). I assert
that is less useful than having "more useful" documentation, even if I
would agree that info generally is indeed more useful than manpages
(which I don't).
Post by Jan NieuwenhuizenPost by Wouter VerhelstIf you have more information, I'm happy to learn about it; let me
start off by disagreeing with the stance that being "terse" or
giving "inadequate explanation of the underlying concepts" is
necessarily a problem.
There's also
In general, a GNU manual should serve both as tutorial and
reference. It should be set up for convenient access to each
topic through Info, and for reading straight through (appendixes
aside). A GNU manual should give a good introduction to a
beginner reading through from the start, and should also provide
all the details that hackers want. The Bison manual is a good
example of this--please take a look at it to see what we mean.
Yeah, well, that's braindead.
For a good tutorial, one needs an easy to read text that does not
necessarily document everything, but one that leads the user through the
major concepts of the program, and points out a few interesting features
here and there without going in too much detail. In the name of
simplifying things for the reader, it's no big deal if a tutorial isn't
fully accurate at the beginning, so long as confusion is cleared out
later. It's not necessary to be able to pick just part of the tutorial;
to really make a tutorial useful, one should be able to read it start to
end; and after doing that, one should at least have an understanding of
how the software works.
For a good reference, an easy to read text is not required; rather, good
reference documentation contains every detail on every part of the
software, no matter how unimportant in the bigger picture, and it should
do so without errors or without simplification. It's not necessary for a
good reference manual to have an easy readable text which can be read
start to end; rather, a reference manual should consist of small blocks
of detailed information which can each be read separately, and which
point to related items.
These two types of documentation are so fundamentally different that
it's plainly impossible to make one text which can serve both purposes
well. Documentation which does serve as both a reference manual is
usually split up in a "Part I: Tutorial" and a "Part II: Reference" or
so. This is even the case in the above mentioned bison info pages; the
first page one gets after entering "info bison" clearly contains a
header "Tutorial section" and a header "Reference section". In fact, I
have yet to see the first piece of documentation that does not work like
that, that can be used both as a reference and as a tutorial, and that
is doing both jobs equally well (as opposed to equally bad).
If it's not possible to create one text that can be used for both
purposes; if it is indeed necessary to logically split up your text
anyway so that you effectively have two manuals in one, then why require
them to be part of the same document in the first place? That has quite
a few drawbacks too:
* People that need a tutorial don't always need the reference
documentation (yet), and vice versa; throwing them together and
forcing people to install both of them or none of them isn't really
nice.
* It makes looking for the required information harder. If I'm looking
at a manpage, using less as a pager, and want to find information on
the "--foo" option, I can hit "/--foo" and be fairly sure I end up
with the reference documentation of the "--foo" option. If I do the
same in `info', it is not at all certain whether I will end up with
either the reference documentation or a section of the tutorial that
happens to handle the --foo option (of course, redoing the same search
helps, but the point is that it's necessary to do that in the first
place)
* People that write good reference documentation are not necessary the
same people that write good tutorials. Forcing both types of
documentation to be part of the same source will either end you up
with one person doing all of it, thereby having a good tutorial and a
bad reference (or vice versa), one group working on the tutorial part
with another working on the reference part, resulting in better
documentation but unnecessary coordination; or one group of people
working on "everything" with overall bad documentation as a result.
Post by Jan NieuwenhuizenJust for fun, have a look at the bison info pages, and compare that
with the FreeBSD yacc man page, for example.
[...]
Post by Jan NieuwenhuizenAnd that's all documentation there is. Your assignment: write a
simple parser using yacc.
The FreeBSD manual page on yacc isn't meant as a tutorial on writing
LALR parsers, nor is it meant as a reference on the options one can have
while writing a parser. It is meant as on-line documentation for using
the 'yacc' binary from the command line, and does this job well.
Post by Jan NieuwenhuizenPost by Wouter VerhelstAs I said, IMO on-line documentation should contain concise and to
the point information; underlying concepts, if they're complex, and
other blatter, are for HOWTO's and books (either digitally or printed).
HOWTOs are often a desperate effort by users to make up for programs
that lack good documentation.
True; but since they're usually written by people who do nothing but
play with the software, use it, write down their experiences, and
publish that, there are quite some HOWTOs that are pure beaty. Yes,
there are exceptions.
--
EARTH
smog | bricks
AIR -- mud -- FIRE
soda water | tequila
WATER
-- with thanks to fortune