diff mbox series

[1/2] git-reset.txt: render tables correctly under Asciidoctor

Message ID 1596a9ff9fa6849f53590de1b15eb18ee6b41e4d.1543429054.git.martin.agren@gmail.com (mailing list archive)
State New, archived
Headers show
Series Re: Broken alignment in git-reset docs | expand

Commit Message

Martin Ågren Nov. 28, 2018, 7:02 p.m. UTC 
Asciidoctor removes the indentation of each line in these tables, so the
last lines of each table have a completely broken alignment.

Similar to 379805051d ("Documentation: render revisions correctly under
Asciidoctor", 2018-05-06), use an explicit literal block to indicate
that we want to keep the leading whitespace in the tables.

Because this gives us some extra indentation, we can remove the one that
we have been carrying explicitly. That is, drop the first six spaces of
indentation on each line. With Asciidoc (8.6.10), this results in
identical rendering before and after this commit, both for git-reset.1
and git-reset.html.

Reported-by: Paweł Samoraj <samoraj.pawel@gmail.com>
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/git-reset.txt | 140 ++++++++++++++++++++----------------
 1 file changed, 78 insertions(+), 62 deletions(-)

Comments

Ævar Arnfjörð Bjarmason Nov. 28, 2018, 7:44 p.m. UTC | #1 
On Wed, Nov 28 2018, Martin Ågren wrote:

> Asciidoctor removes the indentation of each line in these tables, so the
> last lines of each table have a completely broken alignment.
>
> Similar to 379805051d ("Documentation: render revisions correctly under
> Asciidoctor", 2018-05-06), use an explicit literal block to indicate
> that we want to keep the leading whitespace in the tables.
>
> Because this gives us some extra indentation, we can remove the one that
> we have been carrying explicitly. That is, drop the first six spaces of
> indentation on each line. With Asciidoc (8.6.10), this results in
> identical rendering before and after this commit, both for git-reset.1
> and git-reset.html.
>
> Reported-by: Paweł Samoraj <samoraj.pawel@gmail.com>
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>

Earlier I was trying to get the Documentation/doc-diff script to diff
the asciidoc and asciidoctor docs without much success (hadn't used it
before, just hacking the Makefile to turn on asciidoctor yielded syntax
errors or something).

Is something like that a thing we could make into a regression test?
Martin Ågren Nov. 28, 2018, 8:37 p.m. UTC | #2 
On Wed, 28 Nov 2018 at 20:45, Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
> On Wed, Nov 28 2018, Martin Ågren wrote:
>
> > Asciidoctor removes the indentation of each line in these tables, so the
> > last lines of each table have a completely broken alignment.
>
> Earlier I was trying to get the Documentation/doc-diff script to diff
> the asciidoc and asciidoctor docs without much success (hadn't used it
> before, just hacking the Makefile to turn on asciidoctor yielded syntax
> errors or something).
>
> Is something like that a thing we could make into a regression test?

Interesting idea. I just tried a gross hack:

 * Use `make --always-make ... install-man` in doc-diff.
 * ./doc-diff -f HEAD HEAD # note -f
 * Add empty commit and tweak config.mak
 * ./doc-diff HEAD^ HEAD # note no -f

There are lots of irrelevant differences in the headers and footers,
which is a bit unfortunate.

Also, lots of annoying differences originating in Asciidoctor's
inclination to render a space after linkgit:foo . There are those
differences themselves, obviously, but also follow-on differences such
as entire paragraphs that wrap differently.

I could spot a few things that should be fixable on our side, but on a
quick skimming, I didn't spot too many "huge" differences, which feels
good. The one which this patch fixes, obviously, and there's some work
to do in git-status.txt and git-column.txt (at least).

Tacking on `--stat` to the call to `git diff --no-index` singles out
git-config.txt, but it seems like lots of small or maybe even irrelevant
differences, plus lots of spaces around linkgit: , as already mentioned.

Martin
diff mbox series

Patch

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 2dac95c71a..7c925e3a29 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -365,53 +365,65 @@  index in state B.  It resets (i.e. moves) the HEAD (i.e. the tip of
 the current branch, if you are on one) to "target" (which has the file
 in state D).
 
-      working index HEAD target         working index HEAD
-      ----------------------------------------------------
-       A       B     C    D     --soft   A       B     D
-				--mixed  A       D     D
-				--hard   D       D     D
-				--merge (disallowed)
-				--keep  (disallowed)
-
-      working index HEAD target         working index HEAD
-      ----------------------------------------------------
-       A       B     C    C     --soft   A       B     C
-				--mixed  A       C     C
-				--hard   C       C     C
-				--merge (disallowed)
-				--keep   A       C     C
-
-      working index HEAD target         working index HEAD
-      ----------------------------------------------------
-       B       B     C    D     --soft   B       B     D
-				--mixed  B       D     D
-				--hard   D       D     D
-				--merge  D       D     D
-				--keep  (disallowed)
-
-      working index HEAD target         working index HEAD
-      ----------------------------------------------------
-       B       B     C    C     --soft   B       B     C
-				--mixed  B       C     C
-				--hard   C       C     C
-				--merge  C       C     C
-				--keep   B       C     C
-
-      working index HEAD target         working index HEAD
-      ----------------------------------------------------
-       B       C     C    D     --soft   B       C     D
-				--mixed  B       D     D
-				--hard   D       D     D
-				--merge (disallowed)
-				--keep  (disallowed)
-
-      working index HEAD target         working index HEAD
-      ----------------------------------------------------
-       B       C     C    C     --soft   B       C     C
-				--mixed  B       C     C
-				--hard   C       C     C
-				--merge  B       C     C
-				--keep   B       C     C
+....
+working index HEAD target         working index HEAD
+----------------------------------------------------
+ A       B     C    D     --soft   A       B     D
+			  --mixed  A       D     D
+			  --hard   D       D     D
+			  --merge (disallowed)
+			  --keep  (disallowed)
+....
+
+....
+working index HEAD target         working index HEAD
+----------------------------------------------------
+ A       B     C    C     --soft   A       B     C
+			  --mixed  A       C     C
+			  --hard   C       C     C
+			  --merge (disallowed)
+			  --keep   A       C     C
+....
+
+....
+working index HEAD target         working index HEAD
+----------------------------------------------------
+ B       B     C    D     --soft   B       B     D
+			  --mixed  B       D     D
+			  --hard   D       D     D
+			  --merge  D       D     D
+			  --keep  (disallowed)
+....
+
+....
+working index HEAD target         working index HEAD
+----------------------------------------------------
+ B       B     C    C     --soft   B       B     C
+			  --mixed  B       C     C
+			  --hard   C       C     C
+			  --merge  C       C     C
+			  --keep   B       C     C
+....
+
+....
+working index HEAD target         working index HEAD
+----------------------------------------------------
+ B       C     C    D     --soft   B       C     D
+			  --mixed  B       D     D
+			  --hard   D       D     D
+			  --merge (disallowed)
+			  --keep  (disallowed)
+....
+
+....
+working index HEAD target         working index HEAD
+----------------------------------------------------
+ B       C     C    C     --soft   B       C     C
+			  --mixed  B       C     C
+			  --hard   C       C     C
+			  --merge  B       C     C
+			  --keep   B       C     C
+....
 
 "reset --merge" is meant to be used when resetting out of a conflicted
 merge. Any mergy operation guarantees that the working tree file that is
@@ -434,21 +446,25 @@  entries.
 The following tables show what happens when there are unmerged
 entries:
 
-      working index HEAD target         working index HEAD
-      ----------------------------------------------------
-       X       U     A    B     --soft  (disallowed)
-				--mixed  X       B     B
-				--hard   B       B     B
-				--merge  B       B     B
-				--keep  (disallowed)
-
-      working index HEAD target         working index HEAD
-      ----------------------------------------------------
-       X       U     A    A     --soft  (disallowed)
-				--mixed  X       A     A
-				--hard   A       A     A
-				--merge  A       A     A
-				--keep  (disallowed)
+....
+working index HEAD target         working index HEAD
+----------------------------------------------------
+ X       U     A    B     --soft  (disallowed)
+			  --mixed  X       B     B
+			  --hard   B       B     B
+			  --merge  B       B     B
+			  --keep  (disallowed)
+....
+
+....
+working index HEAD target         working index HEAD
+----------------------------------------------------
+ X       U     A    A     --soft  (disallowed)
+			  --mixed  X       A     A
+			  --hard   A       A     A
+			  --merge  A       A     A
+			  --keep  (disallowed)
+....
 
 X means any state and U means an unmerged index.