Skip to contentSkip to conversation

Documentation: render dash correctly

PATCH Superseded Andrei Rybak 3 participants 7 messages Jan 22, 2023 – Jan 23, 2023 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Documentation: render dash correctly

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

---
 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(-)
Documentation/git-apply.txt +1 -1
index 1d478cbe9b..5e16e6db7e 100644
@@ -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
Documentation/git-read-tree.txt +1 -1
index 7567955bad..b09707474d 100644
@@ -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`
Documentation/git.txt +1 -1
index f9a7a4554c..74973d3cc4 100644
@@ -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>.
Documentation/technical/hash-function-transition.txt +1 -1
index e2ac36dd21..ed57481089 100644
@@ -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
Signature · 1 line
2.39.0
#1 lore raw
Quoted 2 lines · Andrei Rybak

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.

#2 lore raw
Quoted 6 lines · Junio C Hamano
Quoted 2 lines · Andrei Rybak

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

Quoted 6 lines

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

#3 lore raw

PATCH v2 1/1 Documentation: render dash correctly

In reply to 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).

---

Quoted 1 line · Martin Ågren

I suspect these were identified by greping for " --- ", spaces included.

Indeed.

Quoted 2 lines

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

Quoted 5 lines

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(-)
Documentation/git-apply.txt +1 -1
index 1d478cbe9b..5e16e6db7e 100644
@@ -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
Documentation/git-read-tree.txt +1 -1
index 7567955bad..b09707474d 100644
@@ -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`
Documentation/git.txt +1 -1
index f9a7a4554c..74973d3cc4 100644
@@ -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>.
Documentation/gitformat-signature.txt +1 -1
index a249869faf..d8e3eb1bac 100644
@@ -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
Documentation/technical/hash-function-transition.txt +1 -1
index e2ac36dd21..ed57481089 100644
@@ -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
Documentation/technical/rerere.txt +1 -1
index 35d4541433..be58f1bee3 100644
@@ -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,
Signature · 1 line
2.39.0
#4 lore raw

Documentation/gitformat-signature.txt line. · line 41

Quoted 4 lines · Andrei Rybak

highlighted with a $ sign; if you are trying to recreate these

Documentation/gitformat-signature.txt +1 -1
-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

#5 lore raw
Quoted 13 lines · Martin Ågren

Documentation/gitformat-signature.txt line. · line 41

Quoted 4 lines · Andrei Rybak

highlighted with a $ sign; if you are trying to recreate these

Documentation/gitformat-signature.txt +1 -1
-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.

Quoted 1 line

This v2 patch looks good to me.

Thanks, both. Will queue.

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

Documentation/gitformat-signature.txt line. · line 41

Quoted 4 lines · Andrei Rybak

highlighted with a $ sign; if you are trying to recreate these

Documentation/gitformat-signature.txt +1 -1
-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

Quoted 1 line

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.

Quoted 1 line

This v2 patch looks good to me.

Thank you for review.

Quoted 1 line

Martin