Using external namespaces with mallard-site-tool

Shaun McCance <shaunm at gnome.org>
Tue Mar 26 10:23:14 EDT 2013

On Tue, 2013-03-19 at 13:44 +0100, Tobias Rapp wrote:
> Hello Mallard List,
> 
> I am currently trying to re-write my personal homepage using
> mallard-site-tool. In some of the pages I would like to include custom HTML
> elements (canvas, input text and button controls). 
> 
> I tried to do this analogous to the external namespaces example [1] but did
> not succeed. The external elements are removed in the output but the text
> between the elements remains. When looking at the HTML sources of the
> online example this seems to happen there, too.
> 
> When I use the example 1:1 (see attached page file) the output created by
> 'mallard-site-tool html -o site/' is:
> 
> Unmatched inline element: ruby
> Unmatched inline element: rb
> Unmatched inline element: rp
> Unmatched inline element: rt
> Unmatched inline element: rp
> 
> My question is, if this is expected behavior or if there is some bug in
> mallard-site-tool, yelp-build or yelp-xsl. I am using the software package
> versions as available on Ubuntu Precise, mallard-site-tool was taken from
> Gitorious [2].

Hi Tobias,

Mallard explicitly allows elements from external namespaces in three
separate contexts, and it defines the fallback behavior for tools that
don't understand those elements. But it doesn't dictate that external
elements will actually do anything other than the fallback behavior.

For example, let's say I made an extension to colorize text, and my
pages looked something like this:

<p xmlns:c="http://example.com/colors/">This is <c:red>red</c:red>,
and this is <c:blue>blue</c:blue>.</p>

If you process that with yelp, you'll get the same kind of warnings
you got with the Ruby example, and because of the defined fallback
behavior, your HTML will look like this:

<p>This is red and this is blue.</p>

The extra color information was lost, but the text is still there.
To make an extension work, you have to write some code. yelp-build
lets you pass in custom XSLT with the -x option. To make your Ruby
example work, use something like this:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:html="http://www.w3.org/1999/xhtml"
                xmlns="http://www.w3.org/1999/xhtml"
                version="1.0">
<xsl:template mode="mal2html.inline.mode" match="html:*">
  <xsl:element name="{local-name(.)} namespace="{$html.namespace}">
    <xsl:apply-templates mode="mal2html.inline.mode"/>
  </xsl:element>
</xsl:template>
</xsl:stylesheet>

(You might think the xsl:element bit is more complicated than it
needs to be. Doing it that way lets you take advantage of Yelp's
dual XHTML and HTML output.)

I do actually think there's value in having HTML pass-through
work in upstream Yelp without customization. The Ruby example
(which is straight off of an example on projectmallard.org) is
a no-brainer for something that should work, but a more complete
HTML pass-through would let you do things like embed a Google
map or a Slideshare presentation.

But Yelp doesn't work that way right now, and the Mallard spec
doesn't require it to.

--
Shaun