A customized DocBook XSL template and the required fonts for building Alan documentation in PDF format via asciidoctor-fopub.
Table of Contents
/fonts/— required third party fonts./xsl-fopub/— DocBook XSL template for Alan.XSL-DevNotes.md— misc. XSL work notes and links.
This DocBook PDF template was originally created for the Alan Docs project, a repository for the documentation of the Alan Interactive Fiction authoring system. Since other Alan-related repositories are now switching to the AsciiDoc format for their documentation, we decided to move the DocBook XSL PDF template and its assets to an independent repository to allow other projects to include it via Git submodules.
Hopefully, a shared template will reduce the maintainance burden and maximize the collaborative effort among the various Alan projects. The Alan community is a small niche, with limited active members and resources, so our strength lies in tight collaboration and sharing of resources.
Working with XSL stylesheets is not an easy task, so providing a ready-to-use template taylored for Alan documentation is a good service to the Alan community, who can then focus its energy on writing contents.
The template was customized to resemble the original layout and styles of the Alan Manual. The goal is to create a dedicated PDF template shared by all Alan-related documentation.
The template was built from the original XSL stylesheets of the asciidoctor-fopub distribution, by Dan Allen (MIT License).
One of the key features of this template is our custom Alan syntax definition for XSLTHL, the FOP syntax highlighter that ships with asciidoctor-fopub, and a dedicated color scheme for Alan code examples blocks.
xsl-fopub/xslthl/alan-hl.xml— Alan syntax definition.
For a preview of how the PDF documents generated using this template look like, refer to the following PDF samples from the Alan Docs project:
These PDFs contain detailed examples of all the template features, with instructions on how to use the template styles in your AsciiDoc project.
Asciidoctor-fopub uses the following components versions:
| Software Project | Version |
|---|---|
| Apache FOP | 2.1 |
| DocBook XSL | 1.78.1 |
| Apache Commons XML Resolver | 1.2 |
| Xalan | 2.6.0 |
| JEuclid | 3.1.9 |
| XSLTHL | 2.1.0 |
| Gradle | 2.0 |
Setting up the asciidoctor-fopub PDF toolchain, and using this template as a Git submodule, require a few careful steps. I'll provide some helpful notes to simplify the whole process, especially for Windows users.
This DocBook template is designed to work with Asciidoctor and asciidoctor-fopub. You'll need to install the following tools on your machine:
- Ruby and the following Ruby Gems:
- Java JDK12
Windows users should install Ruby via RubyInstaller, or using Chocolatey/Chocolatey GUI and the Chocolatey Ruby package.
The AsciiDoc to PDF toolchain requires setting up asciidoctor-fopub on your machine; this tool is required to convert from DocBook to PDF.
Here are some instructions on how to setup asciidoctor-fopub:
-
JDK12 — Download and install Java JDK12.
If you have other versions of Java SE/JDK uninstall them. In order to use asciidoctor-fopub you'll need Java JDK 12 (versions 6, 7 and 8 are also known to work, but are not recomended for security reasons).
NOTE — The previous incompatibility problems with gradle that prevented using Java >=9 is now fixed in asciidoctor-fopub and all users are now advised to update to the the latests JDK, and stop using JDK 8!
-
Clone asciidoctor-fopub — There is no installation for this tool, just clone it somewhere on your hard disk using Git:
git clone https://github.com/asciidoctor/asciidoctor-fopubOn Windows, I also had to carry out the following one-time operation to stop some gradle errors that were preventing using asciidoctor-fopub:
-
Open the CMD in the cloned asciidoctor-fopub folder, and type:
gradlew installappThis (undocumented) step seems necessary to complete the gradle setup of asciidoctor-fopub.
-
-
Add to PATH — After cloning asciidoctor-fopub locally, you should add its path to your system PATH in order to make it available to the scripts in this project.
See also the setup instructions found at the asciidoctor-fopub repository.
The easiest way to include this template into your project and keep it up to date is via Git submodules:
Submodules allow you to keep a Git repository as a subdirectory of another Git repository. This lets you clone another repository into your project and keep your commits separate.
— Pro Git book, §7.11 - Submodules
To add the template as a submodule within your project, use the git submodule add command:
$ git submodule add https://github.com/alan-if/alan-xsl-fopub
This will clone the template subproject into a directory named the same as the repository (i.e. alan-xsl-fopub/). If you wish to use a different folder name, just specify it after the repository url.
Don't forget to initialize the submodules:
$ git submodule update --init
For more info on working with submodules avoiding common pitfalls (beware, there are plenty of them), see the references linked at the end of this document.
You can safely keep the submodule in your project pointing to the tip of master branch in this repository — development of the template will occur in dev branches, and every commit in master will always be a fully working template.
We'll strive to keep all template updates backward-compatible, but since this can't be guaranteed 100%, you're strongly adviced to consult this document for the list of changes before moving the pointer of your submodule in your project.
Currently we haven't decided a formal update strategy for this project: it doesn't employ a versioning scheme and there are no releases. Until further notice, feel safe to always update your submodule to the tip of master branch.
In the future we might adopt SemVer schemed releases, which could simplify intuitively detecting backward-breaking changes and manually updating the submodule pointer accordingly. Any proposal and advice on this topic is most welcome; feel free to open an Issue.
In order to use these XSL Stylesheets, your invoking script must set the working path to the root folder of this submodule/repository (i.e. "alan-xsl-fopub/", unless you choose a different folder name). This is due to the fact that the "fop-config.xml" configuration file relies on relative paths to locate the fonts folder:
<!-- Register all the fonts found in this directory -->
<directory recursive="true">fonts</directory>Therefore, the invoking script must CD to the "alan-xsl-fopub/" folder when invoking asciidoctor-fopub. This also means that you'll have to use an absolute path for the DocBook source file, and that you'll only need to pass -t alan-xsl-fopub to inform asciidoctor-fopub about where to find the XSL Stylesheets.
As a reference example, we'll use the Alan Manual PDF toolchain from the Alan Docs project. Study the manual/PDF_BUILD.bat batch script used in Alan Docs to create the PDF version of the Alan Manual. You'll notice that it stores the current directory and then swtiches to the "_assets/alan-xsl-fopub/" folder before invoking asciidoctor-fopub.
Here is an exemplified version of that script, with comments:
:: "manual\PDF_BUILD.bat"
:: --------------------------------------------------
:: This batch is invoked inside the "manual\" folder.
:: The Alan XSL template repository is submoduled in:
:: _assets\alan-xsl-fopub\
:: --------------------------------------------------
:: Preseve current directory:
SET "CURRDIR=%CD%"
:: Define path to DocBook XSL Template folder (this repo as Git submodule):
SET "FOPUB_DIR=..\_assets\alan-xsl-fopub\"
:: Covnert from AsciiDoc to DocBook via Asciidoctor:
CALL asciidoctor^
-b docbook^
-d book^
-a data-uri!^
--safe-mode unsafe^
--verbose^
manual.asciidoc
:: Need to switch working directory to DocBook XSL Template for FOP:
CD %FOPUB_DIR%
CALL fopub^
-t alan-xsl-fopub^
%CURRDIR%\manual.xml
:: Restore origignal script working directory:
CD %CURRDIR%
EXIT /BI couldn't find a more elegant solution to handle an XSL Stylesheets folder used by different documents and inside a repository shared across different machines — but the current solution isn't complicate to use.
For guidelines on how to use the template in your documents refer to the PDF sample files.
The DocBook template and the bundled fonts have separate licenses.
| Font Name | Author | License |
|---|---|---|
| Fira Sans Condensed | Carrois Apostrophe / Mozzilla | SIL Open Font |
| Noto Sans | Steve Matteson | Apache 2.0 |
| Roboto Mono | Christian Robertson / Google | Apache 2.0 |
The LICENSE file of each font can be found inside its subfolder.
The XSL stylesheets inside the /xsl-fopub/ directory are released under MIT License:
The original XSL stylesheets in this folder tree were taken from the "/src/dist/docbook-xsl/" folder of the asciidoctor-fopub project, Copyright © 2013 Dan Allen (MIT License):
They were subsequently edited by Tristano Ajmone on behalf of the Alan Interactive Fiction Development team to adapt them to the styling needs of Alan documentation. The adaptation work may include deleting some of the original files, as well as adding new ones.
The MIT License
Copyright (C) 2019 Alan Interactive Fiction Development team
Copyright (C) 2018, 2019 Tristano Ajmone
Copyright (C) 2013 Dan Allen
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
- asciidoctor-fopub — at GiHub.
- Apache™ FOP (Formatting Objects Processor)
- XSLTHL (XSLT syntax highlighting) — at Sourceforge.
- XSLTHL Wiki — at Sourceforge.
- DocBook 5: The Definitive Guide — (DocBook 5.0) by Norman Walsh, online book.
- DocBook Wiki — (rebooted) on GitHub.
- Wikipedia » DocBook
- DocBook XSL: The Complete Guide — (4th Edition) by Bob Stayton, online book.
- DocBook XSL Stylesheets: Reference Documentation — by Norman Walsh, online book.
- Wikipedia » DocBook XSL
- https://github.com/docbook/xslt20-stylesheets
- https://github.com/docbook/xslt10-stylesheets
- Pro Git book » Git Submodules — by Scott Chacon and Ben Straub.
- Learn Version Control with Git » Submodules — by Git Tower.
- Using submodules in Git - Tutorial — by Lars Vogel.