Re: Patch updating Info format specification

[Gavin Smith]

On Fri, Jul 18, 2014 at 9:49 PM, Karl Berry <address@hidden> wrote:
>     Subject: Patch updating Info format specification
>
> Thanks.  Only two months later ... sorry.
>
> (Patrice, for your possible convenience:
> http://lists.gnu.org/archive/html/texinfo-devel/2014-05/msg00026.html
> and please see my query at the end of this msg)
>
>     * Whether terminating punctuation ("." or ",") is required for
>     quoted nodenames
>
> I don't see why it should have to be, although of course normally it
> would be.
>
There is a similar question for whether you need punctuation after a
short-form cross-reference, e.g. from the texinfo manual "*Note
Tropical Storms::, for more info." It says that "it's a common mistake
to follow an '@xref' command with a space, but this is never correct."
I don't see why this is necessary because the name of the referenced
node is terminated here with a colon, not a comma or a full stop.

>     * When to use "*Note" or "*note"
>
> I think what you say, namely N at the beginning of a sentence and n
> otherwise, is fine, since that's what I see happening now in makeinfo's
> output.
>
> Clearly N vs. n is not something that is part of the spec, just a hint
> for usage where possible.  We can't be in the business of guaranteeing
> perfect detection of sentence endings.
>
>     * Whether the tag table is optional in non-split files
>
> With makeinfo 4.13 and current makeinfo, the tag table is always
> generated, so far as I can see.  So I think we could make it required if
> that's beneficial to you for reading.

The Info browser has a function to find all the nodes in a file so it
is not necessary (except for split files, where the tag table is used
to say which subfile a node is in based on the subfile offsets). I
expect that this will continue to work. Main use of not having a tag
table would be writing Info files by hand. Quite a rare case but
occasionally useful for testing what Info readers do with different
input. Also I suppose if another if another Info-generating program
existed then it would be useful for them to be able to test their
output if they hadn't implemented tag table generation yet.

>     * Use of "(dir)" in node information lines
>
> What about it?
The pointers Next, Prev, Up normally refer to nodes within the same
file, except for the Top node where Prev and Up can refer to the dir
node.  It's worth mentioning this because otherwise it would mean that
we were looking for a node that was actually called "(dir)" within the
same file.

(Regarding ASCII characters, I have a UTF-8 manual installed that is
unusable in an ISO-8859-1 locale in info 4.13. It doesn't just display
the non-ASCII characters as something else, but text in directional
quotes actually disappears.

For example
------------
Automake is a tool for automatically generating 'Makefile.in's from
files called 'Makefile.am'.  Each 'Makefile.am' is basically a series of
'make' variable definitions(1), with rules being thrown in occasionally.
The generated 'Makefile.in's are compliant with the GNU Makefile
standards.
------------
becomes
------------
Automake is a tool for automatically generating âs from
files called â.  Each â is basically a series o\
f
â variable definitions(1), with rules being thrown in occasionally.
The generated âs are compliant with the GNU Makefile
standards.
------------
It displays okay in current SVN info, though. Nothing can be done
about this incompatibility for older info versions though, apart from
telling the user to use terminals that match the encoding of the Info
files.)

> Second, about "hiding" of text:
>
>   ... That final punctuation is part of the surrounding sentence, and
>   +should be displayed.  (It may be hidden in some circumstances, namely if
>   address@hidden was used and the cross-reference is contained within
>   +parentheses.  @address@hidden@@pxref}}.)
>
> First, I don't think we should recommend that Info text be hidden under
> any circumstances; I'm not even enthused about saying about when it is
> vaguely acceptable as optional behavior.  (I know Emacs randomly
> reparses and redisplays Info files by default, but I think that is
> simply wrong.  I can't change what they do, but I don't want to
> officially bless it.)  So my preference would be to delete this bit.
>
> Second, the text as written looks contradictory to me.  It says the
> final punctuation should be (a) displayed, but at the same time (b)
> hidden under some circumstances.

Miss the whole thing out then, even the recommendation that it should
be displayed (because saying that it should be displayed implies there
is other text that could be hidden).

Other points not mentioned:
* Does anyone know how this would affect menus in texinfo source,
which are info menus in a @menu block? (Same question for @direntry)?
* Are cross-references like *Note (file)node:: allowed? I have seen
them in several files. They seem to work at the moment but there could
be some confusion with a node actually called "(file)node" in the same
file.
* I noticed that in the "info.info" file there was a section about how
to write an Info file by hand (which has been removed now). Most of it
is covered in the texinfo spec, but I noticed that it mentioned that
node separators could contain form feed characters:

   The new node can live in an existing documentation file, or in a new
one.  It must have a `^_' character before it (invisible to the user;
this node has one but you cannot see it), and it ends with either a
`^_', a `^L' ("formfeed"), or the end of file.(1)

   The `^_' starting a node must be followed by a newline or a `^L'
newline, after which comes the node's header line.

Also there is this comment in info/search.c:

  /* A node is started by [^L]^_[^L]\n.  That is to say, the C-l's are
     optional, but the DELETE and NEWLINE are not.  This separator holds
     true for all separated elements in an Info file, including the tags
     table (if present) and the indirect tags table (if present). */

I just thought I'd mention this in case it was important enough to
mention (although I suspect that this is some ancient thing and not be
true of any Info files that anyone is likely to try to read).