{"thread":{"id":"16084","subject":"A typesetting problem with git man pages","startedAt":"2008-10-29T19:16:52Z","lastAt":"2008-11-03T00:12:01Z","messageCount":12,"participants":["Teemu Likonen","Jonas Fonseca","Jeff King","Junio C Hamano","Thomas Adam","Kalle Olavi Niemitalo"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"94208","messageId":"87skqfus7v.fsf@iki.fi","threadId":"16084","inReplyTo":null,"subject":"A typesetting problem with git man pages","fromName":"Teemu Likonen","fromEmail":"tlikonen@iki.fi","sentAt":"2008-10-29T19:16:52Z","receivedAt":"2008-10-29T19:16:52Z","isPatch":false,"sender":{"key":"tlikonen@iki.fi","avatar":null},"body":"I compile git and its man pages myself and I just noticed that the man\npages (invoked with \"git help log\", for example) have a typesetting\nproblem. There are \".ft\" commands here and there, like this:\n\n .ft C\n [i18n]\n commitencoding = ISO-8859-1\n .ft\n\nDoes anybody know why \"man\" prints those \".ft\" commands? The\ncorresponding code in git-log.1 file is this:\n\n \\&.ft C\n [i18n]\n commitencoding = ISO\\-8859\\-1\n \\&.ft\n\nRecently I upgraded my system from Debian 4.0 (Etch) to 5.0 (Lenny) and\nit is possible that some tools which are related to compiling the man\npages are now newer versions.\n"},{"id":"94209","messageId":"2c6b72b30810291235j554cc21dw4e3da4fdbfe633ee@mail.gmail.com","threadId":"16084","inReplyTo":"87skqfus7v.fsf@iki.fi","subject":"Re: A typesetting problem with git man pages","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2008-10-29T19:35:03Z","receivedAt":"2008-10-29T19:35:03Z","isPatch":false,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"On Wed, Oct 29, 2008 at 20:16, Teemu Likonen wrote:\n> Does anybody know why \"man\" prints those \".ft\" commands? The\n> corresponding code in git-log.1 file is this:\n>\n> \\&.ft C\n> [i18n]\n> commitencoding = ISO\\-8859\\-1\n> \\&.ft\n>\n> Recently I upgraded my system from Debian 4.0 (Etch) to 5.0 (Lenny) and\n> it is possible that some tools which are related to compiling the man\n> pages are now newer versions.\n\nI had a similar problem after upgrading on Ubuntu and came up with a\npatch to optionally disable some of asciidoc.conf (commit\n7f55cf451c9e7). Try putting DOCBOOK_XSL_172=Yes in your config.mak.\n\n-- \nJonas Fonseca\n"},{"id":"94210","messageId":"20081029193958.GA12856@sigill.intra.peff.net","threadId":"16084","inReplyTo":"87skqfus7v.fsf@iki.fi","subject":"Re: A typesetting problem with git man pages","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2008-10-29T19:39:59Z","receivedAt":"2008-10-29T19:39:59Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Oct 29, 2008 at 09:16:52PM +0200, Teemu Likonen wrote:\n\n> I compile git and its man pages myself and I just noticed that the man\n> pages (invoked with \"git help log\", for example) have a typesetting\n> problem. There are \".ft\" commands here and there, like this:\n\nI think this is Yet Another docbook or asciidoc issue. The resulting XML\nfrom asciidoc is:\n\n \n .ft C \n ... the actual example contents ...\n .ft \n \n\nwhich kind of seems wrong to me, since it implies that that is part of\nthe literal layout, and would be subject to quoting. It gets rendered\ninto git-log.1 as:\n\n \\&.ft C\n ... the actual examples contents\n \\&.ft\n\nso the problem is the extra \\&. But I don't know why that is being\ngenerated. It _should_ be part of the character entity, I thought, but\nxmlto seems to be rendering it as the newline character entity _plus_\nthe ampersand.\n\nSo it seems like a bug to me in the XML parser, but it is more likely\nthat I'm somehow clueless about XML.\n\n-Peff\n"},{"id":"94216","messageId":"2c6b72b30810291314n75154276ma226cccc1ea07504@mail.gmail.com","threadId":"16084","inReplyTo":"20081029193958.GA12856@sigill.intra.peff.net","subject":"Re: A typesetting problem with git man pages","fromName":"Jonas Fonseca","fromEmail":"jonas.fonseca@gmail.com","sentAt":"2008-10-29T20:14:35Z","receivedAt":"2008-10-29T20:14:35Z","isPatch":false,"sender":{"key":"jonas.fonseca@gmail.com","avatar":"https://gravatar.com/avatar/9b7fa23cce50269e5d164312b6ac5ae818a180f837b38f28f3bdf689dd7f96cd?d=mp&s=160"},"body":"On Wed, Oct 29, 2008 at 20:39, Jeff King wrote:\n> so the problem is the extra \\&. But I don't know why that is being\n> generated. It _should_ be part of the character entity, I thought, but\n> xmlto seems to be rendering it as the newline character entity _plus_\n> the ampersand.\n>\n> So it seems like a bug to me in the XML parser, but it is more likely\n> that I'm somehow clueless about XML.\n\nThe way I understand it is that the DocBook XSL (stylesheet) doing the\nconversion from xml to the manpage ensures that possible problematic\ncharacters that could break the manpage are escaped. A dot in the\nstart of a line is problematic since it could be interpreted as markup\nby the manpage viewer and in the mentioned case, the code was not\ngenerated by the stylesheet, thus it must be escaped. So IMO, the\nstylesheet is hardly to blame, the problem is that the asciidoc.conf\nfile defines a macro for literallayout, in which it expects manpage\ncode to be passed through unescaped.\n\n-- \nJonas Fonseca\n"},{"id":"94235","messageId":"87od13ujm4.fsf@iki.fi","threadId":"16084","inReplyTo":"2c6b72b30810291235j554cc21dw4e3da4fdbfe633ee@mail.gmail.com","subject":"Re: A typesetting problem with git man pages","fromName":"Teemu Likonen","fromEmail":"tlikonen@iki.fi","sentAt":"2008-10-29T22:22:43Z","receivedAt":"2008-10-29T22:22:43Z","isPatch":false,"sender":{"key":"tlikonen@iki.fi","avatar":null},"body":"Jonas Fonseca (2008-10-29 20:35 +0100) wrote:\n\n> On Wed, Oct 29, 2008 at 20:16, Teemu Likonen wrote:\n>> Does anybody know why \"man\" prints those \".ft\" commands? The\n>> corresponding code in git-log.1 file is this:\n\n> I had a similar problem after upgrading on Ubuntu and came up with a\n> patch to optionally disable some of asciidoc.conf (commit\n> 7f55cf451c9e7). Try putting DOCBOOK_XSL_172=Yes in your config.mak.\n\nAh, thank you. That fixed it.\n\nIn case someone is interested there is still a minor flaw that an\nexample command and the following paragraph is printed with no empty\nline between them. Like in the beginning of \"git help tutorial\", for\nexample:\n\n First, note that you can get documentation for a command such as git\n log --graph with:\n\n $ man git-log \n It is a good idea to introduce yourself to git [...]\n\nIt would be nicer if there was empty line after \"$ man git-log\". I can't\nremember if this is new issue or not. This applies only to man pages; in\nhtml pages there are nice boxes around example commands and equal\nspacing before and after them.\n"},{"id":"94271","messageId":"20081030104503.GA17131@diku.dk","threadId":"16084","inReplyTo":"87od13ujm4.fsf@iki.fi","subject":"[PATCH] asciidoc: add minor workaround to add an empty line after code blocks","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2008-10-30T10:45:03Z","receivedAt":"2008-10-30T10:45:03Z","isPatch":true,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"Insert an empty in manpages after code blocks to force and\nempty line.\n\nThe problem can be seen on the manpage for the git tutorial, where an\nexample command and the following paragraph is printed with no empty\nline between them:\n\n First, note that you can get documentation for a command such as git\n log --graph with:\n \n $ man git-log \n It is a good idea to introduce yourself to git [...]\n\nSigned-off-by: Jonas Fonseca \n---\n Documentation/asciidoc.conf | 20 ++++++++++++++++++++\n 1 files changed, 20 insertions(+), 0 deletions(-)\n\n Teemu Likonen wrote Thu, Oct 30, 2008:\n > In case someone is interested there is still a minor flaw that an\n > example command and the following paragraph is printed with no empty\n > line between them. Like in the beginning of \"git help tutorial\", for\n > example:\n > \n > First, note that you can get documentation for a command such as git\n > log --graph with:\n > \n > $ man git-log \n > It is a good idea to introduce yourself to git [...]\n > \n > It would be nicer if there was empty line after \"$ man git-log\". I can't\n > remember if this is new issue or not. This applies only to man pages; in\n > html pages there are nice boxes around example commands and equal\n > spacing before and after them.\n\n This is an old issue reported by Theodore Ts'o and fixed partially in\n commit 63c97ce228f2d2697a8ed954a9592dfb5f286338 for the URL section of\n the fetch/pull/push manpages. I have fixed this in tig using an\n approach similar to the attached. Simple and clean, but only tested\n with docbook-xsl version 1.72 so I have made it conditional.\n\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 40d43b7..2da867d 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -40,6 +40,26 @@ endif::doctype-manpage[]\n \n {title#}\n endif::docbook-xsl-172[]\n+\n+ifdef::docbook-xsl-172[]\n+ifdef::doctype-manpage[]\n+# The following two small workarounds insert a simple paragraph after screen\n+[listingblock]\n+{title}\n+\n+|\n+\n+{title#}\n+\n+[verseblock]\n+{title}\n+{title%}\n+{title#}\n+|\n+\n+{title#}\n+endif::doctype-manpage[]\n+endif::docbook-xsl-172[]\n endif::backend-docbook[]\n \n ifdef::doctype-manpage[]\n-- \n1.6.0.3.756.gb776d.dirty\n\n-- \nJonas Fonseca\n"},{"id":"94282","messageId":"8763nautqo.fsf@iki.fi","threadId":"16084","inReplyTo":"20081030104503.GA17131@diku.dk","subject":"Re: [PATCH] asciidoc: add minor workaround to add an empty line after code blocks","fromName":"Teemu Likonen","fromEmail":"tlikonen@iki.fi","sentAt":"2008-10-30T12:56:15Z","receivedAt":"2008-10-30T12:56:15Z","isPatch":true,"sender":{"key":"tlikonen@iki.fi","avatar":null},"body":"Jonas Fonseca (2008-10-30 11:45 +0100) wrote:\n\n> Insert an empty in manpages after code blocks to force and\n> empty line.\n\n> This is an old issue reported by Theodore Ts'o and fixed partially in\n> commit 63c97ce228f2d2697a8ed954a9592dfb5f286338 for the URL section\n> of the fetch/pull/push manpages. I have fixed this in tig using an\n> approach similar to the attached. Simple and clean, but only tested\n> with docbook-xsl version 1.72 so I have made it conditional.\n\nThanks. Your patch seems to work and code blocks look much nicer now. I\ntested command-line \"man\" as well as Emacs' \"M-x man\" and \"M-x woman\".\nI'm using docbook-xsl Debian package version 1.73.2.dfsg.1-4.\n\nAnother kind of formatting issue exists with some other example\ncommands, like in \"git rebase\" manpage, for example. Not that I care\nthat much, but here's an example. The asciidoc source (git-rebase.txt)\ncontains:\n\n then the command\n\n git rebase --onto topicA~5 topicA~3 topicA\n\n would result in the removal of commits F and G:\n\nIn final manpage output it looks like this:\n\n then the command \n\n git rebase --onto topicA~5 topicA~3 topicA \n would result in the removal of commits F and G:\n"},{"id":"94374","messageId":"8763n9tduo.fsf@iki.fi","threadId":"16084","inReplyTo":"2c6b72b30810291235j554cc21dw4e3da4fdbfe633ee@mail.gmail.com","subject":"Re: A typesetting problem with git man pages","fromName":"Teemu Likonen","fromEmail":"tlikonen@iki.fi","sentAt":"2008-10-31T07:37:03Z","receivedAt":"2008-10-31T07:37:03Z","isPatch":false,"sender":{"key":"tlikonen@iki.fi","avatar":null},"body":"Jonas Fonseca (2008-10-29 20:35 +0100) wrote:\n\n> On Wed, Oct 29, 2008 at 20:16, Teemu Likonen wrote:\n>> Does anybody know why \"man\" prints those \".ft\" commands? The\n>> corresponding code in git-log.1 file is this:\n>>\n>> \\&.ft C\n>> [i18n]\n>> commitencoding = ISO\\-8859\\-1\n>> \\&.ft\n>>\n>> Recently I upgraded my system from Debian 4.0 (Etch) to 5.0 (Lenny) and\n>> it is possible that some tools which are related to compiling the man\n>> pages are now newer versions.\n>\n> I had a similar problem after upgrading on Ubuntu and came up with a\n> patch to optionally disable some of asciidoc.conf (commit\n> 7f55cf451c9e7). Try putting DOCBOOK_XSL_172=Yes in your config.mak.\n\nAlas, there are still problems - or at least I have. Let's look at the\n\"git checkout\" manual page and its output in the \"EXAMPLES\" section:\n\n\n $ git checkout master âfB(1)âfR \n $ git checkout master~2 Makefile âfB(2)âfR \n $ rm -f hello.c \n $ git checkout hello.c âfB(3)âfR \n â \n âfB1. âfRswitch branch â \n âfB2. âfRtake out a file out of other commit â \n âfB3. âfRrestore hello.c from HEAD of current branch\n\n If you have an unfortunate branch that is named hello.c, this step\n would be confused as an instruction to switch to that branch. You\n should instead write:\n\n $ git checkout -- hello.c\n â\n .RE\n\n 2. After working in a wrong branch, switching to the correct branch\n would be done using:\n\n $ git checkout mytopic\n\n\nThe corresponding code in the git-checkout.txt file:\n\n\n ------------ \n $ git checkout master <1> \n $ git checkout master~2 Makefile <2> \n $ rm -f hello.c \n $ git checkout hello.c <3> \n ------------ \n + \n <1> switch branch \n <2> take out a file out of other commit \n <3> restore hello.c from HEAD of current branch\n +\n If you have an unfortunate branch that is named `hello.c`, this\n step would be confused as an instruction to switch to that branch.\n You should instead write:\n +\n ------------\n $ git checkout -- hello.c\n ------------\n\n . After working in a wrong branch, switching to the correct\n branch would be done using:\n +\n ------------\n $ git checkout mytopic\n ------------\n"},{"id":"94380","messageId":"871vxxtb2d.fsf@iki.fi","threadId":"16084","inReplyTo":"8763n9tduo.fsf@iki.fi","subject":"Re: A typesetting problem with git man pages","fromName":"Teemu Likonen","fromEmail":"tlikonen@iki.fi","sentAt":"2008-10-31T08:37:14Z","receivedAt":"2008-10-31T08:37:14Z","isPatch":false,"sender":{"key":"tlikonen@iki.fi","avatar":null},"body":"Teemu Likonen (2008-10-31 09:37 +0200) wrote:\n\n> Alas, there are still problems - or at least I have. Let's look at the\n> \"git checkout\" manual page and its output in the \"EXAMPLES\" section:\n>\n>\n> $ git checkout master âfB(1)âfR \n> $ git checkout master~2 Makefile âfB(2)âfR \n> $ rm -f hello.c \n> $ git checkout hello.c âfB(3)âfR \n> â \n> âfB1. âfRswitch branch â \n> âfB2. âfRtake out a file out of other commit â \n> âfB3. âfRrestore hello.c from HEAD of current branch\n\nThis has been reported to Debian so perhaps the issue is\nDebian-specific. I don't know. The bug was found in Debian git-core\npackage version 1:1.5.6-1.\n\n http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=490863\n"},{"id":"94601","messageId":"7v7i7n3vwe.fsf@gitster.siamese.dyndns.org","threadId":"16084","inReplyTo":"20081030104503.GA17131@diku.dk","subject":"Re: [PATCH] asciidoc: add minor workaround to add an empty line after code blocks","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-11-01T22:48:33Z","receivedAt":"2008-11-01T22:48:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thanks; I do not have an environment with docbook-xsl-172 handy, so I'll\njust take your word and apply it to 'maint'.\n"},{"id":"94605","messageId":"18071eea0811011642g6bc36530sf2036ef15ce0df82@mail.gmail.com","threadId":"16084","inReplyTo":"7v7i7n3vwe.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] asciidoc: add minor workaround to add an empty line after code blocks","fromName":"Thomas Adam","fromEmail":"thomas.adam22@gmail.com","sentAt":"2008-11-01T23:42:44Z","receivedAt":"2008-11-01T23:42:44Z","isPatch":true,"sender":{"key":"thomas.adam22@gmail.com","avatar":"https://gravatar.com/avatar/137f9858bc6bfd5b2f743aefd988c81ce0cbd306248889df80e269519cfc8741?d=mp&s=160"},"body":"Hello --\n\n2008/11/1 Junio C Hamano :\n> Thanks; I do not have an environment with docbook-xsl-172 handy, so I'll\n> just take your word and apply it to 'maint'.\n\nJust out of interest, how much progression on the asciidoc Git\ndocumentation is there with respect to the latest version of asciidoc\nwhich might give new features, if that makes sense? Something the\nELinks project does is distribute a fixed version of the asciidoc\nscript to avoid annoying asciidoc errors each time there's a new\nasciidoc release.\n\nIs this something worth considering for Git as well?\n\n-- Thomas Adam\n"},{"id":"94709","messageId":"87k5blsm5q.fsf@Astalo.kon.iki.fi","threadId":"16084","inReplyTo":"18071eea0811011642g6bc36530sf2036ef15ce0df82@mail.gmail.com","subject":"Re: [PATCH] asciidoc: add minor workaround to add an empty line after code blocks","fromName":"Kalle Olavi Niemitalo","fromEmail":"kon@iki.fi","sentAt":"2008-11-03T00:12:01Z","receivedAt":"2008-11-03T00:12:01Z","isPatch":true,"sender":{"key":"kon@iki.fi","avatar":null},"body":"\"Thomas Adam\" writes:\n\n> Something the ELinks project does is distribute a fixed version\n> of the asciidoc script to avoid annoying asciidoc errors each\n> time there's a new asciidoc release.\n\nActually, we only distribute the AsciiDoc configuration files.\nI should perhaps add the actual asciidoc Python script to the\nELinks source tree as well. That seems to be the recommendation\nin the AsciiDoc manual.\n\nhttp://www.methods.co.nz/asciidoc/userguide.html#_shipping_stand_alone_asciidoc_source\n"}]}