From its start, the MongoDB C Driver has been split into two projects: libbson and libmongoc. Each has its own reference manual, each comprising hundreds of pages, written in the Mallard XML format. We use yelp-build to convert the Mallard to HTML and put it online. For example, here's the reference page for libmongoc's mongoc_collection_find:

mongoc_cursor_t *
mongoc_collection_find (mongoc_collection_t       *collection,
                        mongoc_query_flags_t       flags,
                        uint32_t                   skip,
                        uint32_t                   limit,
                        uint32_t                   batch_size,
                        const bson_t              *query,
                        const bson_t              *fields,
                        const mongoc_read_prefs_t *read_prefs);

Notice how names like mongoc_collection_t are links to other pages in libmongoc's manual. That's easy enough to do with yelp-build:

<code xref="mongoc_collection_t">mongoc_collection_t</code>

What I couldn't figure out was this: how can I link references from libmongoc's manual to libbson's?

With incredible generosity, Shaun McCance designed a solution for me. He told me how to create an "xref extension" using an XML transformation so that an element like this:

<code xref="bson:bson_t">bson_t</code>

...is rendered as a link to libbson's page about the bson_t type.

Here's the XSL file that does the transform:

<xsl:stylesheet>
    <!--
    Turn markup like this:
    <code xref="bson:bson_t">bson_t</code>
    ... into a link like this:
    http://mongoc.org/libbson/current/bson_t.html
    -->
    <xsl:template name="mal.link.target.custom">
        <xsl:param name="node" select="."/>
        <xsl:param name="xref" select="$node/@xref"/>
        <xsl:if test="starts-with($xref, 'bson:')">
            <xsl:variable name="ref"
                          select="substring-after($xref, 'bson:')"/>
            <xsl:text>http://mongoc.org/libmongoc/current/</xsl:text>
            <xsl:value-of select="$ref"/>
            <xsl:text>.html</xsl:text>
        </xsl:if>
    </xsl:template>
</xsl:stylesheet>

Pass that to yelp-build -x and Bob, as they say, is your uncle.

Read the complete discussion on the Project Mallard mailing list.

Image: Mallard Ducks, John James Audubon.