* [PATCH] doc: fix merge-base ASCII art tab spacing
@ 2016-10-20 23:40 Philip Oakley
2016-10-21 0:22 ` Jeff King
2016-10-21 0:27 ` Junio C Hamano
0 siblings, 2 replies; 10+ messages in thread
From: Philip Oakley @ 2016-10-20 23:40 UTC (permalink / raw)
To: GitList; +Cc: Junio C Hamano, 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
^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH] doc: fix merge-base ASCII art tab spacing
2016-10-20 23:40 [PATCH] doc: fix merge-base ASCII art tab spacing Philip Oakley
@ 2016-10-21 0:22 ` Jeff King
2016-10-21 0:48 ` Junio C Hamano
2016-10-21 0:27 ` Junio C Hamano
1 sibling, 1 reply; 10+ messages in thread
From: Jeff King @ 2016-10-21 0:22 UTC (permalink / raw)
To: Philip Oakley; +Cc: GitList, Junio C Hamano
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
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] doc: fix merge-base ASCII art tab spacing
2016-10-21 0:22 ` Jeff King
@ 2016-10-21 0:48 ` Junio C Hamano
0 siblings, 0 replies; 10+ messages in thread
From: Junio C Hamano @ 2016-10-21 0:48 UTC (permalink / raw)
To: Jeff King; +Cc: Philip Oakley, GitList
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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] doc: fix merge-base ASCII art tab spacing
2016-10-20 23:40 [PATCH] doc: fix merge-base ASCII art tab spacing Philip Oakley
2016-10-21 0:22 ` Jeff King
@ 2016-10-21 0:27 ` Junio C Hamano
2016-10-21 21:26 ` Philip Oakley
1 sibling, 1 reply; 10+ messages in thread
From: Junio C Hamano @ 2016-10-21 0:27 UTC (permalink / raw)
To: Philip Oakley; +Cc: GitList
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?
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] doc: fix merge-base ASCII art tab spacing
2016-10-21 0:27 ` Junio C Hamano
@ 2016-10-21 21:26 ` Philip Oakley
2016-10-21 22:54 ` Junio C Hamano
2016-10-22 1:09 ` [PATCH] doc: fix merge-base " Jeff King
0 siblings, 2 replies; 10+ messages in thread
From: Philip Oakley @ 2016-10-21 21:26 UTC (permalink / raw)
To: Junio C Hamano; +Cc: GitList, Jeff King, Johannes Schindelin
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
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] doc: fix merge-base ASCII art tab spacing
2016-10-21 21:26 ` Philip Oakley
@ 2016-10-21 22:54 ` Junio C Hamano
2016-10-22 5:45 ` Philip Oakley
2016-10-24 21:54 ` [PATCH] doc: fix the 'revert a faulty merge' " Philip Oakley
2016-10-22 1:09 ` [PATCH] doc: fix merge-base " Jeff King
1 sibling, 2 replies; 10+ messages in thread
From: Junio C Hamano @ 2016-10-21 22:54 UTC (permalink / raw)
To: Philip Oakley; +Cc: GitList, Jeff King, Johannes Schindelin
"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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] doc: fix merge-base ASCII art tab spacing
2016-10-21 22:54 ` Junio C Hamano
@ 2016-10-22 5:45 ` Philip Oakley
2016-10-24 21:54 ` [PATCH] doc: fix the 'revert a faulty merge' " Philip Oakley
1 sibling, 0 replies; 10+ messages in thread
From: Philip Oakley @ 2016-10-22 5:45 UTC (permalink / raw)
To: Junio C Hamano; +Cc: GitList, Jeff King, Johannes Schindelin
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
^ permalink raw reply [flat|nested] 10+ messages in thread
* [PATCH] doc: fix the 'revert a faulty merge' ASCII art tab spacing
2016-10-21 22:54 ` Junio C Hamano
2016-10-22 5:45 ` Philip Oakley
@ 2016-10-24 21:54 ` Philip Oakley
2016-10-25 11:39 ` Johannes Schindelin
1 sibling, 1 reply; 10+ messages in thread
From: Philip Oakley @ 2016-10-24 21:54 UTC (permalink / raw)
To: gitster; +Cc: Johannes.Schindelin, git, peff, philipoakley
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
^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH] doc: fix the 'revert a faulty merge' ASCII art tab spacing
2016-10-24 21:54 ` [PATCH] doc: fix the 'revert a faulty merge' " Philip Oakley
@ 2016-10-25 11:39 ` Johannes Schindelin
0 siblings, 0 replies; 10+ messages in thread
From: Johannes Schindelin @ 2016-10-25 11:39 UTC (permalink / raw)
To: Philip Oakley; +Cc: gitster, git, peff
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
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] doc: fix merge-base ASCII art tab spacing
2016-10-21 21:26 ` Philip Oakley
2016-10-21 22:54 ` Junio C Hamano
@ 2016-10-22 1:09 ` Jeff King
1 sibling, 0 replies; 10+ messages in thread
From: Jeff King @ 2016-10-22 1:09 UTC (permalink / raw)
To: Philip Oakley; +Cc: Junio C Hamano, GitList, Johannes Schindelin
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
^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2016-10-25 11:40 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-10-20 23:40 [PATCH] doc: fix merge-base ASCII art tab spacing Philip Oakley
2016-10-21 0:22 ` Jeff King
2016-10-21 0:48 ` Junio C Hamano
2016-10-21 0:27 ` Junio C Hamano
2016-10-21 21:26 ` Philip Oakley
2016-10-21 22:54 ` Junio C Hamano
2016-10-22 5:45 ` Philip Oakley
2016-10-24 21:54 ` [PATCH] doc: fix the 'revert a faulty merge' " Philip Oakley
2016-10-25 11:39 ` Johannes Schindelin
2016-10-22 1:09 ` [PATCH] doc: fix merge-base " Jeff King
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).