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

From: Todd Zullinger <tmz@pobox.com>
Date: Apr 5, 2019, 01:26 UTC
Message-ID: <20190405012650.GP4047@pobox.com>
In-Reply-To: <20190401131831.GA12254@sigill.intra.peff.net>

Jeff King wrote:

Show 20 quoted lines

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

Show 14 quoted 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.

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

Show 9 quoted 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.

> 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