[PATCH v1 0/2] minor asciidoc/tor formatting fixes

[PATCH v1 0/2] minor asciidoc/tor formatting fixes

[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

 Documentation/git-status.txt       | 12 ++++++++----
 Documentation/rev-list-options.txt | 22 +++++++++++-----------
 2 files changed, 19 insertions(+), 15 deletions(-)

[PATCH v1 1/2] Documentation/rev-list-options: wrap --date=<format> block with "--"

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

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---

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(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index ca959a7286..7b415dff82 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -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

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

[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

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---

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(-)

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 861d821d7f..d4e8f24f0c 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -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 1/2] Documentation/rev-list-options: wrap --date=<format> block with "--"

[Jeff King]

On Sat, Mar 30, 2019 at 02:30:00PM -0400, Todd Zullinger wrote:

> 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 2/2] Documentation/git-status: fix titles in porcelain v2 section

[Jeff King]

On Sat, Mar 30, 2019 at 02:30:01PM -0400, Todd Zullinger wrote:

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

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

> 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

[Jeff Hostetler]

On 3/30/2019 2:30 PM, Todd Zullinger wrote:
> 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
> 
> Signed-off-by: Todd Zullinger <tmz@pobox.com>
> ---
> 
> 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 0/2] minor asciidoc/tor formatting fixes

[Martin Ågren]

On Sat, 30 Mar 2019 at 19:30, Todd Zullinger <tmz@pobox.com> wrote:
>
> 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

Re: [PATCH v1 1/2] Documentation/rev-list-options: wrap --date=<format> block with "--"

[Todd Zullinger]

Hi,

Jeff King wrote:
> On Sat, Mar 30, 2019 at 02:30:00PM -0400, Todd Zullinger wrote:
> 
>> 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.

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

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

-- 
Todd

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

[Todd Zullinger]

Jeff King wrote:
> On Sat, Mar 30, 2019 at 02:30:01PM -0400, Todd Zullinger wrote:
> 
>> 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:
> 
>> -### 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.

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.

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

No doubt.  I'm sure that would be a long deprecation period.

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

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

-- 
Todd

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

[Todd Zullinger]

Hi,

Jeff Hostetler wrote:
> On 3/30/2019 2:30 PM, Todd Zullinger wrote:
>> 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. ;)

-- 
Todd

Re: [PATCH v1 0/2] minor asciidoc/tor formatting fixes

[Todd Zullinger]

Hi,

Martin Ågren wrote:
> On Sat, 30 Mar 2019 at 19:30, Todd Zullinger <tmz@pobox.com> wrote:
>>
>> 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.

-- 
Todd

Re: [PATCH v1 0/2] minor asciidoc/tor formatting fixes

[Martin Ågren]

Hi Todd,

On Fri, 5 Apr 2019 at 03:40, Todd Zullinger <tmz@pobox.com> wrote:

> > On Sat, 30 Mar 2019 at 19:30, Todd Zullinger <tmz@pobox.com> wrote:
> >>
> >> 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

> 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

[PATCH 0/2] a few more minor asciidoc/tor formatting fixes

[Todd Zullinger]

Hi,

Martin Ågren wrote:
> On Fri, 5 Apr 2019 at 03:40, Todd Zullinger <tmz@pobox.com> wrote:
>> 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?

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(-)

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

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

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---

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(-)

diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 4a01371227..5cc2fcefba 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -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 2/2] Documentation/git-svn: improve asciidoctor compatibility

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

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
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(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index b99029520d..81aaef8e4e 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -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 0/2] a few more minor asciidoc/tor formatting fixes

[Martin Ågren]

On Sat, 6 Apr 2019 at 00:51, Todd Zullinger <tmz@pobox.com> wrote:
> 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

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

[Martin Ågren]

On Sat, 6 Apr 2019 at 00:51, Todd Zullinger <tmz@pobox.com> wrote:
>
> 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.

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

> 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

Re: [PATCH 2/2] Documentation/git-svn: improve asciidoctor compatibility

[Martin Ågren]

On Sat, 6 Apr 2019 at 00:51, Todd Zullinger <tmz@pobox.com> wrote:
>
> 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

[PATCH v2 0/2] a few more minor asciidoc/tor formatting fixes

[Todd Zullinger]

Hi,

Martin Ågren wrote:
> On Sat, 6 Apr 2019 at 00:51, Todd Zullinger <tmz@pobox.com> wrote:
>> 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 <tmz@pobox.com>
     
    -    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.
     
         Signed-off-by: Todd Zullinger <tmz@pobox.com>
     
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.
     
         Signed-off-by: Todd Zullinger <tmz@pobox.com>
     
-- 
Todd

[PATCH v2 1/2] Documentation/git-show-branch: avoid literal {apostrophe}

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

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.

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 Documentation/git-show-branch.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 4a01371227..5cc2fcefba 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -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

[Todd Zullinger]

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.

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 Documentation/git-svn.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index b99029520d..81aaef8e4e 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -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

[Todd Zullinger]

Martin Ågren wrote:
> 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,

-- 
Todd

Re: [PATCH v2 0/2] a few more minor asciidoc/tor formatting fixes

[Junio C Hamano]

Todd Zullinger <tmz@pobox.com> writes:

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