{"thread":{"id":"44346","subject":"[PATCH] doc: fix merge-base ASCII art tab spacing","startedAt":"2016-10-20T23:40:22Z","lastAt":"2016-10-25T11:40:02Z","messageCount":10,"participants":["Philip Oakley","Jeff King","Junio C Hamano","Johannes Schindelin"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"304547","messageId":"20161020234009.1768-1-philipoakley@iee.org","threadId":"44346","inReplyTo":null,"subject":"[PATCH] doc: fix merge-base ASCII art tab spacing","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-10-20T23:40:09Z","receivedAt":"2016-10-20T23:40:22Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The doc-tool stack does not always respect the 'tab = 8 spaces' rule,\nparticularly the git-scm doc pages https://git-scm.com/docs/git-merge-base\nand the Git generated html pages.\n\nUse just spaces within the block of the ascii art.\n\nNoticed when reviewing Junio's suggested update to `git merge-base`\nhttps://public-inbox.org/git/xmqqmvi2sj8f.fsf@gitster.mtv.corp.google.com/T/#u\n\n\nSigned-off-by: Philip Oakley \n---\n\nA fixed consistent prefix of tabs is OK, but once that lead is done, stay\nwith spaces only.\n\nThis complements the jc/merge-base-fp-only series.\n\n---\n Documentation/git-merge-base.txt | 26 +++++++++++++-------------\n 1 file changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt\nindex 808426f..b968b64 100644\n--- a/Documentation/git-merge-base.txt\n+++ b/Documentation/git-merge-base.txt\n@@ -80,8 +80,8 @@ which is reachable from both 'A' and 'B' through the parent relationship.\n \n For example, with this topology:\n \n-\t\t o---o---o---B\n-\t\t/\n+\t o---o---o---B\n+\t /\n \t---o---1---o---o---o---A\n \n the merge base between 'A' and 'B' is '1'.\n@@ -116,11 +116,11 @@ the best common ancestor of all commits.\n When the history involves criss-cross merges, there can be more than one\n 'best' common ancestor for two commits. For example, with this topology:\n \n- ---1---o---A\n-\t \\ /\n-\t X\n-\t / \\\n- ---2---o---o---B\n+\t---1---o---A\n+\t \\ /\n+\t X\n+\t / \\\n+\t---2---o---o---B\n \n both '1' and '2' are merge-bases of A and B. Neither one is better than\n the other (both are 'best' merge bases). When the `--all` option is not given,\n@@ -154,13 +154,13 @@ topic origin/master`, the history of remote-tracking branch\n `origin/master` may have been rewound and rebuilt, leading to a\n history of this shape:\n \n-\t\t\t o---B1\n-\t\t\t/\n+\t o---B1\n+\t /\n \t---o---o---B2--o---o---o---B (origin/master)\n-\t\t\\\n-\t\t B3\n-\t\t \\\n-\t\t Derived (topic)\n+\t \\\n+\t B3\n+\t \\\n+\t Derived (topic)\n \n where `origin/master` used to point at commits B3, B2, B1 and now it\n points at B, and your `topic` branch was started on top of it back\n-- \n2.9.0.windows.1.323.g0305acf\n\n"},{"id":"304550","messageId":"20161021002252.u5v3mwjopvsdcexg@sigill.intra.peff.net","threadId":"44346","inReplyTo":"20161020234009.1768-1-philipoakley@iee.org","subject":"Re: [PATCH] doc: fix merge-base ASCII art tab spacing","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-10-21T00:22:52Z","receivedAt":"2016-10-21T00:23:00Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Oct 21, 2016 at 12:40:09AM +0100, Philip Oakley wrote:\n\n> The doc-tool stack does not always respect the 'tab = 8 spaces' rule,\n> particularly the git-scm doc pages https://git-scm.com/docs/git-merge-base\n> and the Git generated html pages.\n\nHmm, I thought git-scm.com was fixed by:\n\n https://github.com/git/git-scm.com/commit/1e13397edccdecd0e06ff851cffaa1c44e140bf3\n\nNot that I mind using spaces consistently here on principle. I just\ndidn't think it was a problem anymore (my asciidoc seems to get it\nright, too).\n\n-Peff\n"},{"id":"304553","messageId":"xmqqa8dyeebj.fsf@gitster.mtv.corp.google.com","threadId":"44346","inReplyTo":"20161020234009.1768-1-philipoakley@iee.org","subject":"Re: [PATCH] doc: fix merge-base ASCII art tab spacing","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-21T00:27:44Z","receivedAt":"2016-10-21T00:27:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> The doc-tool stack does not always respect the 'tab = 8 spaces' rule,\n> particularly the git-scm doc pages https://git-scm.com/docs/git-merge-base\n> and the Git generated html pages.\n\nSorry, but I do not understand this change.\n\nhttps://git.github.io/htmldocs/git-merge-base.html is \"Git generated\nHTML page\" and I do not see any breakage around the drawings this\npatch touches, and the fp-path series does not touch these drawings,\neither.\n\nIf a broken \"doc-tool stack\" breaks the formatting, I'd prefer to\nsee that \"doc-tool stack\" fixed, instead of working around by\nupdating the source they work on. Otherwise, the broken \"doc-tool\nstack\" will keep producing broken output next time a source that\nrespects \"tab is to skip to the next multiple of 8\" rule is fed to\nit, no?\n\n"},{"id":"304554","messageId":"xmqq60omedcr.fsf@gitster.mtv.corp.google.com","threadId":"44346","inReplyTo":"20161021002252.u5v3mwjopvsdcexg@sigill.intra.peff.net","subject":"Re: [PATCH] doc: fix merge-base ASCII art tab spacing","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-21T00:48:36Z","receivedAt":"2016-10-21T00:48:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Fri, Oct 21, 2016 at 12:40:09AM +0100, Philip Oakley wrote:\n>\n>> The doc-tool stack does not always respect the 'tab = 8 spaces' rule,\n>> particularly the git-scm doc pages https://git-scm.com/docs/git-merge-base\n>> and the Git generated html pages.\n>\n> Hmm, I thought git-scm.com was fixed by:\n>\n> https://github.com/git/git-scm.com/commit/1e13397edccdecd0e06ff851cffaa1c44e140bf3\n>\n> Not that I mind using spaces consistently here on principle. I just\n> didn't think it was a problem anymore (my asciidoc seems to get it\n> right, too).\n\nI do not terribly mind it, either, and I'd prefer to apply Philip's\npatch eventually. But I'd rather want to do so _after_ known broken\nsites, if there are any, are fixed by correcting their tools.\n\n"},{"id":"304644","messageId":"D861234B3E78496DBA70EE63B2BCDB96@PhilipOakley","threadId":"44346","inReplyTo":"xmqqa8dyeebj.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] doc: fix merge-base ASCII art tab spacing","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-10-21T21:26:29Z","receivedAt":"2016-10-21T21:26:38Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Philip Oakley writes:\n>\n>> The doc-tool stack does not always respect the 'tab = 8 spaces' rule,\n>> particularly the git-scm doc pages \n>> https://git-scm.com/docs/git-merge-base\n>> and the Git generated html pages.\n>\n> Sorry, but I do not understand this change.\n>\n> https://git.github.io/htmldocs/git-merge-base.html is \"Git generated\n> HTML page\" and I do not see any breakage around the drawings this\n> patch touches, and the fp-path series does not touch these drawings,\n> either.\n>\n\nI'd been looking the Git for Windows output, which has the same breakage, \nrather than yours. Apologies for failing to check there.\n\n> If a broken \"doc-tool stack\" breaks the formatting, I'd prefer to\n> see that \"doc-tool stack\" fixed, instead of working around by\n\nThe doc-tool stack is question is asciidoctor. It looks like it is an \nexplicit decision that the the 8 space tab substitution is deprecated in \nthese case (see http://asciidoctor.org/docs/user-manual/#migrate-deprecated \n#96.3)\n\nIt appears that acciidoctor sees the art as being a separated mono-spaced \nblock, with border/background as locally appropriate. While the asciidoc \nlooks to simply change to mono-spaced text.\n\n> updating the source they work on. Otherwise, the broken \"doc-tool\n> stack\" will keep producing broken output next time a source that\n> respects \"tab is to skip to the next multiple of 8\" rule is fed to\n> it, no?\n\nBy avoiding tabs *within the art* we would also be tolerant of those who may \nnot have a set their tab spacing to 8 when viewing the raw text.\n\nIt's particularly the criss-cross diagram that needs fixed one way or \nanother (for the doc/doctor differences).\n\nThe update of the asciidoctor version for git-scm, as reported by peff isn't \nsufficient for this case.\n\nalso cc'ing dscho as this breakage shows in GfW (issue 923)\n\nPhilip\n\n\n"},{"id":"304655","messageId":"xmqq1sz9b9ex.fsf@gitster.mtv.corp.google.com","threadId":"44346","inReplyTo":"D861234B3E78496DBA70EE63B2BCDB96@PhilipOakley","subject":"Re: [PATCH] doc: fix merge-base ASCII art tab spacing","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-21T22:54:14Z","receivedAt":"2016-10-21T22:54:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> It appears that acciidoctor sees the art as being a separated\n> mono-spaced block, with border/background as locally\n> appropriate. While the asciidoc looks to simply change to mono-spaced\n> text.\n\nFWIW, I changed my mind and your patch is now queued on 'next'.\n\nThanks.\n\n"},{"id":"304663","messageId":"20161022010918.knvbxwlnjdqedwni@sigill.intra.peff.net","threadId":"44346","inReplyTo":"D861234B3E78496DBA70EE63B2BCDB96@PhilipOakley","subject":"Re: [PATCH] doc: fix merge-base ASCII art tab spacing","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-10-22T01:09:19Z","receivedAt":"2016-10-22T01:09:26Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Oct 21, 2016 at 10:26:29PM +0100, Philip Oakley wrote:\n\n> > updating the source they work on. Otherwise, the broken \"doc-tool\n> > stack\" will keep producing broken output next time a source that\n> > respects \"tab is to skip to the next multiple of 8\" rule is fed to\n> > it, no?\n> \n> By avoiding tabs *within the art* we would also be tolerant of those who may\n> not have a set their tab spacing to 8 when viewing the raw text.\n> \n> It's particularly the criss-cross diagram that needs fixed one way or\n> another (for the doc/doctor differences).\n\nI think the new asciidoctor correctly handles tabs within the art. The\nearlier diagrams begin each line with a tab (to mark the pre-formatted\nblock), and then only some of the lines have additional tabs, and expect\nthose tabs to expand to 8 characters to line up with the other bits\n(which is what caused a problem with earlier asciidoctor).\n\nWhat is funny about that criss-cross diagram is that it actually chooses\ndifferent markers on each line to start the art: sometimes tabs and\nsometimes spaces. And that seems to confuse even recent versions of\nasciidoctor.\n\nIt may be that asciidoctor is wrong here, but I have to admit we are\nventuring well into \"what happens to work with asciidoc\" territory, and\nthe right solution is just fixing the diagram (i.e., your patch).\n\n-Peff\n"},{"id":"304672","messageId":"715E1D41ACDD40D0B8046CA9220B77A9@PhilipOakley","threadId":"44346","inReplyTo":"xmqq1sz9b9ex.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] doc: fix merge-base ASCII art tab spacing","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-10-22T05:45:38Z","receivedAt":"2016-10-22T05:45:49Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> \"Philip Oakley\" writes:\n> \n>> It appears that acciidoctor sees the art as being a separated\n>> mono-spaced block, with border/background as locally\n>> appropriate. While the asciidoc looks to simply change to mono-spaced\n>> text.\n> \n> FWIW, I changed my mind and your patch is now queued on 'next'.\n> \n> Thanks.\n> \nMany thanks\n\nPhilip\n"},{"id":"304809","messageId":"20161024215432.1384-1-philipoakley@iee.org","threadId":"44346","inReplyTo":"xmqq1sz9b9ex.fsf@gitster.mtv.corp.google.com","subject":"[PATCH] doc: fix the 'revert a faulty merge' ASCII art tab spacing","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-10-24T21:54:32Z","receivedAt":"2016-10-24T21:56:46Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The asciidoctor doc-tool stack does not always respect the 'tab = 8 spaces' rule\nexpectation, particularly for the Git-for-Windows generated html pages. This\nfollows on from the 'doc: fix merge-base ASCII art tab spacing' fix.\n\nUse just spaces within the block of the ascii art.\n\nAll other *.txt ascii art containing three dashes has been checked.\nAsciidoctor correctly formats the other art blocks that do contain tabs.\n\nSigned-off-by: Philip Oakley The asciidoctor doc-tool stack does not always respect the 'tab = 8 spaces' rule\n> expectation, particularly for the Git-for-Windows generated html pages. This\n> follows on from the 'doc: fix merge-base ASCII art tab spacing' fix.\n> \n> Use just spaces within the block of the ascii art.\n> \n> All other *.txt ascii art containing three dashes has been checked.\n> Asciidoctor correctly formats the other art blocks that do contain tabs.\n> \n> Signed-off-by: Philip Oakley ---\n> The git-scm doc pages https://git-scm.com/docs/ does not convert this\n> how-to document to html, rather it links to the Github text pages, which\n> does respect the 8 space tab rule.\n\nI confirm that this fixes the misaligned branches when building the\ndocumentation with asciidoctor 1.5.4 in Git for Windows' SDK.\n\nCiao,\nDscho\n"}]}