git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: "Martin Ågren" <martin.agren@gmail.com>
Cc: git@vger.kernel.org, "Sergey Organov" <sorganov@gmail.com>,
	"Patrick Steinhardt" <ps@pks.im>,
	"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Subject: Re: [PATCH 2/3] git.txt: fix monospace rendering
Date: Thu, 18 Feb 2021 10:51:52 -0800	[thread overview]
Message-ID: <xmqqim6pgqev.fsf@gitster.g> (raw)
In-Reply-To: <97c686dd7ba1bbd1c0be6f7f61a3a033adf8adb6.1613590761.git.martin.agren@gmail.com> ("Martin =?utf-8?Q?=C3=85gren=22's?= message of "Wed, 17 Feb 2021 20:56:05 +0100")

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

  parent reply	other threads:[~2021-02-18 19:36 UTC|newest]

Thread overview: 12+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
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 [this message]
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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqqim6pgqev.fsf@gitster.g \
    --to=gitster@pobox.com \
    --cc=avarab@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=martin.agren@gmail.com \
    --cc=ps@pks.im \
    --cc=sorganov@gmail.com \
    --subject='Re: [PATCH 2/3] git.txt: fix monospace rendering' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

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

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 read-only IMAP folder(s) and NNTP newsgroup(s).