Web lists-archives.com

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

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.