Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Nov 20, 2013, 01:24 UTC
Message-ID: <20131120012453.GD4212@google.com>
In-Reply-To: <CAEjxke-C1H1NpD=Hmiz6MO3OjtPvkUktKvF7zSqfGnruHQ9-Ew@mail.gmail.com>

Jason St. John wrote:

> On Tue, Nov 19, 2013 at 7:31 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
>> Jason St. John wrote:

Show 7 quoted lines

>>> Documentation/git-rebase.txt: add a blank line after the two AsciiDoc
>>>     listing blocks
>>
>> I'd leave out the above two description lines, since they're redundant
>> next to the patch text.
>
> I included that because SubmittingPatches says to do so.

Thanks for explaining. Can you point me to which part of SubmittingPatches said to include that kind of thing?

[...]

> How do you recommend I proceed? Should I resubmit with just a revised
> commit message? Should I incorporate this into a larger patch set that
> should fix all of the errors in git-rebase.txt, git-svn.txt, and
> gitweb.txt?

Thanks for checking.  You have a few choices.

 a) Check if asciidoctor reproduces the problem, and if so, report it
    as a compatibility bug.  Ask the gitscm-next maintainers to get
    their copy of asciidoctor up to date.

 b) Come up with a simple rule about how these "----" blocks should be
    formatted, and apply it consistently to the documentation in
    Documentation/, with a commit message explaining the story so
    future contributors know to continue to follow it.

 c) Resend the same patch that just fixes git-rebase.txt.  Include a
    Reported-by line to credit the person who originally caught the
    error.  Explain what's going on in the commit message and that
    there are other instances of the problem that this patch doesn't
    yet fix.

I prefer (b), since it would solve the problem more completely and means future readers wouldn't be confused about which style to use, but other possibilities (e.g., some combination of the options listed above, or something else entirely) could work as well.

Thanks again for tracking this down, and hope that helps, Jonathan