Skip to contentSkip to conversation

fix some doc rendering issues since v2.30.0

PATCH In review Martin Ågren 5 participants 12 messages Feb 17, 2021 – Feb 19, 2021 Documentation

lore
Share & tools
lore
#0 lore raw

cover fix some doc rendering issues since v2.30.0

These three patches fix some rendering issues I came across in the output of

./doc-diff v2.30.0 master

The original topics are so/log-diff-merge, ps/config-env-pairs and ab/mailmap.

Martin Ågren (3):
rev-list-options.txt: fix rendering of bonus paragraph git.txt: fix monospace rendering gitmailmap.txt: fix rendering of e-mail addresses

 Documentation/git.txt              | 2 +-
 Documentation/gitmailmap.txt       | 8 ++++----
 Documentation/rev-list-options.txt | 6 +++---
 3 files changed, 8 insertions(+), 8 deletions(-)
Signature · 1 line
2.30.0.284.gd98b1dd5ea
#1 lore raw

PATCH 1/3 rev-list-options.txt: fix rendering of bonus paragraph

In git-log(1) -- but not in git-shortlog(1) or git-rev-list(1) -- we include a bonus paragraph in the description of --first-parent. But we forgot to add a lone "+" for a list continuation, and we shouldn't be indenting this second paragraph. As a result, we get a different indentation and the backticks render literally.

---
doc-diff:
--- a/.../man/man1/git-log.1
+++ b/.../man/man1/git-log.1
@@ -264,8 +264,8 @@ OPTIONS
time, and this option allows you to ignore the individual commits brought in to your history by such a merge.

- This option also changes default diff format for merge commits
- to first-parent, see --diff-merges=first-parent for details.
+ This option also changes default diff format for merge commits to
+ first-parent, see --diff-merges=first-parent for details.

--not
Reverses the meaning of the ^ prefix (or lack thereof) for all

 Documentation/rev-list-options.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/rev-list-options.txt +3 -3
index 96cc89d157..2fa1629f1e 100644
@@ -129,10 +129,10 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit).
 	adjusting to updated upstream from time to time, and
 	this option allows you to ignore the individual commits
 	brought in to your history by such a merge.
-
 ifdef::git-log[]
-	This option also changes default diff format for merge commits
-	to `first-parent`, see `--diff-merges=first-parent` for details.
++
+This option also changes default diff format for merge commits
+to `first-parent`, see `--diff-merges=first-parent` for details.
 endif::git-log[]
 
 --not::
Signature · 1 line
2.30.0.284.gd98b1dd5ea
#2 lore raw

PATCH 2/3 git.txt: fix monospace rendering

In reply to Martin Ågren

When we write <name>s with the "s" tucked on to the closing backtick, we end up rendering the backticks literally. Rephrase this sentence slightly to render this as monospace.

---
doc-diff:
--- a/.../man/man1/git.1
+++ b/.../man/man1/git.1
@@ -77,8 +77,8 @@ OPTIONS
setting the value to an empty string, instead the environment variable itself must be set to the empty string. It is an error if the <envvar> does not exist in the environment. <envvar> may not

 -           contain an equals sign to avoid ambiguity with `<name>`s which
 -           contain one.
 +           contain an equals sign to avoid ambiguity with <name> containing
 +           one.

This is useful for cases where you want to pass transitory configuration options to git, but are doing so on OS’s where other

 Documentation/git.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git.txt +1 -1
index d36e6fd482..3a9c44987f 100644
@@ -88,7 +88,7 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config
 	empty string, instead the environment variable itself must be
 	set to the empty string.  It is an error if the `<envvar>` does not exist
 	in the environment. `<envvar>` may not contain an equals sign
-	to avoid ambiguity with `<name>`s which contain one.
+	to avoid ambiguity with `<name>` containing one.
 +
 This is useful for cases where you want to pass transitory
 configuration options to git, but are doing so on OS's where
Signature · 1 line
2.30.0.284.gd98b1dd5ea
#3 lore raw

Re: [PATCH 2/3] git.txt: fix monospace rendering

Quoted 4 lines · Martin Ågren

When we write <name>s with the "s" tucked on to the closing backtick, we end up rendering the backticks literally. Rephrase this sentence slightly to render this as monospace.

That seems fine, but one question (diff trimmed way down to make it clearer I hope):

Quoted 3 lines

+ contain an equals sign to avoid ambiguity with <name> containing

+ to avoid ambiguity with <name> containing one.

One replacement drops the backquotes entirely. The other keeps them. Surely these two shouldn't be *different*...?

Chris

#4 lore raw

Re: [PATCH 2/3] git.txt: fix monospace rendering

Quoted 10 lines · Chris Torek
Quoted 4 lines · Martin Ågren

When we write <name>s with the "s" tucked on to the closing backtick, we end up rendering the backticks literally. Rephrase this sentence slightly to render this as monospace.

That seems fine, but one question (diff trimmed way down to make it clearer I hope):

Quoted 6 lines
Quoted 3 lines

+ contain an equals sign to avoid ambiguity with <name> containing

+ to avoid ambiguity with <name> containing one.

One replacement drops the backquotes entirely. The other keeps them. Surely these two shouldn't be *different*...?

I included the output of our "doc-diff" script below the double-dash line. The patch applies just as fine anyway, but I did wonder if it would trip up human readers. :-/

Quoting my original, slightly less trimmed:

Quoted 7 lines · Martin Ågren

doc-diff:
--- a/.../man/man1/git.1
+++ b/.../man/man1/git.1

 -           contain an equals sign to avoid ambiguity with `<name>`s which
 -           contain one.
 +           contain an equals sign to avoid ambiguity with <name> containing
 +           one.

So that's how the rendering is changed. From "oops, we rendered the backticks literally" to "we no longer do". (It's not clear from the doc-diff that they're rendered monospace/bold, but at least this is no longer obviously broken.)

(Note the extra indentation of all of that. This is where one might place some commentary that one don't want to burden the commit message with, but which also isn't part of the actual diff. Now that this looks very much like a diff, I can see how it's confusing.)

And that's because of this change to the actual sources:

Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 91

Quoted 6 lines
Documentation/git.txt +1 -1
index d36e6fd482..3a9c44987f 100644
-       to avoid ambiguity with `<name>`s which contain one.
+       to avoid ambiguity with `<name>` containing one.

I hope that clarifies it? It's a bit unfortunate that the misrendering is so similar to the source in the txt file. But I guess that's still better than some of those misrenderings where some cogwheel slips and everything spins out of control through the rest of the paragraph.

Martin

#5 lore raw

Re: [PATCH 2/3] git.txt: fix monospace rendering

In reply to Martin Ågren
Quoted 13 lines · Martin Ågren

When we write <name>s with the "s" tucked on to the closing backtick, we end up rendering the backticks literally. Rephrase this sentence slightly to render this as monospace.

---
doc-diff:
--- a/.../man/man1/git.1
+++ b/.../man/man1/git.1
@@ -77,8 +77,8 @@ OPTIONS
setting the value to an empty string, instead the environment variable itself must be set to the empty string. It is an error if the <envvar> does not exist in the environment. <envvar> may not

Quoted 4 lines
 -           contain an equals sign to avoid ambiguity with `<name>`s which
 -           contain one.
 +           contain an equals sign to avoid ambiguity with <name> containing
 +           one.

Over here you're also dropping the backticks, while...

Quoted 10 lines

This is useful for cases where you want to pass transitory configuration options to git, but are doing so on OS’s where other

 Documentation/git.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git.txt +0 -0
index d36e6fd482..3a9c44987f 100644

Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 91

Quoted 5 lines
Documentation/git.txt +1 -1
@@ -88,7 +88,7 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config
 	empty string, instead the environment variable itself must be
 	set to the empty string.  It is an error if the `<envvar>` does not exist
 	in the environment. `<envvar>` may not contain an equals sign
-	to avoid ambiguity with `<name>`s which contain one.
+	to avoid ambiguity with `<name>` containing one.

... here you don't. Is this on purpose?

Patrick

Quoted 5 lines
Documentation/git.txt +0 -0
 This is useful for cases where you want to pass transitory
 configuration options to git, but are doing so on OS's where
Signature · 1 line
2.30.0.284.gd98b1dd5ea
#6 lore raw

Re: [PATCH 2/3] git.txt: fix monospace rendering

Quoted 27 lines · Patrick Steinhardt
Quoted 13 lines · Martin Ågren

When we write <name>s with the "s" tucked on to the closing backtick, we end up rendering the backticks literally. Rephrase this sentence slightly to render this as monospace.

---
doc-diff:
--- a/.../man/man1/git.1
+++ b/.../man/man1/git.1
@@ -77,8 +77,8 @@ OPTIONS
setting the value to an empty string, instead the environment variable itself must be set to the empty string. It is an error if the <envvar> does not exist in the environment. <envvar> may not

Quoted 4 lines
 -           contain an equals sign to avoid ambiguity with `<name>`s which
 -           contain one.
 +           contain an equals sign to avoid ambiguity with <name> containing
 +           one.

Over here you're also dropping the backticks, while...

Quoted 5 lines

This is useful for cases where you want to pass transitory configuration options to git, but are doing so on OS’s where other

 Documentation/git.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Quoted 12 lines

Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 91

Quoted 10 lines
Documentation/git.txt +1 -1
index d36e6fd482..3a9c44987f 100644
@@ -88,7 +88,7 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config
      empty string, instead the environment variable itself must be
      set to the empty string.  It is an error if the `<envvar>` does not exist
      in the environment. `<envvar>` may not contain an equals sign
-     to avoid ambiguity with `<name>`s which contain one.
+     to avoid ambiguity with `<name>` containing one.

... here you don't. Is this on purpose?

Your mail crossed with my response to Chris, who had the same question. I'd post a link to lore.kernel.org, but it seems my response hasn't reached it yet. The short answer is the first diff is an indented diff of the rendered manpages (our "doc-diff" script), whereas the second diff is the actual, to-be-applied diff.

I thought it would be helpful to include the doc-diff, but it seems it just created more confusion than it avoided. I'll try to avoid that. :-)

Thanks
Martin

#7 lore raw

Re: [PATCH 2/3] git.txt: fix monospace rendering

In reply to Martin Ågren
Quoted 28 lines · Martin Ågren

When we write <name>s with the "s" tucked on to the closing backtick, we end up rendering the backticks literally. Rephrase this sentence slightly to render this as monospace.

---
doc-diff:
--- a/.../man/man1/git.1
+++ b/.../man/man1/git.1
@@ -77,8 +77,8 @@ OPTIONS
setting the value to an empty string, instead the environment variable itself must be set to the empty string. It is an error if the <envvar> does not exist in the environment. <envvar> may not

 -           contain an equals sign to avoid ambiguity with `<name>`s which
 -           contain one.
 +           contain an equals sign to avoid ambiguity with <name> containing
 +           one.

This is useful for cases where you want to pass transitory configuration options to git, but are doing so on OS’s where other

 Documentation/git.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git.txt +0 -0
index d36e6fd482..3a9c44987f 100644

Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 94

Quoted 8 lines
Documentation/git.txt +1 -1
@@ -88,7 +88,7 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config
 	empty string, instead the environment variable itself must be
 	set to the empty string.  It is an error if the `<envvar>` does not exist
 	in the environment. `<envvar>` may not contain an equals sign
-	to avoid ambiguity with `<name>`s which contain one.
+	to avoid ambiguity with `<name>` containing one.
 +
 This is useful for cases where you want to pass transitory
 configuration options to git, but are doing so on OS's where

The "two" diffs may indeed be misleading.

The patch only changes one source and the "supporting material" is not something that we need to use on the source file---it is only showing the change in the output.

I did appreciate the inclusion of doc-diff myself, but it seems that it confused Chris and Patrick. I doubt that it is an improvement to omit doc-diff. We may want to find a way to make it easier for the readers to tell which part is the patch to be applied and which part is not in similar changes we discuss on the list in the future, and apparently, a one column indentation alone was not quite sufficient in this case. Replacing "doc-diff:" label and patch header lines up to the hunk header with a prose to explain what the intended diff is may have helped, e.g.

...
slightly to render this as monospace.

---

The rendered output changes like the following excerpt from doc-diff output.

             ....  <envvar> may not
 -           contain an equals sign to avoid ambiguity with `<name>`s which
 -           contain one.
 +           contain an equals sign to avoid ambiguity with <name> containing
 +           one.

You can see that backquotes are gone, even though you unfortunately cannot see how <name> is typeset (it is in monospace--trust me ;-).

 Documentation/git.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git.txt +0 -0
index ....
@@ ...
#8 lore raw

Re: [PATCH 2/3] git.txt: fix monospace rendering

Quoted 7 lines · Junio C Hamano

The "two" diffs may indeed be misleading.

The patch only changes one source and the "supporting material" is not something that we need to use on the source file---it is only showing the change in the output.

Quoted 9 lines

I did appreciate the inclusion of doc-diff myself, but it seems that it confused Chris and Patrick. I doubt that it is an improvement to omit doc-diff. We may want to find a way to make it easier for the readers to tell which part is the patch to be applied and which part is not in similar changes we discuss on the list in the future, and apparently, a one column indentation alone was not quite sufficient in this case. Replacing "doc-diff:" label and patch header lines up to the hunk header with a prose to explain what the intended diff is may have helped, e.g.

Glad to know you found the included doc-diff useful. Thanks for the suggestion on how to present it. Next time I'll try wrapping the doc-diff in English prose to make it stand out more. The "doc-diff:" I used now was definitely a bit too subtle.

Thanks
Martin

#9 lore raw

PATCH 3/3 gitmailmap.txt: fix rendering of e-mail addresses

In reply to Martin Ågren

Both AsciiDoc and Asciidoctor are eager to pick up the e-mail addresses in this document and turn them into references at the bottom of the manpage / clickable links. We don't really need that for these dummy addresses. Spell "@" as "&#64;" to make them not do this. In the open block, we can instead avoid this by indenting the contents, similar to the earlier blocks.

Fix a backtick which should have been a single quote mark. With all the quoting that is going on around here, this mistake trips up the parsing and rendering quite a bit.

Before this commit, we have the same failure mode with AsciiDoc 8.6.10 and Asciidoctor 1.5.5, and this change makes both of them happy.

---
doc-diff:
--- a/97c686dd7ba1bbd1c0be6f7f61a3a033adf8adb6-asciidoctor-cut-footer/home/martin/share/man/man5/gitmailmap.5 +++ b/ee0422ac399daf43a7adcc2b662b50312da04631-asciidoctor-cut-footer/home/martin/share/man/man5/gitmailmap.5 @@ -40,9 +40,9 @@ SYNTAX
matching both the specified commit name and email address.

Both E-Mails and names are matched case-insensitively. For example this
- would also match the Commit Name <[email protected][1]> above:
+ would also match the Commit Name <[email protected]> above:

- Proper Name <[email protected][2]> CoMmIt NaMe <[email protected][3]>
+ Proper Name <[email protected]> CoMmIt NaMe <[email protected]>

EXAMPLES
Your history contains commits by two authors, Jane and Joe, whose names
@@ -62,11 +62,10 @@ EXAMPLES
Jane Doe <[email protected]>
Jane Doe <jane@desktop.(none)>

- Note that there’s no need to map the name for jane@laptop.(none) to
+ Note that there’s no need to map the name for <jane@laptop.(none)> to
only correct the names. However, leaving the obviously broken

 -       <jane@laptop.(none)>' and '<jane@desktop.(none)>' E-Mails as-is is
 -       usually not what you want. A `.mailmap file which also corrects those
 -       is:
 +       <jane@laptop.(none)> and <jane@desktop.(none)> E-Mails as-is is usually
 +       not what you want. A .mailmap file which also corrects those is:

Joe R. Developer <[email protected]> Jane Doe <[email protected]> <jane@laptop.(none)>
@@ -93,13 +92,3 @@ SEE ALSO

GIT
Part of the git(1) suite
-
-NOTES
- 1. [email protected]
- mailto:[email protected]
-
- 2. [email protected]
- mailto:[email protected]
-
- 3. [email protected]
- mailto:[email protected]

 Documentation/gitmailmap.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/gitmailmap.txt +4 -4
index 052209b33b..3fb39f801f 100644
@@ -50,9 +50,9 @@ which allows mailmap to replace both the name and the email of a
 commit matching both the specified commit name and email address.
 
 Both E-Mails and names are matched case-insensitively. For example
-this would also match the 'Commit Name <[email protected]>' above:
+this would also match the 'Commit Name <commit&#64;email.xx>' above:
 --
-Proper Name <[email protected]> CoMmIt NaMe <[email protected]>
+	Proper Name <[email protected]> CoMmIt NaMe <[email protected]>
 --
 
 EXAMPLES
@@ -79,9 +79,9 @@ Jane Doe <[email protected]>
 Jane Doe <jane@desktop.(none)>
 ------------
 
-Note that there's no need to map the name for 'jane@laptop.(none)' to
+Note that there's no need to map the name for '<jane&#64;laptop.(none)>' to
 only correct the names. However, leaving the obviously broken
-`<jane@laptop.(none)>' and '<jane@desktop.(none)>' E-Mails as-is is
+'<jane&#64;laptop.(none)>' and '<jane&#64;desktop.(none)>' E-Mails as-is is
 usually not what you want. A `.mailmap` file which also corrects those
 is:
 
Signature · 1 line
2.30.0.284.gd98b1dd5ea
#10 lore raw

Re: [PATCH 3/3] gitmailmap.txt: fix rendering of e-mail addresses

Quoted 7 lines · Martin Ågren

Both AsciiDoc and Asciidoctor are eager to pick up the e-mail addresses in this document and turn them into references at the bottom of the manpage / clickable links. We don't really need that for these dummy addresses. Spell "@" as "&#64;" to make them not do this. In the open block, we can instead avoid this by indenting the contents, similar to the earlier blocks.

Quoted 6 lines

Fix a backtick which should have been a single quote mark. With all the quoting that is going on around here, this mistake trips up the parsing and rendering quite a bit.

Before this commit, we have the same failure mode with AsciiDoc 8.6.10 and Asciidoctor 1.5.5, and this change makes both of them happy.

THanks a lot for the fix & cleaning up my mess. This LGTM.

#11 lore raw
In reply to Martin Ågren
Quoted 13 lines · Martin Ågren

These three patches fix some rendering issues I came across in the output of

./doc-diff v2.30.0 master

The original topics are so/log-diff-merge, ps/config-env-pairs and ab/mailmap.

Martin Ågren (3):
rev-list-options.txt: fix rendering of bonus paragraph git.txt: fix monospace rendering gitmailmap.txt: fix rendering of e-mail addresses

Quoted 4 lines
 Documentation/git.txt              | 2 +-
 Documentation/gitmailmap.txt       | 8 ++++----
 Documentation/rev-list-options.txt | 6 +++---
 3 files changed, 8 insertions(+), 8 deletions(-)

All of them look "obviously correct". Thanks.