patch, 2 partsminor 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(-)

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

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

Yep, makes sense. One observation:

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.

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

Jeff King wrote:

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.

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

Interesting. I didn't notice the matching right hand side while I was looking at the original asciidoc manual.

Seems like a good rule. I presume that when in doubt, we should look to the Asciidoctor reference for the current best practice.

Thanks,

On 3/30/2019 2:30 PM, Todd Zullinger wrote:

Yes, I was probably had markdown on the brain that day. Thanks Jeff

Hi,

Jeff Hostetler wrote:

Cool, thanks. Lucky guess on my part then. It's not like I've ever done something similar in other repos. ;)

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

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

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

Hi,

Jeff King wrote:

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

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.

On Sat, 30 Mar 2019 at 19:30, Todd Zullinger <tmz@pobox.com> wrote:

Nice. I've tested and diffed across various dimensions. Looks good to me.

Martin

Hi,

Martin Ågren wrote:

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.

Hi Todd,

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

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

Hi,

Martin Ågren wrote:

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

On Sat, 6 Apr 2019 at 00:51, Todd Zullinger <tmz@pobox.com> wrote:

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

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

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

Hi,

Martin Ågren wrote:

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 Zullinger <tmz@pobox.com> writes:

Thanks, will replace.

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

On Sat, 6 Apr 2019 at 00:51, Todd Zullinger <tmz@pobox.com> wrote:

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.

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.

Agreed.

Martin

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

On Sat, 6 Apr 2019 at 00:51, Todd Zullinger <tmz@pobox.com> wrote:

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

Martin Ågren wrote:

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,