Mallard transforms with JavaScript?

Shaun McCance <shaunm at gnome.org>
Sun May 16 13:05:26 EDT 2021

Hi all,

I posted this to my blog and Twitter, but I figured it would be good to
post here as well. (I'm posting the same thing to gnome-doc-list.)

A few weeks ago, I got the crazy idea to try to do documentation
transforms in JavaScript with mustache templates. Right now, all our
transforms are in XSLT, which not a lot of people know.

Here's the (very preliminary) code:

https://gitlab.gnome.org/shaunm/hookbill/

Here's my blog post:

https://blogs.gnome.org/shaunm/2021/04/25/documentation-transforms-in-javascript/

Here's an example of a template:

  {{~#if (if_test element)~}}
  {{~#var 'cls' normalize=true}}
    {{element.localname}}
    {{#if (contains element.attrs.style 'lead')}}lead{{/if}}
    {{if_class element}}
  {{/var~}}
  <p class="{{vars.cls}}" {{call 'html-lang-attrs'}}>
    {{~call 'html-inline' element.children~}}
  </p>
  {{~/if~}}

Here's what the corresponding bit of XSLT looks like:

  <xsl:template mode="mal2html.block.mode" match="mal:p">
    <xsl:variable name="if">
      <xsl:call-template name="mal.if.test"/>
    </xsl:variable>
    <xsl:if test="$if != ''">
    <p>
      <xsl:call-template name="html.class.attr">
        <xsl:with-param name="class">
          <xsl:text>p</xsl:text>
          <xsl:if test="contains(concat(' ', @style, ' '), ' lead ')">
            <xsl:text> lead</xsl:text>
          </xsl:if>
          <xsl:if test="$if != 'true'">
            <xsl:text> if-if </xsl:text>
            <xsl:value-of select="$if"/>
          </xsl:if>
        </xsl:with-param>
      </xsl:call-template>
      <xsl:call-template name="html.lang.attrs"/>
      <xsl:apply-templates mode="mal2html.inline.mode"/>
    </p>
    </xsl:if>
  </xsl:template>

So here's the question: Is anybody interested in this as the future of
how we process Mallard documents? I don't think I have the bandwidth to
maintain two sets of transforms long-term, so if I went with this, it
would mean replacing the backend for yelp, yelp-build, and pintail, and
then deprecating yelp-xsl. It would take a significant time investment
to finish this, but I'm willing to do it if it would make it easier for
lots of people to contribute.

Thoughts please.

--
Shaun