git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / Atom feed
* [PATCH 0/3] fix some doc rendering issues since v2.30.0
@ 2021-02-17 19:56 Martin Ågren
  2021-02-17 19:56 ` [PATCH 1/3] rev-list-options.txt: fix rendering of bonus paragraph Martin Ågren
                   ` (3 more replies)
  0 siblings, 4 replies; 12+ messages in thread
From: Martin Ågren @ 2021-02-17 19:56 UTC (permalink / raw)
  To: git
  Cc: Sergey Organov, Patrick Steinhardt,
	Ævar Arnfjörð Bjarmason

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(-)

-- 
2.30.0.284.gd98b1dd5ea


^ permalink raw reply	[flat|nested] 12+ messages in thread

* [PATCH 1/3] rev-list-options.txt: fix rendering of bonus paragraph
  2021-02-17 19:56 [PATCH 0/3] fix some doc rendering issues since v2.30.0 Martin Ågren
@ 2021-02-17 19:56 ` Martin Ågren
  2021-02-17 19:56 ` [PATCH 2/3] git.txt: fix monospace rendering Martin Ågren
                   ` (2 subsequent siblings)
  3 siblings, 0 replies; 12+ messages in thread
From: Martin Ågren @ 2021-02-17 19:56 UTC (permalink / raw)
  To: git
  Cc: Sergey Organov, Patrick Steinhardt,
	Ævar Arnfjörð Bjarmason

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.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 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(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 96cc89d157..2fa1629f1e 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -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::
-- 
2.30.0.284.gd98b1dd5ea


^ permalink raw reply	[flat|nested] 12+ messages in thread

* [PATCH 2/3] git.txt: fix monospace rendering
  2021-02-17 19:56 [PATCH 0/3] fix some doc rendering issues since v2.30.0 Martin Ågren
  2021-02-17 19:56 ` [PATCH 1/3] rev-list-options.txt: fix rendering of bonus paragraph Martin Ågren
@ 2021-02-17 19:56 ` Martin Ågren
  2021-02-17 22:47   ` Chris Torek
                     ` (2 more replies)
  2021-02-17 19:56 ` [PATCH 3/3] gitmailmap.txt: fix rendering of e-mail addresses Martin Ågren
  2021-02-17 21:22 ` [PATCH 0/3] fix some doc rendering issues since v2.30.0 Junio C Hamano
  3 siblings, 3 replies; 12+ messages in thread
From: Martin Ågren @ 2021-02-17 19:56 UTC (permalink / raw)
  To: git
  Cc: Sergey Organov, Patrick Steinhardt,
	Ævar Arnfjörð Bjarmason

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.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 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(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index d36e6fd482..3a9c44987f 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -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
-- 
2.30.0.284.gd98b1dd5ea


^ permalink raw reply	[flat|nested] 12+ messages in thread

* [PATCH 3/3] gitmailmap.txt: fix rendering of e-mail addresses
  2021-02-17 19:56 [PATCH 0/3] fix some doc rendering issues since v2.30.0 Martin Ågren
  2021-02-17 19:56 ` [PATCH 1/3] rev-list-options.txt: fix rendering of bonus paragraph Martin Ågren
  2021-02-17 19:56 ` [PATCH 2/3] git.txt: fix monospace rendering Martin Ågren
@ 2021-02-17 19:56 ` Martin Ågren
  2021-02-18 10:48   ` Ævar Arnfjörð Bjarmason
  2021-02-17 21:22 ` [PATCH 0/3] fix some doc rendering issues since v2.30.0 Junio C Hamano
  3 siblings, 1 reply; 12+ messages in thread
From: Martin Ågren @ 2021-02-17 19:56 UTC (permalink / raw)
  To: git
  Cc: Sergey Organov, Patrick Steinhardt,
	Ævar Arnfjörð Bjarmason

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.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 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 <commit@email.xx[1]> above:
 +       would also match the Commit Name <commit@email.xx> above:
 
 -       Proper Name <proper@email.xx[2]> CoMmIt NaMe <CoMmIt@EmAiL.xX[3]>
 +           Proper Name <proper@email.xx> CoMmIt NaMe <CoMmIt@EmAiL.xX>
 
  EXAMPLES
         Your history contains commits by two authors, Jane and Joe, whose names
 @@ -62,11 +62,10 @@ EXAMPLES
             Jane Doe <jane@example.com>
             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 <joe@example.com>
             Jane Doe <jane@example.com> <jane@laptop.(none)>
 @@ -93,13 +92,3 @@ SEE ALSO
 
  GIT
         Part of the git(1) suite
 -
 -NOTES
 -        1. commit@email.xx
 -           mailto:commit@email.xx
 -
 -        2. proper@email.xx
 -           mailto:proper@email.xx
 -
 -        3. CoMmIt@EmAiL.xX
 -           mailto:CoMmIt@EmAiL.xX
 Documentation/gitmailmap.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/gitmailmap.txt b/Documentation/gitmailmap.txt
index 052209b33b..3fb39f801f 100644
--- a/Documentation/gitmailmap.txt
+++ b/Documentation/gitmailmap.txt
@@ -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 <commit@email.xx>' above:
+this would also match the 'Commit Name <commit&#64;email.xx>' above:
 --
-Proper Name <proper@email.xx> CoMmIt NaMe <CoMmIt@EmAiL.xX>
+	Proper Name <proper@email.xx> CoMmIt NaMe <CoMmIt@EmAiL.xX>
 --
 
 EXAMPLES
@@ -79,9 +79,9 @@ Jane Doe <jane@example.com>
 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:
 
-- 
2.30.0.284.gd98b1dd5ea


^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH 0/3] fix some doc rendering issues since v2.30.0
  2021-02-17 19:56 [PATCH 0/3] fix some doc rendering issues since v2.30.0 Martin Ågren
                   ` (2 preceding siblings ...)
  2021-02-17 19:56 ` [PATCH 3/3] gitmailmap.txt: fix rendering of e-mail addresses Martin Ågren
@ 2021-02-17 21:22 ` Junio C Hamano
  3 siblings, 0 replies; 12+ messages in thread
From: Junio C Hamano @ 2021-02-17 21:22 UTC (permalink / raw)
  To: Martin Ågren
  Cc: git, Sergey Organov, Patrick Steinhardt,
	Ævar Arnfjörð Bjarmason

Martin Ågren <martin.agren@gmail.com> writes:

> 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(-)

All of them look "obviously correct".  Thanks.

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH 2/3] git.txt: fix monospace rendering
  2021-02-17 19:56 ` [PATCH 2/3] git.txt: fix monospace rendering Martin Ågren
@ 2021-02-17 22:47   ` Chris Torek
  2021-02-18  6:28     ` Martin Ågren
  2021-02-18  6:27   ` Patrick Steinhardt
  2021-02-18 18:51   ` Junio C Hamano
  2 siblings, 1 reply; 12+ messages in thread
From: Chris Torek @ 2021-02-17 22:47 UTC (permalink / raw)
  To: Martin Ågren
  Cc: Git List, Sergey Organov, Patrick Steinhardt,
	Ævar Arnfjörð Bjarmason

On Wed, Feb 17, 2021 at 1:21 PM Martin Ågren <martin.agren@gmail.com> wrote:
>
> 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):

>  +           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

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH 2/3] git.txt: fix monospace rendering
  2021-02-17 19:56 ` [PATCH 2/3] git.txt: fix monospace rendering Martin Ågren
  2021-02-17 22:47   ` Chris Torek
@ 2021-02-18  6:27   ` Patrick Steinhardt
  2021-02-18  6:32     ` Martin Ågren
  2021-02-18 18:51   ` Junio C Hamano
  2 siblings, 1 reply; 12+ messages in thread
From: Patrick Steinhardt @ 2021-02-18  6:27 UTC (permalink / raw)
  To: Martin Ågren
  Cc: git, Sergey Organov, Ævar Arnfjörð Bjarmason

[-- Attachment #1: Type: text/plain, Size: 1979 bytes --]

On Wed, Feb 17, 2021 at 08:56:05PM +0100, Martin Ågren wrote:
> 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.
> 
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
>  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.

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

>              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(-)
> 
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index d36e6fd482..3a9c44987f 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -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

>  This is useful for cases where you want to pass transitory
>  configuration options to git, but are doing so on OS's where
> -- 
> 2.30.0.284.gd98b1dd5ea
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH 2/3] git.txt: fix monospace rendering
  2021-02-17 22:47   ` Chris Torek
@ 2021-02-18  6:28     ` Martin Ågren
  0 siblings, 0 replies; 12+ messages in thread
From: Martin Ågren @ 2021-02-18  6:28 UTC (permalink / raw)
  To: Chris Torek
  Cc: Git List, Sergey Organov, Patrick Steinhardt,
	Ævar Arnfjörð Bjarmason

On Wed, 17 Feb 2021 at 23:47, Chris Torek <chris.torek@gmail.com> wrote:
>
> On Wed, Feb 17, 2021 at 1:21 PM Martin Ågren <martin.agren@gmail.com> wrote:
> >
> > 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):
>
> >  +           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:

On Wed, 17 Feb 2021 at 20:56, Martin Ågren <martin.agren@gmail.com> wrote:
>  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:

> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index d36e6fd482..3a9c44987f 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> -       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

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH 2/3] git.txt: fix monospace rendering
  2021-02-18  6:27   ` Patrick Steinhardt
@ 2021-02-18  6:32     ` Martin Ågren
  0 siblings, 0 replies; 12+ messages in thread
From: Martin Ågren @ 2021-02-18  6:32 UTC (permalink / raw)
  To: Patrick Steinhardt
  Cc: Git Mailing List, Sergey Organov, Ævar Arnfjörð Bjarmason

On Thu, 18 Feb 2021 at 07:27, Patrick Steinhardt <ps@pks.im> wrote:
>
> On Wed, Feb 17, 2021 at 08:56:05PM +0100, Martin Ågren wrote:
> > 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.
> >
> > Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> > ---
> >  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.
>
> Over here you're also dropping the backticks, while...
>
> >              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(-)
> >
> > diff --git a/Documentation/git.txt b/Documentation/git.txt
> > index d36e6fd482..3a9c44987f 100644
> > --- a/Documentation/git.txt
> > +++ b/Documentation/git.txt
> > @@ -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

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH 3/3] gitmailmap.txt: fix rendering of e-mail addresses
  2021-02-17 19:56 ` [PATCH 3/3] gitmailmap.txt: fix rendering of e-mail addresses Martin Ågren
@ 2021-02-18 10:48   ` Ævar Arnfjörð Bjarmason
  0 siblings, 0 replies; 12+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-02-18 10:48 UTC (permalink / raw)
  To: Martin Ågren; +Cc: git, Sergey Organov, Patrick Steinhardt


On Wed, Feb 17 2021, Martin Ågren wrote:

> 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.

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

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH 2/3] git.txt: fix monospace rendering
  2021-02-17 19:56 ` [PATCH 2/3] git.txt: fix monospace rendering Martin Ågren
  2021-02-17 22:47   ` Chris Torek
  2021-02-18  6:27   ` Patrick Steinhardt
@ 2021-02-18 18:51   ` Junio C Hamano
  2021-02-19  6:33     ` Martin Ågren
  2 siblings, 1 reply; 12+ messages in thread
From: Junio C Hamano @ 2021-02-18 18:51 UTC (permalink / raw)
  To: Martin Ågren
  Cc: git, Sergey Organov, Patrick Steinhardt,
	Ævar Arnfjörð Bjarmason

Martin Ågren <martin.agren@gmail.com> writes:

> 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.
>
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
>  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(-)
>
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index d36e6fd482..3a9c44987f 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -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.

Signed-off-by: A U Thor <au@thor.xz>
---

 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(-)

diff --git a/.... 
index ....
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ ...

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH 2/3] git.txt: fix monospace rendering
  2021-02-18 18:51   ` Junio C Hamano
@ 2021-02-19  6:33     ` Martin Ågren
  0 siblings, 0 replies; 12+ messages in thread
From: Martin Ågren @ 2021-02-19  6:33 UTC (permalink / raw)
  To: Junio C Hamano
  Cc: Git Mailing List, Sergey Organov, Patrick Steinhardt,
	Ævar Arnfjörð Bjarmason

On Thu, 18 Feb 2021 at 19:51, Junio C Hamano <gitster@pobox.com> wrote:
>
> 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.

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

^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2021-02-19  6:35 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-02-17 19:56 [PATCH 0/3] fix some doc rendering issues since v2.30.0 Martin Ågren
2021-02-17 19:56 ` [PATCH 1/3] rev-list-options.txt: fix rendering of bonus paragraph Martin Ågren
2021-02-17 19:56 ` [PATCH 2/3] git.txt: fix monospace rendering Martin Ågren
2021-02-17 22:47   ` Chris Torek
2021-02-18  6:28     ` Martin Ågren
2021-02-18  6:27   ` Patrick Steinhardt
2021-02-18  6:32     ` Martin Ågren
2021-02-18 18:51   ` Junio C Hamano
2021-02-19  6:33     ` Martin Ågren
2021-02-17 19:56 ` [PATCH 3/3] gitmailmap.txt: fix rendering of e-mail addresses Martin Ågren
2021-02-18 10:48   ` Ævar Arnfjörð Bjarmason
2021-02-17 21:22 ` [PATCH 0/3] fix some doc rendering issues since v2.30.0 Junio C Hamano

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for the project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git