Re: info: display '--' as '-'

[Jeff King <peff@peff.net>]

On Tue, Aug 07, 2012 at 09:17:50AM +0200, David Kastrup wrote:

> Not really: @display does not change fonts, merely indentation.  From
> the Texinfo manual:
> [...]
> But in non-typewriter fonts, -- is a shorthand for an en-dash (see
> "conventions" in the Texinfo manual):

Thanks, that's the missing piece I didn't have.

So it seems like docbook2-texi is at fault. The "--" does not have a
special meaning in docbook XML, but is special markup specially in
Texinfo source. By passing it through literally, docbook2-texi is
changing the meaning of the text. It should be escaped somehow, just as
you would escape other markup characters (e.g., "@display" literally in
the text would also need to be escaped).

I suppose you could argue that the "--" conversion is not markup, but a
presentation choice for free-form text. I find that a little dubious
when coming from docbook, which could use "&endash;" if it really wanted
an en dash.

> So somewhere in your conversion chains, you should try detecting code
> examples and translate them into @example...@end example rather than the
> merely indented @display ... @end display.  It is likely that it will
> look better in other parts of the production chain as well.

I think that's a reasonable work-around for this particular incarnation
of the bug. I still think it's wrong of the docbook to texinfo
conversion process to leave "--" in place in general, but it matters
most in fixed-font displays.

It looks like some of our asciidoc workarounds were causing listing
blocks not to be marked as monospace. I've got a patch to address that,
and it fixes this particular class of bug.

However, we also use literal "--" in lots of non-monospaced contexts.
The whole documentation tree needs to be audited for use of "--" (e.g.,
every option mentioned in git-log.txt is currently wrong in the
gitman.info result). I think the end result will look better, but it is
going to be a giant pain.

> > Cc-ing David Kastrup, who added the info version originally, and might
> > be more clueful about that part of the toolchain.
> 
> I think you are significantly overstating my contribution.  Unless my
> memory is failing me (always an option), I probably raised the main
> stink at one time about the info documentation falling into a decrepit
> state, but I don't think that I was all that much involved with getting
> it up to scratch again, and I don't think I had been responsible for
> originally implementing it.

I based my assumption on your 4739809 (Add support for an info version
of the user manual, 2007-08-06). I don't think any of the regular
contributors actually uses info, which is why it has remained largely
untouched since then.

Anyway, I was right; you were more clueful than I (not that it took
much...). Thanks for pointing me in the right direction.

-Peff