On Mon, Feb 25, 2019 at 09:02:40PM +0100, Martin Ågren wrote:
> 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.
> 
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
>  Documentation/asciidoctor-extensions.rb | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
> index ec83b4959e..f7a5982f8b 100644
> --- a/Documentation/asciidoctor-extensions.rb
> +++ b/Documentation/asciidoctor-extensions.rb
> @@ -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.
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204