threads / bug / 25981

[BUG] yet another doc formatting problem

Subject: [BUG] yet another doc formatting problem

## tl;dr

9 messages between Dec 7, 2010 and Dec 8, 2010.

replies: 8people: 4as markdown or json

Jeff King· Dec 7, 2010, 05:07 UTC · lore
When I build git-rm.1, some of the headings look odd. For example:
   Using  git commit -a""
          If you intend that your next commit should record...
   ...
   Using  git add -A""
          When accepting a new code drop for a vendor branch

Note the funny double-space and the weird "" at the end. I get the same thing from "git show origin/man:man1/git-rm.1 | nroff -man".

The source looks like this:
  $ git grep -A1 Using..git.commit git-rm.txt
  git-rm.txt:Using "git commit -a"
  git-rm.txt-~~~~~~~~~~~~~~~~~~~~~
which looks sane to me. The generated xml also looks OK to me:
  $ grep Using..git.commit git-rm.xml
  <title>Using "git commit -a"</title>
But the resulting roff doesn't:
  $ grep Using..git.commit git-rm.1
  .SS "Using "git commit \-a""
which looks like a quoting error to me, which implies a bug in docbook.

I guess we can hack around it with some XSL magic, but I am tempted to do the simple:

diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt
index 71e3d9f..8ee559b 100644
--- a/Documentation/git-rm.txt
+++ b/Documentation/git-rm.txt
@@ -89,8 +89,8 @@ the paths that have disappeared from the filesystem. However,
 depending on the use case, there are several ways that can be
 done.
 
-Using "git commit -a"
-~~~~~~~~~~~~~~~~~~~~~
+Using git commit -a
+~~~~~~~~~~~~~~~~~~~
 If you intend that your next commit should record all modifications
 of tracked files in the working tree and record all removals of
 files that have been removed from the working tree with `rm`
@@ -98,8 +98,8 @@ files that have been removed from the working tree with `rm`
 automatically notice and record all removals.  You can also have a
 similar effect without committing by using `git add -u`.
 
-Using "git add -A"
-~~~~~~~~~~~~~~~~~~
+Using git add -A
+~~~~~~~~~~~~~~~~
 When accepting a new code drop for a vendor branch, you probably
 want to record both the removal of paths and additions of new paths
 as well as modifications of existing paths.

-Peff
Michael J Gruber· Dec 7, 2010, 08:42 UTC · re: Jeff King · lore

Re: [BUG] yet another doc formatting problem

Jeff King venit, vidit, dixit 07.12.2010 06:07:
Show 60 quoted lines
> When I build git-rm.1, some of the headings look odd. For example:
> 
>    Using  git commit -a""
>           If you intend that your next commit should record...
>    ...
>    Using  git add -A""
>           When accepting a new code drop for a vendor branch
> 
> Note the funny double-space and the weird "" at the end. I get the same
> thing from "git show origin/man:man1/git-rm.1 | nroff -man".
> 
> The source looks like this:
> 
>   $ git grep -A1 Using..git.commit git-rm.txt
>   git-rm.txt:Using "git commit -a"
>   git-rm.txt-~~~~~~~~~~~~~~~~~~~~~
> 
> which looks sane to me. The generated xml also looks OK to me:
> 
>   $ grep Using..git.commit git-rm.xml
>   <title>Using "git commit -a"</title>
> 
> But the resulting roff doesn't:
> 
>   $ grep Using..git.commit git-rm.1
>   .SS "Using "git commit \-a""
> 
> which looks like a quoting error to me, which implies a bug in docbook.
> 
> I guess we can hack around it with some XSL magic, but I am tempted to
> do the simple:
> 
> diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt
> index 71e3d9f..8ee559b 100644
> --- a/Documentation/git-rm.txt
> +++ b/Documentation/git-rm.txt
> @@ -89,8 +89,8 @@ the paths that have disappeared from the filesystem. However,
>  depending on the use case, there are several ways that can be
>  done.
>  
> -Using "git commit -a"
> -~~~~~~~~~~~~~~~~~~~~~
> +Using git commit -a
> +~~~~~~~~~~~~~~~~~~~
>  If you intend that your next commit should record all modifications
>  of tracked files in the working tree and record all removals of
>  files that have been removed from the working tree with `rm`
> @@ -98,8 +98,8 @@ files that have been removed from the working tree with `rm`
>  automatically notice and record all removals.  You can also have a
>  similar effect without committing by using `git add -u`.
>  
> -Using "git add -A"
> -~~~~~~~~~~~~~~~~~~
> +Using git add -A
> +~~~~~~~~~~~~~~~~
>  When accepting a new code drop for a vendor branch, you probably
>  want to record both the removal of paths and additions of new paths
>  as well as modifications of existing paths.
> 
> -Peff
Couple'o'things goin' on here ;)

First of all, we shouldn't use a literal " to denote a "quotation". Just like in HTML, this may or may not work. Typographically, the outcome was *always* wrong. The proper way in asciidoc is surrounding the ``quotation'' by double backticks and double ticks. Doing it right in git-rm.txt will lead to proper nroff and html outputs, e.g.:

Using “git commit -a”

Of course, literal " works in most place - well, save the fact that it never really works because it never produces typographically correct output. Am I repeating myself? ;)

Here, a literal " in asciidoc ends up as a literal " in html and xml. Any browser groks it in a place like that, producing correct output - well, save the fact that...

docbook (translating xml to nroff) does not grok it. Now that is a surprise... Pleeease, someone get me straight asciidoc to nroff!

On a side note, looking at origin/man I get the impression that these subheaders were always wrong.

So, in summary, we should really ``quote'' things properly, but this would need to be done consistently, because a mix of new (typographhically correct) quotes and old ones looks even worse. If we really want to go that route I'd volunteer to do things one by one. Actually, it seems we've been partially going that route already, using {tilde}, {apostrophe} etc.

Michael
Michael J Gruber· Dec 7, 2010, 09:07 UTC · re: Michael J Gruber · lore

[PATCH] git-rm.txt: Fix quoting

Literal " produces typographically incorrect quotations, but "works" in most circumstances. In the subheadings of git-rm.txt, it "works" for the html backend but not for the docbook conversion to nroff: double "" and spurious double spaces appear in the output.

Replace "incorrect" quotations by ``correct'' ones, and fix other "quotations" which are really `code fragments`.

This should make git-rm.txt "-clean.
Reported-by: Jeff King <peff@peff.net>
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
We still have a lingering inconsistency for denoting code fragments.
Single backticks merely are a literal monospaced environment; html outputcolors
this, nroff does not indicate it at all. I'm staying consistent with the
surrounding text here.
 Documentation/git-rm.txt |    8 ++++----
 1 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt
index 71e3d9f..dd61ebd 100644
--- a/Documentation/git-rm.txt
+++ b/Documentation/git-rm.txt
@@ -89,7 +89,7 @@ the paths that have disappeared from the filesystem. However,
 depending on the use case, there are several ways that can be
 done.
 
-Using "git commit -a"
+Using ``git commit -a''
 ~~~~~~~~~~~~~~~~~~~~~
 If you intend that your next commit should record all modifications
 of tracked files in the working tree and record all removals of
@@ -98,7 +98,7 @@ files that have been removed from the working tree with `rm`
 automatically notice and record all removals.  You can also have a
 similar effect without committing by using `git add -u`.
 
-Using "git add -A"
+Using ``git add -A''
 ~~~~~~~~~~~~~~~~~~
 When accepting a new code drop for a vendor branch, you probably
 want to record both the removal of paths and additions of new paths
@@ -111,8 +111,8 @@ tree using this command:
 git ls-files -z | xargs -0 rm -f
 ----------------
 
-and then "untar" the new code in the working tree. Alternately
-you could "rsync" the changes into the working tree.
+and then `untar` the new code in the working tree. Alternately
+you could `rsync` the changes into the working tree.
 
 After that, the easiest way to record all removals, additions, and
 modifications in the working tree is:

-- 
1.7.3.2.660.g7cc83
Jeff King· Dec 7, 2010, 16:43 UTC · re: Michael J Gruber · lore

Re: [PATCH] git-rm.txt: Fix quoting

On Tue, Dec 07, 2010 at 10:07:11AM +0100, Michael J Gruber wrote:
Show 9 quoted lines
> Literal " produces typographically incorrect quotations, but "works" in
> most circumstances. In the subheadings of git-rm.txt, it "works" for the
> html backend but not for the docbook conversion to nroff: double "" and
> spurious double spaces appear in the output.
> 
> Replace "incorrect" quotations by ``correct'' ones, and fix other
> "quotations" which are really `code fragments`.
> 
> This should make git-rm.txt "-clean.
Thanks, this is a much better solution than what I posted earlier.
Acked-by: Jeff King <peff@peff.net>
> We still have a lingering inconsistency for denoting code fragments.
> Single backticks merely are a literal monospaced environment; html outputcolors
> this, nroff does not indicate it at all. I'm staying consistent with the
> surrounding text here.
Try setting MAN_BOLD_LITERAL in your config.mak.
-Peff
Michael J Gruber· Dec 8, 2010, 08:08 UTC · re: Jeff King · lore

Re: [PATCH] git-rm.txt: Fix quoting

Jeff King venit, vidit, dixit 07.12.2010 17:43:
Show 22 quoted lines
> On Tue, Dec 07, 2010 at 10:07:11AM +0100, Michael J Gruber wrote:
> 
>> Literal " produces typographically incorrect quotations, but "works" in
>> most circumstances. In the subheadings of git-rm.txt, it "works" for the
>> html backend but not for the docbook conversion to nroff: double "" and
>> spurious double spaces appear in the output.
>>
>> Replace "incorrect" quotations by ``correct'' ones, and fix other
>> "quotations" which are really `code fragments`.
>>
>> This should make git-rm.txt "-clean.
> 
> Thanks, this is a much better solution than what I posted earlier.
> 
> Acked-by: Jeff King <peff@peff.net>
> 
>> We still have a lingering inconsistency for denoting code fragments.
>> Single backticks merely are a literal monospaced environment; html outputcolors
>> this, nroff does not indicate it at all. I'm staying consistent with the
>> surrounding text here.
> 
> Try setting MAN_BOLD_LITERAL in your config.mak.

Always learning something new about our doc tooclchain... and what a great name for an option! Although it should be "Man, bold, literally!".

Michael
Jonathan Nieder· Dec 7, 2010, 17:19 UTC · re: Michael J Gruber · lore

Re: [PATCH] git-rm.txt: Fix quoting

Michael J Gruber wrote:
Show 10 quoted lines
> --- a/Documentation/git-rm.txt
> +++ b/Documentation/git-rm.txt
> @@ -111,8 +111,8 @@ tree using this command:
>  git ls-files -z | xargs -0 rm -f
>  ----------------
>  
> -and then "untar" the new code in the working tree. Alternately
> -you could "rsync" the changes into the working tree.
> +and then `untar` the new code in the working tree. Alternately
> +you could `rsync` the changes into the working tree.
I like the patch.  Is there really an "untar" command?

Maybe something like this on top? ('rsync' is in italics because it is just a command name rather than a full command ready to be typed on the command line.) ---

diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt
index dd61ebd..0adbe8b 100644
--- a/Documentation/git-rm.txt
+++ b/Documentation/git-rm.txt
@@ -90,7 +90,7 @@ depending on the use case, there are several ways that can be
 done.
 
 Using ``git commit -a''
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~
 If you intend that your next commit should record all modifications
 of tracked files in the working tree and record all removals of
 files that have been removed from the working tree with `rm`
@@ -99,7 +99,7 @@ automatically notice and record all removals.  You can also have a
 similar effect without committing by using `git add -u`.
 
 Using ``git add -A''
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~
 When accepting a new code drop for a vendor branch, you probably
 want to record both the removal of paths and additions of new paths
 as well as modifications of existing paths.
@@ -111,8 +111,8 @@ tree using this command:
 git ls-files -z | xargs -0 rm -f
 ----------------
 
-and then `untar` the new code in the working tree. Alternately
-you could `rsync` the changes into the working tree.
+and then untar the new code in the working tree. Alternately
+you could 'rsync' the changes into the working tree.
 
 After that, the easiest way to record all removals, additions, and
 modifications in the working tree is:
Jeff King· Dec 7, 2010, 17:25 UTC · re: Jonathan Nieder · lore

Re: [PATCH] git-rm.txt: Fix quoting

On Tue, Dec 07, 2010 at 11:19:39AM -0600, Jonathan Nieder wrote:
Show 14 quoted lines
> Michael J Gruber wrote:
> 
> > --- a/Documentation/git-rm.txt
> > +++ b/Documentation/git-rm.txt
> > @@ -111,8 +111,8 @@ tree using this command:
> >  git ls-files -z | xargs -0 rm -f
> >  ----------------
> >  
> > -and then "untar" the new code in the working tree. Alternately
> > -you could "rsync" the changes into the working tree.
> > +and then `untar` the new code in the working tree. Alternately
> > +you could `rsync` the changes into the working tree.
> 
> I like the patch.  Is there really an "untar" command?

Heh. Yeah, I was so caught up in looking at formatting that I didn't think about the actual meaning. :) Untar should definitely not be a literal (and should not have been quoted in the first place).

> Maybe something like this on top?  ('rsync' is in italics because it
> is just a command name rather than a full command ready to be typed on
> the command line.)
No opinion on that from me.
>  Using ``git commit -a''
> -~~~~~~~~~~~~~~~~~~~~~
> +~~~~~~~~~~~~~~~~~~~~~~~

I think this length doesn't have to match the text above, but I agree it looks better to viewers of the source if it does.

-Peff
Michael J Gruber· Dec 8, 2010, 11:15 UTC · re: Jeff King · lore

[PATCHv2] git-rm.txt: Fix quoting

Literal " produces typographically incorrect quotations, but "works" in most circumstances. In the subheadings of git-rm.txt, it "works" for the html backend but not for the docbook conversion to nroff: double "" and spurious double spaces appear in the output.

Replace "incorrect" quotations by ``correct'' ones, and fix other "quotations" which are really 'command names' resp. plain words.

This should make git-rm.txt "-clean.
Reported-by: Jeff King <peff@peff.net>
Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
While we don't need to match the underlines to the header's length, it
looks nicer. So v2 incorporates this and the other changes:
- untar is not a command on proper OSs
- rsync is not a complete command line (implicit style guide...)
 Documentation/git-rm.txt |   12 ++++++------
 1 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt
index 71e3d9f..0adbe8b 100644
--- a/Documentation/git-rm.txt
+++ b/Documentation/git-rm.txt
@@ -89,8 +89,8 @@ the paths that have disappeared from the filesystem. However,
 depending on the use case, there are several ways that can be
 done.
 
-Using "git commit -a"
-~~~~~~~~~~~~~~~~~~~~~
+Using ``git commit -a''
+~~~~~~~~~~~~~~~~~~~~~~~
 If you intend that your next commit should record all modifications
 of tracked files in the working tree and record all removals of
 files that have been removed from the working tree with `rm`
@@ -98,8 +98,8 @@ files that have been removed from the working tree with `rm`
 automatically notice and record all removals.  You can also have a
 similar effect without committing by using `git add -u`.
 
-Using "git add -A"
-~~~~~~~~~~~~~~~~~~
+Using ``git add -A''
+~~~~~~~~~~~~~~~~~~~~
 When accepting a new code drop for a vendor branch, you probably
 want to record both the removal of paths and additions of new paths
 as well as modifications of existing paths.
@@ -111,8 +111,8 @@ tree using this command:
 git ls-files -z | xargs -0 rm -f
 ----------------
 
-and then "untar" the new code in the working tree. Alternately
-you could "rsync" the changes into the working tree.
+and then untar the new code in the working tree. Alternately
+you could 'rsync' the changes into the working tree.
 
 After that, the easiest way to record all removals, additions, and
 modifications in the working tree is:

-- 
1.7.3.2.662.g6fd5b8.dirty
Junio C Hamano· Dec 7, 2010, 19:12 UTC · re: Michael J Gruber · lore

Re: [PATCH] git-rm.txt: Fix quoting

Michael J Gruber <git@drmicha.warpmail.net> writes:
> -Using "git commit -a"
> +Using ``git commit -a''
>  ~~~~~~~~~~~~~~~~~~~~~

Can you keep the length of the underline the same here, or do you need to extend it?

← back to recent threads