| Message ID | 20190330183001.16624-3-tmz@pobox.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | minor asciidoc/tor formatting fixes | expand |
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. -Peff
On 3/30/2019 2:30 PM, 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. > > [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? Yes, I was probably had markdown on the brain that day. Thanks Jeff
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,
Hi, Jeff Hostetler wrote: > On 3/30/2019 2:30 PM, Todd Zullinger wrote: >> 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? > > Yes, I was probably had markdown on the brain that day. Cool, thanks. Lucky guess on my part then. It's not like I've ever done something similar in other repos. ;)
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 861d821d7f..d4e8f24f0c 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -278,7 +278,8 @@ Header lines start with "#" and are added in response to specific command line arguments. Parsers should ignore headers they don't recognize. -### Branch Headers +Branch Headers +^^^^^^^^^^^^^^ If `--branch` is given, a series of header lines are printed with information about the current branch. @@ -294,7 +295,8 @@ Line Notes ------------------------------------------------------------ .... -### Changed Tracked Entries +Changed Tracked Entries +^^^^^^^^^^^^^^^^^^^^^^^ Following the headers, a series of lines are printed for tracked entries. One of three different line formats may be used to describe @@ -365,7 +367,8 @@ Field Meaning -------------------------------------------------------- .... -### Other Items +Other Items +^^^^^^^^^^^ Following the tracked entries (and if requested), a series of lines will be printed for untracked and then ignored items @@ -379,7 +382,8 @@ Ignored items have the following format: ! <path> -### Pathname Format Notes and -z +Pathname Format Notes and -z +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the `-z` option is given, pathnames are printed as is and without any quoting and lines are terminated with a NUL (ASCII 0x00)
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(-)