asciidoctor-extensions: fix spurious space after linkgit
cover asciidoctor-extensions: fix spurious space after linkgit
Patch 3/3 gets rid of a spurious space which shows up immediately after Asciidoctor has expanded linkgit:foo[bar] if the macro is followed by punctuation such as a comma, period or closing parenthesis.
Patch 2/3 adds a missing dependency to the makefile, so that the docs will actually be rebuilt with that final patch. Patch 1/3 isn't needed for this series, but could help someone in the future, similar to how already having patch 2/3 would have helped me...
Martin Ågren (3):
Documentation/Makefile: add missing xsl dependencies for manpages Documentation/Makefile: add missing dependency on
asciidoctor-extensions
asciidoctor-extensions: fix spurious space after linkgit
Documentation/Makefile | 4 ++-- Documentation/asciidoctor-extensions.rb | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-)
Signature · 1 line
2.21.0
PATCH 1/3 Documentation/Makefile: add missing xsl dependencies for manpages
These stylesheets very rarely change, but when they do, it really helps if the manpages depend on them. We're casting the net a bit too wide here, since we'll only ever use a subset of the stylesheets, but since these files change so rarely, that should be ok. It's better than missing a dependency.
--- Documentation/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/Makefile +1 -1
@@ -354,7 +354,7 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf manpage-base-url.xsl: manpage-base-url.xsl.in $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ -%.1 %.5 %.7 : %.xml manpage-base-url.xsl +%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl) $(QUIET_XMLTO)$(RM) $@ && \ $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
Signature · 1 line
2.21.0
Re: [PATCH 1/3] Documentation/Makefile: add missing xsl dependencies for manpages
Documentation/Makefile $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf · line 354
Quoted 12 lines · Martin Ågren
These stylesheets very rarely change, but when they do, it really helps if the manpages depend on them. We're casting the net a bit too wide here, since we'll only ever use a subset of the stylesheets, but since these files change so rarely, that should be ok. It's better than missing a dependency.
Signed-off-by Martin Ågren <[email protected]>---
Documentation/Makefile +1
-1@@ -354,7 +354,7 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf -%.1 %.5 %.7 : %.xml manpage-base-url.xsl +%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
The wildcard expression also matches the manpage-base-url.xsl mentioned explicitly. Did you intentionally retain the explicit one or was that an oversight?
Re: [PATCH 1/3] Documentation/Makefile: add missing xsl dependencies for manpages
Quoted 8 lines · Eric Sunshine
Quoted 6 lines · Martin Ågren
These stylesheets very rarely change, but when they do, it really helps if the manpages depend on them. We're casting the net a bit too wide here, since we'll only ever use a subset of the stylesheets, but since these files change so rarely, that should be ok. It's better than missing a dependency.
Quoted 10 lines
Documentation/Makefile $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf · line 354
Quoted 6 lines
Signed-off-by Martin Ågren <[email protected]>---
Documentation/Makefile +1
-1@@ -354,7 +354,7 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf -%.1 %.5 %.7 : %.xml manpage-base-url.xsl +%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)The wildcard expression also matches the manpage-base-url.xsl mentioned explicitly. Did you intentionally retain the explicit one or was that an oversight?
Hmm, I should have mentioned that, thanks for asking for clarification.
It's intentional. You can see in the context how manpage-base-url.xsl is actually generated, so the wildcard won't be able to expand to mention it. That's subtle enough that it warrants being mentioned upfront.
Martin
Re: [PATCH 1/3] Documentation/Makefile: add missing xsl dependencies for manpages
Quoted 9 lines · Martin Ågren
Quoted 7 lines · Eric Sunshine
Quoted 2 lines · Martin Ågren
-%.1 %.5 %.7 : %.xml manpage-base-url.xsl
+%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)The wildcard expression also matches the manpage-base-url.xsl mentioned explicitly. Did you intentionally retain the explicit one or was that an oversight?
Quoted 5 lines
Hmm, I should have mentioned that, thanks for asking for clarification.
It's intentional. You can see in the context how manpage-base-url.xsl is actually generated, so the wildcard won't be able to expand to mention it. That's subtle enough that it warrants being mentioned upfront.
I guess I was further confused by the fact that manpage-base-url.xsl is still present even after "make distclean", which is not something I would have expected for a generated file. (Perhaps something to consider "fixing" if you re-roll, or not if it's out of scope.)
Re: [PATCH 1/3] Documentation/Makefile: add missing xsl dependencies for manpages
Quoted 8 lines · Eric Sunshine
Quoted 6 lines · Martin Ågren
Quoted 4 lines · Eric Sunshine
The wildcard expression also matches the manpage-base-url.xsl mentioned explicitly. Did you intentionally retain the explicit one or was that an oversight?
Quoted 8 lines
Quoted 3 lines
Hmm, I should have mentioned that, thanks for asking for clarification.
It's intentional.
I guess I was further confused by the fact that manpage-base-url.xsl is still present even after "make distclean", which is not something I would have expected for a generated file. (Perhaps something to consider "fixing" if you re-roll, or not if it's out of scope.)
Are you sure? make distclean in the top directory depends on the "clean" target, which calls out to make -C Documentation/ clean, which removes the file. A test-run works here:
Before:
$ ls | grep manpage-base manpage-base-url.xsl manpage-base-url.xsl.in manpage-base.xsl
After:
$ ls | grep manpage-base manpage-base-url.xsl.in manpage-base.xsl
Were you perhaps mislead by one of the similarly-named files?
Martin
Re: [PATCH 1/3] Documentation/Makefile: add missing xsl dependencies for manpages
Quoted 10 lines · Martin Ågren
Quoted 4 lines · Eric Sunshine
I guess I was further confused by the fact that manpage-base-url.xsl is still present even after "make distclean", which is not something I would have expected for a generated file. (Perhaps something to consider "fixing" if you re-roll, or not if it's out of scope.)
Are you sure?
make distcleanin the top directory depends on the "clean" target, which calls out tomake -C Documentation/ clean, which removes the file. [...]
Were you perhaps mislead by one of the similarly-named files?
Yes, I was misled by similar names. Sorry for the noise.
Re: [PATCH 1/3] Documentation/Makefile: add missing xsl dependencies for manpages
Quoted 5 lines · Eric Sunshine
Quoted 1 line · Martin Ågren
Were you perhaps mislead by one of the similarly-named files?
Yes, I was misled by similar names. Sorry for the noise.
Hey, no problem. And thanks for the subtle hint about "misled". ;-) I appreciate it.
Martin
PATCH 2/3 Documentation/Makefile: add missing dependency on asciidoctor-extensions
In reply to Martin Ågrenasciidoctor-extensions.rb has never changed, but when it does -- such as in the next commit --, it helps if the xml-files depend on it. We're casting the net a bit too wide here, since we'll be rebuilding even with AsciiDoc, which won't look at this file. But since this file changes so rarely, that should be ok. It's better than missing a dependency.
--- Documentation/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/Makefile +1 -1
@@ -358,7 +358,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in $(QUIET_XMLTO)$(RM) $@ && \ $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< -%.xml : %.txt asciidoc.conf +%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_XML) -d manpage -o $@+ $< && \ mv $@+ $@
Signature · 1 line
2.21.0
PATCH 3/3 asciidoctor-extensions: fix spurious space after linkgit
In reply to Martin ÅgrenWhen we render, e.g., "linkgit:gitglossary[7]." with Asciidoctor, we get "gitglossary(7) ." with a space between the linkgit macro expansion and the punctuation. We can fix this by dropping the trailing newline after we've turned linkgit:foo[bar] into <citerefentry>..</citerefentry>.
The diff produced by USE_ASCIIDOCTOR=Yes ./doc-diff HEAD^ HEAD is almost 6000 lines large and shows how this fixes "git-foo(x) ,", "(see git-bar(y) )" and so on. One might wonder whether this also turns, e.g., "see linkgit:foo[1] for more" into "see foo(1)for more", but no. We get "...</citerefentry> for more" in the XML, see, e.g., git-am.xml, so the space ends up in git-am.1 just fine.
--- Documentation/asciidoctor-extensions.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/asciidoctor-extensions.rb +1 -1
@@ -16,7 +16,7 @@ module Git "<citerefentry>\n" \ "<refentrytitle>#{target}</refentrytitle>" \ "<manvolnum>#{attrs[1]}</manvolnum>\n" \ - "</citerefentry>\n" + "</citerefentry>" end end end
Signature · 1 line
2.21.0
Quoted 22 lines · Martin Ågren
When we render, e.g., "linkgit:gitglossary[7]." with Asciidoctor, we get "gitglossary(7) ." with a space between the linkgit macro expansion and the punctuation. We can fix this by dropping the trailing newline after we've turned
linkgit:foo[bar]into<citerefentry>..</citerefentry>.The diff produced by
USE_ASCIIDOCTOR=Yes ./doc-diff HEAD^ HEADis almost 6000 lines large and shows how this fixes "git-foo(x) ,", "(see git-bar(y) )" and so on. One might wonder whether this also turns, e.g., "see linkgit:foo[1] for more" into "see foo(1)for more", but no. We get "...</citerefentry> for more" in the XML, see, e.g., git-am.xml, so the space ends up in git-am.1 just fine.Signed-off-by Martin Ågren <[email protected]>--- Documentation/asciidoctor-extensions.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/asciidoctor-extensions.rb +0
-0
Documentation/asciidoctor-extensions.rb module Git · line 22
Quoted 8 lines
Documentation/asciidoctor-extensions.rb +1
-1@@ -16,7 +16,7 @@ module Git "<citerefentry>\n" \ "<refentrytitle>#{target}</refentrytitle>" \ "<manvolnum>#{attrs[1]}</manvolnum>\n" \ - "</citerefentry>\n" + "</citerefentry>" end end end
Yeah, I think this is clearly correct. I also like that you mentioned the concern about potentially not including the space, which might not be obvious to someone not intimately familiar with DocBook and the stylesheets.
Signature · 2 lines
brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204
Quoted 15 lines · Martin Ågren
Patch 3/3 gets rid of a spurious space which shows up immediately after Asciidoctor has expanded linkgit:foo[bar] if the macro is followed by punctuation such as a comma, period or closing parenthesis.
Patch 2/3 adds a missing dependency to the makefile, so that the docs will actually be rebuilt with that final patch. Patch 1/3 isn't needed for this series, but could help someone in the future, similar to how already having patch 2/3 would have helped me...
Martin Ågren (3):
Documentation/Makefile: add missing xsl dependencies for manpagesDocumentation/Makefile: add missing dependency on
asciidoctor-extensions
asciidoctor-extensions: fix spurious space after linkgit
Quoted 3 lines
Documentation/Makefile | 4 ++-- Documentation/asciidoctor-extensions.rb | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-)
Thanks for putting this series together. I would suggest an update to the commit message in 1/3 explaining the edge case that Eric Sunshine mentioned, but otherwise, I think this looks good.
Signature · 2 lines
brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204
Quoted 4 lines · brian m. carlson
Thanks for putting this series together. I would suggest an update to the commit message in 1/3 explaining the edge case that Eric Sunshine mentioned, but otherwise, I think this looks good.
Thank you. I'll do that, after waiting for a while for any other comments, and to see what conclusion I and Eric can reach on the make distclean tangent.
Martin
v2 cover asciidoctor-extensions: fix spurious space after linkgit
Just like v1 [1], this v2 removes a spurious space which shows up in a large number of places in our manpages when Asciidoctor expands the linkgit:foo[bar] macro. The only difference is a new paragraph in the commit message of the first patch to explain why we need to explicitly list a file we depend on.
Thanks Eric and brian for your comments on v1.
[1] https://public-inbox.org/git/[email protected]/
Martin Ågren (3):
Documentation/Makefile: add missing xsl dependencies for manpages Documentation/Makefile: add missing dependency on
asciidoctor-extensions
asciidoctor-extensions: fix spurious space after linkgit
Documentation/Makefile | 4 ++-- Documentation/asciidoctor-extensions.rb | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-)
Signature · 1 line
2.21.0
PATCH v2 1/3 Documentation/Makefile: add missing xsl dependencies for manpages
These stylesheets very rarely change, but when they do, it really helps if the manpages depend on them. We're casting the net a bit too wide here, since we'll only ever use a subset of the stylesheets, but since these files change so rarely, that should be ok. It's better than missing a dependency.
Observe that manpage-base-url.xsl is a generated file, so we need to list it explicitly, besides the wildcard expression we're adding here.
--- Documentation/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/Makefile +1 -1
@@ -354,7 +354,7 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf manpage-base-url.xsl: manpage-base-url.xsl.in $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ -%.1 %.5 %.7 : %.xml manpage-base-url.xsl +%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl) $(QUIET_XMLTO)$(RM) $@ && \ $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
Signature · 1 line
2.21.0
PATCH v2 2/3 Documentation/Makefile: add missing dependency on asciidoctor-extensions
In reply to Martin Ågrenasciidoctor-extensions.rb has never changed, but when it does -- such as in the next commit --, it helps if the xml-files depend on it. We're casting the net a bit too wide here, since we'll be rebuilding even with AsciiDoc, which won't look at this file. But since this file changes so rarely, that should be ok. It's better than missing a dependency.
--- Documentation/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/Makefile +1 -1
@@ -358,7 +358,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in $(QUIET_XMLTO)$(RM) $@ && \ $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< -%.xml : %.txt asciidoc.conf +%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_XML) -d manpage -o $@+ $< && \ mv $@+ $@
Signature · 1 line
2.21.0
PATCH v2 3/3 asciidoctor-extensions: fix spurious space after linkgit
In reply to Martin ÅgrenWhen we render, e.g., "linkgit:gitglossary[7]." with Asciidoctor, we get "gitglossary(7) ." with a space between the linkgit macro expansion and the punctuation. We can fix this by dropping the trailing newline after we've turned linkgit:foo[bar] into <citerefentry>..</citerefentry>.
The diff produced by USE_ASCIIDOCTOR=Yes ./doc-diff HEAD^ HEAD is almost 6000 lines large and shows how this fixes "git-foo(x) ,", "(see git-bar(y) )" and so on. One might wonder whether this also turns, e.g., "see linkgit:foo[1] for more" into "see foo(1)for more", but no. We get "...</citerefentry> for more" in the XML, see, e.g., git-am.xml, so the space ends up in git-am.1 just fine.
--- Documentation/asciidoctor-extensions.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/asciidoctor-extensions.rb +1 -1
@@ -16,7 +16,7 @@ module Git "<citerefentry>\n" \ "<refentrytitle>#{target}</refentrytitle>" \ "<manvolnum>#{attrs[1]}</manvolnum>\n" \ - "</citerefentry>\n" + "</citerefentry>" end end end
Signature · 1 line
2.21.0
Quoted 16 lines · Martin Ågren
Just like v1 [1], this v2 removes a spurious space which shows up in a large number of places in our manpages when Asciidoctor expands the linkgit:foo[bar] macro. The only difference is a new paragraph in the commit message of the first patch to explain why we need to explicitly list a file we depend on.
Thanks Eric and brian for your comments on v1.
[1] https://public-inbox.org/git/[email protected]/
Martin Ågren (3):
Documentation/Makefile: add missing xsl dependencies for manpagesDocumentation/Makefile: add missing dependency on
asciidoctor-extensions
asciidoctor-extensions: fix spurious space after linkgit
Quoted 3 lines
Documentation/Makefile | 4 ++-- Documentation/asciidoctor-extensions.rb | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-)
This version looks good to me. Thanks again for getting this cleaned up.
Signature · 2 lines
brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204
Quoted 17 lines · brian m. carlson
Quoted 16 lines · Martin Ågren
Just like v1 [1], this v2 removes a spurious space which shows up in a large number of places in our manpages when Asciidoctor expands the linkgit:foo[bar] macro. The only difference is a new paragraph in the commit message of the first patch to explain why we need to explicitly list a file we depend on.
Thanks Eric and brian for your comments on v1.
[1] https://public-inbox.org/git/[email protected]/
Martin Ågren (3):
Documentation/Makefile: add missing xsl dependencies for manpagesDocumentation/Makefile: add missing dependency on
asciidoctor-extensions
asciidoctor-extensions: fix spurious space after linkgit
Quoted 5 lines
Quoted 3 lines
Documentation/Makefile | 4 ++-- Documentation/asciidoctor-extensions.rb | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-)This version looks good to me. Thanks again for getting this cleaned up.
Thanks, all. Will queue.
cover fix spurious space after linkgit, now in *.html
Quoted 11 lines · Junio C Hamano
Quoted 6 lines · brian m. carlson
Quoted 3 lines · Martin Ågren
Just like v1 [1], this v2 removes a spurious space which shows up in a large number of places in our manpages when Asciidoctor expands the linkgit:foo[bar] macro. [...]
This version looks good to me. Thanks again for getting this cleaned up.
Thanks, all. Will queue.
Bleh. For some reason [1] I thought the html-files were exempt from this "extra space after linkgit" problem. They're not, as I just noticed. To add insult to injury, my original patch 2 which adds a missing dependency to the xml targets fails to add the exact same dependency for a few other targets. So of the three patches discussed above, at least two were incomplete.
Since this has hit "next", here are two patches on top to address this.
Sorry about this.
Martin
[1] I could have sworn I checked the html docs and saw that they didn't have this extra space. Looking at git-scm.com again reveals that it's not there. Huh. Seems like the site's html-rendering doesn't go through our Makefile at all and handles "linkgit:" on its own:
https://github.com/git/git-scm.com/blob/master/script/doc_importer
Martin Ågren (2):
Documentation/Makefile: add missing dependencies on
asciidoctor-extensions
asciidoctor-extensions: fix spurious space after linkgit in *.html
Documentation/Makefile | 6 +++--- Documentation/asciidoctor-extensions.rb | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-)
Signature · 1 line
2.21.0
PATCH 1/2 Documentation/Makefile: add missing dependencies on asciidoctor-extensions
I really should have caught this when I wrote 00c87bceaa ("Documentation/Makefile: add missing dependency on asciidoctor-extensions", 2019-02-27). That commit made sure that the xml-files depend on our Asciidoctor-specific extensions, but that just helps for the ".txt -> .xml -> .[157]" transformations.
Because we produce the html-files directly as ".txt -> .html" -- not as ".txt -> .xml -> .html" --, we need to make the html-files too depend on asciidoctor-extensions.rb.
There's one exception to the above paragraph. We do render user-manual.html by going through an intermediate user-manual.xml, which is an explicit, special-cased target. Add the missing dependency to user-manual.xml.
--- Documentation/Makefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/Makefile +3 -3
@@ -334,12 +334,12 @@ clean: $(RM) $(cmds_txt) $(mergetools_txt) *.made $(RM) manpage-base-url.xsl -$(MAN_HTML): %.html : %.txt asciidoc.conf +$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_HTML) -d manpage -o $@+ $< && \ mv $@+ $@ -$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf +$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_HTML) -o $@+ $< && \ mv $@+ $@
@@ -356,7 +356,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in $(TXT_TO_XML) -d manpage -o $@+ $< && \ mv $@+ $@ -user-manual.xml: user-manual.txt user-manual.conf +user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_XML) -d book -o $@+ $< && \ mv $@+ $@
Signature · 1 line
2.21.0
PATCH 2/2 asciidoctor-extensions: fix spurious space after linkgit in *.html
In reply to Martin ÅgrenI really should have caught this when I wrote c3b4efa030 ("asciidoctor-extensions: fix spurious space after linkgit", 2019-02-27). Turns out that when we create html-files, we take a different path through this macro. So similar to c3b4efa030, we need to drop a "\n" which turns into a space before punctuation.
Just like with c3b4efa030, note that if what follows is a word, not punctuation, the white space renders just fine. So constructions such as "see linkgit:foo[1] for more" still render as intended.
--- Documentation/asciidoctor-extensions.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/asciidoctor-extensions.rb +1 -1
@@ -11,7 +11,7 @@ module Git def process(parent, target, attrs) if parent.document.basebackend? 'html' prefix = parent.document.attr('git-relative-html-prefix') - %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>\n) + %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) elsif parent.document.basebackend? 'docbook' "<citerefentry>\n" \ "<refentrytitle>#{target}</refentrytitle>" \
Signature · 1 line
2.21.0
Re: [PATCH 0/2] fix spurious space after linkgit, now in *.html
In reply to Martin ÅgrenQuoted 5 lines · Martin Ågren
[1] I could have sworn I checked the html docs and saw that they didn't have this extra space. Looking at git-scm.com again reveals that it's not there. Huh. Seems like the site's html-rendering doesn't go through our
Makefileat all and handles "linkgit:" on its own:
https://github.com/git/git-scm.com/blob/master/script/doc_importer
Correct. It significantly predates any support for asciidoctor in our Makefile, and needs to do some custom ruby-level tweaking (though possibly that could be cleaned up these days).
The doc_importer script you found, though, is not part of that process. I _think_ it's just leftover cruft. The actual import and conversion happens as part of the rake task in:
https://github.com/git/git-scm.com/blob/master/lib/tasks/index.rake
(Not that any of this matters for your series; just sprinkling some fun facts into the conversation).
-Peff
Re: [PATCH 0/2] fix spurious space after linkgit, now in *.html
Quoted 13 lines · Jeff King
Quoted 5 lines · Martin Ågren
[1] I could have sworn I checked the html docs and saw that they didn't have this extra space. Looking at git-scm.com again reveals that it's not there. Huh. Seems like the site's html-rendering doesn't go through our
Makefileat all and handles "linkgit:" on its own:
https://github.com/git/git-scm.com/blob/master/script/doc_importerCorrect. It significantly predates any support for asciidoctor in our
Makefile, and needs to do some custom ruby-level tweaking (though possibly that could be cleaned up these days).
Quoted 8 lines
The
doc_importerscript you found, though, is not part of that process. I _think_ it's just leftover cruft. The actual import and conversion happens as part of the rake task in:https://github.com/git/git-scm.com/blob/master/lib/tasks/index.rake
(Not that any of this matters for your series; just sprinkling some fun facts into the conversation).
Thanks for this background info, and for the correct link. :-)
Martin
Re: [PATCH 0/2] fix spurious space after linkgit, now in *.html
In reply to Martin ÅgrenQuoted 10 lines · Martin Ågren
Bleh. For some reason [1] I thought the html-files were exempt from this "extra space after linkgit" problem. They're not, as I just noticed. To add insult to injury, my original patch 2 which adds a missing dependency to the xml targets fails to add the exact same dependency for a few other targets. So of the three patches discussed above, at least two were incomplete.
Since this has hit "next", here are two patches on top to address this.
Sorry about this.
Thanks.
If it makes it easier, we can eject ma/asciidoctor-fixes out of 'next' when we rebuild 'next'. I actually am tempted to start 'next' from empty for this round after merging some obviously correct ones that are there to the 'master' branch.
Re: [PATCH 0/2] fix spurious space after linkgit, now in *.html
Quoted 5 lines · Junio C Hamano
Quoted 2 lines · Martin Ågren
Since this has hit "next", here are two patches on top to address this.
Quoted 8 lines
Quoted 1 line
Sorry about this.
Thanks.
If it makes it easier, we can eject ma/asciidoctor-fixes out of 'next' when we rebuild 'next'. I actually am tempted to start 'next' from empty for this round after merging some obviously correct ones that are there to the 'master' branch.
Ok, then I'll take that offer. I'll squash these two patches into the original series. Thanks.
Martin
Re: [PATCH 0/2] fix spurious space after linkgit, now in *.html
Quoted 2 lines · Martin Ågren
Ok, then I'll take that offer. I'll squash these two patches into the original series. Thanks.
Our mails might cross, but just in case you haven't started, here are the locally squashed results with updated log messages.
PATCH v3 1/3 Documentation/Makefile: add missing xsl dependencies for manpages
From: Martin Ågren <[email protected]>
These stylesheets very rarely change, but when they do, it really helps if the manpages depend on them. We're casting the net a bit too wide here, since we'll only ever use a subset of the stylesheets, but since these files change so rarely, that should be ok. It's better than missing a dependency.
Observe that manpage-base-url.xsl is a generated file, so we need to list it explicitly, besides the wildcard expression we're adding here.
--- Documentation/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/Makefile +1 -1
@@ -347,7 +347,7 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf manpage-base-url.xsl: manpage-base-url.xsl.in $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ -%.1 %.5 %.7 : %.xml manpage-base-url.xsl +%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl) $(QUIET_XMLTO)$(RM) $@ && \ $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
Signature · 1 line
2.21.0-155-ge902e9bcae
PATCH v3 2/3 Documentation/Makefile: add missing dependency on asciidoctor-extensions
From: Martin Ågren <[email protected]>
asciidoctor-extensions.rb has never changed, but when it does -- such as in the next commit --, it helps if the xml-files depend on it. We're casting the net a bit too wide here, since we'll be rebuilding even with AsciiDoc, which won't look at this file. But since this file changes so rarely, that should be ok. It's better than missing a dependency.
Similarly, most of the html-files are produced directly from ".txt'; make the html-files too depend on asciidoctor-extensions.rb, both the HTMLified manual pages as well as the user-manual that does use .xml intermediary.
--- Documentation/Makefile | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/Makefile +4 -4
@@ -334,12 +334,12 @@ clean: $(RM) $(cmds_txt) $(mergetools_txt) *.made $(RM) manpage-base-url.xsl -$(MAN_HTML): %.html : %.txt asciidoc.conf +$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_HTML) -d manpage -o $@+ $< && \ mv $@+ $@ -$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf +$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_HTML) -o $@+ $< && \ mv $@+ $@
@@ -351,12 +351,12 @@ manpage-base-url.xsl: manpage-base-url.xsl.in $(QUIET_XMLTO)$(RM) $@ && \ $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< -%.xml : %.txt asciidoc.conf +%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_XML) -d manpage -o $@+ $< && \ mv $@+ $@ -user-manual.xml: user-manual.txt user-manual.conf +user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_XML) -d book -o $@+ $< && \ mv $@+ $@
Signature · 1 line
2.21.0-155-ge902e9bcae
PATCH v3 3/3 asciidoctor-extensions: fix spurious space after linkgit
In reply to Junio C HamanoFrom: Martin Ågren <[email protected]>
When we render, e.g., "linkgit:gitglossary[7]." with Asciidoctor, we get "gitglossary(7) ." with a space between the linkgit macro expansion and the punctuation. We can fix this by dropping the trailing newline after we've turned linkgit:foo[bar] into <citerefentry>..</citerefentry>.
The diff produced by USE_ASCIIDOCTOR=Yes ./doc-diff HEAD^ HEAD is almost 6000 lines large and shows how this fixes "git-foo(x) ,", "(see git-bar(y) )" and so on. One might wonder whether this also turns, e.g., "see linkgit:foo[1] for more" into "see foo(1)for more", but no. We get "...</citerefentry> for more" in the XML, see, e.g., git-am.xml, so the space ends up in git-am.1 just fine. The same is true for the HTML output.
--- Documentation/asciidoctor-extensions.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/asciidoctor-extensions.rb +2 -2
@@ -11,12 +11,12 @@ module Git def process(parent, target, attrs) if parent.document.basebackend? 'html' prefix = parent.document.attr('git-relative-html-prefix') - %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>\n) + %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) elsif parent.document.basebackend? 'docbook' "<citerefentry>\n" \ "<refentrytitle>#{target}</refentrytitle>" \ "<manvolnum>#{attrs[1]}</manvolnum>\n" \ - "</citerefentry>\n" + "</citerefentry>" end end end
Signature · 1 line
2.21.0-155-ge902e9bcae
Re: [PATCH 0/2] fix spurious space after linkgit, now in *.html
In reply to Junio C HamanoQuoted 8 lines · Junio C Hamano
Quoted 2 lines · Martin Ågren
Ok, then I'll take that offer. I'll squash these two patches into the original series. Thanks.
Our mails might cross, but just in case you haven't started, here are the locally squashed results with updated log messages.
Thank you so much! This looks good to me.
Martin