Skip to contentSkip to conversation

minor asciidoc/tor formatting fixes

PATCH In review Todd Zullinger 5 participants 23 messages Mar 30, 2019 – Apr 10, 2019 Documentation

lore
Share & tools
lore
#0 lore raw

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(-)
#1 lore raw

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
index ca959a7286..7b415dff82 100644
@@ -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
#2 lore raw

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

#3 lore raw

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
#4 lore raw

PATCH 2/2 Documentation/git-status: fix titles in porcelain v2 section

In reply to 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.

[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
index 861d821d7f..d4e8f24f0c 100644
@@ -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)
#5 lore raw

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

#6 lore raw

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:

https://github.com/asciidoctor/asciidoctor/issues/418

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
#7 lore raw

Re: [PATCH v1 2/2] Documentation/git-status: fix titles in porcelain v2 section

In reply to Todd Zullinger
Quoted 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.

[1] http://asciidoc.org/userguide.html#X17

Quoted 7 lines

---

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

#8 lore raw

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
#9 lore raw
In reply to Todd Zullinger
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

#10 lore raw

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 section

Nice. 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
#11 lore raw

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

#12 lore raw

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(-)
#13 lore raw

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

#14 lore raw

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
index 4a01371227..5cc2fcefba 100644
@@ -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".
#15 lore raw

PATCH v2 2/2 Documentation/git-svn: improve asciidoctor compatibility

In reply to Martin Ågren

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.

---
 Documentation/git-svn.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/git-svn.txt +3 -3
index b99029520d..81aaef8e4e 100644
@@ -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'.
 
#16 lore raw

v2 cover a few more minor asciidoc/tor formatting fixes

In reply to Martin Ågren

Hi,

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
#17 lore raw

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.

#18 lore raw

PATCH 1/2 Documentation/git-show-branch: drop last use of {apostrophe}

In reply to Martin Ågren

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.

---

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
index 4a01371227..5cc2fcefba 100644
@@ -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".
#19 lore raw

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 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.

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

#20 lore raw

PATCH 2/2 Documentation/git-svn: improve asciidoctor compatibility

In reply to Martin Ågren

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 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
index b99029520d..81aaef8e4e 100644
@@ -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'.
 
#21 lore raw

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

#22 lore raw

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