minor asciidoc/tor formatting fixes
cover minor asciidoc/tor formatting fixes
Just chipping away at the remaining differences between asciidoc and asciidoctor.
Todd Zullinger (2):
Documentation/rev-list-options: wrap --date=<format> block with "--" Documentation/git-status: fix titles in porcelain v2 section
Documentation/git-status.txt | 12 ++++++++---- Documentation/rev-list-options.txt | 22 +++++++++++----------- 2 files changed, 19 insertions(+), 15 deletions(-)
PATCH 1/2 Documentation/rev-list-options: wrap --date=<format> block with "--"
Using "+" to continue multiple list items is more tedious and error-prone than wrapping the entire block with "--" block markers.
When using asciidoctor, the list items after the --date=iso list items are incorrectly formatted when using "+" continuation. Use "--" block markers to correctly format the block.
When using asciidoc there is no change in how the content is rendered.
---
The issue this fixes can be seen in the git-log and git-rev-list docs on git-scm.com:
https://git-scm.com/docs/git-log#Documentation/git-log.txt---dateltformatgt
https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---dateltformatgt
Documentation/rev-list-options.txt | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-)
Documentation/rev-list-options.txt +11 -11
@@ -805,12 +805,13 @@ include::pretty-options.txt[] author's). If `-local` is appended to the format (e.g., `iso-local`), the user's local time zone is used instead. + +-- `--date=relative` shows dates relative to the current time, e.g. ``2 hours ago''. The `-local` option has no effect for `--date=relative`. -+ + `--date=local` is an alias for `--date=default-local`. -+ + `--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format. The differences to the strict ISO 8601 format are:
@@ -818,15 +819,14 @@ The differences to the strict ISO 8601 format are: - a space between time and time zone - no colon between hours and minutes of the time zone -+ `--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict ISO 8601 format. -+ + `--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 format, often found in email messages. -+ + `--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format. -+ + `--date=raw` shows the date as seconds since the epoch (1970-01-01 00:00:00 UTC), followed by a space, and then the timezone as an offset from UTC (a `+` or `-` with four digits; the first two are hours, and
@@ -835,28 +835,28 @@ with `strftime("%s %z")`). Note that the `-local` option does not affect the seconds-since-epoch value (which is always measured in UTC), but does switch the accompanying timezone value. -+ + `--date=human` shows the timezone if the timezone does not match the current time-zone, and doesn't print the whole date if that matches (ie skip printing year for dates that are "this year", but also skip the whole date itself if it's in the last few days and we can just say what weekday it was). For older dates the hour and minute is also omitted. -+ + `--date=unix` shows the date as a Unix epoch timestamp (seconds since 1970). As with `--raw`, this is always in UTC and therefore `-local` has no effect. -+ + `--date=format:...` feeds the format `...` to your system `strftime`, except for %z and %Z, which are handled internally. Use `--date=format:%c` to show the date in your system locale's preferred format. See the `strftime` manual for a complete list of format placeholders. When using `-local`, the correct syntax is `--date=format-local:...`. -+ + `--date=default` is the default format, and is similar to `--date=rfc2822`, with a few exceptions: - +-- - there is no comma after the day-of-week - the time zone is omitted when the local time zone is used
Re: [PATCH v1 1/2] Documentation/rev-list-options: wrap --date=<format> block with "--"
Quoted 8 lines · Todd Zullinger
Using "+" to continue multiple list items is more tedious and error-prone than wrapping the entire block with "--" block markers.
When using asciidoctor, the list items after the --date=iso list items are incorrectly formatted when using "+" continuation. Use "--" block markers to correctly format the block.
When using asciidoc there is no change in how the content is rendered.
This seems like an asciidoctor bug, though I think this kind of list-within-a-list stuff is inherently a bit heuristic-driven just due to the syntax.
I do agree that the result after your patch is more readable, so I think I prefer it even if the asciidoctor bug were fixed. I suspect we could be using "--" blocks for readability in more places (I don't think it's worth going on a hunt to convert old spots, but something to keep in mind as we write new documentation).
-Peff
Re: [PATCH v1 1/2] Documentation/rev-list-options: wrap --date=<format> block with "--"
Hi,
Quoted 9 lines · Jeff King
Quoted 7 lines · Todd Zullinger
Using "+" to continue multiple list items is more tedious and error-prone than wrapping the entire block with "--" block markers.
When using asciidoctor, the list items after the --date=iso list items are incorrectly formatted when using "+" continuation. Use "--" block markers to correctly format the block.
Quoted 5 lines
Quoted 1 line
When using asciidoc there is no change in how the content is rendered.
This seems like an asciidoctor bug, though I think this kind of list-within-a-list stuff is inherently a bit heuristic-driven just due to the syntax.
Indeed. There's certainly a limit to the changes we want to make solely to work-around issues in either asciidoc or asciidoctor. When the work-around is (at least arguably) an improvement, then it's probably worthwhile. That's how I thought about it, anyway. :)
Quoted 5 lines
I do agree that the result after your patch is more readable, so I think I prefer it even if the asciidoctor bug were fixed. I suspect we could be using "--" blocks for readability in more places (I don't think it's worth going on a hunt to convert old spots, but something to keep in mind as we write new documentation).
Agreed, that sounds perfectly reasonable to me. The Asciidoctor user manual says:
If you’re attaching more than one block to a list item, you’re strongly encouraged to wrap the content inside an open block. That way, you only need a single list continuation line to attach the open block to the list item. Within the open block, you write like you normally would, no longer having to worry about adding list continuations between the blocks to keep them attached to the list item.
https://asciidoctor.org/docs/user-manual/#list-continuation
I imagine it's "strongly encouraged" both to help consumers avoid these sort of oddly-parsed continuation issues, as well as the Asciidoctor devs from having to field as many bug reports.
Signature · 1 line
Todd
PATCH 2/2 Documentation/git-status: fix titles in porcelain v2 section
In reply to Todd ZullingerAsciidoc uses either one-line or two-line syntax for document/section titles[1]. The two-line form is used in git-status. Fix a few section titles in the porcelain v2 section which were inadvertently using markdown syntax.
[1] http://asciidoc.org/userguide.html#X17
---
The '^### ' lines were added in 1cd828ddc8 ("git-status.txt: describe --porcelain=v2 format", 2016-08-11). I'm _presuming_ they were made with markdown syntax in mind, but if not I can drop that bit from the commit message. Jeff H, do you happen to recall?
As an aside, while I was reading the Asciidoc/tor manuals, I notice the two-line title syntax was not mentioned in Asciidoctor. That seems to be because Asciidoctor has suggested the two-line title format should be deprecated, as discussed at:
https://github.com/asciidoctor/asciidoctor/issues/418
I'm not sure how likely that is to occur. With the 2.0 release, asciidoctor plans to use semantic versioning, so I would not expect any deprecation to happen before at least 2.1. It would only affect use without compat-mode.
Documentation/git-status.txt | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-)
Documentation/git-status.txt +8 -4
@@ -278,7 +278,8 @@ Header lines start with "#" and are added in response to specific command line arguments. Parsers should ignore headers they don't recognize. -### Branch Headers +Branch Headers +^^^^^^^^^^^^^^ If `--branch` is given, a series of header lines are printed with information about the current branch.
@@ -294,7 +295,8 @@ Line Notes ------------------------------------------------------------ .... -### Changed Tracked Entries +Changed Tracked Entries +^^^^^^^^^^^^^^^^^^^^^^^ Following the headers, a series of lines are printed for tracked entries. One of three different line formats may be used to describe
@@ -365,7 +367,8 @@ Field Meaning -------------------------------------------------------- .... -### Other Items +Other Items +^^^^^^^^^^^ Following the tracked entries (and if requested), a series of lines will be printed for untracked and then ignored items
@@ -379,7 +382,8 @@ Ignored items have the following format: ! <path> -### Pathname Format Notes and -z +Pathname Format Notes and -z +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the `-z` option is given, pathnames are printed as is and without any quoting and lines are terminated with a NUL (ASCII 0x00)
Re: [PATCH v1 2/2] Documentation/git-status: fix titles in porcelain v2 section
Quoted 4 lines · Todd Zullinger
Asciidoc uses either one-line or two-line syntax for document/section titles[1]. The two-line form is used in git-status. Fix a few section titles in the porcelain v2 section which were inadvertently using markdown syntax.
Yep, makes sense. One observation:
Documentation/git-status.txt Header lines start with "#" and are added in response to specific · line 282
Quoted 3 lines
Documentation/git-status.txt +2
-1-### Branch Headers +Branch Headers +^^^^^^^^^^^^^^
The one-line equivalent in asciidoc would be something like:
=== Branch Headers
but that's actually a "level 2" header (because it counts from zero), whereas "^" underlining is a "level 3" header. But I think "^" is right here, because this is under level 2 "~" header.
Quoted 11 lines
As an aside, while I was reading the Asciidoc/tor manuals, I notice the two-line title syntax was not mentioned in Asciidoctor. That seems to be because Asciidoctor has suggested the two-line title format should be deprecated, as discussed at:
https://github.com/asciidoctor/asciidoctor/issues/418
I'm not sure how likely that is to occur. With the 2.0 release, asciidoctor plans to use semantic versioning, so I would not expect any deprecation to happen before at least 2.1. It would only affect use without compat-mode.
I think it's probably fine to punt on this until we see some actual movement upstream on the deprecation / removal.
One side note. The original asciidoc user guide says one-line headers have equals on either side, like:
=== Branch Headers ===
but that one can omit the trailing delimiter. The asciidoctor reference just suggests using the one-sided:
=== Branch Headers
So presumably if we do want to convert, we would just go with the one-sided version.
-Peff
Re: [PATCH v1 2/2] Documentation/git-status: fix titles in porcelain v2 section
Quoted 15 lines · Jeff King
Quoted 4 lines · Todd Zullinger
Asciidoc uses either one-line or two-line syntax for document/section titles[1]. The two-line form is used in git-status. Fix a few section titles in the porcelain v2 section which were inadvertently using markdown syntax.
Yep, makes sense. One observation:
Documentation/git-status.txt Header lines start with "#" and are added in response to specific · line 282
Quoted 3 lines
Documentation/git-status.txt +2
-1-### Branch Headers +Branch Headers +^^^^^^^^^^^^^^The one-line equivalent in asciidoc would be something like:
Quoted 5 lines
=== Branch Headers
but that's actually a "level 2" header (because it counts from zero), whereas "^" underlining is a "level 3" header. But I think "^" is right here, because this is under level 2 "~" header.
Yeah, since there were a number of existing two-line headers in the document, I thought it would be better to simply update these to that form than convert the others. We have far more of the two-line form too, so it's more consistent with the existing docs.
Quoted 7 lines
Quoted 7 lines
As an aside, while I was reading the Asciidoc/tor manuals, I notice the two-line title syntax was not mentioned in Asciidoctor. That seems to be because Asciidoctor has suggested the two-line title format should be deprecated, as discussed at:
Quoted 7 lines
Quoted 4 lines
I'm not sure how likely that is to occur. With the 2.0 release, asciidoctor plans to use semantic versioning, so I would not expect any deprecation to happen before at least 2.1. It would only affect use without compat-mode.
I think it's probably fine to punt on this until we see some actual movement upstream on the deprecation / removal.
No doubt. I'm sure that would be a long deprecation period.
Quoted 9 lines
One side note. The original asciidoc user guide says one-line headers have equals on either side, like:
=== Branch Headers ===
but that one can omit the trailing delimiter. The asciidoctor reference just suggests using the one-sided:
=== Branch Headers
Interesting. I didn't notice the matching right hand side while I was looking at the original asciidoc manual.
Quoted 2 lines
So presumably if we do want to convert, we would just go with the one-sided version.
Seems like a good rule. I presume that when in doubt, we should look to the Asciidoctor reference for the current best practice.
Thanks,
Signature · 1 line
Todd
Re: [PATCH v1 2/2] Documentation/git-status: fix titles in porcelain v2 section
In reply to Todd ZullingerQuoted 7 lines · Todd Zullinger
Asciidoc uses either one-line or two-line syntax for document/section titles[1]. The two-line form is used in git-status. Fix a few section titles in the porcelain v2 section which were inadvertently using markdown syntax.
Quoted 7 lines
Signed-off-by Todd Zullinger <[email protected]>---
The '^### ' lines were added in
1cd828ddc8("git-status.txt: describe --porcelain=v2 format", 2016-08-11). I'm _presuming_ they were made with markdown syntax in mind, but if not I can drop that bit from the commit message. Jeff H, do you happen to recall?
Yes, I was probably had markdown on the brain that day. Thanks
Jeff
Re: [PATCH v1 2/2] Documentation/git-status: fix titles in porcelain v2 section
Hi,
Quoted 7 lines · Jeff Hostetler
Quoted 4 lines · Todd Zullinger
The '^### ' lines were added in
1cd828ddc8("git-status.txt: describe --porcelain=v2 format", 2016-08-11). I'm _presuming_ they were made with markdown syntax in mind, but if not I can drop that bit from the commit message. Jeff H, do you happen to recall?Yes, I was probably had markdown on the brain that day.
Cool, thanks. Lucky guess on my part then. It's not like I've ever done something similar in other repos. ;)
Signature · 1 line
Todd
Quoted 7 lines · Todd Zullinger
Just chipping away at the remaining differences between asciidoc and asciidoctor.
Todd Zullinger (2):
Documentation/rev-list-options: wrap --date=<format> block with "--"Documentation/git-status: fix titles in porcelain v2 section
Nice. I've tested and diffed across various dimensions. Looks good to me.
Martin
Hi,
Quoted 10 lines · Martin Ågren
Quoted 7 lines · Todd Zullinger
Just chipping away at the remaining differences between asciidoc and asciidoctor.
Todd Zullinger (2):
Documentation/rev-list-options: wrap --date=<format> block with "--"Documentation/git-status: fix titles in porcelain v2 sectionNice. I've tested and diffed across various dimensions. Looks good to me.
Thanks for testing! On pu we're down to a fairly small amount of differences now. Most of what remains are whitespace changes; some of which I would like to bring up to the Asciidoctor team to see if they're intentional.
There are two other changes I've got queued locally. One in git-show-branch.txt removes the last use of {apostrophe}. Another in git-svn.txt is a bit of a work-around for a difference in the way asciidoc and asciidoctor parse the second paragraph in the CONFIGURATION section. That may well be an asiidoctor bug, but it seems like one we can adjust for without much effort.
Signature · 1 line
Todd
Hi Todd,
Quoted 9 lines · Todd Zullinger
Quoted 8 lines · Todd Zullinger
Quoted 7 lines
Just chipping away at the remaining differences between asciidoc and asciidoctor.
Todd Zullinger (2):
Documentation/rev-list-options: wrap --date=<format> block with "--"Documentation/git-status: fix titles in porcelain v2 section
Quoted 7 lines
There are two other changes I've got queued locally. One in git-show-branch.txt removes the last use of {apostrophe}. Another in git-svn.txt is a bit of a work-around for a difference in the way asciidoc and asciidoctor parse the second paragraph in the CONFIGURATION section. That may well be an asiidoctor bug, but it seems like one we can adjust for without much effort.
The second one looks like it can be fixed by using * instead of '\*', which I think is more correct anyway. I don't know what your local workaround looks like, but I think a patch like "use backticks consistently" (both change to them, in a number of places, and add them, where we currently have nothing) would be a good change by itself, and we could note that "BTW, this fixes ...". How does that compare to what you have?
Martin
cover a few more minor asciidoc/tor formatting fixes
Hi,
Quoted 9 lines · Martin Ågren
Quoted 7 lines · Todd Zullinger
There are two other changes I've got queued locally. One in git-show-branch.txt removes the last use of {apostrophe}. Another in git-svn.txt is a bit of a work-around for a difference in the way asciidoc and asciidoctor parse the second paragraph in the CONFIGURATION section. That may well be an asiidoctor bug, but it seems like one we can adjust for without much effort.
Quoted 7 lines
The second one looks like it can be fixed by using
*instead of '\*', which I think is more correct anyway. I don't know what your local workaround looks like, but I think a patch like "use backticks consistently" (both change to them, in a number of places, and add them, where we currently have nothing) would be a good change by itself, and we could note that "BTW, this fixes ...". How does that compare to what you have?
That's exactly what I have -- except that I only changed the parts needed to improve compatibility between asciidoc and asciidoctor. So my commit message justifies it differently.
You're probably right that a more general cleanup could be done and then we get better asciidoctor compatibilty as a consequence. I was trying to keep from taking too many tangents to avoid making more work (both for myself and reviewers). :)
Here's what I have currently. I haven't tested this much with asciidoctor-1.5.x releases (or maybe not at all -- it's been a week or so since I worked on this).
Todd Zullinger (2):
Documentation/git-show-branch: drop last use of {apostrophe} Documentation/git-svn: improve asciidoctor compatibility
Documentation/git-show-branch.txt | 2 +- Documentation/git-svn.txt | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-)
Re: [PATCH 0/2] a few more minor asciidoc/tor formatting fixes
Quoted 3 lines · Todd Zullinger
Here's what I have currently. I haven't tested this much with asciidoctor-1.5.x releases (or maybe not at all -- it's been a week or so since I worked on this).
Tested with Asciidoctor 1.5.5. For both patches, AsciiDoctor stumbles before the patch, but not after it. Great. :-) For AsciiDoc 8.6.10, the first patch is a no-op, while the second patch makes the difference it intends to do. I'll follow up with comments on the individual patches.
Martin
PATCH v2 1/2 Documentation/git-show-branch: avoid literal {apostrophe}
The {apostrophe} was needed at the time of a521845800 ("Documentation:
remove stray backslash in show-branch discussion", 2010-08-20). All other uses of {apostrophe} were removed in 6cf378f0cb ("docs: stop using asciidoc no-inline-literal", 2012-04-26).
Unfortunately, the {apostrophe} is rendered literally with Asciidoctor (at least with 1.5.5-2.0.3). Avoid this by using single-quotes.
Escaping the leading single-quote allows the content to render properly in AsciiDoc and Asciidoctor.
--- Documentation/git-show-branch.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-show-branch.txt +1 -1
@@ -167,7 +167,7 @@ $ git show-branch master fixes mhf ------------------------------------------------ These three branches all forked from a common commit, [master], -whose commit message is "Add {apostrophe}git show-branch{apostrophe}". +whose commit message is "Add \'git show-branch'". The "fixes" branch adds one commit "Introduce "reset type" flag to "git reset"". The "mhf" branch adds many other commits. The current branch is "master".
PATCH v2 2/2 Documentation/git-svn: improve asciidoctor compatibility
In reply to Martin ÅgrenThe second paragraph in the CONFIGURATION section intends to emphasize the word 'must' with bold type. It does so by writing it as *must*, and this works fine with AsciiDoc. It usually works great with Asciidoctor, too, but in this particular instance, we have another "*" earlier in the paragraph. We do escape it, and it is rendered literally just like we want it to, but Asciidoctor then ends up tripping on the second (or third) of the asterisks in this paragraph.
Since that asterisk is (part of) a literal example, we can set it in monospace, by giving it as *. Adjust the whole paragraph in this way. There's lots more monospacing to be done in this document, but since our main motivation is addressing AsciiDoc/Asciidoctor discrepancies like this one, let's just convert this one paragraph.
--- Documentation/git-svn.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/git-svn.txt +3 -3
@@ -1100,10 +1100,10 @@ listed below are allowed: tags = tags/*/project-a:refs/remotes/project-a/tags/* ------------------------------------------------------------------------ -Keep in mind that the '\*' (asterisk) wildcard of the local ref -(right of the ':') *must* be the farthest right path component; +Keep in mind that the `*` (asterisk) wildcard of the local ref +(right of the `:`) *must* be the farthest right path component; however the remote wildcard may be anywhere as long as it's an -independent path component (surrounded by '/' or EOL). This +independent path component (surrounded by `/` or EOL). This type of configuration is not automatically created by 'init' and should be manually entered with a text-editor or using 'git config'.
v2 cover a few more minor asciidoc/tor formatting fixes
In reply to Martin ÅgrenHi,
Quoted 9 lines · Martin Ågren
Quoted 3 lines · Todd Zullinger
Here's what I have currently. I haven't tested this much with asciidoctor-1.5.x releases (or maybe not at all -- it's been a week or so since I worked on this).
Tested with Asciidoctor 1.5.5. For both patches, AsciiDoctor stumbles before the patch, but not after it. Great. :-) For AsciiDoc 8.6.10, the first patch is a no-op, while the second patch makes the difference it intends to do. I'll follow up with comments on the individual patches.
Thanks for testing these against older Asciidoctor and for the helpful feedback on the commit messages.
I reworded the message in the first commit to make it clearer that Asciidoctor renders the {apostrophe} literally. I updated the body of the second commit using your suggested wording. It was much better than the original. :)
The contents of each commit remain unchanged.
Todd Zullinger (2):
Documentation/git-show-branch: avoid literal {apostrophe} Documentation/git-svn: improve asciidoctor compatibility
Documentation/git-show-branch.txt | 2 +- Documentation/git-svn.txt | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-)
Range-diff against v1:
1: 70e3339859 ! 1: da553a596c Documentation/git-show-branch: drop last use of {apostrophe}
@@ -1,14 +1,17 @@
Author: Todd Zullinger <[email protected]>
- Documentation/git-show-branch: drop last use of {apostrophe}
+ Documentation/git-show-branch: avoid literal {apostrophe}
The {apostrophe} was needed at the time of a521845800 ("Documentation:
remove stray backslash in show-branch discussion", 2010-08-20). All other uses of {apostrophe} were removed in 6cf378f0cb ("docs: stop using asciidoc no-inline-literal", 2012-04-26).
- Escape only the leading single-quote. This renders properly in asciidoc
- and asciidoctor.
+ Unfortunately, the {apostrophe} is rendered literally with Asciidoctor
+ (at least with 1.5.5-2.0.3). Avoid this by using single-quotes.
+
+ Escaping the leading single-quote allows the content to render properly
+ in AsciiDoc and Asciidoctor.
2: e8f6f873bc ! 2: 6fd412bd97 Documentation/git-svn: improve asciidoctor compatibility
@@ -3,8 +3,18 @@
Documentation/git-svn: improve asciidoctor compatibility
The second paragraph in the CONFIGURATION section intends to emphasize
- the word 'must' with bold type. Adjust the formatting slightly to
- provide similar results between asciidoc and asciidoctor.
+ the word 'must' with bold type. It does so by writing it as *must*, and
+ this works fine with AsciiDoc. It usually works great with Asciidoctor,
+ too, but in this particular instance, we have another "*" earlier in the
+ paragraph. We do escape it, and it is rendered literally just like we
+ want it to, but Asciidoctor then ends up tripping on the second (or
+ third) of the asterisks in this paragraph.
+
+ Since that asterisk is (part of) a literal example, we can set it in
+ monospace, by giving it as *. Adjust the whole paragraph in this way.
+ There's lots more monospacing to be done in this document, but since our
+ main motivation is addressing AsciiDoc/Asciidoctor discrepancies like
+ this one, let's just convert this one paragraph.
Signature · 1 line
Todd
Re: [PATCH v2 0/2] a few more minor asciidoc/tor formatting fixes
Quoted 7 lines · Todd Zullinger
Thanks for testing these against older Asciidoctor and for the helpful feedback on the commit messages.
I reworded the message in the first commit to make it clearer that Asciidoctor renders the {apostrophe} literally. I updated the body of the second commit using your suggested wording. It was much better than the original. :)
Thanks, will replace.
PATCH 1/2 Documentation/git-show-branch: drop last use of {apostrophe}
In reply to Martin ÅgrenThe {apostrophe} was needed at the time of a521845800 ("Documentation:
remove stray backslash in show-branch discussion", 2010-08-20). All other uses of {apostrophe} were removed in 6cf378f0cb ("docs: stop using asciidoc no-inline-literal", 2012-04-26).
Escape only the leading single-quote. This renders properly in asciidoc and asciidoctor.
---
Maybe it would be easier to change the example commit messages and avoid having to nest single quotes within double quotes? I don't know if that's much preferable to escaping only the opening single quote.
I went with the more minimal change to avoid having to rewrite other bits of the example (and risk making them not match what users would see if they ran similar commands).
This is another potential parsing bug in asciidoctor. Of course, distros will have versions of asciidoctor in place for some time which have trouble parsing this doc. Since it's not much work for us to adjust the text to work around it, that seemed reasonable.
Documentation/git-show-branch.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-show-branch.txt +1 -1
@@ -167,7 +167,7 @@ $ git show-branch master fixes mhf ------------------------------------------------ These three branches all forked from a common commit, [master], -whose commit message is "Add {apostrophe}git show-branch{apostrophe}". +whose commit message is "Add \'git show-branch'". The "fixes" branch adds one commit "Introduce "reset type" flag to "git reset"". The "mhf" branch adds many other commits. The current branch is "master".
Re: [PATCH 1/2] Documentation/git-show-branch: drop last use of {apostrophe}
Quoted 8 lines · Todd Zullinger
The {apostrophe} was needed at the time of
a521845800("Documentation:
remove stray backslash in show-branch discussion", 2010-08-20). All other uses of {apostrophe} were removed in6cf378f0cb("docs: stop using asciidoc no-inline-literal", 2012-04-26).Escape only the leading single-quote. This renders properly in asciidoc and asciidoctor.
You could perhaps say that "{apostrophe}" renders literally with Asciidoctor (at least with 1.5.5). Right now, you sort of undersell this patch. I know from context that you have some Asciidoctor "issue", but it's not clear from this patch alone.
Quoted 6 lines
---
Maybe it would be easier to change the example commit messages and avoid having to nest single quotes within double quotes? I don't know if that's much preferable to escaping only the opening single quote.
Yeah, those commit messages are a bit unfortunate from the point of view of quoting. Avoiding all that nesting would probably improve the reading experience, but I don't think that should hold up this patch.
Quoted 5 lines
This is another potential parsing bug in asciidoctor. Of course, distros will have versions of asciidoctor in place for some time which have trouble parsing this doc. Since it's not much work for us to adjust the text to work around it, that seemed reasonable.
Agreed.
Martin
PATCH 2/2 Documentation/git-svn: improve asciidoctor compatibility
In reply to Martin ÅgrenThe second paragraph in the CONFIGURATION section intends to emphasize the word 'must' with bold type. Adjust the formatting slightly to provide similar results between asciidoc and asciidoctor.
---
I debated changing 'must' from bold to italic in this hunk. There are two other emphasized uses of 'must' in git-svn.txt. One is bold and one is italic. So I left this one bold and simply adjusted the "'" quotes to "`" around the "*" and ":" characters. This is the more minimal fix to keep the output rendered the same in asciidoc and asciidoctor.
Documentation/git-svn.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/git-svn.txt +3 -3
@@ -1100,10 +1100,10 @@ listed below are allowed: tags = tags/*/project-a:refs/remotes/project-a/tags/* ------------------------------------------------------------------------ -Keep in mind that the '\*' (asterisk) wildcard of the local ref -(right of the ':') *must* be the farthest right path component; +Keep in mind that the `*` (asterisk) wildcard of the local ref +(right of the `:`) *must* be the farthest right path component; however the remote wildcard may be anywhere as long as it's an -independent path component (surrounded by '/' or EOL). This +independent path component (surrounded by `/` or EOL). This type of configuration is not automatically created by 'init' and should be manually entered with a text-editor or using 'git config'.
Re: [PATCH 2/2] Documentation/git-svn: improve asciidoctor compatibility
Quoted 4 lines · Todd Zullinger
The second paragraph in the CONFIGURATION section intends to emphasize the word 'must' with bold type. Adjust the formatting slightly to provide similar results between asciidoc and asciidoctor.
I don't think this explains the problem you're solving well enough. It also doesn't make it clear enough, IMHO, how what we're doing here solves that problem. How about something like this?
The second paragraph in the CONFIGURATION section intends to emphasize the word 'must' with bold type. It does so by writing it as *must*, and this works fine with AsciiDoc. It usually works great with Asciidoctor, too, but in this particular instance, we have another "*" earlier in the paragraph. We do escape it, and it is rendered literally just like we want it to, but Asciidoctor then ends up tripping on the second (or third) of the asterisks in this paragraph.
Since that asterisk is (part of) a literal example, we can set it in monospace, by giving it as *. Adjust the whole paragraph in this way. There's lots more monospacing to be done in this document, but since our main motivation is addressing AsciiDoc/Asciidoctor discrepancies like this one, let's just convert this one paragraph.
I think what's happening could be related to the fix in the first patch. There, it's ok to explicitly escape only the first '. The second one is matched to it and gets escaped implicitly. Something like that could be happening here, too, just that we don't want it to. (Should we escape the implicit escaping? ...) Just speculation, though.
Martin
Re: [PATCH 2/2] Documentation/git-svn: improve asciidoctor compatibility
Quoted 5 lines · Martin Ågren
I think what's happening could be related to the fix in the first patch. There, it's ok to explicitly escape only the first '. The second one is matched to it and gets escaped implicitly. Something like that could be happening here, too, just that we don't want it to. (Should we escape the implicit escaping? ...) Just speculation, though.
It could well be a similar issue. I think I tried adding an escape to the existing \* and/or to elsewhere in the block of text, without success. But I didn't try very hard though, as adjusting the test to use * seemed like an improvement.
Thanks,
Signature · 1 line
Todd