yelp-build: link to pages in another directory?

Shaun, option #2 worked perfectly for me; I'm going to deploy it soon.
Thank you so much. I'm going to write up an article on this solution and
share it with you in case you want to use it for an example in the Yelp or
Mallard docs.

On Mon, Apr 27, 2015 at 3:05 PM, A. Jesse Jiryu Davis <jesse at emptysquare.net
> wrote:

> Thanks so much for this explanation, and especially for writing me the
> XSLT! I'm going to try option #2 soon and let you know.
>
> On Mon, Apr 27, 2015 at 10:45 AM, Shaun McCance <shaunm at gnome.org> wrote:
>
>> Hi Jesse,
>>
>> I'm going to CC mallard-list. I think this is generally interesting to
>> Mallard folks. Answers inline below:
>>
>> On Sun, 2015-04-26 at 17:10 -0400, A. Jesse Jiryu Davis wrote:
>> > Hi Gnome folk,
>> >
>> >
>> > I'm taking over a project, the MongoDB C Driver, that Christian
>> > Hergert documented in Mallard. It builds with yelp-build. The
>> > documentation is split into two directories, one here:
>>
>> > https://github.com/mongodb/libbson/tree/master/doc
>>
>> > And the other here:
>>
>> > https://github.com/mongodb/mongo-c-driver/tree/master/doc
>>
>> > Pages in the latter directory include references to pages in the
>> > former. (But not vice versa.) We build each directory with a separate
>> > invocation of "yelp-build html <directory>".
>> >
>> >
>> > THE PROBLEM: when a page in the "mongo-c-driver" directory reference
>> > pages in the "libbson" directory, our current build system doesn't
>> > make correct HTML links. For example, the "bson_error_t" link here:
>> >
>> > http://api.mongodb.org/c/current/mongoc_collection_update.html
>> >
>> >
>> >
>> > ... tries to link to a bson_error_t.html page in the *same* directory,
>> > instead of to the proper page here:
>> >
>> >
>> > https://api.mongodb.org/libbson/current/bson_error_t.html
>> >
>> >
>> >
>> > Since the link is wrong, it's a 404, which on our particular server
>> > means you're redirected to the home page. People rightly call this a
>> > bug in our documentation: https://jira.mongodb.org/browse/CDRIVER-524
>>
>> Right. So Mallard, at its core, is about creating documents, where a
>> document is a collection of pages. Cross-references are links inside a
>> document. Linking to other documents requires something else. You would
>> have the same issue with DocBook or anything else document-based.
>>
>> > I tried just putting the two invocations into a single one:
>> >
>> >
>> > $ yelp-build html libbson/doc mongo-c-driver/doc
>> >
>> >
>> > But that munges all the documentation together badly, instead of link
>> > from one to the other. Here's the output of that:
>> >
>> >
>> > http://emptysqua.re/merged-libbson-libmongoc-docs/
>>
>> Doing this, you're effectively making a single document that contains
>> all the pages from two directories.
>>
>> > How can I tell yelp-build to take a reference from a file in
>> > "mongo-c-driver/" to an id in the other directory, like
>> > "bson_error_t", and render it as a URL like
>> > "../libbson/bson_error_t.html"? Instead of what it does right now,
>> > which is render a link to "bson_error_t.html" in the current
>> > directory, where no such file exists.
>>
>> I can think of three options:
>>
>> 1) Just use hrefs.
>> 2) Create an xref extension.
>> 3) Use Pintail.
>>
>>
>> 1) Just use hrefs. If you know where your docs are published, and you
>> only care about them being published in that one place, then just use
>> the href attribute to give an honest-to-goodness URL:
>>
>> <code
>> href="https://api.mongodb.org/libbson/current/bson_error_t.html
>> ">bson_error_t</code>
>>
>> This is very straightforward if it fits your needs, but it has no
>> flexibility in terms of where things are published or viewed. This
>> wouldn't work well in GNOME, for example, because docs are viewed both
>> locally in Yelp and online.
>>
>>
>> 2) Create an xref extension. Any xref that contains a "/" or ":" is an
>> extended xref in Mallard. So you could do something like:
>>
>> <code xref="mongodb:libbson/bson_error_t">bson_error_t</code>
>>
>> You'd have to provide an implementation for that, of course.
>>
>> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
>> version="1.0">
>> <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, 'mongodb:')">
>>   <xsl:variable name="ref" select="substring-after($xref, 'mongodb:')"/>
>>   <xsl:text>https://api.mongodb.org/</xsl:text>
>>   <xsl:value-of select="substring-before($ref, '/')"/>
>>   <xsl:text>/current/</xsl:text>
>>   <xsl:value-of select="substring-after($ref, '/')"/>
>>   <xsl:text>.html</xsl:text>
>>  </xsl:if>
>> </xsl:template>
>> </xsl:stylesheet>
>>
>> Put that in a file and pass it to yelp-build with -x. (Warning: I did
>> not test this code.) This can be nicer to type, and is more flexible.
>> For example, if you want to publish to a staging server, you can edit
>> the extension stylesheet to reflect that. This is exactly what GNOME
>> does in Yelp to let you link to local documents with help: xrefs.
>>
>> You could even provide both these xrefs and hrefs, like this:
>>
>> <code xref="mongodb:libbson/bson_error_t"
>> href="https://api.mongodb.org/libbson/current/bson_error_t.html
>> ">bson_error_t</code>
>>
>> When you build with your extensions that understands mongodb: xrefs,
>> those will be used. But if I grab your docs and build with vanilla
>> yelp-build, href will be used instead. You lose the ease-of-typing, but
>> gain portability.
>>
>>
>> 3) Use Pintail instead of yelp-build. yelp-build gives you a reasonable
>> amount of power to plug into it, but it's meant to be a fire-and-forget
>> single-document builder. Pintail, on the other hand, builds entire sites
>> of multiple Mallard documents. (It could potentially build documents in
>> other source formats, with plugins.)
>>
>> https://github.com/projectmallard/pintail
>>
>> Pintail lets you references pages in other directories ("documents") by
>> putting slashes in your xref.
>>
>> <code xref="/libbson/current/bson_error_t">bson_error_t</code>
>>
>> Just as with the previous option, you could use both xref and href to
>> have better portability with tools that don't support the extended
>> xrefs.
>>
>> <code xref="/libbson/current/bson_error_t"
>> href="https://api.mongodb.org/libbson/current/bson_error_t.html
>> ">bson_error_t</code>
>>
>> Again, portability vs ease-of-typing. The nice thing is that you can get
>> all the goodness of inside-document xrefs, like automatic link text and
>> tooltips. You could pull that off with option (2), but with considerable
>> effort that the small extension stylesheet I provided.
>>
>> Pintail is still pretty early in development. There are surely kinks.
>> But it is being used today to build projectmallard.org (and, in fact,
>> conf.openhelp.cc, because why not).
>>
>> --
>> Shaun
>>
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20150501/612448ed/attachment.html>