[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
(no subject)
From: |
Albert van der Horst |
Subject: |
(no subject) |
Date: |
Thu, 26 Oct 2000 14:37:47 +0100 |
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
- (no subject),
Albert van der Horst <=