From: Eric Wong <e@80x24.org>
Date: Thu, 26 Jan 2017 07:43:04 GMT
Subject: Re: [PATCH] Documentation: implement linkgit macro for Asciidoctor
Message-ID: <20170126074304.GA26530@starla>
In-Reply-To: <20170126034655.fwzow2mgkjj5dpek@sigill.intra.peff.net>

Jeff King <peff@peff.net> wrote:
> On Thu, Jan 26, 2017 at 12:13:44AM +0000, brian m. carlson wrote:
> > +
> > +      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>
> > +)

<snip>

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

You can use '\' to continue long lines with any Ruby version:

    "<citerefentry>" \
      "<refentrytitle>#{target}</refentrytitle>" \
      "<manvolnum>#{attrs[1]}</manvolnum>" \
    "</citerefentry>"

The above happens during the parse phase, so there's no garbage
or method call overhead compared to the more-frequently seen '+'
or '<<' method calls to combine strings.

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

Ick...

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

Agreed.