Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
"Kyle J. McKay" 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. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
On Jan 14, 2014, at 21:36, Jason St. John wrote: On Mon, Jan 13, 2014 at 12:55 PM, Junio C Hamano wrote: "Jason St. John" 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..* 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://u...@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://u...@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..* 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://u...@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://u...@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://
Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
On Mon, Jan 13, 2014 at 12:55 PM, Junio C Hamano wrote: > "Jason St. John" 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
"Jason St. John" 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. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
On Tue, Nov 19, 2013 at 11:43 PM, Junio C Hamano wrote: > "Jason St. John" 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 >> --- >> 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
"Jason St. John" 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 > --- > 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? -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
Jason St. John wrote: > On Tue, Nov 19, 2013 at 7:31 PM, Jonathan Nieder 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
On Tue, Nov 19, 2013 at 7:31 PM, Jonathan Nieder 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)
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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
