Re: info: display '--' as '-'
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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: info: display '--' as '-'
Jeff King 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, sch...@linux-m68k.org GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different." -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: info: display '--' as '-'
Jeff King 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 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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: info: display '--' as '-'
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 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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
