* [PATCH] Documentation: remove unnecessary backslashes
@ 2016-01-20 17:21 Matt Kraai
2016-01-20 18:24 ` Jeff King
0 siblings, 1 reply; 6+ messages in thread
From: Matt Kraai @ 2016-01-20 17:21 UTC (permalink / raw
To: git, Philip Oakley; +Cc: Matthew Kraai
From: Matthew Kraai <matt.kraai@abbott.com>
asciidoctor does not remove backslashes used to escape curly brackets from
the HTML output if the contents of the curly brackets are empty or contain
at least a <, -, or space. asciidoc does not require the backslashes in
these cases, so just remove them.
Signed-off-by: Matthew Kraai <matt.kraai@abbott.com>
Reported-by: Philip Oakley <philipoakley@iee.org>
---
Documentation/revisions.txt | 20 ++++++++++----------
1 file changed, 10 insertions(+), 10 deletions(-)
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index d85e303..fa4bdb2 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -61,11 +61,11 @@ some output processing may assume ref names in UTF-8.
'@'::
'@' alone is a shortcut for 'HEAD'.
-'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}'::
+'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
A ref followed by the suffix '@' with a date specification
enclosed in a brace
- pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
- second ago\}' or '\{1979-02-26 18:30:00\}') specifies the value
+ pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1
+ second ago}' or '{1979-02-26 18:30:00}') specifies the value
of the ref at a prior point in time. This suffix may only be
used immediately following a ref name and the ref must have an
existing log ('$GIT_DIR/logs/<ref>'). Note that this looks up the state
@@ -73,7 +73,7 @@ some output processing may assume ref names in UTF-8.
'master' branch last week. If you want to look at commits made during
certain times, see '--since' and '--until'.
-'<refname>@\{<n>\}', e.g. 'master@\{1\}'::
+'<refname>@{<n>}', e.g. 'master@\{1\}'::
A ref followed by the suffix '@' with an ordinal specification
enclosed in a brace pair (e.g. '\{1\}', '\{15\}') specifies
the n-th prior value of that ref. For example 'master@\{1\}'
@@ -82,13 +82,13 @@ some output processing may assume ref names in UTF-8.
immediately following a ref name and the ref must have an existing
log ('$GIT_DIR/logs/<refname>').
-'@\{<n>\}', e.g. '@\{1\}'::
+'@{<n>}', e.g. '@\{1\}'::
You can use the '@' construct with an empty ref part to get at a
reflog entry of the current branch. For example, if you are on
branch 'blabla' then '@\{1\}' means the same as 'blabla@\{1\}'.
-'@\{-<n>\}', e.g. '@\{-1\}'::
- The construct '@\{-<n>\}' means the <n>th branch/commit checked out
+'@{-<n>}', e.g. '@{-1}'::
+ The construct '@{-<n>}' means the <n>th branch/commit checked out
before the current one.
'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
@@ -139,7 +139,7 @@ from one location and push to another. In a non-triangular workflow,
'<rev>{caret}1{caret}1{caret}1'. See below for an illustration of
the usage of this form.
-'<rev>{caret}\{<type>\}', e.g. 'v0.99.8{caret}\{commit\}'::
+'<rev>{caret}{<type>}', e.g. 'v0.99.8{caret}\{commit\}'::
A suffix '{caret}' followed by an object type name enclosed in
brace pair means dereference the object at '<rev>' recursively until
an object of type '<type>' is found or the object cannot be
@@ -159,13 +159,13 @@ it does not have to be dereferenced even once to get to an object.
'rev{caret}\{tag\}' can be used to ensure that 'rev' identifies an
existing tag object.
-'<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}'::
+'<rev>{caret}{}', e.g. 'v0.99.8{caret}{}'::
A suffix '{caret}' followed by an empty brace pair
means the object could be a tag,
and dereference the tag recursively until a non-tag object is
found.
-'<rev>{caret}\{/<text>\}', e.g. 'HEAD^{/fix nasty bug}'::
+'<rev>{caret}{/<text>}', e.g. 'HEAD^{/fix nasty bug}'::
A suffix '{caret}' to a revision parameter, followed by a brace
pair that contains a text led by a slash,
is the same as the ':/fix nasty bug' syntax below except that
--
2.7.0.windows.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] Documentation: remove unnecessary backslashes
2016-01-20 17:21 [PATCH] Documentation: remove unnecessary backslashes Matt Kraai
@ 2016-01-20 18:24 ` Jeff King
2016-01-20 20:28 ` Junio C Hamano
2016-01-20 21:35 ` Matt Kraai
0 siblings, 2 replies; 6+ messages in thread
From: Jeff King @ 2016-01-20 18:24 UTC (permalink / raw
To: Matt Kraai; +Cc: git, Philip Oakley, Matthew Kraai
On Wed, Jan 20, 2016 at 09:21:37AM -0800, Matt Kraai wrote:
> From: Matthew Kraai <matt.kraai@abbott.com>
>
> asciidoctor does not remove backslashes used to escape curly brackets from
> the HTML output if the contents of the curly brackets are empty or contain
> at least a <, -, or space. asciidoc does not require the backslashes in
> these cases, so just remove them.
I think these backslashes may have been necessary in older versions of
asciidoc, but I don't recall the details. Looks like we did a similar
round of cleanups already in 4538a88256, so this is probably safe (and I
verified with asciidoc 8.6.9 that the generated output is the same).
> -'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}'::
> +'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
I see you didn't tweak the middle one here, because it _does_ look like
an attribute. Does asciidoctor actually remove the backslashes there?
> -'<refname>@\{<n>\}', e.g. 'master@\{1\}'::
> +'<refname>@{<n>}', e.g. 'master@\{1\}'::
Ditto here for "1". IMHO asciidoctor's behavior is somewhat crazy, as it
means you have to know arcane quoting rules to get correct output (you
cannot just err on the side of quoting). But it's probably still worth
working around.
-Peff
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Documentation: remove unnecessary backslashes
2016-01-20 18:24 ` Jeff King
@ 2016-01-20 20:28 ` Junio C Hamano
2016-01-20 20:34 ` Jeff King
2016-01-20 21:35 ` Matt Kraai
1 sibling, 1 reply; 6+ messages in thread
From: Junio C Hamano @ 2016-01-20 20:28 UTC (permalink / raw
To: Jeff King; +Cc: Matt Kraai, git, Philip Oakley, Matthew Kraai
Jeff King <peff@peff.net> writes:
> On Wed, Jan 20, 2016 at 09:21:37AM -0800, Matt Kraai wrote:
>
>> From: Matthew Kraai <matt.kraai@abbott.com>
>>
>> asciidoctor does not remove backslashes used to escape curly brackets from
>> the HTML output if the contents of the curly brackets are empty or contain
>> at least a <, -, or space. asciidoc does not require the backslashes in
>> these cases, so just remove them.
>
> I think these backslashes may have been necessary in older versions of
> asciidoc, but I don't recall the details. Looks like we did a similar
> round of cleanups already in 4538a88256, so this is probably safe (and I
> verified with asciidoc 8.6.9 that the generated output is the same).
>
>> -'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}'::
>> +'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
>
> I see you didn't tweak the middle one here, because it _does_ look like
> an attribute. Does asciidoctor actually remove the backslashes there?
A more important question is if it works without the backslashes.
If not-too-stale versions of asciidoc everybody uses these days are
all OK without braces quoted with backslashes, and if the same holds
true for asciidoctor, then we would want consistency here.
On the other hand, if this line must be spelled like the above to
please asciidoctor, i.e. the first and the last must not have
backslashes and the second must have backslashes, I'd have to say
we have a bigger problem. Perhaps asciidoctor needs to be fixed
until normal people like we can rely on it.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Documentation: remove unnecessary backslashes
2016-01-20 20:28 ` Junio C Hamano
@ 2016-01-20 20:34 ` Jeff King
2016-01-22 2:46 ` brian m. carlson
0 siblings, 1 reply; 6+ messages in thread
From: Jeff King @ 2016-01-20 20:34 UTC (permalink / raw
To: Junio C Hamano; +Cc: Matt Kraai, git, Philip Oakley, Matthew Kraai
On Wed, Jan 20, 2016 at 12:28:53PM -0800, Junio C Hamano wrote:
> >> -'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}'::
> >> +'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
> >
> > I see you didn't tweak the middle one here, because it _does_ look like
> > an attribute. Does asciidoctor actually remove the backslashes there?
>
> A more important question is if it works without the backslashes.
> If not-too-stale versions of asciidoc everybody uses these days are
> all OK without braces quoted with backslashes, and if the same holds
> true for asciidoctor, then we would want consistency here.
The answer to that is implied in the original commit message; no, it
does not work, because it is syntactically an asciidoc attribute.
> On the other hand, if this line must be spelled like the above to
> please asciidoctor, i.e. the first and the last must not have
> backslashes and the second must have backslashes, I'd have to say
> we have a bigger problem. Perhaps asciidoctor needs to be fixed
> until normal people like we can rely on it.
Yeah, that is the "insane" part I mentioned. It _does_ make sense
syntactically ("-1" cannot possibly be an attribute name, so it does not
parse as one), but I do not like the degree to which writers must know
all of the arcane syntax rules (and cannot rely on something simple like
"{ is special, so I must escape it, and over-escaping is not a
problem").
-Peff
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Documentation: remove unnecessary backslashes
2016-01-20 18:24 ` Jeff King
2016-01-20 20:28 ` Junio C Hamano
@ 2016-01-20 21:35 ` Matt Kraai
1 sibling, 0 replies; 6+ messages in thread
From: Matt Kraai @ 2016-01-20 21:35 UTC (permalink / raw
To: Jeff King; +Cc: git, Philip Oakley, Matthew Kraai
Hi,
On Wed, Jan 20, 2016 at 01:24:21PM -0500, Jeff King wrote:
> On Wed, Jan 20, 2016 at 09:21:37AM -0800, Matt Kraai wrote:
> > -'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}'::
> > +'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
>
> I see you didn't tweak the middle one here, because it _does_ look like
> an attribute. Does asciidoctor actually remove the backslashes there?
Yes, asciidoctor appears to remove the backslashes in some cases but
not others. I removed the backslashes from the source if it did not
remove them. I verified that the asciidoc output isn't affected.
> > -'<refname>@\{<n>\}', e.g. 'master@\{1\}'::
> > +'<refname>@{<n>}', e.g. 'master@\{1\}'::
>
> Ditto here for "1". IMHO asciidoctor's behavior is somewhat crazy, as it
> means you have to know arcane quoting rules to get correct output (you
> cannot just err on the side of quoting). But it's probably still worth
> working around.
I couldn't find any documentation of asciidoctor's behavior. I didn't
try figuring the behavior out from asciidoctor's source code.
--
Matt https://ftbfs.org/~kraai/
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Documentation: remove unnecessary backslashes
2016-01-20 20:34 ` Jeff King
@ 2016-01-22 2:46 ` brian m. carlson
0 siblings, 0 replies; 6+ messages in thread
From: brian m. carlson @ 2016-01-22 2:46 UTC (permalink / raw
To: Jeff King; +Cc: Junio C Hamano, Matt Kraai, git, Philip Oakley, Matthew Kraai
[-- Attachment #1: Type: text/plain, Size: 1424 bytes --]
On Wed, Jan 20, 2016 at 03:34:30PM -0500, Jeff King wrote:
> On Wed, Jan 20, 2016 at 12:28:53PM -0800, Junio C Hamano wrote:
> > On the other hand, if this line must be spelled like the above to
> > please asciidoctor, i.e. the first and the last must not have
> > backslashes and the second must have backslashes, I'd have to say
> > we have a bigger problem. Perhaps asciidoctor needs to be fixed
> > until normal people like we can rely on it.
>
> Yeah, that is the "insane" part I mentioned. It _does_ make sense
> syntactically ("-1" cannot possibly be an attribute name, so it does not
> parse as one), but I do not like the degree to which writers must know
> all of the arcane syntax rules (and cannot rely on something simple like
> "{ is special, so I must escape it, and over-escaping is not a
> problem").
The underlying issue is that both AsciiDoc and Asciidoctor use regexps
to parse their data, which we all know is a bad idea. Asciidoctor does
less forward looking because it's much faster, so it's a bit less
flexible with overescaping.
There are plans for Asciidoctor to move to a defined grammar at some
point, which should hopefully make things a bit less insane.
--
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 836 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2016-01-22 2:46 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-01-20 17:21 [PATCH] Documentation: remove unnecessary backslashes Matt Kraai
2016-01-20 18:24 ` Jeff King
2016-01-20 20:28 ` Junio C Hamano
2016-01-20 20:34 ` Jeff King
2016-01-22 2:46 ` brian m. carlson
2016-01-20 21:35 ` Matt Kraai
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.