* [PATCH] git-filter-branch.txt: use {caret} for ^
@ 2020-02-02 19:33 Martin Ågren
2020-02-03 11:45 ` Jeff King
0 siblings, 1 reply; 5+ messages in thread
From: Martin Ågren @ 2020-02-02 19:33 UTC (permalink / raw)
To: git; +Cc: Elijah Newren
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(-)
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
--
2.25.0
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] git-filter-branch.txt: use {caret} for ^
2020-02-02 19:33 [PATCH] git-filter-branch.txt: use {caret} for ^ Martin Ågren
@ 2020-02-03 11:45 ` Jeff King
2020-02-03 20:36 ` git-filter-branch.txt: wrap "maths" notation in backticks Martin Ågren
0 siblings, 1 reply; 5+ messages in thread
From: Jeff King @ 2020-02-03 11:45 UTC (permalink / raw)
To: Martin Ågren; +Cc: git, Elijah Newren
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: git-filter-branch.txt: wrap "maths" notation in backticks
2020-02-03 11:45 ` Jeff King
@ 2020-02-03 20:36 ` Martin Ågren
2020-02-03 20:40 ` Elijah Newren
2020-02-03 21:03 ` Jeff King
0 siblings, 2 replies; 5+ messages in thread
From: Martin Ågren @ 2020-02-03 20:36 UTC (permalink / raw)
To: Jeff King; +Cc: git, Elijah Newren
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
--
2.25.0
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: git-filter-branch.txt: wrap "maths" notation in backticks
2020-02-03 20:36 ` git-filter-branch.txt: wrap "maths" notation in backticks Martin Ågren
@ 2020-02-03 20:40 ` Elijah Newren
2020-02-03 21:03 ` Jeff King
1 sibling, 0 replies; 5+ messages in thread
From: Elijah Newren @ 2020-02-03 20:40 UTC (permalink / raw)
To: Martin Ågren; +Cc: Jeff King, Git Mailing List
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...
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: git-filter-branch.txt: wrap "maths" notation in backticks
2020-02-03 20:36 ` git-filter-branch.txt: wrap "maths" notation in backticks Martin Ågren
2020-02-03 20:40 ` Elijah Newren
@ 2020-02-03 21:03 ` Jeff King
1 sibling, 0 replies; 5+ messages in thread
From: Jeff King @ 2020-02-03 21:03 UTC (permalink / raw)
To: Martin Ågren; +Cc: git, Elijah Newren
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
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2020-02-03 21:03 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-02-02 19:33 [PATCH] git-filter-branch.txt: use {caret} for ^ Martin Ågren
2020-02-03 11:45 ` Jeff King
2020-02-03 20:36 ` git-filter-branch.txt: wrap "maths" notation in backticks Martin Ågren
2020-02-03 20:40 ` Elijah Newren
2020-02-03 21:03 ` Jeff King
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
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 read-only IMAP folder(s) and NNTP newsgroup(s).