* [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
@ 2013-11-20 0:14 Jason St. John
2013-11-20 0:31 ` Jonathan Nieder
2013-11-20 4:43 ` Junio C Hamano
0 siblings, 2 replies; 10+ messages in thread
From: Jason St. John @ 2013-11-20 0:14 UTC (permalink / raw)
To: git; +Cc: Jason St. John
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 <jstjohn@purdue.edu>
---
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
^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
2013-11-20 0:14 [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version) Jason St. John
@ 2013-11-20 0:31 ` Jonathan Nieder
2013-11-20 1:12 ` Jason St. John
2013-11-20 4:43 ` Junio C Hamano
1 sibling, 1 reply; 10+ messages in thread
From: Jonathan Nieder @ 2013-11-20 0:31 UTC (permalink / raw)
To: Jason St. John; +Cc: git
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
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
2013-11-20 0:31 ` Jonathan Nieder
@ 2013-11-20 1:12 ` Jason St. John
2013-11-20 1:24 ` Jonathan Nieder
0 siblings, 1 reply; 10+ messages in thread
From: Jason St. John @ 2013-11-20 1:12 UTC (permalink / raw)
To: Jonathan Nieder; +Cc: git
On Tue, Nov 19, 2013 at 7:31 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> 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.
>
I included that because SubmittingPatches says to do so.
>> 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
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
2013-11-20 1:12 ` Jason St. John
@ 2013-11-20 1:24 ` Jonathan Nieder
0 siblings, 0 replies; 10+ messages in thread
From: Jonathan Nieder @ 2013-11-20 1:24 UTC (permalink / raw)
To: Jason St. John; +Cc: git
Jason St. John wrote:
> On Tue, Nov 19, 2013 at 7:31 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
>> 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.
>
> 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
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
2013-11-20 0:14 [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version) Jason St. John
2013-11-20 0:31 ` Jonathan Nieder
@ 2013-11-20 4:43 ` Junio C Hamano
2014-01-11 1:25 ` Jason St. John
1 sibling, 1 reply; 10+ messages in thread
From: Junio C Hamano @ 2013-11-20 4:43 UTC (permalink / raw)
To: Jason St. John; +Cc: git
"Jason St. John" <jstjohn@purdue.edu> writes:
> Documentation/git-rebase.txt: add a blank line after the two AsciiDoc
> listing blocks
That looks funnily formatted, out of place and redundant.
> 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 <jstjohn@purdue.edu>
> ---
> You can see the carnage here:
> http://git-scm.com/docs/git-rebase#_bugs
>
> This fixes GitHub issue github/gitscm-next#281
Hmph. https://git-htmldocs.googlecode.com/git/git.html has HTML
documentation pages I preformat, but as far as I can see, the bugs
section of git-rebase(1) does not have such a "carnage".
Perhaps git-scm.com uses some buggy formatter?
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
2013-11-20 4:43 ` Junio C Hamano
@ 2014-01-11 1:25 ` Jason St. John
2014-01-13 17:55 ` Junio C Hamano
0 siblings, 1 reply; 10+ messages in thread
From: Jason St. John @ 2014-01-11 1:25 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git
On Tue, Nov 19, 2013 at 11:43 PM, Junio C Hamano <gitster@pobox.com> wrote:
> "Jason St. John" <jstjohn@purdue.edu> writes:
>
>> Documentation/git-rebase.txt: add a blank line after the two AsciiDoc
>> listing blocks
>
> That looks funnily formatted, out of place and redundant.
>
>> 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 <jstjohn@purdue.edu>
>> ---
>> You can see the carnage here:
>> http://git-scm.com/docs/git-rebase#_bugs
>>
>> This fixes GitHub issue github/gitscm-next#281
>
> Hmph. https://git-htmldocs.googlecode.com/git/git.html has HTML
> documentation pages I preformat, but as far as I can see, the bugs
> section of git-rebase(1) does not have such a "carnage".
>
> Perhaps git-scm.com uses some buggy formatter?
This does seem to be an issue with git-scm.com only, so this is
probably an issue with the AsciiDoc formatter they use.
What AsciiDoc formatter (and version) do you use?
Sorry for the long delay in replying!
Jason
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
2014-01-11 1:25 ` Jason St. John
@ 2014-01-13 17:55 ` Junio C Hamano
2014-01-15 5:36 ` Jason St. John
0 siblings, 1 reply; 10+ messages in thread
From: Junio C Hamano @ 2014-01-13 17:55 UTC (permalink / raw)
To: Jason St. John; +Cc: git
"Jason St. John" <jstjohn@purdue.edu> writes:
> What AsciiDoc formatter (and version) do you use?
$ asciidoc --version
asciidoc 8.6.8
Checking with www.methods.co.nz/asciidoc, I am behind by about 2
months, it seems, though.
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
2014-01-13 17:55 ` Junio C Hamano
@ 2014-01-15 5:36 ` Jason St. John
2014-01-15 11:29 ` Kyle J. McKay
0 siblings, 1 reply; 10+ messages in thread
From: Jason St. John @ 2014-01-15 5:36 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git
On Mon, Jan 13, 2014 at 12:55 PM, Junio C Hamano <gitster@pobox.com> wrote:
> "Jason St. John" <jstjohn@purdue.edu> writes:
>
>> What AsciiDoc formatter (and version) do you use?
>
> $ asciidoc --version
> asciidoc 8.6.8
>
> Checking with www.methods.co.nz/asciidoc, I am behind by about 2
> months, it seems, though.
I just went through git-scm.com's GitHub issue tracker, and I found
that git-scm.com is, in fact, using their own AsciiDoc parser[1].
This issue, along with the other formatting issues found in
git-svn.txt and gitweb.txt, will hopefully be resolved soon, as one of
the GitHub maintainers opened an issue to update their AsciiDoc
parser[2].
[1] https://github.com/git/git-scm.com/issues/134#issuecomment-27539970
[2] https://github.com/git/git-scm.com/issues/350
Jason
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
2014-01-15 5:36 ` Jason St. John
@ 2014-01-15 11:29 ` Kyle J. McKay
2014-01-16 0:29 ` Junio C Hamano
0 siblings, 1 reply; 10+ messages in thread
From: Kyle J. McKay @ 2014-01-15 11:29 UTC (permalink / raw)
To: Jason St. John, Junio C Hamano; +Cc: Git Mailing List
On Jan 14, 2014, at 21:36, Jason St. John wrote:
> On Mon, Jan 13, 2014 at 12:55 PM, Junio C Hamano <gitster@pobox.com>
> wrote:
>> "Jason St. John" <jstjohn@purdue.edu> writes:
>>
>>> What AsciiDoc formatter (and version) do you use?
>>
>> $ asciidoc --version
>> asciidoc 8.6.8
>>
>> Checking with www.methods.co.nz/asciidoc, I am behind by about 2
>> months, it seems, though.
>
> I just went through git-scm.com's GitHub issue tracker, and I found
> that git-scm.com is, in fact, using their own AsciiDoc parser[1].
>
> This issue, along with the other formatting issues found in
> git-svn.txt and gitweb.txt, will hopefully be resolved soon, as one of
> the GitHub maintainers opened an issue to update their AsciiDoc
> parser[2].
>
> [1] https://github.com/git/git-scm.com/issues/
> 134#issuecomment-27539970
> [2] https://github.com/git/git-scm.com/issues/350
Hmmm. I've also had some problems as well getting a correct man page
build although it's the non-web version. In my case I use the git-
config.1 man page to detect the problem. Uninteresting lines have
been replaced with "[...]" for brevity in the following samples.
Using 'MANWIDTH=65 man -c ./git-config.1' the bad man page has a
section that looks like this:
http.<url>.*
Any of the http.* options above can be applied
selectively to some urls. For a config key to
match a URL, each element of the config key is
compared to that of the URL, in the following
order:
1. Scheme (e.g., https in
https://example.com/). This field must
match exactly between the config key and
the URL.
[...]
5. User name (e.g., user in
https://user@example.com/repo.git). If the
[...]
precedence than a config key with a user
name.
The list above is ordered by decreasing
precedence; a URL that matches a config
[...]
be preferred over a config key match of
https://user@example.com.
All URLs are normalized before attempting
any matching (the password part, if
[...]
any URLs visited as a result of a
redirection do not participate in matching.
i18n.commitEncoding
Character encoding the commit messages are
stored in; Git itself does not care per se,
The rest of the man page continues to be incorrectly indented too far,
but I've omitted it for brevity.
The good output for the same section looks like this:
http.<url>.*
Any of the http.* options above can be applied
selectively to some urls. For a config key to
match a URL, each element of the config key is
compared to that of the URL, in the following
order:
1. Scheme (e.g., https in
https://example.com/). This field must
match exactly between the config key and
the URL.
[...]
5. User name (e.g., user in
https://user@example.com/repo.git). If the
[...]
precedence than a config key with a user
name.
The list above is ordered by decreasing
precedence; a URL that matches a config key's
[...]
preferred over a config key match of
https://user@example.com.
All URLs are normalized before attempting any
matching (the password part, if embedded in the
[...]
URLs visited as a result of a redirection do
not participate in matching.
i18n.commitEncoding
Character encoding the commit messages are
stored in; Git itself does not care per se, but
I have two different systems to build these pages on:
System A:
OS X + Mac Ports
asciidoc --version
asciidoc 8.6.6
xmlto --version
xmlto version 0.0.24
docbook-xsl is 1.75.2_0
produces bad git-config.1
System B:
Ubuntu
asciidoc --version
asciidoc 8.5.2
xmlto --version
xmlto version 0.0.23
docbook-xsl is 1.75.2+dfsg-3
produces good git-config.1
The git-config.1 file is built like so:
1. asciidoc produces git-config.xml from git-config.txt
2. xmlto produces git-config.1 from git-config.xml
System A:
git-config.txt: md5=c63cbafddb1bc3d6c38b6b2941f8cbce
git-config.xml: md5=99c0caa45ec02e8712c346e8842a7ce6
git-config.1: md5=812f8d180ec82c2786b95e986219a5d0
System B:
git-config.txt: md5=c63cbafddb1bc3d6c38b6b2941f8cbce
git-config.xml: md5=99c0caa45ec02e8712c346e8842a7ce6
git-config.1: md5=7298467bedd0225d5edefa8700bc9b2a
So actually the problem here is not the asciidoc step, it's actually
the xmlto step.
And, if I make the following changes to the git-config.1 file produced
on system A:
diff --git git-config.1 git-config-fix.1
--- git-config.1
+++ git-config-fix.1
@@ -3299,7 +3299,7 @@ user
in
https://user@example\&.com/repo\&.git)\&. If the config key
has[...]
.RE
-.RS 4
+.sp
The list above is ordered by decreasing precedence; a URL that
[...]
https://user@example\&.com/foo/bar
a config key match of
@@ -4460,7 +4460,7 @@ normal
all
\- Show also individual files in untracked directories\&.
.RE
-.RS 4
+.sp
If this variable is not specified, it defaults to
\fInormal\fR\&. This variable can be overridden with the [...]
\fBgit-status\fR(1)
Then it will format properly again (and in fact the $googlecode/git-
manpages-*.tar.gz files have the same correct ".sp" instead of ".RS 4"
lines).
Trying xmlto versions 0.0.23 and 0.0.25 on System A still produce the
same wrong output, so while it appears to be the xmlto step that's the
problem, it's not xmlto itself.
After much gnashing of teeth and digging it turns out the problem is
in the docbook-xsl sources. Debian includes a patch file
"8530_manpages_lists_indentation_fix.dpatch" in [1]:
---- BEGIN PATCH ----
#! /bin/sh /usr/share/dpatch/dpatch-run
## 8530_manpages_lists_indentation_fix.dpatch by Daniel Leidert (dale)
<daniel.leidert@wgdd.de>
##
## All lines beginning with `## DP:' are a description of the patch.
## DP: Upstream fix from revision 8530 ( dleidert ):
## DP: Fix two indentation issues: In the first case there is no
corresponding
## DP: .RS macro (Debian #519438, sf.net 2793873). In the second
case an .RS
## DP: instead of the probably intended .sp leads to an indentation
bug
## DP: (Debian #527309, sf.net #2642139).
## DP:
## DP: <URL:http://docbook.svn.sourceforge.net/docbook/?rev=8530&view=rev
>
## DP: <URL:http://sourceforge.net/search/?type_of_search=artifact&group_id=21935&words=2642139
>
## DP: <URL:http://bugs.debian.org/519438>
## DP: <URL:http://bugs.debian.org/527309>
@DPATCH@
diff -urNad trunk~/manpages/lists.xsl trunk/manpages/lists.xsl
--- trunk~/manpages/lists.xsl 2009-03-27 02:25:08.000000000 +0100
+++ trunk/manpages/lists.xsl 2009-11-04 00:54:35.000000000 +0100
@@ -259,8 +259,8 @@
<!-- * it, within the same para, then add a blank line and move -->
<!-- * the left margin back to where it was -->
<xsl:if test="parent::para and following-sibling::node()">
- <xsl:text>.sp </xsl:text>
- <xsl:text>.RE </xsl:text>
+ <xsl:text>.sp</xsl:text>
+ <xsl:text> </xsl:text>
</xsl:if>
</xsl:template>
@@ -280,11 +280,7 @@
parent::para[following-sibling::node()] or
parent::simpara[following-sibling::node()] or
parent::remark[following-sibling::node()]">
- <xsl:text>.RS</xsl:text>
- <xsl:if test="not($list-indent = '')">
- <xsl:text> </xsl:text>
- <xsl:value-of select="$list-indent"/>
- </xsl:if>
+ <xsl:text>.sp</xsl:text>
<xsl:text> </xsl:text>
</xsl:if>
</xsl:template>
---- END PATCH ----
And once I have applied that I suddenly get a correct git-config.1
file on System A. On System A that file is found at:
/opt/local/share/xsl/docbook-xsl/manpages/lists.xsl
and on System B it's found at:
/usr/share/xml/docbook/stylesheet/docbook-xsl/manpages/lists.xsl
So while this is not exactly the same problem you describe, I thought
I'd point out the fix for others and also that the issue can end up
not being in asciidoc at all especially since "System B" produces a
correct git-config.1 file out-of-the-box and is running an asciidoc
version released over four years ago (2009-12-07).
FYI, I did build git-rebase.html on "System B" (with its 4-year-old
asciidoc version 8.5.2) and it looks correct (i.e. it has correct
formatting in the BUGS section).
--Kyle
[1] http://ftp.de.debian.org/debian/pool/main/d/docbook-xsl/docbook-xsl_1.75.2+dfsg-5.diff.gz
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
2014-01-15 11:29 ` Kyle J. McKay
@ 2014-01-16 0:29 ` Junio C Hamano
0 siblings, 0 replies; 10+ messages in thread
From: Junio C Hamano @ 2014-01-16 0:29 UTC (permalink / raw)
To: Kyle J. McKay; +Cc: Jason St. John, Git Mailing List
"Kyle J. McKay" <mackyle@gmail.com> writes:
> in the docbook-xsl sources. Debian includes a patch file
> "8530_manpages_lists_indentation_fix.dpatch" in [1]:
> ...
> And once I have applied that I suddenly get a correct git-config.1
> file on System A.
> ...
> --Kyle
>
> [1] http://ftp.de.debian.org/debian/pool/main/d/docbook-xsl/docbook-xsl_1.75.2+dfsg-5.diff.gz
Thanks for digging and sharing the result for others.
^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2014-01-16 0:29 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-11-20 0:14 [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version) Jason St. John
2013-11-20 0:31 ` Jonathan Nieder
2013-11-20 1:12 ` Jason St. John
2013-11-20 1:24 ` Jonathan Nieder
2013-11-20 4:43 ` Junio C Hamano
2014-01-11 1:25 ` Jason St. John
2014-01-13 17:55 ` Junio C Hamano
2014-01-15 5:36 ` Jason St. John
2014-01-15 11:29 ` Kyle J. McKay
2014-01-16 0:29 ` Junio C Hamano
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.