Documentation: render dash correctly
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
@@ -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
@@ -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
@@ -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
@@ -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
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.
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-diffto 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 1/1 Documentation: render dash correctly
In reply to Andrei RybakThree 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 andtechnical/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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
Documentation/gitformat-signature.txt line. · line 41
Quoted 4 lines · Andrei Rybak
highlighted with a
$sign; if you are trying to recreate theseDocumentation/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
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 theseDocumentation/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.
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 theseDocumentation/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