<div dir="ltr">Thanks so much for this explanation, and especially for writing me the XSLT! I&#39;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">&lt;<a href="mailto:shaunm@gnome.org" target="_blank">shaunm@gnome.org</a>&gt;</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&#39;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>
&gt; Hi Gnome folk,<br>
&gt;<br>
&gt;<br>
&gt; I&#39;m taking over a project, the MongoDB C Driver, that Christian<br>
&gt; Hergert documented in Mallard. It builds with yelp-build. The<br>
&gt; documentation is split into two directories, one here:<br>
<br>
&gt; <a href="https://github.com/mongodb/libbson/tree/master/doc" target="_blank">https://github.com/mongodb/libbson/tree/master/doc</a><br>
<br>
&gt; And the other here:<br>
<br>
&gt; <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>
&gt; Pages in the latter directory include references to pages in the<br>
&gt; former. (But not vice versa.) We build each directory with a separate<br>
&gt; invocation of &quot;yelp-build html &lt;directory&gt;&quot;.<br>
&gt;<br>
&gt;<br>
&gt; THE PROBLEM: when a page in the &quot;mongo-c-driver&quot; directory reference<br>
&gt; pages in the &quot;libbson&quot; directory, our current build system doesn&#39;t<br>
&gt; make correct HTML links. For example, the &quot;bson_error_t&quot; link here:<br>
&gt;<br>
&gt; <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>
&gt;<br>
&gt;<br>
&gt;<br>
&gt; ... tries to link to a bson_error_t.html page in the *same* directory,<br>
&gt; instead of to the proper page here:<br>
&gt;<br>
&gt;<br>
&gt; <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>
&gt;<br>
&gt;<br>
&gt;<br>
&gt; Since the link is wrong, it&#39;s a 404, which on our particular server<br>
&gt; means you&#39;re redirected to the home page. People rightly call this a<br>
&gt; 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>
&gt; I tried just putting the two invocations into a single one:<br>
&gt;<br>
&gt;<br>
&gt; $ yelp-build html libbson/doc mongo-c-driver/doc<br>
&gt;<br>
&gt;<br>
&gt; But that munges all the documentation together badly, instead of link<br>
&gt; from one to the other. Here&#39;s the output of that:<br>
&gt;<br>
&gt;<br>
&gt; <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&#39;re effectively making a single document that contains<br>
all the pages from two directories.<br>
<span class=""><br>
&gt; How can I tell yelp-build to take a reference from a file in<br>
&gt; &quot;mongo-c-driver/&quot; to an id in the other directory, like<br>
&gt; &quot;bson_error_t&quot;, and render it as a URL like<br>
&gt; &quot;../libbson/bson_error_t.html&quot;? Instead of what it does right now,<br>
&gt; which is render a link to &quot;bson_error_t.html&quot; in the current<br>
&gt; 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>
&lt;code<br>
href=&quot;<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>&quot;&gt;bson_error_t&lt;/code&gt;<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&#39;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 &quot;/&quot; or &quot;:&quot; is an<br>
extended xref in Mallard. So you could do something like:<br>
<br>
&lt;code xref=&quot;mongodb:libbson/bson_error_t&quot;&gt;bson_error_t&lt;/code&gt;<br>
<br>
You&#39;d have to provide an implementation for that, of course.<br>
<br>
&lt;xsl:stylesheet xmlns:xsl=&quot;<a href="http://www.w3.org/1999/XSL/Transform" target="_blank">http://www.w3.org/1999/XSL/Transform</a>&quot;<br>
version=&quot;1.0&quot;&gt;<br>
&lt;xsl:template name=&quot;mal.link.target.custom&quot;&gt;<br>
 &lt;xsl:param name=&quot;node&quot; select=&quot;.&quot;/&gt;<br>
 &lt;xsl:param name=&quot;xref&quot; select=&quot;$node/@xref&quot;/&gt;<br>
 &lt;xsl:if test=&quot;starts-with($xref, &#39;mongodb:&#39;)&quot;&gt;<br>
  &lt;xsl:variable name=&quot;ref&quot; select=&quot;substring-after($xref, &#39;mongodb:&#39;)&quot;/&gt;<br>
  &lt;xsl:text&gt;<a href="https://api.mongodb.org/" target="_blank">https://api.mongodb.org/</a>&lt;/xsl:text&gt;<br>
  &lt;xsl:value-of select=&quot;substring-before($ref, &#39;/&#39;)&quot;/&gt;<br>
  &lt;xsl:text&gt;/current/&lt;/xsl:text&gt;<br>
  &lt;xsl:value-of select=&quot;substring-after($ref, &#39;/&#39;)&quot;/&gt;<br>
  &lt;xsl:text&gt;.html&lt;/xsl:text&gt;<br>
 &lt;/xsl:if&gt;<br>
&lt;/xsl:template&gt;<br>
&lt;/xsl:stylesheet&gt;<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>
&lt;code xref=&quot;mongodb:libbson/bson_error_t&quot;<br>
href=&quot;<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>&quot;&gt;bson_error_t&lt;/code&gt;<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&#39;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 (&quot;documents&quot;) by<br>
putting slashes in your xref.<br>
<br>
&lt;code xref=&quot;/libbson/current/bson_error_t&quot;&gt;bson_error_t&lt;/code&gt;<br>
<br>
Just as with the previous option, you could use both xref and href to<br>
have better portability with tools that don&#39;t support the extended<br>
xrefs.<br>
<br>
&lt;code xref=&quot;/libbson/current/bson_error_t&quot;<br>
href=&quot;<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>&quot;&gt;bson_error_t&lt;/code&gt;<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>