When we first designed Mallard, we designed it around creating documents: non-linear collections of pages about a particular subject. Documents are manageable and maintainable, and we’re able to define all of Mallard’s automatic linking within the confines of a document.
If you wanted to publish a set of Mallard documents on the web, you could build each of them individually with a tool like yelp-build, then output some extra navigation pages to help people find the right document. But there was no simple way to create those extra pages. What’s more, you couldn’t link between documents except by using external href links. Mallard’s automatic links are confined to documents.
Enter Pintail. Pintail lets you build entire web sites from Mallard sources. Just lay out your pages in the directory structure you like, and let Pintail build the site for you. Put full Mallard documents in their own directories, then use Mallard to create the extra navigation pages between them. Better still, you can use an extended xref syntax to refer to pages in other directories. Just include the path to the target page with slashes, like so:
<link xref="/about/learn/svg"/>
This isn’t just a simple link. You can use this in topic links and seealso links and anywhere else that Mallard lets you put an xref attribute. Pintail makes Mallard’s automatic linking work across multiple documents.
Pintail is designed to allow other formats to be used, so you could use it to build all your documentation in an environment where not everything is in one format. It already supports Mallard Ducktype as well as XML. But Mallard is the primary format.
One of the really nice features is that it can pull it documents in other git repositories, so you don’t have to keep all your documentation in a single source tree. In fact, the site in your main repository might be little more than glue pages and the pintail.cfg file that specifies where all the actual documentation lives.
Pintail builds the projectmallard.org web site right now, as well as a few other random sites I maintain. I hope it turns out to be useful for heavy Mallard users like GNOME, Ubuntu, and Endless. And I hope it makes Mallard easier for others who are considering using it.
No software is ever finished, but here are some of the top things I plan to add soon:
- Page merging: Mallard allows pages to be dropped into a document and seamlessly integrated into the navigation. Sometimes you want to publish a document with pages pulled from other places. For example, GNOME generally wants to publish GNOME Help with the optional Getting Started video pages merged in.
- Translations: Mallard was designed from day one to be translator-friendly, and itstool ships with ITS rules for Mallard. I just need to hook the pieces together.
- Search: An extensive documentation site needs configurable search. You often want to restrict search within a single document. Also, some documents (or versions of documents) shouldn’t appear in global search results.
What would you like to see a Mallard site tool do?
