[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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)

         yacc - an LALR(1) parser generator

         yacc [-dlrtv] [-b file_prefix] [-o output_filename] [-p symbol_prefix]

         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.


         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 Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond - The music typesetter
http://www.xs4all.nl/~jantien       | http://www.lilypond.org

Reply to: