Re: Texinfo documentation

[Eli Zaretskii]

On Thu, 26 Oct 2000, Albert van der Horst wrote:

> What I report is not a bug, but certainly a defect.

Thank you for your report.  We generally treat incorrect or incomplete
documentation as real bugs.

> The documentation of texinfo is poor.
[snip]
> The texinfo exhibits the hallmark of bad documentation :

This is harsh.  I wonder whether you really meant that.  I didn't
write the Texinfo manual, but I use it all the time, and I find the
docs very complete, well indexed, and easy to read and understand.

Of course, improvement is always possible and welcome, but by and
large, I think we owe the authors of the Texinfo docs lots of
gratitude.

> DEFECT REPORT concering texinfo documented 3.12
>                      and makeinfo versio 1.68

Please note that this is a very old version: the latest version of
Texinfo is v4.0, it was released almost a year ago.  Some of the
problems you have bumped into, including documentation problems, are
corrected in the latest version; I suggest to upgrade.

> 1. leading spaces are ignored (what about trailing)

The trailing whitespace is also ignored.

Thanks for pointing out this problem; I will add an index entry about
whitespace in node names, so that this information could be found
easily.

> 2. "A @-command is not acceptable in a name".

I cannot find this phrase in the docs of Texinfo 4.0; perhaps it was
replaced by a better wording.  I can find this description:

  * @-commands used in node names generally confuse Info, so you should
    avoid them.  For a few rare cases when this is useful, Texinfo has
    limited support for using @-commands in node names; see *Note
    Pointer Validation::.

>    I take it that this means that no @ are allowed in a name.

For the most part, this is true; however, makeinfo 4.0 has a special
command-line option to allow some of the @-commands in node name,
albeit at a price of much slower formatting.

> 3. Apparently commas and apostrophes are not allowed. 

Periods, commas, colons, and apostrophes are not allowed.  There are
index entries (e.g., "Apostrophe in nodename") in the manual that lead 
directly to this information.

> An example of this is that it is allowed to have an empty 
> node name.

An empty node name is NOT allowed, even if the program can cope with
such blunders and doesn't crash or abort.

> Unexpectedly too, spaces in names are allowed.

If by "names" you mean "node names", then the documentation says that
a node name is similar to a section name, so spaces should not come as
unexpected, I think.  I will add that info anyway, to make it
explicit.

> And yes this is weird. No programming language I know off can handle
> spaces in names.

Node names are not identifiers.  The "@node" directive itself _is_ an
identifier, but the node's name is not.

>         Every sequence of characters should be acceptable as node
>         name and precise documentation must be available about
>         how to do get this right.

Unfortunately, this is impossible.  Texinfo needs to be converted into
several different formats (currently, Info, TeX, and HTML, but more
formats will be added in the future).  Each one of the conversions
uses different tools (makeinfo for Info and HTML, TeX macros for TeX),
and each format is read using different browsers.  Thus, the Texinfo
language is limited by the limitations inherent to all those tools;
many of the tools are not even maintained as part of the Texinfo
project.  If you want your documents to work in all formats, you have
no other way but obey the limitations.

>         Carefully document what characters are allowed in a node
>         name and do this in the section "Node Names" and not in
>         the section "Node Line Requirements"

The sections "Node Names" and "Node Line Requirements" are both parts
of the chapter "The @node command".  I don't see anything wrong with
breaking the chapter into several sections, to avoid having too long
sections that most people won't read due to its length.

A reader who wants to become acquainted with the syntax of @node and
with related issues, should read the entire chapter.  A reader who
looks for specific information about @node directive, should use
index-searching commands to find the information quickly.  For
example, there's an index entry "Characters, invalid in node name"
(and other similar entries) which will quickly land you on the right
spot.

> ( This is following the current filosofy that
> node names are visible to the users of texinfo. 
> This in itself is a design error, that leads to the 
> previous problem. ) 

??? What exactly do you suggest as an alternative?  Nodes impose
structure on the document, and only a human knows what structure that
should be.  Texinfo manuals are hypertext documents, not linear text.

> In generating documentation for a forth system I run
> into problems with the following characters in node 
> names :
> @ . ,  ' : ( * { } - 

The dash `-' is allowed in a node name; if you cannot use it, please
post a short example of a Texinfo file which exhibits this problem.  I
just tried, and it worked for me.

The characters @ . , ' : are listed in the paragraph I cited above.

As for the others, they are documented elsewhere in the manual; I will
add them explicitly to the list in the section "Node Line
Requirements".  Thanks for pointing this out.

> If info is to be a general documentation tool, and not just
> for c this must be fixed.

This is impossible, for the reasons I explained above.  You can use
any characters you like in chapter and section names, but nodes cannot
endure some characters, because they are interpreted by the browsers
and by makeinfo.

> The problems to be expected with a name like (LINE) or (LIST)
> cannot be found in the texinfo part of the manual. Apparently
> they are intended to be used as filenames

Yes, (foo) means a file `foo'.  And * means an entire file.  So these
characters are allowed in node names, but they have special reserved
meaning.

> NOTE : tex with tex-info has no problems with sections
> that are called : @ ' : , .  ( - .
> That is: my current documentation actually has sections 
> with the above names and names such as (LINE) .
> It generates the documentation straightforwardly and with
> a single complaint that I still have to sort out.
> By the way also in html this is no problem at all.

The dashes are allowed, see above.  Apostrophes are not allowed due to
TeX, the rest are not allowed because of the limitations of different
Info browsers.

> I think the poor quality of the texinfo documentation 
> is the result of abandoning the man concept.

After 10 years of reading and writing Texinfo docs, I disagree.  I
think poor quality has nothing to do with the docs format.  I think
Texinfo has features, such as index entries, of which man pages can
only dream.  I also think that complex packages such as Texinfo,
Emacs, or Gawk cannot be adequately described in a man page.

> TEXINFO mixes tutorials and reference manuals, and occasional
> narcistic remarks about the difference 
> between mathenatical arguments and discussion arguments, eating
> away my precious attention while I crave for a very specific information.

A Texinfo document, in its on-line form (i.e., after conversion to the
Info format) serves two purposes: a tutorial/manual, and a reference.

For the former, the ``chatty'' form is imperative, because you cannot
introduce someone to new material without explaining it in so many
words.

For the latter, you need to use the index-search command (press `i'
inside the Info reader) and the auto-completion avialable with that
command in the stand-alone Info reader, to find the information
quickly and efficiently.  FWIW, I usually find information in any
Texinfo manual in a matter of seconds, using index-search.  I can only
dream about this in a man page.

Of course, a manual should be well indexed to allow such efficient
searches.  However, most GNU manuals are indeed indexed very well; and
the Texinfo manual is one of those.  (If you find an issue that
couldn't be found using the index-search command, please report it as
a documentation bug.)

> Remember Unix was intended to be a set of cooperating small programs. 
> Each program described by at most a few pages.

You cannot document a language in a few pages.  How many pages did it
take Donald Knuth to describe TeX?

> Even the largest item nroff takes a mere seven pages.                    

Does that include all the macro packages used with nroff?  No.  Does
that include stylistic recommendations for writing nroff documents?
No.  Does that include the description of nroff-related commands in
Emacs?  No.

Please keep in mind that Texinfo is the main tool for writing
documentation for the GNU project.  Many GNU package maintainers need
to master that tool in order to write and maintain docs for their
packages.  Given this, it makes a lot of sense (IMHO) to have all the
relevant information in a single comprehensive manual.  Of course, to
be efficient, that manual needs to be well written and well indexed.
I think it basically is, but thank you for the comments which will
make it even better in a future release.

> Mustn't we abandon "GNU is Not Unix" and start a 
> "Unix is Not Windows" project?

I can hardly believe that you really mean the latter part of this.  I
work on Windows a lot, and it is my sad experience that Windows
documentation is simply awful: its information signal-to-noise ratio
is abysmally small.  It usually explains all the obvious things (``To
open a file, click "File" and choose "Open"''), but leaves all the
important and non-obvious parts out, nowhere to be found.  I cannot
imagine you can say that about Texinfo docs written as part of the GNU
project.

Thanks again for your comments.