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
