Re: TRAMP User Manual problems with Texinfo 5.0

[Eli Zaretskii]

> Date: Sat, 23 Feb 2013 00:00:28 +0100
> From: Patrice Dumas <address@hidden>
> 
> On Thu, Feb 21, 2013 at 10:38:39PM +0200, Eli Zaretskii wrote:
> > 
> >   @macro xxx address@hidden
> >   @set address@hidden
> >   @end macro
> > 
> >   @macro yyy {one, address@hidden
> >   @address@hidden
> >   @ifclear address@hidden
> >   address@hidden@c
> >   @end ifclear
> >   @clear address@hidden
> >   @end macro
> > 
> >   @macro trampfn {method, user, host, address@hidden
> >   @address@hidden,@address@hidden,@@address@hidden@c
> >   @end macro
> > 
> > The important one is the last one: it needs to produce results like
> > this:
> > 
> >   @address@hidden, daniel%BIZARRE, melancholia, /daniel$$/.emacs}}
> > 
> >    => `/smb:address@hidden:/daniel$$/.emacs'
> 
> In the new implementation, the result not that, because the last newline 
> of a user macro invocation is always stripped, and it remains a mystery
> why previous makeinfo processed that right as it also stripped the last
> newline -- maybe not consistently.

If it's important, I can trace through the C makeinfo and report what
exactly happens there.  Let me know.

> So, there is a fix:
> * add a blank line in @yyy definition.
> * Remove the trailing @c in @trmpfn definition.
> 
> Would that be ok?  In my testings TeX gives also a correct result.
> 
> 
> 
> note: there is also still a spurious warning about @end in @file, 
> I'll correct that.

This produces the same output with makeinfo 4.13a.  With makeinfo 5.0,
it mostly works, but there are still a few problems:

  . There are many warnings like this:

    tramp.texi:481: warning: @set should only appear at a line beginning 
(possibly involving @xxx)

    tramp.texi:481: warning: @set should not appear in @file (possibly 
involving @xxx)

    tramp.texi:481: warning: @set should not appear in @file (possibly 
involving @xxx)

    tramp.texi:1188: warning: @set should not appear in @kbd (possibly 
involving @xxx)

    tramp.texi:2345: warning: @set should not appear in @item (possibly 
involving @xxx)

  . There are some errors:

    tramp.texi:2457: misplaced { (possibly involving @xxx)
    tramp.texi:2457: misplaced }
    tramp.texi:2457: misplaced {
    tramp.texi:2457: misplaced }
    tramp.texi:2459: too many columns in multitable item (max 1)
    tramp.texi:2460: too many columns in multitable item (max 1)
    tramp.texi:2484: misplaced { (possibly involving @xxx)
    tramp.texi:2484: misplaced }
    tramp.texi:2484: misplaced {
    tramp.texi:2484: misplaced }

  . @item @trampfn{, , melancholia, .emacs} and similar constructs
    (see tramp.texi around line 3230) produce this:

    '/'
         melancholia:.emacs

    instead of this:

    `/melancholia:.emacs'

  . The text between lines 2453 and 2491, starting with "If you, for
    example, type" and ending with "Now you can choose" produces
    something weird, probably because there are extra @ifset
    conditionals there.  Here's the diff against v4.13:

--------------- begin diffs ---------------
 Filename completion works with TRAMP for completion of method names, of
 user names and of machine names as well as for completion of file names
-on remote machines.  In order to enable this, partial completion must
-be activated in your `.emacs'.  *Note Completion Options:
-(emacs)Completion Options.
-
-   If you, for example, type `C-x C-f /t <TAB>', TRAMP might give you
-as result the choice for
-
-     telnet:                           tmp/
-     toto:
-
-   `telnet:' is a possible completion for the respective method, `tmp/'
-stands for the directory `/tmp' on your local machine, and `toto:'
-might be a host TRAMP has detected in your `~/.ssh/known_hosts' file
-(given you're using default method `ssh').
-
-   If you go on to type `e <TAB>', the minibuffer is completed to
-`/telnet:'.  Next `<TAB>' brings you all machine names TRAMP detects in
-your `/etc/hosts' file, let's say
-
-     /telnet:127.0.0.1:                /telnet:192.168.0.1:
-     /telnet:[::1]:                    /telnet:localhost:
-     /telnet:melancholia.danann.net:   /telnet:melancholia:
+on remote machines.  In order to enable this, partial completion must be
+activated in your '.emacs'.  *Note (emacs)Completion Options::.
+
+   If you, for example, type 'C-x C-f /t <TAB>', TRAMP might give you as
+result the choice for
+
+     telnet:melancholia.danann.net: /telnet:192.168.0.1:
+     telnet:
+     tmp/
+     toto:
+
+   'telnet:' is a possible completion for the respective method, 'tmp/'
+stands for the directory '/tmp' on your local machine, and 'toto:' might
+be a host TRAMP has detected in your '~/.ssh/known_hosts' file (given
+you're using default method 'ssh').
+
+   If you go on to type 'e <TAB>', the minibuffer is completed to
+'/telnet:'.  Next '<TAB>' brings you all machine names TRAMP detects in
+your '/etc/hosts' file, let's say
+
+     telnet:melancholia.danann.net: /telnet:192.168.0.1:
+     /telnet:127.0.0.1:
+     /telnet:192.168.0.1:
+     /telnet:[::1]:
+     /telnet:localhost:
+     /telnet:melancholia.danann.net:
+     /telnet:melancholia:

    Now you can choose the desired machine, and you can continue to
--------------- end diffs ---------------

  . This call:

    emacsclient @trampfn{ssh, $(whoami), $(hostname --fqdn), $1}

    is converted to "emacsclient /ssh:$(hostname --fqdn):$1", omitting
    the "$(whoami)@" part.

Btw, the comparison of the produced files is made gratuitously hard by
spurious unrelated changes in the output.  The most annoying one is
that @code and @samp now produce 'foo' rather than `foo'.  I tried to
disable this change by setting OPEN_QUOTE_SYMBOL=` on the command
line, but that didn't work.  The documentation of that option (and
also of CLOSE_QUOTE_SYMBOL) is impenetrable for me:

  'OPEN_QUOTE_SYMBOL'
       When an opening quote is needed, use the corresponding character;
       default '&lsquo;' for HTML, '&#8216;' for Docbook.

What is "the corresponding character"?  How to tell texi2any to use `
in Info output?  Is this option at all relevant to Info output format?
I find no answers to these questions in this documentation.

Similarly, the documentation of the customization file, viz.:

  '--init-file=FILE'
       Load FILE as code to modify the behavior and output of the
       generated manual.  It is customary to use the '.pm' or the '.init'
       extensions for these customization files, but that is not enforced;
       the FILE name can be anything.  The '--conf-dir' option (see above)
       can be used to add to the list of directories in which these
       customization files are searched for.

doesn't say whether there's a built-in default name for a
customization file.  (If there isn't, there should be, because using
"--init-file=" in every invocation is extremely inconvenient.)  More
importantly, it says _nothing_at_all_ about the syntax of the
customization file.  The following naive attempt:

  OPEN_QUOTE_SYMBOL=`

triggers this cryptic diagnostics:

  makeinfo: warning: error loading d:/usr/eli/foo.init: Can't find string 
terminator "`" anywhere before EOF at d:/usr/eli/foo.init line 1.
  Compilation failed in require at D:\usr\bin\makeinfo line 376.

And if I try this:

  OPEN_QUOTE_SYMBOL=&lsquo;

I get this:

  makeinfo: warning: error loading d:/usr/eli/foo.init: Can't modify constant 
item in scalar assignment at d:/usr/eli/foo.init line 1, near "&lsquo;"
  Compilation failed in require at D:\usr\bin\makeinfo line 376.

Did I miss something in the documentation?  If not, these aspects
certainly need some attention in the docs.  It is easy to imagine that
the differences between the old makeinfo and the new one will cause
people to try to customize away some of the differences since day one,
so the documentation of these customizations should be clear and
extensive, IMO.