Re: Minor man page weirdness?

From: Jeff King <peff@peff.net>
Date: Oct 16, 2017, 22:56 UTC
Message-ID: <20171016225641.x76jwycb7mcpvrw3@sigill.intra.peff.net>
In-Reply-To: <A4E5D8CC-19A7-442A-814C-FD5A46391982@gmail.com>

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

Show 12 quoted lines

> 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