Formats of this publication

Output formats

To make this publication as user-friendly as possible across all formats, we use 'web-first' writing techniques — as opposed to traditional 'print-first' techniques which tend to yield poor usability in Web-based publications.

Right now, this website is the only output format for this publication — but we’re testing functionality that will allow us to also publish other formats every time we publish updates to the content. The idea is to automatically provide up-to-date PDF files (mainly for those who want to print physical copies) and an installable app that has offline functionality (so that you can consult the rules even when you have no Internet access).

About our publishing toolchain

In case you’re geeky enough to be interested:

This project uses Antora, a static site generator for the Asciidoc plain-text markup language, and GitHub Actions, to deploy updates to the website with very little effort.

We’ll use additional extensions and scripts to publish PDF files and progressive web app (PWA) functionality with dynamic caching.

This is non-trivial, and I don’t have a background in coding. But I’ve made good progress in testing, and if I can get it working at a satisfactory level, the automation makes it easy to publish these extra formats in parallel with the website. Otherwise, these extra formats would demand a lot of additional manual effort to produce — not just once, but every time there is an update — and I don’t consider that to be a good use of time, especially while the content in this project is still undergoing significant change.
— Eric Weston

Current limitations

Some limitations that we’re forced to deal with at the moment, along with corresponding compromises and workarounds we’re using (not a comprehensive list).

PDF outputs: Cross-references lack target page numbers

PDF outputs render hyperlinks for cross-references, but not the target page numbers; this lack will be annoying for those who want to print the PDF outputs to paper. Unfortunately, this is not practical for us to solve ourselves — but we hope that future developments to the PDF extension will fix this issue.

PDF outputs: Footnotes render as endnotes instead

For PDF outputs, content we’ve coded as footnotes become endnotes instead. This is because the PDF extension does not support 'content reflows' (the lack of cross-reference page numbers has a similar root cause). Again, perhaps developers will add functionality to support this in future.

In the meantime, this unfortunately means that footnotes that are convenient and helpful in HTML outputs may be rather less so in PDF outputs.

PDF outputs: Some very long URL texts

While you can use PDF outputs on-screen, the HTML outputs are much better for this — so we provide PDF outputs mainly for those who want to print the rules to paper. However, you can’t use hyperlinks on paper…​ so the system converts outgoing hyperlinks to full URL text that the reader can read and then type into a browser if they want to.

That’s sensible, but some URLs in this project are very long and complex — particularly where we link to detachments that we’ve defined in the Builder for your convenience. Such URLs take up a lot of space and are too complex to be of much use on paper.

For now we’ll just live with this issue, but in future we might simply hide some of this content from PDF outputs, or find some other alternative.

PDF outputs: Limited control of flow across page breaks

Page breaks can cause a range of complications for the flow of content. The system handles some things fairly gracefully, other things less so. We don’t want to tweak things manually every time we make an update, so for the most part, we just have to live with this issue — but where we can tweak the configuration to yield better results, we’ll do so.

Constraints on appearance

Unfortunately, the PDF extension makes the build process much more fussy and fragile than when the process only needs to deliver HTML. This actually means that some otherwise simple code that would enhance appearance and usability of the outputs can actually lead to errors that break the entire build process, because of the way the PDF extension works. Again, we hope that future improvements to the PDF extension might improve matters.

All outputs: Lack of styling for keywords

One particular consequence of this affects some keywords that we define in global attributes (so that we can reuse the keywords across the project with 100% consistency): When we were publishing only the website, we styled special ability keywords in italics to highlight and disambiguate them. But, publishing to PDF currently means that we can’t use such styling with these keywords for any of the output formats. So, as a workaround, we’re using ·dot markers· instead.

PDF outputs: Lack of inline images

Similarly, there are some statements for order and condition markers that we define in global attributes, with inline images that depict the markers. These attributes still render as expected in HTML outputs, but the in PDF outputs we get the text but not the inline images (we get the text "[core]" instead, as in "Broken [core] condition marker", for example). For now, the workaround is simply to live with this, as it is still intelligible.

PDF outputs: Lack of control over the appearance of 'admonitions'

So-called 'admonitions' — tips, notes, cautions, and other notices that draw your attention — are difficult to style and customise for PDF outputs. For now, compromises include:

  • Admonitions in PDF outputs render their corresponding icons, but not their label text. (So, for example, 'tip' admonitions show a green lightbulb icon, but no "TIP" label text).

  • Our custom 'option' admonition renders in HTML outputs, but not in PDF outputs — there we see only the base 'note' admonition styling. So, as a workaround, we insert "Option: " title text into 'option' admonitions.