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

From: Jeff King <peff@peff.net>
Date: Apr 1, 2019, 13:18 UTC
Message-ID: <20190401131831.GA12254@sigill.intra.peff.net>
In-Reply-To: <20190330183001.16624-3-tmz@pobox.com>

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.

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

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