* [PATCH] Documentation: render dash correctly @ 2023-01-22 16:56 Andrei Rybak 2023-01-22 22:53 ` Junio C Hamano 2023-01-23 9:01 ` [PATCH v2] " Andrei Rybak 0 siblings, 2 replies; 7+ messages in thread From: Andrei Rybak @ 2023-01-22 16:56 UTC (permalink / raw) To: git 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 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH] Documentation: render dash correctly 2023-01-22 16:56 [PATCH] Documentation: render dash correctly Andrei Rybak @ 2023-01-22 22:53 ` Junio C Hamano 2023-01-23 8:19 ` Martin Ågren 2023-01-23 9:01 ` [PATCH v2] " Andrei Rybak 1 sibling, 1 reply; 7+ messages in thread From: Junio C Hamano @ 2023-01-22 22:53 UTC (permalink / raw) To: Andrei Rybak; +Cc: git 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. ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] Documentation: render dash correctly 2023-01-22 22:53 ` Junio C Hamano @ 2023-01-23 8:19 ` Martin Ågren 0 siblings, 0 replies; 7+ messages in thread From: Martin Ågren @ 2023-01-23 8:19 UTC (permalink / raw) To: Junio C Hamano; +Cc: Andrei Rybak, git 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 ^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH v2] Documentation: render dash correctly 2023-01-22 16:56 [PATCH] Documentation: render dash correctly Andrei Rybak 2023-01-22 22:53 ` Junio C Hamano @ 2023-01-23 9:01 ` Andrei Rybak 2023-01-23 11:04 ` Martin Ågren 1 sibling, 1 reply; 7+ messages in thread From: Andrei Rybak @ 2023-01-23 9:01 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Martin Ågren 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 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH v2] Documentation: render dash correctly 2023-01-23 9:01 ` [PATCH v2] " Andrei Rybak @ 2023-01-23 11:04 ` Martin Ågren 2023-01-23 17:39 ` Junio C Hamano 2023-01-23 18:52 ` Andrei Rybak 0 siblings, 2 replies; 7+ messages in thread From: Martin Ågren @ 2023-01-23 11:04 UTC (permalink / raw) To: Andrei Rybak; +Cc: git, Junio C Hamano 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 ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH v2] Documentation: render dash correctly 2023-01-23 11:04 ` Martin Ågren @ 2023-01-23 17:39 ` Junio C Hamano 2023-01-23 18:52 ` Andrei Rybak 1 sibling, 0 replies; 7+ messages in thread From: Junio C Hamano @ 2023-01-23 17:39 UTC (permalink / raw) To: Martin Ågren; +Cc: Andrei Rybak, git 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. ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH v2] Documentation: render dash correctly 2023-01-23 11:04 ` Martin Ågren 2023-01-23 17:39 ` Junio C Hamano @ 2023-01-23 18:52 ` Andrei Rybak 1 sibling, 0 replies; 7+ messages in thread From: Andrei Rybak @ 2023-01-23 18:52 UTC (permalink / raw) To: Martin Ågren; +Cc: git, Junio C Hamano 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 ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2023-01-23 18:52 UTC | newest] Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2023-01-22 16:56 [PATCH] Documentation: render dash correctly Andrei Rybak 2023-01-22 22:53 ` Junio C Hamano 2023-01-23 8:19 ` Martin Ågren 2023-01-23 9:01 ` [PATCH v2] " Andrei Rybak 2023-01-23 11:04 ` Martin Ågren 2023-01-23 17:39 ` Junio C Hamano 2023-01-23 18:52 ` Andrei Rybak
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 NNTP newsgroup(s).