Re: TRAMP User Manual problems with Texinfo 5.0

[Patrice Dumas]

On Sat, Feb 23, 2013 at 12:15:11PM +0200, Eli Zaretskii wrote:
> 
> 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 don't like that change either (nor Karl does, if I recall well), but 
it was consistent with some changes in the GNU coding standards.

> 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 '‘' for HTML, '‘' for Docbook.
> 
> What is "the corresponding character"?  

The character you specified.

> How to tell texi2any to use `
> in Info output?  Is this option at all relevant to Info output format?

No, it isn't.  In general the only customizable output format is HTML.
Here it also affects DocBook, but that's merely a coincidence.  I guess
this could be clearer.  Karl, I let the wording to you?

> I find no answers to these questions in this documentation.

If you want to come back to the old behaviour, I think you need to
change the code in tp/Texinfo/Convert/Plaintext.pm line 272, and replace

  $style_map{$quoted_command} = ["'", "'"];

with

  $style_map{$quoted_command} = ["`", "'"];

> 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

There is a built-in default name for customization files if I recall
well, but left intentionally undocumented for now, until it is stable.

Maybe the text for --init-file above should be completed by

  Handling of init files is not finalized, so you should not try to
  write your own for now.

> importantly, it says _nothing_at_all_ about the syntax of the
> customization file.  The following naive attempt:

That's because it is not finalized for now.  These files are perl files
and should follow an API that is not final for now.  Should be along

  set_from_init_file('OPEN_QUOTE_SYMBOL', '`');

(but this won't have any impact on Info output).

> Did I miss something in the documentation?  If not, these aspects
> certainly need some attention in the docs. 

We intentionally let everything related to init files out of the
documentation, to avoid that people use it before it is stable.

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

Hopefully it will be for the next non bugfix only release.

-- 
Pat