Minor man page weirdness?

Minor man page weirdness?

[Lars Schneider]

Hi,

I just noticed that a space between "-f" and "git" is missing in `man git-branch`.
The space is present in "Documentation/git-branch.txt", though. I am using `man`
version 1.6c on macOS.

-f, --force
           Reset <branchname> to <startpoint> if <branchname> exists already. Without
           -fgit branch refuses to change an existing branch. In combination with -d (or
            ^^

Can you reproduce the "problem"?

Cheers,
Lars

Re: Minor man page weirdness?

[Jeff King]

On Mon, Oct 16, 2017 at 07:16:49AM -0700, Lars Schneider wrote:

> Hi,
> 
> I just noticed that a space between "-f" and "git" is missing in `man git-branch`.
> The space is present in "Documentation/git-branch.txt", though. I am using `man`
> version 1.6c on macOS.
> 
> -f, --force
>            Reset <branchname> to <startpoint> if <branchname> exists already. Without
>            -fgit branch refuses to change an existing branch. In combination with -d (or
>             ^^
> 
> Can you reproduce the "problem"?

I don't see it on my copy (Debian man-db 2.7.6.1-2) . What does:

  cd Documentation
  make git-branch.1
  grep Without git-branch.xml

show? I see:

  ... <literal>-f</literal> <emphasis>git branch</emphasis> ...

If there's no space there, then the problem is in asciidoc. If not, then
we can further check:

  grep -A3 Without git-branch.1

I get:

  Reset <branchname> to <startpoint> if <branchname> exists already\&. Without
  \fB\-f\fR
  \fIgit branch\fR
  refuses to change an existing branch\&. In combination with

Since there's no space there, I think we're relying on roff to insert
one between lines. I'm not familiar enough with roff to say if that's a
reasonable expectation or not. But if the problem is at this level, it's
actually an issue between docbook and roff, and there's probably not a
lot we can do on the Git side.

We do have some hacks/workarounds for broken versions of the toolchain.
You can try tweaking various knobs you find in Documentation/Makefile).
DOCBOOK_SUPPRESS_SP sounds promising, but I think it actually does the
opposite (removes extra spaces).

-Peff

Re: Minor man page weirdness?

[Andreas Schwab]

On Okt 16 2017, Jeff King <peff@peff.net> wrote:

> I get:
>
>   Reset <branchname> to <startpoint> if <branchname> exists already\&. Without
>   \fB\-f\fR
>   \fIgit branch\fR
>   refuses to change an existing branch\&. In combination with

I see this in git-branch.1:

  Reset <branchname> to <startpoint> if <branchname> exists already\&. Without
  \fB\-f\fR\fIgit branch\fR
  refuses to change an existing branch\&. In combination with

This is with asciidoc 8.6.9.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Minor man page weirdness?

[Jeff King]

On Tue, Oct 17, 2017 at 06:29:59PM +0200, Andreas Schwab wrote:

> On Okt 16 2017, Jeff King <peff@peff.net> wrote:
> 
> > I get:
> >
> >   Reset <branchname> to <startpoint> if <branchname> exists already\&. Without
> >   \fB\-f\fR
> >   \fIgit branch\fR
> >   refuses to change an existing branch\&. In combination with
> 
> I see this in git-branch.1:
> 
>   Reset <branchname> to <startpoint> if <branchname> exists already\&. Without
>   \fB\-f\fR\fIgit branch\fR
>   refuses to change an existing branch\&. In combination with
> 
> This is with asciidoc 8.6.9.

Thanks, that seems a likely culprit, then. What's in your git-branch.xml
after you build the documentation?

-Peff

Re: Minor man page weirdness?

[Andreas Schwab]

On Okt 17 2017, Jeff King <peff@peff.net> wrote:

> On Tue, Oct 17, 2017 at 06:29:59PM +0200, Andreas Schwab wrote:
>
>> On Okt 16 2017, Jeff King <peff@peff.net> wrote:
>> 
>> > I get:
>> >
>> >   Reset <branchname> to <startpoint> if <branchname> exists already\&. Without
>> >   \fB\-f\fR
>> >   \fIgit branch\fR
>> >   refuses to change an existing branch\&. In combination with
>> 
>> I see this in git-branch.1:
>> 
>>   Reset <branchname> to <startpoint> if <branchname> exists already\&. Without
>>   \fB\-f\fR\fIgit branch\fR
>>   refuses to change an existing branch\&. In combination with
>> 
>> This is with asciidoc 8.6.9.
>
> Thanks, that seems a likely culprit, then. What's in your git-branch.xml
> after you build the documentation?

Same as yours, with the space.  I'd guess it's rather xmlto (version
0.0.25) that's the culprit here.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Minor man page weirdness?

[Jeff King]

On Tue, Oct 17, 2017 at 07:25:28PM +0200, Andreas Schwab wrote:

> >> I see this in git-branch.1:
> >> 
> >>   Reset <branchname> to <startpoint> if <branchname> exists already\&. Without
> >>   \fB\-f\fR\fIgit branch\fR
> >>   refuses to change an existing branch\&. In combination with
> >> 
> >> This is with asciidoc 8.6.9.
> >
> > Thanks, that seems a likely culprit, then. What's in your git-branch.xml
> > after you build the documentation?
> 
> Same as yours, with the space.  I'd guess it's rather xmlto (version
> 0.0.25) that's the culprit here.

Yes, it's in that step, but xmlto is just driving the xslt
transformation done by docbook. So the interesting version is probably
docbook. I have docbook-xsl 1.79.1+dfsg-2 (from Debian unstable).

-Peff

Re: Minor man page weirdness?

[Andreas Schwab]

On Okt 17 2017, Jeff King <peff@peff.net> wrote:

> On Tue, Oct 17, 2017 at 07:25:28PM +0200, Andreas Schwab wrote:
>
>> >> I see this in git-branch.1:
>> >> 
>> >>   Reset <branchname> to <startpoint> if <branchname> exists already\&. Without
>> >>   \fB\-f\fR\fIgit branch\fR
>> >>   refuses to change an existing branch\&. In combination with
>> >> 
>> >> This is with asciidoc 8.6.9.
>> >
>> > Thanks, that seems a likely culprit, then. What's in your git-branch.xml
>> > after you build the documentation?
>> 
>> Same as yours, with the space.  I'd guess it's rather xmlto (version
>> 0.0.25) that's the culprit here.
>
> Yes, it's in that step, but xmlto is just driving the xslt
> transformation done by docbook. So the interesting version is probably
> docbook. I have docbook-xsl 1.79.1+dfsg-2 (from Debian unstable).

docbook-xsl-stylesheets-1.78.1+svn9743

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Minor man page weirdness?

[Andreas Schwab]

On Okt 16 2017, Jeff King <peff@peff.net> wrote:

> We do have some hacks/workarounds for broken versions of the toolchain.
> You can try tweaking various knobs you find in Documentation/Makefile).
> DOCBOOK_SUPPRESS_SP sounds promising, but I think it actually does the
> opposite (removes extra spaces).

An easy workaround would be to add a comma between `-f` and 'git
branch'.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Minor man page weirdness?

[Jeff King]

On Tue, Oct 17, 2017 at 07:52:03PM +0200, Andreas Schwab wrote:

> > Yes, it's in that step, but xmlto is just driving the xslt
> > transformation done by docbook. So the interesting version is probably
> > docbook. I have docbook-xsl 1.79.1+dfsg-2 (from Debian unstable).
> 
> docbook-xsl-stylesheets-1.78.1+svn9743

Hmm. That could be it, though I was unable to bisect on the docbook repo
since I couldn't get their build to work reliably.

One other thing to try:

  rm git-branch.1
  make NO_MAN_BOLD_LITERAL=1 git-branch.1

It's possible our snippet to add in the bolding causes problems.

-Peff

Re: Minor man page weirdness?

[Andreas Schwab]

On Okt 17 2017, Jeff King <peff@peff.net> wrote:

> One other thing to try:
>
>   rm git-branch.1
>   make NO_MAN_BOLD_LITERAL=1 git-branch.1

That doesn't help:

   Reset <branchname> to <startpoint> if <branchname> exists already\&. Without
   \-f\fIgit branch\fR
   refuses to change an existing branch\&. In combination with

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Minor man page weirdness?

[Junio C Hamano]

Andreas Schwab <schwab@linux-m68k.org> writes:

> On Okt 16 2017, Jeff King <peff@peff.net> wrote:
>
>> We do have some hacks/workarounds for broken versions of the toolchain.
>> You can try tweaking various knobs you find in Documentation/Makefile).
>> DOCBOOK_SUPPRESS_SP sounds promising, but I think it actually does the
>> opposite (removes extra spaces).
>
> An easy workaround would be to add a comma between `-f` and 'git
> branch'.

That sounds like a good idea, regardless of the mark-up issue.

Re: Minor man page weirdness?

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Andreas Schwab <schwab@linux-m68k.org> writes:
>
>> On Okt 16 2017, Jeff King <peff@peff.net> wrote:
>>
>>> We do have some hacks/workarounds for broken versions of the toolchain.
>>> You can try tweaking various knobs you find in Documentation/Makefile).
>>> DOCBOOK_SUPPRESS_SP sounds promising, but I think it actually does the
>>> opposite (removes extra spaces).
>>
>> An easy workaround would be to add a comma between `-f` and 'git
>> branch'.
>
> That sounds like a good idea, regardless of the mark-up issue.

-- >8 --
branch doc: sprinkle a few commas for readability

The "--force" option can also be used when the named branch does not
yet exist, and the point of the option is the user can (re)point the
branch to the named commit even if it does.  Add 'even' before 'if'
to clarify.  Also, insert another comma after "Without -f" before
"the command refuses..." to make the text easier to parse.

Incidentally, this change should help certain versions of
docbook-xsl-stylesheets that renders the original without any
whitespace between "-f" and "git".

Noticed-by: Lars Schneider <larsxschneider@gmail.com>
Helped-by: Jeff King <peff@peff.net>
Helped-by: Andreas Schwab <schwab@suse.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-branch.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index fe029ac6fc..d6587c5e96 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -104,8 +104,8 @@ OPTIONS
 
 -f::
 --force::
-	Reset <branchname> to <startpoint> if <branchname> exists
-	already. Without `-f` 'git branch' refuses to change an existing branch.
+	Reset <branchname> to <startpoint>, even if <branchname> exists
+	already. Without `-f`, 'git branch' refuses to change an existing branch.
 	In combination with `-d` (or `--delete`), allow deleting the
 	branch irrespective of its merged status. In combination with
 	`-m` (or `--move`), allow renaming the branch even if the new

Re: Minor man page weirdness?

[Jeff King]

On Wed, Oct 18, 2017 at 11:34:31AM +0900, Junio C Hamano wrote:

> -- >8 --
> branch doc: sprinkle a few commas for readability
> 
> The "--force" option can also be used when the named branch does not
> yet exist, and the point of the option is the user can (re)point the
> branch to the named commit even if it does.  Add 'even' before 'if'
> to clarify.  Also, insert another comma after "Without -f" before
> "the command refuses..." to make the text easier to parse.
> 
> Incidentally, this change should help certain versions of
> docbook-xsl-stylesheets that renders the original without any
> whitespace between "-f" and "git".

Thanks, this looks good.

It does make me wonder if there are other instances of the missing-space
problem lurking. Grepping for backtick followed by single-quote shows
only one more case in user-manual.txt. I have no idea if that one hits
the same problem on older docbook versions. Or if it's a problem for any
other punctuation combinations. I'm happy to punt on it until somebody
with an affected docbook produces more bug reports. :)

-Peff

Re: Minor man page weirdness?

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> It does make me wonder if there are other instances of the missing-space
> problem lurking. Grepping for backtick followed by single-quote shows
> only one more case in user-manual.txt. I have no idea if that one hits
> the same problem on older docbook versions.

I had an impression that this is only for roff, but we do not
produce user-manual.[0-9], do we?

> Or if it's a problem for any
> other punctuation combinations. I'm happy to punt on it until somebody
> with an affected docbook produces more bug reports. :)

Yup, we cannot _fix_ what we do not know are broken ;-)

Thanks.

Re: Minor man page weirdness?

[Jeff King]

On Wed, Oct 18, 2017 at 12:41:03PM +0900, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > It does make me wonder if there are other instances of the missing-space
> > problem lurking. Grepping for backtick followed by single-quote shows
> > only one more case in user-manual.txt. I have no idea if that one hits
> > the same problem on older docbook versions.
> 
> I had an impression that this is only for roff, but we do not
> produce user-manual.[0-9], do we?

Yeah, I think you're right. We do produce XML of it, but it goes to
other formats like texi and pdf (and if this is a docbook bug, it may or
may not be present in those other output formats).

-Peff

Re: Minor man page weirdness?

[Lars Schneider]

> On 18 Oct 2017, at 05:21, Jeff King <peff@peff.net> wrote:
> 
> On Wed, Oct 18, 2017 at 11:34:31AM +0900, Junio C Hamano wrote:
> 
>> -- >8 --
>> branch doc: sprinkle a few commas for readability
>> 
>> The "--force" option can also be used when the named branch does not
>> yet exist, and the point of the option is the user can (re)point the
>> branch to the named commit even if it does.  Add 'even' before 'if'
>> to clarify.  Also, insert another comma after "Without -f" before
>> "the command refuses..." to make the text easier to parse.
>> 
>> Incidentally, this change should help certain versions of
>> docbook-xsl-stylesheets that renders the original without any
>> whitespace between "-f" and "git".
> 
> Thanks, this looks good.

To me, too! Thanks for investigating and fixing the issue :-)

- Lars