Re: git-filter-branch.txt: wrap "maths" notation in backticks
- From
- Martin Ågren <martin.agren@gmail.com>
- Date
- Feb 3, 2020, 20:36 UTC
- Message-ID
- <20200203203650.31914-1-martin.agren@gmail.com>
- In-Reply-To
- <20200203114549.GA4157558@coredump.intra.peff.net>
On Mon, 3 Feb 2020 at 12:45, Jeff King <peff@peff.net> wrote:
Show 12 quoted lines
>
> 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. IYeah, 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
-- 2.25.0