| Message ID | 20190405225115.3882-2-tmz@pobox.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [1/2] Documentation/git-show-branch: drop last use of {apostrophe} | expand |
On Sat, 6 Apr 2019 at 00:51, Todd Zullinger <tmz@pobox.com> wrote: > > The {apostrophe} was needed at the time of a521845800 ("Documentation: > remove stray backslash in show-branch discussion", 2010-08-20). All > other uses of {apostrophe} were removed in 6cf378f0cb ("docs: stop using > asciidoc no-inline-literal", 2012-04-26). > > Escape only the leading single-quote. This renders properly in asciidoc > and asciidoctor. You could perhaps say that "{apostrophe}" renders literally with Asciidoctor (at least with 1.5.5). Right now, you sort of undersell this patch. I know from context that you have some Asciidoctor "issue", but it's not clear from this patch alone. > --- > > Maybe it would be easier to change the example commit messages > and avoid having to nest single quotes within double quotes? I > don't know if that's much preferable to escaping only the opening > single quote. Yeah, those commit messages are a bit unfortunate from the point of view of quoting. Avoiding all that nesting would probably improve the reading experience, but I don't think that should hold up this patch. > This is another potential parsing bug in asciidoctor. Of course, > distros will have versions of asciidoctor in place for some time > which have trouble parsing this doc. Since it's not much work > for us to adjust the text to work around it, that seemed > reasonable. Agreed. Martin
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 4a01371227..5cc2fcefba 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -167,7 +167,7 @@ $ git show-branch master fixes mhf ------------------------------------------------ These three branches all forked from a common commit, [master], -whose commit message is "Add {apostrophe}git show-branch{apostrophe}". +whose commit message is "Add \'git show-branch'". The "fixes" branch adds one commit "Introduce "reset type" flag to "git reset"". The "mhf" branch adds many other commits. The current branch is "master".
The {apostrophe} was needed at the time of a521845800 ("Documentation: remove stray backslash in show-branch discussion", 2010-08-20). All other uses of {apostrophe} were removed in 6cf378f0cb ("docs: stop using asciidoc no-inline-literal", 2012-04-26). Escape only the leading single-quote. This renders properly in asciidoc and asciidoctor. Signed-off-by: Todd Zullinger <tmz@pobox.com> --- Maybe it would be easier to change the example commit messages and avoid having to nest single quotes within double quotes? I don't know if that's much preferable to escaping only the opening single quote. I went with the more minimal change to avoid having to rewrite other bits of the example (and risk making them not match what users would see if they ran similar commands). This is another potential parsing bug in asciidoctor. Of course, distros will have versions of asciidoctor in place for some time which have trouble parsing this doc. Since it's not much work for us to adjust the text to work around it, that seemed reasonable. Documentation/git-show-branch.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)