[PATCH] doc: fix merge-base ASCII art tab spacing

[PATCH] doc: fix merge-base ASCII art tab spacing

[Philip Oakley]

The doc-tool stack does not always respect the 'tab = 8 spaces' rule,
particularly the git-scm doc pages https://git-scm.com/docs/git-merge-base
and the Git generated html pages.

Use just spaces within the block of the ascii art.

Noticed when reviewing Junio's suggested update to `git merge-base`
https://public-inbox.org/git/xmqqmvi2sj8f.fsf@gitster.mtv.corp.google.com/T/#u


Signed-off-by: Philip Oakley <philipoakley@iee.org>
---

A fixed consistent prefix of tabs is OK, but once that lead is done, stay
with spaces only.

This complements the jc/merge-base-fp-only series.

---
 Documentation/git-merge-base.txt | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index 808426f..b968b64 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -80,8 +80,8 @@ which is reachable from both 'A' and 'B' through the parent relationship.
 
 For example, with this topology:
 
-		 o---o---o---B
-		/
+	         o---o---o---B
+	        /
 	---o---1---o---o---o---A
 
 the merge base between 'A' and 'B' is '1'.
@@ -116,11 +116,11 @@ the best common ancestor of all commits.
 When the history involves criss-cross merges, there can be more than one
 'best' common ancestor for two commits.  For example, with this topology:
 
-       ---1---o---A
-	   \ /
-	    X
-	   / \
-       ---2---o---o---B
+	---1---o---A
+	    \ /
+	     X
+	    / \
+	---2---o---o---B
 
 both '1' and '2' are merge-bases of A and B.  Neither one is better than
 the other (both are 'best' merge bases).  When the `--all` option is not given,
@@ -154,13 +154,13 @@ topic origin/master`, the history of remote-tracking branch
 `origin/master` may have been rewound and rebuilt, leading to a
 history of this shape:
 
-			 o---B1
-			/
+	                 o---B1
+	                /
 	---o---o---B2--o---o---o---B (origin/master)
-		\
-		 B3
-		  \
-		   Derived (topic)
+	        \
+	         B3
+	          \
+	           Derived (topic)
 
 where `origin/master` used to point at commits B3, B2, B1 and now it
 points at B, and your `topic` branch was started on top of it back
-- 
2.9.0.windows.1.323.g0305acf

Re: [PATCH] doc: fix merge-base ASCII art tab spacing

[Jeff King]

On Fri, Oct 21, 2016 at 12:40:09AM +0100, Philip Oakley wrote:

> The doc-tool stack does not always respect the 'tab = 8 spaces' rule,
> particularly the git-scm doc pages https://git-scm.com/docs/git-merge-base
> and the Git generated html pages.

Hmm, I thought git-scm.com was fixed by:

  https://github.com/git/git-scm.com/commit/1e13397edccdecd0e06ff851cffaa1c44e140bf3

Not that I mind using spaces consistently here on principle. I just
didn't think it was a problem anymore (my asciidoc seems to get it
right, too).

-Peff

Re: [PATCH] doc: fix merge-base ASCII art tab spacing

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> The doc-tool stack does not always respect the 'tab = 8 spaces' rule,
> particularly the git-scm doc pages https://git-scm.com/docs/git-merge-base
> and the Git generated html pages.

Sorry, but I do not understand this change.

https://git.github.io/htmldocs/git-merge-base.html is "Git generated
HTML page" and I do not see any breakage around the drawings this
patch touches, and the fp-path series does not touch these drawings,
either.

If a broken "doc-tool stack" breaks the formatting, I'd prefer to
see that "doc-tool stack" fixed, instead of working around by
updating the source they work on.  Otherwise, the broken "doc-tool
stack" will keep producing broken output next time a source that
respects "tab is to skip to the next multiple of 8" rule is fed to
it, no?

Re: [PATCH] doc: fix merge-base ASCII art tab spacing

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Fri, Oct 21, 2016 at 12:40:09AM +0100, Philip Oakley wrote:
>
>> The doc-tool stack does not always respect the 'tab = 8 spaces' rule,
>> particularly the git-scm doc pages https://git-scm.com/docs/git-merge-base
>> and the Git generated html pages.
>
> Hmm, I thought git-scm.com was fixed by:
>
>   https://github.com/git/git-scm.com/commit/1e13397edccdecd0e06ff851cffaa1c44e140bf3
>
> Not that I mind using spaces consistently here on principle. I just
> didn't think it was a problem anymore (my asciidoc seems to get it
> right, too).

I do not terribly mind it, either, and I'd prefer to apply Philip's
patch eventually. But I'd rather want to do so _after_ known broken
sites, if there are any, are fixed by correcting their tools.

Re: [PATCH] doc: fix merge-base ASCII art tab spacing

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> Philip Oakley <philipoakley@iee.org> writes:
>
>> The doc-tool stack does not always respect the 'tab = 8 spaces' rule,
>> particularly the git-scm doc pages 
>> https://git-scm.com/docs/git-merge-base
>> and the Git generated html pages.
>
> Sorry, but I do not understand this change.
>
> https://git.github.io/htmldocs/git-merge-base.html is "Git generated
> HTML page" and I do not see any breakage around the drawings this
> patch touches, and the fp-path series does not touch these drawings,
> either.
>

I'd been looking the Git for Windows output, which has the same breakage, 
rather than yours. Apologies for failing to check there.

> If a broken "doc-tool stack" breaks the formatting, I'd prefer to
> see that "doc-tool stack" fixed, instead of working around by

The doc-tool stack is question is asciidoctor. It looks like it is an 
explicit decision that the the 8 space tab substitution is deprecated in 
these case (see http://asciidoctor.org/docs/user-manual/#migrate-deprecated 
#96.3)

It appears that acciidoctor sees the art as being a separated mono-spaced 
block, with border/background as locally appropriate. While the asciidoc 
looks to simply change to mono-spaced text.

> updating the source they work on.  Otherwise, the broken "doc-tool
> stack" will keep producing broken output next time a source that
> respects "tab is to skip to the next multiple of 8" rule is fed to
> it, no?

By avoiding tabs *within the art* we would also be tolerant of those who may 
not have a set their tab spacing to 8 when viewing the raw text.

It's particularly the criss-cross diagram that needs fixed one way or 
another (for the doc/doctor differences).

The update of the asciidoctor version for git-scm, as reported by peff isn't 
sufficient for this case.

also cc'ing dscho as this breakage shows in GfW (issue 923)

Philip

Re: [PATCH] doc: fix merge-base ASCII art tab spacing

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> It appears that acciidoctor sees the art as being a separated
> mono-spaced block, with border/background as locally
> appropriate. While the asciidoc looks to simply change to mono-spaced
> text.

FWIW, I changed my mind and your patch is now queued on 'next'.

Thanks.

Re: [PATCH] doc: fix merge-base ASCII art tab spacing

[Jeff King]

On Fri, Oct 21, 2016 at 10:26:29PM +0100, Philip Oakley wrote:

> > updating the source they work on.  Otherwise, the broken "doc-tool
> > stack" will keep producing broken output next time a source that
> > respects "tab is to skip to the next multiple of 8" rule is fed to
> > it, no?
> 
> By avoiding tabs *within the art* we would also be tolerant of those who may
> not have a set their tab spacing to 8 when viewing the raw text.
> 
> It's particularly the criss-cross diagram that needs fixed one way or
> another (for the doc/doctor differences).

I think the new asciidoctor correctly handles tabs within the art. The
earlier diagrams begin each line with a tab (to mark the pre-formatted
block), and then only some of the lines have additional tabs, and expect
those tabs to expand to 8 characters to line up with the other bits
(which is what caused a problem with earlier asciidoctor).

What is funny about that criss-cross diagram is that it actually chooses
different markers on each line to start the art: sometimes tabs and
sometimes spaces. And that seems to confuse even recent versions of
asciidoctor.

It may be that asciidoctor is wrong here, but I have to admit we are
venturing well into "what happens to work with asciidoc" territory, and
the right solution is just fixing the diagram (i.e., your patch).

-Peff

Re: [PATCH] doc: fix merge-base ASCII art tab spacing

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> "Philip Oakley" <philipoakley@iee.org> writes:
> 
>> It appears that acciidoctor sees the art as being a separated
>> mono-spaced block, with border/background as locally
>> appropriate. While the asciidoc looks to simply change to mono-spaced
>> text.
> 
> FWIW, I changed my mind and your patch is now queued on 'next'.
> 
> Thanks.
> 
Many thanks

Philip

[PATCH] doc: fix the 'revert a faulty merge' ASCII art tab spacing

[Philip Oakley]

The asciidoctor doc-tool stack does not always respect the 'tab = 8 spaces' rule
expectation, particularly for the Git-for-Windows generated html pages. This
follows on from the 'doc: fix merge-base ASCII art tab spacing' fix.

Use just spaces within the block of the ascii art.

All other *.txt ascii art containing three dashes has been checked.
Asciidoctor correctly formats the other art blocks that do contain tabs.

Signed-off-by: Philip Oakley <philipoakley@iee.org
---
The git-scm doc pages https://git-scm.com/docs/ does not convert this
how-to document to html, rather it links to the Github text pages, which
does respect the 8 space tab rule.
---
 Documentation/howto/revert-a-faulty-merge.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/howto/revert-a-faulty-merge.txt b/Documentation/howto/revert-a-faulty-merge.txt
index 462255e..19f59cc 100644
--- a/Documentation/howto/revert-a-faulty-merge.txt
+++ b/Documentation/howto/revert-a-faulty-merge.txt
@@ -30,7 +30,7 @@ The history immediately after the "revert of the merge" would look like
 this:
 
  ---o---o---o---M---x---x---W
-	       /
+               /
        ---A---B
 
 where A and B are on the side development that was not so good, M is the
@@ -47,7 +47,7 @@ After the developers of the side branch fix their mistakes, the history
 may look like this:
 
  ---o---o---o---M---x---x---W---x
-	       /
+               /
        ---A---B-------------------C---D
 
 where C and D are to fix what was broken in A and B, and you may already
@@ -81,7 +81,7 @@ In such a situation, you would want to first revert the previous revert,
 which would make the history look like this:
 
  ---o---o---o---M---x---x---W---x---Y
-	       /
+               /
        ---A---B-------------------C---D
 
 where Y is the revert of W.  Such a "revert of the revert" can be done
@@ -93,14 +93,14 @@ This history would (ignoring possible conflicts between what W and W..Y
 changed) be equivalent to not having W or Y at all in the history:
 
  ---o---o---o---M---x---x-------x----
-	       /
+               /
        ---A---B-------------------C---D
 
 and merging the side branch again will not have conflict arising from an
 earlier revert and revert of the revert.
 
  ---o---o---o---M---x---x-------x-------*
-	       /                       /
+               /                       /
        ---A---B-------------------C---D
 
 Of course the changes made in C and D still can conflict with what was
@@ -111,13 +111,13 @@ faulty A and B, and redone the changes on top of the updated mainline
 after the revert, the history would have looked like this:
 
  ---o---o---o---M---x---x---W---x---x
-	       /                 \
+               /                 \
        ---A---B                   A'--B'--C'
 
 If you reverted the revert in such a case as in the previous example:
 
  ---o---o---o---M---x---x---W---x---x---Y---*
-	       /                 \         /
+               /                 \         /
        ---A---B                   A'--B'--C'
 
 where Y is the revert of W, A' and B' are rerolled A and B, and there may
@@ -129,7 +129,7 @@ lot of overlapping changes that result in conflicts.  So do not do "revert
 of revert" blindly without thinking..
 
  ---o---o---o---M---x---x---W---x---x
-	       /                 \
+               /                 \
        ---A---B                   A'--B'--C'
 
 In the history with rebased side branch, W (and M) are behind the merge
-- 
2.9.0.windows.1.323.g0305acf

Re: [PATCH] doc: fix the 'revert a faulty merge' ASCII art tab spacing

[Johannes Schindelin]

Hi Philip,

On Mon, 24 Oct 2016, Philip Oakley wrote:

> The asciidoctor doc-tool stack does not always respect the 'tab = 8 spaces' rule
> expectation, particularly for the Git-for-Windows generated html pages. This
> follows on from the 'doc: fix merge-base ASCII art tab spacing' fix.
> 
> Use just spaces within the block of the ascii art.
> 
> All other *.txt ascii art containing three dashes has been checked.
> Asciidoctor correctly formats the other art blocks that do contain tabs.
> 
> Signed-off-by: Philip Oakley <philipoakley@iee.org
> ---
> The git-scm doc pages https://git-scm.com/docs/ does not convert this
> how-to document to html, rather it links to the Github text pages, which
> does respect the 8 space tab rule.

I confirm that this fixes the misaligned branches when building the
documentation with asciidoctor 1.5.4 in Git for Windows' SDK.

Ciao,
Dscho