{"thread":{"id":"31193","subject":"info: display '--' as '-'","startedAt":"2012-08-06T03:08:39Z","lastAt":"2012-08-07T20:07:38Z","messageCount":6,"participants":["mofaph","Jeff King","David Kastrup","Andreas Schwab"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"196533","messageId":"CANes+HZ3EH70x6KiaPsV=SQpbjr5o+pEzj2+4Xx613GPZv0SLw@mail.gmail.com","threadId":"31193","inReplyTo":null,"subject":"info: display '--' as '-'","fromName":"mofaph","fromEmail":"mofaph@gmail.com","sentAt":"2012-08-06T03:08:39Z","receivedAt":"2012-08-06T03:08:39Z","isPatch":false,"sender":{"key":"mofaph@gmail.com","avatar":null},"body":"Hi, all.\n\nI am using Git 1.7.11.4 now. I compile and then install it from the repo.\n\n$ git checkout v1.7.11.4\n$ make prefix=$HOME/opt/git/1.7.11.4 all doc info\n$ make prefix=$HOME/opt/git/1.7.11.4 install{,-doc,-html,-info}\n\nRecently, I found some problem when I read the git.info.\n\nFor example, you can see it in \"3.7.1 Getting conflict-resolution help during a\nmerge\":\n\n$ git log -merge\n$ gitk -merge\n\nSee, it should be type like this:\n\n$ git log --merge\n$ gitk --merge\n\nYou will see this typo almost in the whole info file.\n\nmofaph\n2012/8/6\n"},{"id":"196595","messageId":"20120807060157.GA13222@sigill.intra.peff.net","threadId":"31193","inReplyTo":"CANes+HZ3EH70x6KiaPsV=SQpbjr5o+pEzj2+4Xx613GPZv0SLw@mail.gmail.com","subject":"Re: info: display '--' as '-'","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-07T06:01:57Z","receivedAt":"2012-08-07T06:01:57Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Aug 06, 2012 at 11:08:39AM +0800, mofaph wrote:\n\n> I am using Git 1.7.11.4 now. I compile and then install it from the repo.\n> \n> $ git checkout v1.7.11.4\n> $ make prefix=$HOME/opt/git/1.7.11.4 all doc info\n> $ make prefix=$HOME/opt/git/1.7.11.4 install{,-doc,-html,-info}\n> \n> Recently, I found some problem when I read the git.info.\n> \n> For example, you can see it in \"3.7.1 Getting conflict-resolution help during a\n> merge\":\n> \n> $ git log -merge\n> $ gitk -merge\n> \n> See, it should be type like this:\n> \n> $ git log --merge\n> $ gitk --merge\n> \n> You will see this typo almost in the whole info file.\n\nYeah, I can reproduce it here. The data goes through these\ntransformations to get to the final info form:\n\n user-manual.txt (source)\n -> user-manual.xml (via asciidoc)\n -> user-manual.texi (via docbook2x-texi)\n -> git.info (via makeinfo)\n\nThe data looks OK in user-manual.texi, but \"--\" is converted to \"-\" in\ngit.info. So either:\n\n 1. There is a bug in makeinfo, which should not be doing this\n conversion inside a \"@display\" section.\n\n 2. There is a bug in docbook2x-texi, which should be quoting the\n contents of the when generating the @display\n section.\n\nI don't know enough about texinfo to say which. But I'm sure that the\ncontents of user-manual.xml are correct, because I do actually speak\ndocbook, which means the problem happens after that step.\n\nCc-ing David Kastrup, who added the info version originally, and might\nbe more clueful about that part of the toolchain.\n\n-Peff\n"},{"id":"196599","messageId":"874nofcgrl.fsf@fencepost.gnu.org","threadId":"31193","inReplyTo":"20120807060157.GA13222@sigill.intra.peff.net","subject":"Re: info: display '--' as '-'","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2012-08-07T07:17:50Z","receivedAt":"2012-08-07T07:17:50Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Jeff King writes:\n\n> On Mon, Aug 06, 2012 at 11:08:39AM +0800, mofaph wrote:\n>\n>> I am using Git 1.7.11.4 now. I compile and then install it from the repo.\n>> \n>> $ git checkout v1.7.11.4\n>> $ make prefix=$HOME/opt/git/1.7.11.4 all doc info\n>> $ make prefix=$HOME/opt/git/1.7.11.4 install{,-doc,-html,-info}\n>> \n>> Recently, I found some problem when I read the git.info.\n>> \n>> For example, you can see it in \"3.7.1 Getting conflict-resolution\n>> help during a\n>> merge\":\n>> \n>> $ git log -merge\n>> $ gitk -merge\n>> \n>> See, it should be type like this:\n>> \n>> $ git log --merge\n>> $ gitk --merge\n>> \n>> You will see this typo almost in the whole info file.\n>\n> Yeah, I can reproduce it here. The data goes through these\n> transformations to get to the final info form:\n>\n> user-manual.txt (source)\n> -> user-manual.xml (via asciidoc)\n> -> user-manual.texi (via docbook2x-texi)\n> -> git.info (via makeinfo)\n>\n> The data looks OK in user-manual.texi,\n\nIf you are interpreting it visually instead of as Texinfo source...\n\n> but \"--\" is converted to \"-\" in git.info. So either:\n>\n> 1. There is a bug in makeinfo, which should not be doing this\n> conversion inside a \"@display\" section.\n\nNot really: @display does not change fonts, merely indentation. From\nthe Texinfo manual:\n\n The `@display' command begins a kind of example, where each line of\n input produces a line of output, and the output is indented. It is\n thus like the `@example' command except that, in a printed manual,\n `@display' does not select the fixed-width font. In fact, it does not\n specify the font at all, so that the text appears in the same font it\n would have appeared in without the `@display' command.\n\n This is an example of text written between an `@display' command\n and an `@end display' command. The `@display' command\n indents the text, but does not fill it.\n\nBut in non-typewriter fonts, -- is a shorthand for an en-dash (see\n\"conventions\" in the Texinfo manual):\n\n * Use three hyphens in a row, `---', to produce a long dash--like\n this (called an \"em dash\"), used for punctuation in sentences.\n Use two hyphens, `--', to produce a medium dash (called an \"en\n dash\"), used primarily for numeric ranges, as in \"June 25-26\".\n Use a single hyphen, `-', to produce a standard hyphen used in\n compound words. For display on the screen, Info reduces three\n hyphens to two and two hyphens to one (not transitively!). Of\n course, any number of hyphens in the source remain as they are in\n literal contexts, such as `@code' and `@example'.\n\nSo somewhere in your conversion chains, you should try detecting code\nexamples and translate them into @example...@end example rather than the\nmerely indented @display ... @end display. It is likely that it will\nlook better in other parts of the production chain as well.\n\n> 2. There is a bug in docbook2x-texi, which should be quoting the\n> contents of the when generating the @display\n> section.\n\nQuoting won't help. You can likely get by with @w{-}@w{-} (putting the\nhyphens separately in an unbreakable box), but the real formatting fix\nis to use an environment suitable for literal character quotings rather\nthan free-flow text.\n\n> I don't know enough about texinfo to say which. But I'm sure that the\n> contents of user-manual.xml are correct, because I do actually speak\n> docbook, which means the problem happens after that step.\n>\n> Cc-ing David Kastrup, who added the info version originally, and might\n> be more clueful about that part of the toolchain.\n\nI think you are significantly overstating my contribution. Unless my\nmemory is failing me (always an option), I probably raised the main\nstink at one time about the info documentation falling into a decrepit\nstate, but I don't think that I was all that much involved with getting\nit up to scratch again, and I don't think I had been responsible for\noriginally implementing it.\n\n-- \nDavid Kastrup\n"},{"id":"196601","messageId":"m2lihrxfzn.fsf@igel.home","threadId":"31193","inReplyTo":"20120807060157.GA13222@sigill.intra.peff.net","subject":"Re: info: display '--' as '-'","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2012-08-07T08:29:00Z","receivedAt":"2012-08-07T08:29:00Z","isPatch":false,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"Jeff King writes:\n\n> The data looks OK in user-manual.texi, but \"--\" is converted to \"-\" in\n> git.info. So either:\n>\n> 1. There is a bug in makeinfo, which should not be doing this\n> conversion inside a \"@display\" section.\n\nThe texinfo manual says that @display does not change the font (unlike\n@example), so the body will be rendered like normal text apart from the\nextra indentation and preserved line breaks.\n\nAndreas.\n\n-- \nAndreas Schwab, schwab@linux-m68k.org\nGPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5\n\"And now for something completely different.\"\n"},{"id":"196617","messageId":"20120807194211.GB440@sigill.intra.peff.net","threadId":"31193","inReplyTo":"874nofcgrl.fsf@fencepost.gnu.org","subject":"Re: info: display '--' as '-'","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-07T19:42:11Z","receivedAt":"2012-08-07T19:42:11Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Aug 07, 2012 at 09:17:50AM +0200, David Kastrup wrote:\n\n> Not really: @display does not change fonts, merely indentation. From\n> the Texinfo manual:\n> [...]\n> But in non-typewriter fonts, -- is a shorthand for an en-dash (see\n> \"conventions\" in the Texinfo manual):\n\nThanks, that's the missing piece I didn't have.\n\nSo it seems like docbook2-texi is at fault. The \"--\" does not have a\nspecial meaning in docbook XML, but is special markup specially in\nTexinfo source. By passing it through literally, docbook2-texi is\nchanging the meaning of the text. It should be escaped somehow, just as\nyou would escape other markup characters (e.g., \"@display\" literally in\nthe text would also need to be escaped).\n\nI suppose you could argue that the \"--\" conversion is not markup, but a\npresentation choice for free-form text. I find that a little dubious\nwhen coming from docbook, which could use \"&endash;\" if it really wanted\nan en dash.\n\n> So somewhere in your conversion chains, you should try detecting code\n> examples and translate them into @example...@end example rather than the\n> merely indented @display ... @end display. It is likely that it will\n> look better in other parts of the production chain as well.\n\nI think that's a reasonable work-around for this particular incarnation\nof the bug. I still think it's wrong of the docbook to texinfo\nconversion process to leave \"--\" in place in general, but it matters\nmost in fixed-font displays.\n\nIt looks like some of our asciidoc workarounds were causing listing\nblocks not to be marked as monospace. I've got a patch to address that,\nand it fixes this particular class of bug.\n\nHowever, we also use literal \"--\" in lots of non-monospaced contexts.\nThe whole documentation tree needs to be audited for use of \"--\" (e.g.,\nevery option mentioned in git-log.txt is currently wrong in the\ngitman.info result). I think the end result will look better, but it is\ngoing to be a giant pain.\n\n> > Cc-ing David Kastrup, who added the info version originally, and might\n> > be more clueful about that part of the toolchain.\n> \n> I think you are significantly overstating my contribution. Unless my\n> memory is failing me (always an option), I probably raised the main\n> stink at one time about the info documentation falling into a decrepit\n> state, but I don't think that I was all that much involved with getting\n> it up to scratch again, and I don't think I had been responsible for\n> originally implementing it.\n\nI based my assumption on your 4739809 (Add support for an info version\nof the user manual, 2007-08-06). I don't think any of the regular\ncontributors actually uses info, which is why it has remained largely\nuntouched since then.\n\nAnyway, I was right; you were more clueful than I (not that it took\nmuch...). Thanks for pointing me in the right direction.\n\n-Peff\n"},{"id":"196618","messageId":"20120807200738.GC440@sigill.intra.peff.net","threadId":"31193","inReplyTo":"20120807194211.GB440@sigill.intra.peff.net","subject":"[PATCH] docs: monospace listings in docbook output","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-07T20:07:38Z","receivedAt":"2012-08-07T20:07:38Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"When asciidoc converts a listing block like:\n\n----------------------\n$ git log --merge\n----------------------\n\nit marks it to be displayed in a monospace font. This works\nfine when generating HTML output. However, when generating\ndocbook output, we override the expansion of a listingblock\nto work around bugs in some versions of the docbook\ntoolchain. Our override did not mark the listingblock with\nthe \"monospaced\" class.\n\nThe main output that uses docbook as an intermediate format\nis the manpages. We didn't notice any issue there because\nthe monospaced class seems to be ignored when generating\nroff from the docbook manpages.\n\nHowever, when generating texinfo to make info pages, docbook\ndoes respect this class. The resulting texinfo output\nproperly uses \"@example\" blocks to display the listing in\nthis case. Besides possibly looking prettier in some texinfo\nbackends, one important effect is that the monospace font\nsuppresses texinfo's expansion of \"--\" and \"---\" into\nen-dashes and em-dashes. With the current code, the example\nabove ends up looking like \"git log -merge\", which is\nconfusing and wrong.\n\nSigned-off-by: Jeff King \n---\nI wonder if we can maybe just rip out our custom overrides entirely.\nThey date back to versions of docbook from 2006. I'm not sure I entirely\nunderstand their purpose, though (they seem to also be about inserting\nextra line breaks, and handling manual additions of roff).\n\nThis cleans up many of the problems with the info result. However, there\nare still lots of places that use \"--\" outside of a listing block or a\nbacktick literal. Those still look bad in the generated info page.\n\n Documentation/asciidoc.conf | 4 ++--\n Documentation/user-manual.conf | 2 +-\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex a26d245..1273a85 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -36,7 +36,7 @@ ifndef::git-asciidoc-no-roff[]\n # v1.72 breaks with this because it replaces dots not in roff requests.\n [listingblock]\n {title}\n-\n+\n ifdef::doctype-manpage[]\n .ft C \n endif::doctype-manpage[]\n@@ -53,7 +53,7 @@ ifdef::doctype-manpage[]\n # The following two small workarounds insert a simple paragraph after screen\n [listingblock]\n {title}\n-\n+\n |\n \n {title#}\ndiff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf\nindex 339b309..d87294d 100644\n--- a/Documentation/user-manual.conf\n+++ b/Documentation/user-manual.conf\n@@ -14,7 +14,7 @@ ifdef::backend-docbook[]\n # \"unbreak\" docbook-xsl v1.68 for manpages. v1.69 works with or without this.\n [listingblock]\n {title}\n-\n+\n |\n \n {title#}\n-- \n1.7.12.rc1.12.g5eaae48\n"}]}