Mallard Ducks - John James Audubon

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);



A mongoc_collection_t.


A mongoc_query_flags_t.


Number of documents to skip.


Max number of documents to return or 0.


Batch size of document result sets or 0 for default.


A bson_t.


A bson_t containing fields to return or NULL.


A mongoc_read_prefs_t or NULL for default read preferences.

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> rendered as a link to libbson's page about the bson_t type.

Here's the XSL file that does the transform:

    Turn markup like this:
    <code xref="bson:bson_t">bson_t</code>
    ... into a link like this:
    <xsl:template name="">
        <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:value-of select="$ref"/>

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.