Some questions about mallard

On Mon, 2011-06-27 at 09:47 +0200, Aurélien Naldi wrote:
> How are extension supposed to work from the code side? Can we just
> drop a xslt file into the mix and ask yelp-build to take it into
> account with a command-line flag?

Yes, there's a -x option to yelp-build to pass a custom XSLT file.
Your custom XSLT file doesn't have to import or include the yelp-xsl
stylesheets. yelp-build automatically creates a wrapper stylesheet
that imports yelp-xsl and includes your customization. That way you
don't have to deal with different installation paths.

> Anyway, I checked out and built the latest yelp-xsl and yelp-tools and
> it works fine, but did it lost the ability to provide a custom css
> file as gnome-doc-tool allows?

You can, just not the same way. The -x option lets you override the
XSLT. The XSLT already provides an API, so I decided not to try to
augment that with a custom command-line API. I'd just end up using
templates that you can override with -x anyway. So the way to do
custom CSS with yelp-build is to override html.css.custom, e.g.

<xsl:template name="html.css.custom">
<xsl:text>
h1 { font-size: 4em; }
</xsl:text>
</xsl:template>

So some types of extensions and customizations will be easy to do
with a custom stylesheet. For example, adding a new inline element
that just does some formatting is pretty simple. Just add a match
for that element in mal2html.inline.mode and provide some CSS in
html.css.custom.

Some things will require you do a bit more surgery. Overriding the
linking mechanism usually requires rewriting templates. (I've done
that in at least two customizations. It's non-trivial, but doable.)

As an example, I've attached a customization I put together to
scroll to arbitrary block elements. On any block element, you can
add the xml:id attribute, like so:

<figure xml:id="mainwindow">...</figure>

Then on any linkable element, you can add the e:scrollto attribute,
like so:

<link xref="gameplay" e:scrollto="mainwindow"
      xmlns:e="http://projectmallard.org/experimental/"/>

The extension has to completely override mal.link.target, which is
not ideal. As I said, I've overridden this in at least two other
customizations. I haven't figured out a better way to structure the
XSLT to make this easier. It also matches anything with xml:id in
block mode, then does xsl:apply-imports. Finally, it implements
html.css.custom, so that the wrapper divs it uses don't affect
spacing.

This hack only works on normal block elements. It doesn't work on
e.g. items in a terms list. That's a little trickier. You can't
just wrap dt elements around dt elements, like you can do with div
elements, so the xsl:apply-imports trick won't work. You'll have
to completely override the match for mal:terms/mal:item.

Anyway, rough proof of concept of doing a simple scroll-to-blocks
extension. Hopefully it gives people a better idea of how they
can define extensions and customize yelp-xsl to support them.

--
Shaun

-------------- next part --------------
A non-text attachment was scrubbed...
Name: scrollto.xsl
Type: application/xslt+xml
Size: 2081 bytes
Desc: not available
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20110629/40e677d5/attachment.xsl>