Lars SchneiderHi,
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
Jeff KingRe: Minor man page weirdness?
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
Andreas SchwabRe: Minor man page weirdness?
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."
Jeff KingRe: Minor man page weirdness?
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
Andreas SchwabRe: Minor man page weirdness?
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."
Jeff KingRe: Minor man page weirdness?
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
Andreas SchwabRe: Minor man page weirdness?
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."
Jeff KingRe: Minor man page weirdness?
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
Andreas SchwabRe: Minor man page weirdness?
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."
Andreas SchwabRe: Minor man page weirdness?
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."
Junio C HamanoRe: Minor man page weirdness?
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.
Junio C HamanoRe: Minor man page weirdness?
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
Jeff KingRe: Minor man page weirdness?
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
Junio C HamanoRe: Minor man page weirdness?
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.
Jeff KingRe: Minor man page weirdness?
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
Lars SchneiderRe: Minor man page weirdness?
> 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