(no subject)

[Albert van der Horst]

A lesson : a bug is in my definition :
   "a deviation from wanted behaviour that is unequivocally
   documented and in line with the general philosophy of the
   program". 

Because any major defect questions the general philosophy of
a program, bugs are by definition minor.

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

The documentation of texinfo is poor.
I have to wade through all the information about generating nodes
to find out that :
1. leading spaces are ignored (what about trailing)
2. "A @-command is not acceptable in a name". This is nonsensical.
   A name is a string, so I take it that this means that no @
   are allowed in a name.
3. Apparently commas and apostrophes are not allowed. 

The texinfo exhibits the hallmark of bad documentation :
the examples show crucial aspects that do not follow from 
the unsufficiently precisely formulated reference section.
An example of this is that it is allowed to have an empty 
node name. This follows from the examples but is nowhere to
be found in the pertinent sections. Unexpectedly too, spaces
in names are allowed. And yes this is weird. No programming 
language I know off can handle spaces in names.

        But now about the defect.

DEFECT REPORT concering texinfo documented 3.12
                     and makeinfo versio 1.68


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

        If you do not want to go for this:

        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" 

( 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. ) 

Elaboration :
In generating documentation for a forth system I run
into problems with the following characters in node 
names :
@ . ,  ' : ( * { } - 
All these single characters are Forth commands and natural section
headers and node names for Forth documentation. 

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

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, which you can find 
elsewhere.

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.

To ponder:
I think the poor quality of the texinfo documentation 
is the result of abandoning the man concept.
It is too verbose and chatty.
Of course the idea of generating a manual and a cross reference
index from the same base is very valuable. We must use that as 
a starting point. I am thinking about multi level documentation,
where you can suppress tutorial material and examples.
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.

Remember Unix was intended to be a set of cooperating small programs. 
Each program described by at most a few pages.
In my hardcopy of the man pages from Mark WIlliams
Coherent, de docs of m4 (a very powerful tool indeed)
run 2.5 page flat. 
Even the largest item nroff takes a mere seven pages.                    
Mustn't we abandon "GNU is Not Unix" and start a 
"Unix is Not Windows" project?

Albert van der Horst,Oranjestr 8,3511 RA UTRECHT,THE NETHERLANDS
To suffer is the prerogative of the strong. The weak -- perish.
address@hidden     http://home.hccnet.nl/a.w.m.van.der.horst