yelp-build: link to pages in another directory?

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/20150427/e716dd09/attachment.html>