[PATCH] Documentation: render dash correctly

[PATCH] Documentation: render dash correctly

[Andrei Rybak]

Three hyphens are rendered verbatim in documentation, so "--" has to be
used to produce a dash.  Fix asciidoc output for dashes.  This is
similar to previous commits f0b922473e (Documentation: render special
characters correctly, 2021-07-29) and de82095a95 (doc
hash-function-transition: fix asciidoc output, 2021-02-05).

Signed-off-by: Andrei Rybak <rybak.a.v@gmail.com>
---
 Documentation/git-apply.txt                          | 2 +-
 Documentation/git-read-tree.txt                      | 2 +-
 Documentation/git.txt                                | 2 +-
 Documentation/technical/hash-function-transition.txt | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 1d478cbe9b..5e16e6db7e 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -208,7 +208,7 @@ behavior:
 * `warn` outputs warnings for a few such errors, but applies the
   patch as-is (default).
 * `fix` outputs warnings for a few such errors, and applies the
-  patch after fixing them (`strip` is a synonym --- the tool
+  patch after fixing them (`strip` is a synonym -- the tool
   used to consider only trailing whitespace characters as errors, and the
   fix involved 'stripping' them, but modern Gits do more).
 * `error` outputs warnings for a few such errors, and refuses
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 7567955bad..b09707474d 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -219,7 +219,7 @@ see which of the "local changes" that you made were carried forward by running
 `git diff-index --cached $M`.  Note that this does not
 necessarily match what `git diff-index --cached $H` would have
 produced before such a two tree merge.  This is because of cases
-18 and 19 --- if you already had the changes in $M (e.g. maybe
+18 and 19 -- if you already had the changes in $M (e.g. maybe
 you picked it up via e-mail in a patch form), `git diff-index
 --cached $H` would have told you about the change before this
 merge, but it would not show in `git diff-index --cached $M`
diff --git a/Documentation/git.txt b/Documentation/git.txt
index f9a7a4554c..74973d3cc4 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -613,7 +613,7 @@ The file parameters can point at the user's working file
 (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
 when a new file is added), or a temporary file (e.g. `old-file` in the
 index).  `GIT_EXTERNAL_DIFF` should not worry about unlinking the
-temporary file --- it is removed when `GIT_EXTERNAL_DIFF` exits.
+temporary file -- it is removed when `GIT_EXTERNAL_DIFF` exits.
 +
 For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1
 parameter, <path>.
diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt
index e2ac36dd21..ed57481089 100644
--- a/Documentation/technical/hash-function-transition.txt
+++ b/Documentation/technical/hash-function-transition.txt
@@ -562,7 +562,7 @@ hash re-encode during clone and to encourage peers to modernize.
 The design described here allows fetches by SHA-1 clients of a
 personal SHA-256 repository because it's not much more difficult than
 allowing pushes from that repository. This support needs to be guarded
-by a configuration option --- servers like git.kernel.org that serve a
+by a configuration option -- servers like git.kernel.org that serve a
 large number of clients would not be expected to bear that cost.
 
 Meaning of signatures
-- 
2.39.0

Re: [PATCH] Documentation: render dash correctly

[Junio C Hamano]

Andrei Rybak <rybak.a.v@gmail.com> writes:

> Three hyphens are rendered verbatim in documentation, so "--" has to be
> used to produce a dash.

Sad but true.  I suspect folks with TeX background were so
accustomed to type three dashes to obtain em dash, but with AsciiDoc
(and asciidoctor), sadly, two dashes is a way to ask for em dash.

The changes in your patch look all reasonable to me at the source
level; I didn't do Documentation/doc-diff to verify, though.

Thanks.

Re: [PATCH] Documentation: render dash correctly

[Martin Ågren]

On Sun, 22 Jan 2023 at 23:55, Junio C Hamano <gitster@pobox.com> wrote:
>
> Andrei Rybak <rybak.a.v@gmail.com> writes:
>
> > Three hyphens are rendered verbatim in documentation, so "--" has to be
> > used to produce a dash.
>
> Sad but true.  I suspect folks with TeX background were so
> accustomed to type three dashes to obtain em dash, but with AsciiDoc
> (and asciidoctor), sadly, two dashes is a way to ask for em dash.
>
> The changes in your patch look all reasonable to me at the source
> level; I didn't do Documentation/doc-diff to verify, though.

doc-diff looks good.

I suspect these were identified by greping for " --- ", spaces included.
We seem to have some "---" that aren't surrounded by spaces. They're
perhaps a bit more tedious to find, but I see there are two in
gitformat-signature.txt and technical/rerere.txt. Maybe it would be
worthwhile addressing them too in this patch.

Martin

[PATCH v2] Documentation: render dash correctly

[Andrei Rybak]

Three hyphens are rendered verbatim in documentation, so "--" has to be
used to produce a dash.  Fix asciidoc output for dashes.  This is
similar to previous commits f0b922473e (Documentation: render special
characters correctly, 2021-07-29) and de82095a95 (doc
hash-function-transition: fix asciidoc output, 2021-02-05).

Signed-off-by: Andrei Rybak <rybak.a.v@gmail.com>
---

On 2023-01-23T09:19, Martin Ågren wrote:
> I suspect these were identified by greping for " --- ", spaces included.

Indeed.

> We seem to have some "---" that aren't surrounded by spaces. They're
> perhaps a bit more tedious to find,

Not really:

    git grep -P -i '[^-][a-z0-9]+---[a-z0-9]+[^-]' -- Documentation/

The "[^-]" part is needed to exclude many examples of commit graphs.

The following:

    The horizontal line of history A---Q is taken to be the first parent of each
    merge.

also comes up in 'Documentation/rev-list-options.txt', but it might be better to
leave "A---Q" as is to be similar to the commit graph example above it (there
are commits between A and Q in the graph, but still).

> but I see there are two in
> gitformat-signature.txt and technical/rerere.txt. Maybe it would be
> worthwhile addressing them too in this patch.
> 
> Martin

Thank you for review, here's v2.

Changes from v1:

 - Added two fixes in gitformat-signature.txt and technical/rerere.txt, as
   suggested by Martin Ågren.

 Documentation/git-apply.txt                          | 2 +-
 Documentation/git-read-tree.txt                      | 2 +-
 Documentation/git.txt                                | 2 +-
 Documentation/gitformat-signature.txt                | 2 +-
 Documentation/technical/hash-function-transition.txt | 2 +-
 Documentation/technical/rerere.txt                   | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 1d478cbe9b..5e16e6db7e 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -208,7 +208,7 @@ behavior:
 * `warn` outputs warnings for a few such errors, but applies the
   patch as-is (default).
 * `fix` outputs warnings for a few such errors, and applies the
-  patch after fixing them (`strip` is a synonym --- the tool
+  patch after fixing them (`strip` is a synonym -- the tool
   used to consider only trailing whitespace characters as errors, and the
   fix involved 'stripping' them, but modern Gits do more).
 * `error` outputs warnings for a few such errors, and refuses
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 7567955bad..b09707474d 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -219,7 +219,7 @@ see which of the "local changes" that you made were carried forward by running
 `git diff-index --cached $M`.  Note that this does not
 necessarily match what `git diff-index --cached $H` would have
 produced before such a two tree merge.  This is because of cases
-18 and 19 --- if you already had the changes in $M (e.g. maybe
+18 and 19 -- if you already had the changes in $M (e.g. maybe
 you picked it up via e-mail in a patch form), `git diff-index
 --cached $H` would have told you about the change before this
 merge, but it would not show in `git diff-index --cached $M`
diff --git a/Documentation/git.txt b/Documentation/git.txt
index f9a7a4554c..74973d3cc4 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -613,7 +613,7 @@ The file parameters can point at the user's working file
 (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
 when a new file is added), or a temporary file (e.g. `old-file` in the
 index).  `GIT_EXTERNAL_DIFF` should not worry about unlinking the
-temporary file --- it is removed when `GIT_EXTERNAL_DIFF` exits.
+temporary file -- it is removed when `GIT_EXTERNAL_DIFF` exits.
 +
 For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1
 parameter, <path>.
diff --git a/Documentation/gitformat-signature.txt b/Documentation/gitformat-signature.txt
index a249869faf..d8e3eb1bac 100644
--- a/Documentation/gitformat-signature.txt
+++ b/Documentation/gitformat-signature.txt
@@ -37,7 +37,7 @@ line.
 This is even true for an originally empty line.  In the following
 examples, the end of line that ends with a whitespace letter is
 highlighted with a `$` sign; if you are trying to recreate these
-example by hand, do not cut and paste them---they are there
+example by hand, do not cut and paste them--they are there
 primarily to highlight extra whitespace at the end of some lines.
 
 The signed payload and the way the signature is embedded depends
diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt
index e2ac36dd21..ed57481089 100644
--- a/Documentation/technical/hash-function-transition.txt
+++ b/Documentation/technical/hash-function-transition.txt
@@ -562,7 +562,7 @@ hash re-encode during clone and to encourage peers to modernize.
 The design described here allows fetches by SHA-1 clients of a
 personal SHA-256 repository because it's not much more difficult than
 allowing pushes from that repository. This support needs to be guarded
-by a configuration option --- servers like git.kernel.org that serve a
+by a configuration option -- servers like git.kernel.org that serve a
 large number of clients would not be expected to bear that cost.
 
 Meaning of signatures
diff --git a/Documentation/technical/rerere.txt b/Documentation/technical/rerere.txt
index 35d4541433..be58f1bee3 100644
--- a/Documentation/technical/rerere.txt
+++ b/Documentation/technical/rerere.txt
@@ -99,7 +99,7 @@ conflict to leave line D means that the user declares:
     compatible with what AB and AC wanted to do.
 
 So the conflict we would see when merging AB into ACAB should be
-resolved the same way---it is the resolution that is in line with that
+resolved the same way--it is the resolution that is in line with that
 declaration.
 
 Imagine that similarly previously a branch XYXZ was forked from XY,
-- 
2.39.0

Re: [PATCH v2] Documentation: render dash correctly

[Martin Ågren]

On Mon, 23 Jan 2023 at 10:01, Andrei Rybak <rybak.a.v@gmail.com> wrote:

>  highlighted with a `$` sign; if you are trying to recreate these
> -example by hand, do not cut and paste them---they are there
> +example by hand, do not cut and paste them--they are there
>  primarily to highlight extra whitespace at the end of some lines.

OK, so this is one of the new ones compared to v1. I can see the
argument for adding some spaces around the "--" for consistency and to
make this a bit easier to read in the resulting manpage (which can of
course be very subjective), but then I can also see that kind of change
being left out as orthogonal to this patch.

This v2 patch looks good to me.

Martin

Re: [PATCH v2] Documentation: render dash correctly

[Junio C Hamano]

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

> On Mon, 23 Jan 2023 at 10:01, Andrei Rybak <rybak.a.v@gmail.com> wrote:
>
>>  highlighted with a `$` sign; if you are trying to recreate these
>> -example by hand, do not cut and paste them---they are there
>> +example by hand, do not cut and paste them--they are there
>>  primarily to highlight extra whitespace at the end of some lines.
>
> OK, so this is one of the new ones compared to v1. I can see the
> argument for adding some spaces around the "--" for consistency and to
> make this a bit easier to read in the resulting manpage (which can of
> course be very subjective), but then I can also see that kind of change
> being left out as orthogonal to this patch.
>
> This v2 patch looks good to me.

Thanks, both.  Will queue.

Re: [PATCH v2] Documentation: render dash correctly

[Andrei Rybak]

On 23/01/2023 12:04, Martin Ågren wrote:
> On Mon, 23 Jan 2023 at 10:01, Andrei Rybak <rybak.a.v@gmail.com> wrote:
> 
>>   highlighted with a `$` sign; if you are trying to recreate these
>> -example by hand, do not cut and paste them---they are there
>> +example by hand, do not cut and paste them--they are there
>>   primarily to highlight extra whitespace at the end of some lines.
> 
> OK, so this is one of the new ones compared to v1. I can see the
> argument for adding some spaces around the "--" for consistency and to
> make this a bit easier to read in the resulting manpage (which can of
> course be very subjective), but then I can also see that kind of change

There are some less subjective guidelines.  Asciidoc turns "--" into an
em-dash.[1]  In English, em-dash is almost always not surrounded by
spaces (it is in French, for example), while en-dash is spaced in
English when used instead of an em-dash.[2][3][4]

This means that it's all the other places that use " -- " with spaces
that are incorrect.

References:

1. https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#text-replacements

2. English Wikipedia is clear about its usage of en- and em-dashes:
    https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style#Dashes

3. Chicago Manual of Style FAQ doesn't spell out the spacing, but it's
    clear from examples:
    https://www.chicagomanualofstyle.org/qanda/data/faq/topics/HyphensEnDashesEmDashes/faq0002.html

4. More confirmation on English Language and Usage Q&A website on Stack
    Exchange network: https://english.stackexchange.com/a/154998/54197

> being left out as orthogonal to this patch.

Indeed, correcting spacing around dashes is orthogonal.  Also, it might
not be very desirable to have so much churn for spacing issues.
  
> This v2 patch looks good to me.

Thank you for review.
  
> Martin