info: display '--' as '-'

info: display '--' as '-'

[mofaph]

Hi, all.

I am using Git 1.7.11.4 now. I compile and then install it from the repo.

$ git checkout v1.7.11.4
$ make prefix=$HOME/opt/git/1.7.11.4 all doc info
$ make prefix=$HOME/opt/git/1.7.11.4 install{,-doc,-html,-info}

Recently, I found some problem when I read the git.info.

For example, you can see it in "3.7.1 Getting conflict-resolution help during a
merge":

$ git log -merge
$ gitk -merge

See, it should be type like this:

$ git log --merge
$ gitk --merge

You will see this typo almost in the whole info file.

mofaph
2012/8/6

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

[Jeff King]

On Mon, Aug 06, 2012 at 11:08:39AM +0800, mofaph wrote:

> I am using Git 1.7.11.4 now. I compile and then install it from the repo.
> 
> $ git checkout v1.7.11.4
> $ make prefix=$HOME/opt/git/1.7.11.4 all doc info
> $ make prefix=$HOME/opt/git/1.7.11.4 install{,-doc,-html,-info}
> 
> Recently, I found some problem when I read the git.info.
> 
> For example, you can see it in "3.7.1 Getting conflict-resolution help during a
> merge":
> 
> $ git log -merge
> $ gitk -merge
> 
> See, it should be type like this:
> 
> $ git log --merge
> $ gitk --merge
> 
> You will see this typo almost in the whole info file.

Yeah, I can reproduce it here. The data goes through these
transformations to get to the final info form:

  user-manual.txt  (source)
   -> user-manual.xml (via asciidoc)
     -> user-manual.texi (via docbook2x-texi)
       -> git.info (via makeinfo)

The data looks OK in user-manual.texi, but "--" is converted to "-" in
git.info. So either:

  1. There is a bug in makeinfo, which should not be doing this
     conversion inside a "@display" section.

  2. There is a bug in docbook2x-texi, which should be quoting the
     contents of the <literallayout> when generating the @display
     section.

I don't know enough about texinfo to say which. But I'm sure that the
contents of user-manual.xml are correct, because I do actually speak
docbook, which means the problem happens after that step.

Cc-ing David Kastrup, who added the info version originally, and might
be more clueful about that part of the toolchain.

-Peff

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

[David Kastrup]

Jeff King <peff@peff.net> writes:

> On Mon, Aug 06, 2012 at 11:08:39AM +0800, mofaph wrote:
>
>> I am using Git 1.7.11.4 now. I compile and then install it from the repo.
>> 
>> $ git checkout v1.7.11.4
>> $ make prefix=$HOME/opt/git/1.7.11.4 all doc info
>> $ make prefix=$HOME/opt/git/1.7.11.4 install{,-doc,-html,-info}
>> 
>> Recently, I found some problem when I read the git.info.
>> 
>> For example, you can see it in "3.7.1 Getting conflict-resolution
>> help during a
>> merge":
>> 
>> $ git log -merge
>> $ gitk -merge
>> 
>> See, it should be type like this:
>> 
>> $ git log --merge
>> $ gitk --merge
>> 
>> You will see this typo almost in the whole info file.
>
> Yeah, I can reproduce it here. The data goes through these
> transformations to get to the final info form:
>
>   user-manual.txt  (source)
>    -> user-manual.xml (via asciidoc)
>      -> user-manual.texi (via docbook2x-texi)
>        -> git.info (via makeinfo)
>
> The data looks OK in user-manual.texi,

If you are interpreting it visually instead of as Texinfo source...

> but "--" is converted to "-" in git.info. So either:
>
>   1. There is a bug in makeinfo, which should not be doing this
>      conversion inside a "@display" section.

Not really: @display does not change fonts, merely indentation.  From
the Texinfo manual:

    The `@display' command begins a kind of example, where each line of
    input produces a line of output, and the output is indented.  It is
    thus like the `@example' command except that, in a printed manual,
    `@display' does not select the fixed-width font.  In fact, it does not
    specify the font at all, so that the text appears in the same font it
    would have appeared in without the `@display' command.

         This is an example of text written between an `@display' command
         and an `@end display' command.  The `@display' command
         indents the text, but does not fill it.

But in non-typewriter fonts, -- is a shorthand for an en-dash (see
"conventions" in the Texinfo manual):

   * Use three hyphens in a row, `---', to produce a long dash--like
     this (called an "em dash"), used for punctuation in sentences.
     Use two hyphens, `--', to produce a medium dash (called an "en
     dash"), used primarily for numeric ranges, as in "June 25-26".
     Use a single hyphen, `-', to produce a standard hyphen used in
     compound words.  For display on the screen, Info reduces three
     hyphens to two and two hyphens to one (not transitively!).  Of
     course, any number of hyphens in the source remain as they are in
     literal contexts, such as `@code' and `@example'.

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.

>   2. There is a bug in docbook2x-texi, which should be quoting the
>      contents of the <literallayout> when generating the @display
>      section.

Quoting won't help.  You can likely get by with @w{-}@w{-} (putting the
hyphens separately in an unbreakable box), but the real formatting fix
is to use an environment suitable for literal character quotings rather
than free-flow text.

> I don't know enough about texinfo to say which. But I'm sure that the
> contents of user-manual.xml are correct, because I do actually speak
> docbook, which means the problem happens after that step.
>
> 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.

-- 
David Kastrup

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

[Jeff King]

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

[PATCH] docs: monospace listings in docbook output

[Jeff King]

When asciidoc converts a listing block like:

----------------------
$ git log --merge
----------------------

it marks it to be displayed in a monospace font. This works
fine when generating HTML output. However, when generating
docbook output, we override the expansion of a listingblock
to work around bugs in some versions of the docbook
toolchain. Our override did not mark the listingblock with
the "monospaced" class.

The main output that uses docbook as an intermediate format
is the manpages. We didn't notice any issue there because
the monospaced class seems to be ignored when generating
roff from the docbook manpages.

However, when generating texinfo to make info pages, docbook
does respect this class. The resulting texinfo output
properly uses "@example" blocks to display the listing in
this case. Besides possibly looking prettier in some texinfo
backends,  one important effect is that the monospace font
suppresses texinfo's expansion of "--" and "---" into
en-dashes and em-dashes.  With the current code, the example
above ends up looking like "git log -merge", which is
confusing and wrong.

Signed-off-by: Jeff King <peff@peff.net>
---
I wonder if we can maybe just rip out our custom overrides entirely.
They date back to versions of docbook from 2006. I'm not sure I entirely
understand their purpose, though (they seem to also be about inserting
extra line breaks, and handling manual additions of roff).

This cleans up many of the problems with the info result. However, there
are still lots of places that use "--" outside of a listing block or a
backtick literal. Those still look bad in the generated info page.

 Documentation/asciidoc.conf    | 4 ++--
 Documentation/user-manual.conf | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index a26d245..1273a85 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -36,7 +36,7 @@ ifndef::git-asciidoc-no-roff[]
 # v1.72 breaks with this because it replaces dots not in roff requests.
 [listingblock]
 <example><title>{title}</title>
-<literallayout>
+<literallayout class="monospaced">
 ifdef::doctype-manpage[]
 &#10;.ft C&#10;
 endif::doctype-manpage[]
@@ -53,7 +53,7 @@ ifdef::doctype-manpage[]
 # The following two small workarounds insert a simple paragraph after screen
 [listingblock]
 <example><title>{title}</title>
-<literallayout>
+<literallayout class="monospaced">
 |
 </literallayout><simpara></simpara>
 {title#}</example>
diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf
index 339b309..d87294d 100644
--- a/Documentation/user-manual.conf
+++ b/Documentation/user-manual.conf
@@ -14,7 +14,7 @@ ifdef::backend-docbook[]
 # "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
 [listingblock]
 <example><title>{title}</title>
-<literallayout>
+<literallayout class="monospaced">
 |
 </literallayout>
 {title#}</example>
-- 
1.7.12.rc1.12.g5eaae48

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

[Andreas Schwab]

Jeff King <peff@peff.net> writes:

> The data looks OK in user-manual.texi, but "--" is converted to "-" in
> git.info. So either:
>
>   1. There is a bug in makeinfo, which should not be doing this
>      conversion inside a "@display" section.

The texinfo manual says that @display does not change the font (unlike
@example), so the body will be rendered like normal text apart from the
extra indentation and preserved line breaks.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."