{"thread":{"id":"46977","subject":"Minor man page weirdness?","startedAt":"2017-10-16T18:28:24Z","lastAt":"2017-10-19T22:29:28Z","messageCount":16,"participants":["Lars Schneider","Jeff King","Andreas Schwab","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"330476","messageId":"A4E5D8CC-19A7-442A-814C-FD5A46391982@gmail.com","threadId":"46977","inReplyTo":null,"subject":"Minor man page weirdness?","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2017-10-16T14:16:49Z","receivedAt":"2017-10-16T18:28:24Z","isPatch":false,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"Hi,\n\nI just noticed that a space between \"-f\" and \"git\" is missing in `man git-branch`.\nThe space is present in \"Documentation/git-branch.txt\", though. I am using `man`\nversion 1.6c on macOS.\n\n-f, --force\n Reset to if exists already. Without\n -fgit branch refuses to change an existing branch. In combination with -d (or\n ^^\n\nCan you reproduce the \"problem\"?\n\nCheers,\nLars"},{"id":"330488","messageId":"20171016225641.x76jwycb7mcpvrw3@sigill.intra.peff.net","threadId":"46977","inReplyTo":"A4E5D8CC-19A7-442A-814C-FD5A46391982@gmail.com","subject":"Re: Minor man page weirdness?","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-16T22:56:41Z","receivedAt":"2017-10-16T22:56:47Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Oct 16, 2017 at 07:16:49AM -0700, Lars Schneider wrote:\n\n> Hi,\n> \n> I just noticed that a space between \"-f\" and \"git\" is missing in `man git-branch`.\n> The space is present in \"Documentation/git-branch.txt\", though. I am using `man`\n> version 1.6c on macOS.\n> \n> -f, --force\n> Reset to if exists already. Without\n> -fgit branch refuses to change an existing branch. In combination with -d (or\n> ^^\n> \n> Can you reproduce the \"problem\"?\n\nI don't see it on my copy (Debian man-db 2.7.6.1-2) . What does:\n\n cd Documentation\n make git-branch.1\n grep Without git-branch.xml\n\nshow? I see:\n\n ... -f git branch ...\n\nIf there's no space there, then the problem is in asciidoc. If not, then\nwe can further check:\n\n grep -A3 Without git-branch.1\n\nI get:\n\n Reset to if exists already\\&. Without\n \\fB\\-f\\fR\n \\fIgit branch\\fR\n refuses to change an existing branch\\&. In combination with\n\nSince there's no space there, I think we're relying on roff to insert\none between lines. I'm not familiar enough with roff to say if that's a\nreasonable expectation or not. But if the problem is at this level, it's\nactually an issue between docbook and roff, and there's probably not a\nlot we can do on the Git side.\n\nWe do have some hacks/workarounds for broken versions of the toolchain.\nYou can try tweaking various knobs you find in Documentation/Makefile).\nDOCBOOK_SUPPRESS_SP sounds promising, but I think it actually does the\nopposite (removes extra spaces).\n\n-Peff\n"},{"id":"330550","messageId":"87d15lu48o.fsf@linux-m68k.org","threadId":"46977","inReplyTo":"20171016225641.x76jwycb7mcpvrw3@sigill.intra.peff.net","subject":"Re: Minor man page weirdness?","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2017-10-17T16:29:59Z","receivedAt":"2017-10-17T16:30:08Z","isPatch":false,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"On Okt 16 2017, Jeff King wrote:\n\n> I get:\n>\n> Reset to if exists already\\&. Without\n> \\fB\\-f\\fR\n> \\fIgit branch\\fR\n> refuses to change an existing branch\\&. In combination with\n\nI see this in git-branch.1:\n\n Reset to if exists already\\&. Without\n \\fB\\-f\\fR\\fIgit branch\\fR\n refuses to change an existing branch\\&. In combination with\n\nThis is with asciidoc 8.6.9.\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":"330551","messageId":"20171017163828.igmlsbdynpe6m37w@sigill.intra.peff.net","threadId":"46977","inReplyTo":"87d15lu48o.fsf@linux-m68k.org","subject":"Re: Minor man page weirdness?","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-17T16:38:29Z","receivedAt":"2017-10-17T16:38:35Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Oct 17, 2017 at 06:29:59PM +0200, Andreas Schwab wrote:\n\n> On Okt 16 2017, Jeff King wrote:\n> \n> > I get:\n> >\n> > Reset to if exists already\\&. Without\n> > \\fB\\-f\\fR\n> > \\fIgit branch\\fR\n> > refuses to change an existing branch\\&. In combination with\n> \n> I see this in git-branch.1:\n> \n> Reset to if exists already\\&. Without\n> \\fB\\-f\\fR\\fIgit branch\\fR\n> refuses to change an existing branch\\&. In combination with\n> \n> This is with asciidoc 8.6.9.\n\nThanks, that seems a likely culprit, then. What's in your git-branch.xml\nafter you build the documentation?\n\n-Peff\n"},{"id":"330553","messageId":"878tg9u1o7.fsf@linux-m68k.org","threadId":"46977","inReplyTo":"20171017163828.igmlsbdynpe6m37w@sigill.intra.peff.net","subject":"Re: Minor man page weirdness?","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2017-10-17T17:25:28Z","receivedAt":"2017-10-17T17:25:36Z","isPatch":false,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"On Okt 17 2017, Jeff King wrote:\n\n> On Tue, Oct 17, 2017 at 06:29:59PM +0200, Andreas Schwab wrote:\n>\n>> On Okt 16 2017, Jeff King wrote:\n>> \n>> > I get:\n>> >\n>> > Reset to if exists already\\&. Without\n>> > \\fB\\-f\\fR\n>> > \\fIgit branch\\fR\n>> > refuses to change an existing branch\\&. In combination with\n>> \n>> I see this in git-branch.1:\n>> \n>> Reset to if exists already\\&. Without\n>> \\fB\\-f\\fR\\fIgit branch\\fR\n>> refuses to change an existing branch\\&. In combination with\n>> \n>> This is with asciidoc 8.6.9.\n>\n> Thanks, that seems a likely culprit, then. What's in your git-branch.xml\n> after you build the documentation?\n\nSame as yours, with the space. I'd guess it's rather xmlto (version\n0.0.25) that's the culprit here.\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":"330554","messageId":"20171017172930.var7jsodxtgzoz5t@sigill.intra.peff.net","threadId":"46977","inReplyTo":"878tg9u1o7.fsf@linux-m68k.org","subject":"Re: Minor man page weirdness?","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-17T17:29:30Z","receivedAt":"2017-10-17T17:29:37Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Oct 17, 2017 at 07:25:28PM +0200, Andreas Schwab wrote:\n\n> >> I see this in git-branch.1:\n> >> \n> >> Reset to if exists already\\&. Without\n> >> \\fB\\-f\\fR\\fIgit branch\\fR\n> >> refuses to change an existing branch\\&. In combination with\n> >> \n> >> This is with asciidoc 8.6.9.\n> >\n> > Thanks, that seems a likely culprit, then. What's in your git-branch.xml\n> > after you build the documentation?\n> \n> Same as yours, with the space. I'd guess it's rather xmlto (version\n> 0.0.25) that's the culprit here.\n\nYes, it's in that step, but xmlto is just driving the xslt\ntransformation done by docbook. So the interesting version is probably\ndocbook. I have docbook-xsl 1.79.1+dfsg-2 (from Debian unstable).\n\n-Peff\n"},{"id":"330562","messageId":"874lqxu0fw.fsf@linux-m68k.org","threadId":"46977","inReplyTo":"20171017172930.var7jsodxtgzoz5t@sigill.intra.peff.net","subject":"Re: Minor man page weirdness?","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2017-10-17T17:52:03Z","receivedAt":"2017-10-17T17:52:10Z","isPatch":false,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"On Okt 17 2017, Jeff King wrote:\n\n> On Tue, Oct 17, 2017 at 07:25:28PM +0200, Andreas Schwab wrote:\n>\n>> >> I see this in git-branch.1:\n>> >> \n>> >> Reset to if exists already\\&. Without\n>> >> \\fB\\-f\\fR\\fIgit branch\\fR\n>> >> refuses to change an existing branch\\&. In combination with\n>> >> \n>> >> This is with asciidoc 8.6.9.\n>> >\n>> > Thanks, that seems a likely culprit, then. What's in your git-branch.xml\n>> > after you build the documentation?\n>> \n>> Same as yours, with the space. I'd guess it's rather xmlto (version\n>> 0.0.25) that's the culprit here.\n>\n> Yes, it's in that step, but xmlto is just driving the xslt\n> transformation done by docbook. So the interesting version is probably\n> docbook. I have docbook-xsl 1.79.1+dfsg-2 (from Debian unstable).\n\ndocbook-xsl-stylesheets-1.78.1+svn9743\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":"330564","messageId":"87zi8psli3.fsf@linux-m68k.org","threadId":"46977","inReplyTo":"20171016225641.x76jwycb7mcpvrw3@sigill.intra.peff.net","subject":"Re: Minor man page weirdness?","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2017-10-17T18:00:04Z","receivedAt":"2017-10-17T18:00:18Z","isPatch":false,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"On Okt 16 2017, Jeff King wrote:\n\n> We do have some hacks/workarounds for broken versions of the toolchain.\n> You can try tweaking various knobs you find in Documentation/Makefile).\n> DOCBOOK_SUPPRESS_SP sounds promising, but I think it actually does the\n> opposite (removes extra spaces).\n\nAn easy workaround would be to add a comma between `-f` and 'git\nbranch'.\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":"330566","messageId":"20171017191108.6tcmpbuasbgrb4sk@sigill.intra.peff.net","threadId":"46977","inReplyTo":"874lqxu0fw.fsf@linux-m68k.org","subject":"Re: Minor man page weirdness?","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-17T19:11:08Z","receivedAt":"2017-10-17T19:11:15Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Oct 17, 2017 at 07:52:03PM +0200, Andreas Schwab wrote:\n\n> > Yes, it's in that step, but xmlto is just driving the xslt\n> > transformation done by docbook. So the interesting version is probably\n> > docbook. I have docbook-xsl 1.79.1+dfsg-2 (from Debian unstable).\n> \n> docbook-xsl-stylesheets-1.78.1+svn9743\n\nHmm. That could be it, though I was unable to bisect on the docbook repo\nsince I couldn't get their build to work reliably.\n\nOne other thing to try:\n\n rm git-branch.1\n make NO_MAN_BOLD_LITERAL=1 git-branch.1\n\nIt's possible our snippet to add in the bolding causes problems.\n\n-Peff\n"},{"id":"330568","messageId":"87r2u1sfrz.fsf@linux-m68k.org","threadId":"46977","inReplyTo":"20171017191108.6tcmpbuasbgrb4sk@sigill.intra.peff.net","subject":"Re: Minor man page weirdness?","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2017-10-17T20:03:44Z","receivedAt":"2017-10-17T20:03:52Z","isPatch":false,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"On Okt 17 2017, Jeff King wrote:\n\n> One other thing to try:\n>\n> rm git-branch.1\n> make NO_MAN_BOLD_LITERAL=1 git-branch.1\n\nThat doesn't help:\n\n Reset to if exists already\\&. Without\n \\-f\\fIgit branch\\fR\n refuses to change an existing branch\\&. In combination with\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":"330570","messageId":"xmqq1sm1o5k5.fsf@gitster.mtv.corp.google.com","threadId":"46977","inReplyTo":"87zi8psli3.fsf@linux-m68k.org","subject":"Re: Minor man page weirdness?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-17T20:58:02Z","receivedAt":"2017-10-17T20:58:10Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Schwab writes:\n\n> On Okt 16 2017, Jeff King wrote:\n>\n>> We do have some hacks/workarounds for broken versions of the toolchain.\n>> You can try tweaking various knobs you find in Documentation/Makefile).\n>> DOCBOOK_SUPPRESS_SP sounds promising, but I think it actually does the\n>> opposite (removes extra spaces).\n>\n> An easy workaround would be to add a comma between `-f` and 'git\n> branch'.\n\nThat sounds like a good idea, regardless of the mark-up issue.\n"},{"id":"330589","messageId":"xmqqfuahkwug.fsf@gitster.mtv.corp.google.com","threadId":"46977","inReplyTo":"xmqq1sm1o5k5.fsf@gitster.mtv.corp.google.com","subject":"Re: Minor man page weirdness?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-18T02:34:31Z","receivedAt":"2017-10-18T02:34:39Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Andreas Schwab writes:\n>\n>> On Okt 16 2017, Jeff King wrote:\n>>\n>>> We do have some hacks/workarounds for broken versions of the toolchain.\n>>> You can try tweaking various knobs you find in Documentation/Makefile).\n>>> DOCBOOK_SUPPRESS_SP sounds promising, but I think it actually does the\n>>> opposite (removes extra spaces).\n>>\n>> An easy workaround would be to add a comma between `-f` and 'git\n>> branch'.\n>\n> That sounds like a good idea, regardless of the mark-up issue.\n\n-- >8 --\nbranch doc: sprinkle a few commas for readability\n\nThe \"--force\" option can also be used when the named branch does not\nyet exist, and the point of the option is the user can (re)point the\nbranch to the named commit even if it does. Add 'even' before 'if'\nto clarify. Also, insert another comma after \"Without -f\" before\n\"the command refuses...\" to make the text easier to parse.\n\nIncidentally, this change should help certain versions of\ndocbook-xsl-stylesheets that renders the original without any\nwhitespace between \"-f\" and \"git\".\n\nNoticed-by: Lars Schneider \nHelped-by: Jeff King \nHelped-by: Andreas Schwab \nSigned-off-by: Junio C Hamano \n---\n Documentation/git-branch.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex fe029ac6fc..d6587c5e96 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -104,8 +104,8 @@ OPTIONS\n \n -f::\n --force::\n-\tReset to if exists\n-\talready. Without `-f` 'git branch' refuses to change an existing branch.\n+\tReset to , even if exists\n+\talready. Without `-f`, 'git branch' refuses to change an existing branch.\n \tIn combination with `-d` (or `--delete`), allow deleting the\n \tbranch irrespective of its merged status. In combination with\n \t`-m` (or `--move`), allow renaming the branch even if the new\n\n\n"},{"id":"330590","messageId":"20171018032103.p6bz7wciiedokiyy@sigill.intra.peff.net","threadId":"46977","inReplyTo":"xmqqfuahkwug.fsf@gitster.mtv.corp.google.com","subject":"Re: Minor man page weirdness?","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-18T03:21:04Z","receivedAt":"2017-10-18T03:21:10Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Oct 18, 2017 at 11:34:31AM +0900, Junio C Hamano wrote:\n\n> -- >8 --\n> branch doc: sprinkle a few commas for readability\n> \n> The \"--force\" option can also be used when the named branch does not\n> yet exist, and the point of the option is the user can (re)point the\n> branch to the named commit even if it does. Add 'even' before 'if'\n> to clarify. Also, insert another comma after \"Without -f\" before\n> \"the command refuses...\" to make the text easier to parse.\n> \n> Incidentally, this change should help certain versions of\n> docbook-xsl-stylesheets that renders the original without any\n> whitespace between \"-f\" and \"git\".\n\nThanks, this looks good.\n\nIt does make me wonder if there are other instances of the missing-space\nproblem lurking. Grepping for backtick followed by single-quote shows\nonly one more case in user-manual.txt. I have no idea if that one hits\nthe same problem on older docbook versions. Or if it's a problem for any\nother punctuation combinations. I'm happy to punt on it until somebody\nwith an affected docbook produces more bug reports. :)\n\n-Peff\n"},{"id":"330591","messageId":"xmqqbml5ktrk.fsf@gitster.mtv.corp.google.com","threadId":"46977","inReplyTo":"20171018032103.p6bz7wciiedokiyy@sigill.intra.peff.net","subject":"Re: Minor man page weirdness?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-18T03:41:03Z","receivedAt":"2017-10-18T03:41:12Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> It does make me wonder if there are other instances of the missing-space\n> problem lurking. Grepping for backtick followed by single-quote shows\n> only one more case in user-manual.txt. I have no idea if that one hits\n> the same problem on older docbook versions.\n\nI had an impression that this is only for roff, but we do not\nproduce user-manual.[0-9], do we?\n\n> Or if it's a problem for any\n> other punctuation combinations. I'm happy to punt on it until somebody\n> with an affected docbook produces more bug reports. :)\n\nYup, we cannot _fix_ what we do not know are broken ;-)\n\nThanks.\n"},{"id":"330592","messageId":"20171018040146.xuhchqtmzqzkzbgf@sigill.intra.peff.net","threadId":"46977","inReplyTo":"xmqqbml5ktrk.fsf@gitster.mtv.corp.google.com","subject":"Re: Minor man page weirdness?","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-18T04:01:46Z","receivedAt":"2017-10-18T04:01:53Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Oct 18, 2017 at 12:41:03PM +0900, Junio C Hamano wrote:\n\n> Jeff King writes:\n> \n> > It does make me wonder if there are other instances of the missing-space\n> > problem lurking. Grepping for backtick followed by single-quote shows\n> > only one more case in user-manual.txt. I have no idea if that one hits\n> > the same problem on older docbook versions.\n> \n> I had an impression that this is only for roff, but we do not\n> produce user-manual.[0-9], do we?\n\nYeah, I think you're right. We do produce XML of it, but it goes to\nother formats like texi and pdf (and if this is a docbook bug, it may or\nmay not be present in those other output formats).\n\n-Peff\n"},{"id":"330697","messageId":"A34B4C99-94FD-4EF2-AE60-0522D621BAE6@gmail.com","threadId":"46977","inReplyTo":"20171018032103.p6bz7wciiedokiyy@sigill.intra.peff.net","subject":"Re: Minor man page weirdness?","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2017-10-19T22:29:21Z","receivedAt":"2017-10-19T22:29:28Z","isPatch":false,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"\n> On 18 Oct 2017, at 05:21, Jeff King wrote:\n> \n> On Wed, Oct 18, 2017 at 11:34:31AM +0900, Junio C Hamano wrote:\n> \n>> -- >8 --\n>> branch doc: sprinkle a few commas for readability\n>> \n>> The \"--force\" option can also be used when the named branch does not\n>> yet exist, and the point of the option is the user can (re)point the\n>> branch to the named commit even if it does. Add 'even' before 'if'\n>> to clarify. Also, insert another comma after \"Without -f\" before\n>> \"the command refuses...\" to make the text easier to parse.\n>> \n>> Incidentally, this change should help certain versions of\n>> docbook-xsl-stylesheets that renders the original without any\n>> whitespace between \"-f\" and \"git\".\n> \n> Thanks, this looks good.\n\nTo me, too! Thanks for investigating and fixing the issue :-)\n\n- Lars\n\n"}]}