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

Documentation/git-rebase.txt: add a blank line after the two AsciiDoc
    listing blocks

Without these blank lines, AsciiDoc thinks the opening "-----" is a
section heading and typesets the word "to" as such, which causes
cascading formatting/typesetting issues until the end of the document.

Signed-off-by: Jason St. John <redacted>
---
You can see the carnage here:
http://git-scm.com/docs/git-rebase#_bugs

This fixes GitHub issue github/gitscm-next#281
https://github.com/github/gitscm-next/issues/281


 Documentation/git-rebase.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 94e07fd..88d0afb 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt

@@ -743,9 +743,11 @@ For example, an attempt to rearrange
 1 --- 2 --- 3 --- 4 --- 5
 ------------
 to
+
 ------------
 1 --- 2 --- 4 --- 3 --- 5
 ------------
+
 by moving the "pick 4" line will result in the following history:
 ------------
 	3

-- 
1.8.4.2

Hi,

Jason St. John wrote:

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.

Without these blank lines, AsciiDoc thinks the opening "-----" is a
section heading and typesets the word "to" as such, which causes
cascading formatting/typesetting issues until the end of the document.

Interesting.  Alas, I can't reproduce this.

Are you sure it is AsciiDoc that misinterprets the document, and not,
e.g., the predecessor of asciidoctor in gitscm-next?

Do

  Documentation/git-check-attr.txt
  Documentation/git-commit.txt
  Documentation/git-cvsserver.txt
  Documentation/git-p4.txt
  Documentation/git-svn.txt
  Documentation/gitcli.txt
  Documentation/gitweb.txt
  Documentation/mailmap.txt
  
avoid this problem?

Thanks and hope that helps,
Jonathan

On Tue, Nov 19, 2013 at 7:31 PM, Jonathan Nieder [off-list ref] wrote:

Hi,

Jason St. John wrote:

quoted

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.

quoted

Without these blank lines, AsciiDoc thinks the opening "-----" is a
section heading and typesets the word "to" as such, which causes
cascading formatting/typesetting issues until the end of the document.

Interesting.  Alas, I can't reproduce this.

Are you sure it is AsciiDoc that misinterprets the document, and not,
e.g., the predecessor of asciidoctor in gitscm-next?

I regrettably must admit that I didn't test this before submitting, so
I had presumed that it was AsciiDoc itself.

Do

  Documentation/git-check-attr.txt
  Documentation/git-commit.txt
  Documentation/git-cvsserver.txt
  Documentation/git-p4.txt
  Documentation/git-svn.txt
  Documentation/gitcli.txt
  Documentation/gitweb.txt
  Documentation/mailmap.txt

avoid this problem?

Thanks and hope that helps,
Jonathan

All of the files you referenced appear to render okay except for
git-svn.txt and gitweb.txt.

Documentation/git-svn.txt:
* Commands | fetch | --ignore-paths
* Commands | dcommit | --commit-url
* Commands | dcommit | --mergeinfo
* Commands | reset | --parent
* Caveats (third paragraph)
See http://git-scm.com/docs/git-svn#_commands and
http://git-scm.com/docs/git-svn#_caveats

Documentation/gitweb.txt:
* This cascades from the virtual host config file example until the
Bugs section.
See: http://git-scm.com/docs/gitweb#_webserver_configuration_with_multiple_projects'_root

Based on this and the source files, I suspect the problem lies with,
for example, the predecessor of asciidoctor in gitscm-next.

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,
Jason

Jason St. John wrote:

On Tue, Nov 19, 2013 at 7:31 PM, Jonathan Nieder [off-list ref] wrote:

quoted

Jason St. John wrote:

quoted

quoted

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