Skip to contentSkip to conversation

asciidoctor-extensions: fix spurious space after linkgit

PATCH Superseded Martin Ågren 5 participants 31 messages Feb 25, 2019 – Mar 11, 2019 Documentation

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index 26a2342bea..0f8054a115 100644
@@ -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
#2 lore raw

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.

---

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?

#3 lore raw

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

---

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

#4 lore raw

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.)

#5 lore raw

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

#6 lore raw

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 distclean in the top directory depends on the "clean" target, which calls out to make -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.

#7 lore raw

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

#8 lore raw

PATCH 2/3 Documentation/Makefile: add missing dependency on asciidoctor-extensions

In reply to Martin Ågren

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.

---
 Documentation/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/Makefile +1 -1
index 0f8054a115..a9697f5146 100644
@@ -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
#9 lore raw

PATCH 3/3 asciidoctor-extensions: fix spurious space after linkgit

In reply to 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^ 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
index ec83b4959e..f7a5982f8b 100644
@@ -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
#10 lore raw
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^ 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 +0 -0
index ec83b4959e..f7a5982f8b 100644

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
#11 lore raw
In reply to Martin Ågren
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 manpages Documentation/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
#12 lore raw
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

#13 lore raw

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
#14 lore raw

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
index 26a2342bea..0f8054a115 100644
@@ -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
#15 lore raw

PATCH v2 2/3 Documentation/Makefile: add missing dependency on asciidoctor-extensions

In reply to Martin Ågren

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.

---
 Documentation/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/Makefile +1 -1
index 0f8054a115..a9697f5146 100644
@@ -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
#16 lore raw

PATCH v2 3/3 asciidoctor-extensions: fix spurious space after linkgit

In reply to 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^ 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
index ec83b4959e..f7a5982f8b 100644
@@ -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
#17 lore raw
In reply to Martin Ågren
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 manpages Documentation/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
#18 lore raw
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 manpages Documentation/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.

#19 lore raw

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
#20 lore raw

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
index f63c775e88..f58904a929 100644
@@ -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
#21 lore raw

PATCH 2/2 asciidoctor-extensions: fix spurious space after linkgit in *.html

In reply to Martin Ågren

I 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
index f7a5982f8b..0089e0cfb8 100644
@@ -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
#22 lore raw

Re: [PATCH 0/2] fix spurious space after linkgit, now in *.html

In reply to Martin Ågren
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 Makefile at 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

#23 lore raw

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 Makefile at 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).

Quoted 8 lines

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).

Thanks for this background info, and for the correct link. :-)

Martin

#24 lore raw

Re: [PATCH 0/2] fix spurious space after linkgit, now in *.html

In reply to Martin Ågren
Quoted 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.

#25 lore raw

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

#26 lore raw

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.

#27 lore raw

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
index d5d936e6a7..ea6b8e5d72 100644
@@ -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
#28 lore raw

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
index ea6b8e5d72..f58904a929 100644
@@ -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
#29 lore raw

PATCH v3 3/3 asciidoctor-extensions: fix spurious space after linkgit

In reply to Junio C Hamano

From: 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
index ec83b4959e..0089e0cfb8 100644
@@ -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
#30 lore raw

Re: [PATCH 0/2] fix spurious space after linkgit, now in *.html

In reply to Junio C Hamano
Quoted 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