Re: [PATCH] Documentation: implement linkgit macro for Asciidoctor

From: Jeff King <peff@peff.net>
Date: Jan 26, 2017, 03:46 UTC
Message-ID: <20170126034655.fwzow2mgkjj5dpek@sigill.intra.peff.net>
In-Reply-To: <20170126001344.445534-1-sandals@crustytoothpaste.net>

On Thu, Jan 26, 2017 at 12:13:44AM +0000, brian m. carlson wrote:

Show 13 quoted lines

> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 19c42eb60..d1b7a6865 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -179,10 +179,7 @@ ASCIIDOC = asciidoctor
>  ASCIIDOC_CONF =
>  ASCIIDOC_HTML = xhtml5
>  ASCIIDOC_DOCBOOK = docbook45
> -ifdef ASCIIDOCTOR_EXTENSIONS_LAB
> -ASCIIDOC_EXTRA = -I$(ASCIIDOCTOR_EXTENSIONS_LAB) -rasciidoctor/extensions -rman-inline-macro
> -endif
> -ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
> +ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions -alitdd='&\#x2d;&\#x2d;'

Might be more readable to just leave the litdd part on its own line.

Show 30 quoted lines

> diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
> new file mode 100644
> index 000000000..09f7088ee
> --- /dev/null
> +++ b/Documentation/asciidoctor-extensions.rb
> @@ -0,0 +1,28 @@
> +require 'asciidoctor'
> +require 'asciidoctor/extensions'
> +
> +module Git
> +  module Documentation
> +    class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor
> +      use_dsl
> +
> +      named :chrome
> +
> +      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)
> +        elsif parent.document.basebackend? 'docbook'
> +          %(<citerefentry>
> +<refentrytitle>#{target}</refentrytitle><manvolnum>#{attrs[1]}</manvolnum>
> +</citerefentry>
> +)
> +        end
> +      end
> +    end
> +  end
> +end

I think this looks reasonable. There's some boilerplate, but even as somebody not familiar with asciidoctor, it's all quite obvious.

The multi-line string is kind of ugly because of the indentation. Apparently Ruby has here-docs that will eat leading whitespace, but the syntax was not introduce until Ruby 2.3, which is probably more recent than we should count on.

I think you could write:

          %(<citerefentry>
            <refentrytitle>#{target}</refentrytitle><manvolnum>#{attrs[1]}</manvolnum>
            </citerefentry>
	  ).gsub(/^\s*/, "")

I don't know if that's too clever or not.

But either way, I like this better than introducing an extra dependency.

-Peff