Re: Texinfo vs man (was: Re: Debian GNU/Linux Reference Card under construction)
Wouter Verhelst writes:
> I 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? I really dislike
having to travel down the path of possible sources of documentation.
In general, I like info pages a lot, I can live with man pages, find
.txt.gz files in /usr/share/doc/* a bit clumsy. But 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.
> This 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;
it illustrates why `man 2 open' is fine, but `must have man' does not
guarantee sanity or bring enlightenment.
> Since 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.
> If 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.
Just for fun, have a look at the bison info pages, and compare that
with the FreeBSD yacc man page, for example.
YACC(1) FreeBSD General Commands Manual YACC(1)
NAME
yacc - an LALR(1) parser generator
SYNOPSIS
yacc [-dlrtv] [-b file_prefix] [-o output_filename] [-p symbol_prefix]
filename
DESCRIPTION
The yacc utility reads the grammar specification in
the file filename and generates an LR(1) parser for it. The
parsers consist of a set of LALR(1) parsing tables and a
driver routine written in the C programming language. The
yacc utility normally writes the parse tables and the driver
routine to the file y.tab.c.
The following options are available:
<SNIP options>
If the environment variable TMPDIR is set, the string denoted
by TMPDIR will be used as the name of the directory where the
temporary files are created.
FILES
y.code.c
y.tab.c
y.tab.h
y.output
/tmp/yacc.aXXXXXXXXXX
/tmp/yacc.tXXXXXXXXXX
/tmp/yacc.uXXXXXXXXXX
DIAGNOSTICS
If there are rules that are never reduced, the number of such
rules is reported on standard error. If there are any
LALR(1) conflicts, the num- ber of conflicts is reported on
standard error.
FreeBSD 4.7 May 24, 1993 FreeBSD 4.7
And that's all documentation there is. Your assignment: write a
simple parser using yacc.
> As 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. We agree about blatter, I think.
Adding words does not necesarily make bad documentation better.
Jan.
--
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond - The music typesetter
http://www.xs4all.nl/~jantien | http://www.lilypond.org
Reply to: