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