| Message ID | 20200202193319.1966-1-martin.agren@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | git-filter-branch.txt: use {caret} for ^ | expand |
On Sun, Feb 02, 2020 at 08:33:19PM +0100, Martin Ågren wrote: > In this paragraph, we have a few instances of the '^' character, which > we give as "\^". This renders well with AsciiDoc ("^"), but Asciidoctor > renders it literally as "\^". Dropping the backslashes renders fine > with Asciidoctor, but not AsciiDoc... Let's use "{caret}" instead, to > avoid these escaping problems. Makes sense. The source is pretty ugly to read both before and after, though. I wonder if using a literal like `5*10^5` would be even nicer. That makes the source pretty readable, and the output would put it in <tt> or similar. Which maybe is a little funny, but kind of makes sense to me typographically as a kind of "this is math" style. -Peff
On Mon, 3 Feb 2020 at 12:45, Jeff King <peff@peff.net> wrote: > > On Sun, Feb 02, 2020 at 08:33:19PM +0100, Martin Ågren wrote: > > > In this paragraph, we have a few instances of the '^' character, which > > we give as "\^". This renders well with AsciiDoc ("^"), but Asciidoctor > > renders it literally as "\^". Dropping the backslashes renders fine > > with Asciidoctor, but not AsciiDoc... Let's use "{caret}" instead, to > > avoid these escaping problems. > > Makes sense. > > The source is pretty ugly to read both before and after, though. I Yeah, I was happy to have improved the situation a bit, but didn't quite feel that it looked great.. > wonder if using a literal like `5*10^5` would be even nicer. That makes > the source pretty readable, and the output would put it in <tt> or > similar. Which maybe is a little funny, but kind of makes sense to me > typographically as a kind of "this is math" style. Hmm, that somehow makes sense. How about the below? Outside of RelNotes/ and technical/, I only saw one spot where we could do something similar ("O(n^2)" in diff-options.txt; it has an accompanying loose "n"). I had actually expected more. Most hits for "{caret}" are in revisions.txt (duh) and the one hit for "\^" that remains after this patch is a shell snippet. Going for "1e5" and so on would be one way, I guess, but suffers from the same problem that it somehow looks like a random pile of characters in the middle of a sentence (unless it's typeset in, e.g., monospace). One could of course move in a different direction entirely and talk about "a thousand", "a million" and so on... --->8--- Subject: [PATCH v2] git-filter-branch.txt: wrap "maths" notation in backticks In this paragraph, we have a few instances of the '^' character, which we give as "\^". This renders well with AsciiDoc ("^"), but Asciidoctor renders it literally as "\^". Dropping the backslashes renders fine with Asciidoctor, but not AsciiDoc... An earlier version of this patch used "{caret}" instead of "^", which avoided these escaping problems. The rendering was still so-so, though -- these expressions end up set as normal text, similarly to when one provides, e.g., computer code in the middle of running text, without properly marking it with `backticks` to be monospaced. As noted by Jeff King, this suggests actually wrapping these expressions in backticks, setting them in monospace. The lone "5" could be left as is or wrapped as `5`. Spell it out as "five" instead -- this generally looks better anyway for small numbers in the middle of text like this. Suggested-by: Jeff King <peff@peff.net> Signed-off-by: Martin Ågren <martin.agren@gmail.com> --- Documentation/git-filter-branch.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index a530fef7e5..40ba4aa3e6 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -467,9 +467,9 @@ impossible for a backward-compatible implementation to ever be fast: * In editing files, git-filter-branch by design checks out each and every commit as it existed in the original repo. If your repo has - 10\^5 files and 10\^5 commits, but each commit only modifies 5 - files, then git-filter-branch will make you do 10\^10 modifications, - despite only having (at most) 5*10^5 unique blobs. + `10^5` files and `10^5` commits, but each commit only modifies five + files, then git-filter-branch will make you do `10^10` modifications, + despite only having (at most) `5*10^5` unique blobs. * If you try and cheat and try to make git-filter-branch only work on files modified in a commit, then two things happen
On Mon, Feb 3, 2020 at 12:37 PM Martin Ågren <martin.agren@gmail.com> wrote: > > On Mon, 3 Feb 2020 at 12:45, Jeff King <peff@peff.net> wrote: > > > > On Sun, Feb 02, 2020 at 08:33:19PM +0100, Martin Ågren wrote: > > > > > In this paragraph, we have a few instances of the '^' character, which > > > we give as "\^". This renders well with AsciiDoc ("^"), but Asciidoctor > > > renders it literally as "\^". Dropping the backslashes renders fine > > > with Asciidoctor, but not AsciiDoc... Let's use "{caret}" instead, to > > > avoid these escaping problems. > > > > Makes sense. > > > > The source is pretty ugly to read both before and after, though. I > > Yeah, I was happy to have improved the situation a bit, but didn't quite > feel that it looked great.. > > > wonder if using a literal like `5*10^5` would be even nicer. That makes > > the source pretty readable, and the output would put it in <tt> or > > similar. Which maybe is a little funny, but kind of makes sense to me > > typographically as a kind of "this is math" style. > > Hmm, that somehow makes sense. How about the below? Outside of RelNotes/ > and technical/, I only saw one spot where we could do something similar > ("O(n^2)" in diff-options.txt; it has an accompanying loose "n"). I had > actually expected more. Most hits for "{caret}" are in revisions.txt > (duh) and the one hit for "\^" that remains after this patch is a shell > snippet. > > Going for "1e5" and so on would be one way, I guess, but suffers from > the same problem that it somehow looks like a random pile of characters > in the middle of a sentence (unless it's typeset in, e.g., monospace). > > One could of course move in a different direction entirely and talk > about "a thousand", "a million" and so on... > > --->8--- > Subject: [PATCH v2] git-filter-branch.txt: wrap "maths" notation in backticks > > In this paragraph, we have a few instances of the '^' character, which > we give as "\^". This renders well with AsciiDoc ("^"), but Asciidoctor > renders it literally as "\^". Dropping the backslashes renders fine > with Asciidoctor, but not AsciiDoc... > > An earlier version of this patch used "{caret}" instead of "^", which > avoided these escaping problems. The rendering was still so-so, though > -- these expressions end up set as normal text, similarly to when one > provides, e.g., computer code in the middle of running text, without > properly marking it with `backticks` to be monospaced. > > As noted by Jeff King, this suggests actually wrapping these > expressions in backticks, setting them in monospace. > > The lone "5" could be left as is or wrapped as `5`. Spell it out as > "five" instead -- this generally looks better anyway for small numbers > in the middle of text like this. > > Suggested-by: Jeff King <peff@peff.net> > Signed-off-by: Martin Ågren <martin.agren@gmail.com> > --- > Documentation/git-filter-branch.txt | 6 +++--- > 1 file changed, 3 insertions(+), 3 deletions(-) > > diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt > index a530fef7e5..40ba4aa3e6 100644 > --- a/Documentation/git-filter-branch.txt > +++ b/Documentation/git-filter-branch.txt > @@ -467,9 +467,9 @@ impossible for a backward-compatible implementation to ever be fast: > > * In editing files, git-filter-branch by design checks out each and > every commit as it existed in the original repo. If your repo has > - 10\^5 files and 10\^5 commits, but each commit only modifies 5 > - files, then git-filter-branch will make you do 10\^10 modifications, > - despite only having (at most) 5*10^5 unique blobs. > + `10^5` files and `10^5` commits, but each commit only modifies five > + files, then git-filter-branch will make you do `10^10` modifications, > + despite only having (at most) `5*10^5` unique blobs. Looks good to me. > * If you try and cheat and try to make git-filter-branch only work on > files modified in a commit, then two things happen It's so tempting to remove "try and" to get rid of the duplicate "try" at the same time...
On Mon, Feb 03, 2020 at 09:36:50PM +0100, Martin Ågren wrote: > --->8--- > Subject: [PATCH v2] git-filter-branch.txt: wrap "maths" notation in backticks Yep, this looks fine to me. Thanks. (I'd consider it fine to also put the O(n^2) you found in backticks, but if it renders fine in both places already, I'm happy either way). -Peff
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index a530fef7e5..9e58d34c6a 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -467,9 +467,9 @@ impossible for a backward-compatible implementation to ever be fast: * In editing files, git-filter-branch by design checks out each and every commit as it existed in the original repo. If your repo has - 10\^5 files and 10\^5 commits, but each commit only modifies 5 - files, then git-filter-branch will make you do 10\^10 modifications, - despite only having (at most) 5*10^5 unique blobs. + 10{caret}5 files and 10{caret}5 commits, but each commit only modifies 5 + files, then git-filter-branch will make you do 10{caret}10 modifications, + despite only having (at most) 5*10{caret}5 unique blobs. * If you try and cheat and try to make git-filter-branch only work on files modified in a commit, then two things happen
In this paragraph, we have a few instances of the '^' character, which we give as "\^". This renders well with AsciiDoc ("^"), but Asciidoctor renders it literally as "\^". Dropping the backslashes renders fine with Asciidoctor, but not AsciiDoc... Let's use "{caret}" instead, to avoid these escaping problems. Signed-off-by: Martin Ågren <martin.agren@gmail.com> --- Documentation/git-filter-branch.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)