tramp.texi

[Luc Teirlinck <teirllm@dms.auburn.edu>]

I do not know whether the following concerns bugs in tramp.texi, in
Emacs, or in makeinfo, although I believe the two latter.  Anyway, Kai
reads Emacs devel and I included a CC to Karl.

I reported on this problem before, but I do not believe it has been
fixed.  What is new is that I now know how to deal at least with the
symptoms.

Description of the symptom:

In standalone Info (info (GNU texinfo) 4.5) do m tramp:

Result:

Cannot find node `Top'.

In Emacs we do C-h i m tramp

No problem here.  But now we do: m Overview

Result:

byte-code: No such anchor in tag table or node in tag table or file:
Overview

Now what is going on?

Tramp contains:

@c Entries for @command{install-info} to use
@dircategory Emacs
@direntry
* TRAMP: (tramp).                Transparent Remote Access, Multiple
Protocol
                                 Emacs remote file access via rsh and
rcp.
@end direntry

Perfectly correct, but apparently appears too soon.

If we kill that code and paste it later, just in front of:

@tex

@titlepage
@title @tramp{} version @trampver{} User Manual

then both the standalone and Emacs Info are suddenly perfectly happy with
tramp.texi

At first view, it seems that this was a bug in tramp.texi and we fixed
it.

I do not believe so, although making that small change will indeed
make the Tramp documentation work perfectly. I believe that there is
no bug in tramp.texi at all, but a bug in makeinfo (or in its
documentation) and a bug in texinfo-mode in Emacs.

First of all the main bug:

>From (texinfo)Installing Dir Entries:

    Always use the `@direntry' and `@dircategory' commands near the
    beginning of the Texinfo input, before the first `@node' command.  If
    you use them later on in the input, `install-info' will not notice
    them.

This warns about putting it too _late_, but tramp.texi took this
warning a little bit too seriously and put it too _early_.  But the
documentation does not mention anything about too _early_.  This is
either a bug in makeinfo or a bug in the documentation.  One can not
blame authors for taking what they are told seriously.  (I am not the
author by the way.)

While actually trying to solve the problem I ran into some auxiliary
problems, which I believe are a bug in Emacs' texinfo-mode.

What I did in Emacs was, I copied the file tramp.texi to ~/info and
ran C-u C-s C-u m on it. Then I did C-x C-s and C-c C-m C-b.  Result:

    /home/teirllm/info/tramp.texi:133: Reached eof before matching @end
    ifset.
    /home/teirllm/info/tramp.texi:126: No matching `@end menu'.
    /home/teirllm/info/tramp.texi:80: Next reference to nonexistent node
    `Overview'.
    /home/teirllm/info/tramp.texi:132: Menu reference to nonexistent node
    `History'.
    /home/teirllm/info/tramp.texi:131: Menu reference to nonexistent node
    `Obtaining @sc{tramp}'.
    /home/teirllm/info/tramp.texi:127: Menu reference to nonexistent node
    `Overview'.
    makeinfo: Removing output file `../info/tramp' due to errors; use
    --force to preserve.

    Compilation exited abnormally with code 2 at Sat Jun 14 21:10:04

This occurs with or without prior application of the "fix" described
above.  The problem is that before C-u C-s C-u m, the @end if and @end
menu were there, but C-u C-s C-u m erased them.  I believe that this
is  a bug in Emacs' texinfo-mode.  Indeed M-! makeinfo --fill-column=70
worked perfectly (after switching the above code around, as
described). 

Sincerely,

Luc.