I’ve been procrastinating on this post, mostly because I had to get the content straight in my head first.
In other words, overthinking. Again.
One of the stumbling blocks I’ve faced with this whole overhaul has to do with how to efficiently build it.
When you’re coding one thing, you can code directly to your needs. You don’t need to take into account a lot of ‘what ifs?’
What I’m doing here means having several sets of options. The code for individual sets of options isn’t that bad. Managing it all and keeping things from getting out of hand can be.
What do ‘rules’ have to do with this? I need to understand the transformations so I know what rules to add to my Makefiles.
The Options In Front of Me
Let’s look at the variety of options I need to deal with. How I (re)organize things will have a big effect on how i build out.
Existing Options
The first set of options, I’ve always had: what data set to include in each book. The Echelon Reference Series has several variations, include ‘PRD-only’, ‘3pp+PRD’, ‘all’ (which I’ve not published).
The second set of options got conflated with the first. ‘src’ builds included the title of the book each game element came from. This looks like it can be contrary to OGL v1.1 (titles are typically Product Identity, PI), but I don’t publish these. ‘dev’ builds are like ‘src’, and include some internal information such as object IDs and the like.
Until now, the two sets of options above were lumped together, with ‘src’ and ‘dev’ being activated using flags. This led to a fair amount of logic in the transformation scripts, deciding what and how to print things.
New Options
Now we get into options I didn’t have before.
First, and one of the biggest is page geometry. Everything I’ve published has been letter paper (8.5″x11″), two column. I want to explore a Tufte-style layout and digest (6″x9″) layout.
Second, and needed for the first, more options when it comes to document headings. Right now they’re all the same, and fairly heavy so they can stand out given the game object headings. Tufte calls for a much lighter style in the headings, so I’ll need to have more choices.
Third, ‘printer friendliness’. I’ve been using solid-fill headers for game objects for… quite some time now. I’ve experimented with printer-friendlier versions and they look pretty good to me. I won’t want to have them on all the time though, so this will need to be configurable.
Fourth, object header shapes. Right now they’re all tcolorbox objects (drawn as fancy rectangles). I see three general header types, usable for both game objects and document objects. All three will themselves be configurable.
- Display tcolorbox headers, which are what I use today.
- Display text headers, which are what LateX has built-in and I’ve been avoiding… but don’t need to.
- Inline text headers, where the header is inline with the paragraph text. In Pathfinder 1e, this is how class features and subfeatures (such as rogue talents and rage powers) are typically shown.
Fonts, colors, breaking rules, and a few other things can be set for each.
How To Implement
Here’s where it gets tricky. Or so I thought.
LaTeX Macros/Environments
Through the power of abstraction, it looks like I can have document and game object headers conform to an interface. For the rest of this post I’ll use ‘object’ generically to apply to both. I’ll qualify with ‘document’ or ‘object’ if I need to be specific.
Object headers
- have a name/title
- may have a ‘stat block’ (content varies by object type)
- have a few specific fields that get handled specially
- level/point cost
- types
- prerequisites/cost/restrictions
- object content (the spell descriptive text, skill description, and so on; may contain child objects)
- may have a ‘footer block’ (as seen with Pathfinder 1e magic items)… I haven’t this often, but it’s a style choice I want available.
These objects are all structurally similar, even if their content is wildly different. I can build to a single template, all I need to know is what to put in each piece. From there, the template itself can figure it out.
That is, I can have a feat generate LaTeX something like
\begin[level=3,types={Item Creation},id={feat.item-creation.prd.crb}]{egdDisplayBlock}{Brew Potion}{{\bfseries Prerequisite } Caster level 3rd}
% feat description here
\end{egdDisplayBlock}or
%printer friendly
\begin[level=3,types={Item Creation},id={feat.item-creation.prd.crb},framecolor=egdBrownIV,fillcolor=white,titlecolor=egdBrownI]{egdDisplayTCB}{Brew Potion}{{\bfseries Prerequisite } Caster level 3rd}
% feat description here
\end{egdDisplayTCB}or
%printer hostile
\begin[level=3,types={Item Creation},id={feat.item-creation.prd.crb},framecolor=egdBrownI,fillcolor=egdBrownIV,titlecolor=egdBrownI]{egdDisplayTCB}{Brew Potion}{{\bfseries Prerequisite } Caster level 3rd}
% feat description here
\end{egdDisplayTCB}They’ll each do the right thing, despite having almost exactly the same input. The only significant difference between them, if we ignore the color details, is the name of the environment.
This transformation actually will be simpler after the change than it is today… if I get the next bit right.
Makefiles
When I do know, or need to know, what?
Looking over the existing transformation workflow, everything up to ‘Package’ stays the same. The Package stage collects all the document content, but does not need to arrange it for presentation. For instance, Echelon Reference Series: Cleric pulls in all domains, and for each collects any supplementary information:
- TL;DR blocks
- supplementary blocks (there can be a table showing how each subdomain modifies the domain).
- Subdomains of the domain.
Each document domain (system and data set collection) pulls from a different master data file and ensures the right content. In this new model, it does not mandate how they are displayed.
Instead, the PubTeX stage seems the natural place for that. The content is the same, but can be presented in several different ways… including
The diagrams are picked up from the Position file for the document domain, and can be drawn in different styles… or at least, different color sets. These color sets will be based on the target object type, so it still fits the style files.
Building the layout file is going to depend on the taxonomy file, at the Group stage, not the Helper stage. I need to taxonomy hierarchy. So somewhere between Group and PubTex… I think I’ll call them ‘layout’ files.
I could make them each XSLT files, but that would be a headache. I don’t want to merge local elements with the taxonomy file. I’d rather keep the layout details outside my XSLT, and have only a single XSLT file for the stage.
TL;DR
All of that boils down to:
- Adding new LaTeX environments for different header types:
- Display tcolorbox
- Display text
- Display inline
- Adding new stage the the XML workflow, ‘layout’, that maps layout rules to taxonomy elements. This file will be applied during the PubTeX phase to package objects using the header types above. The layout file will describe how to build the object for presentation, including fonts and colors. The layout file will also affect the color and presentation of diagrams, but not node or edge placement.
Closing Comments
This is what it looks like when I think in the open. I’m sorry you had to see this, it took a long time to distill down to such a simple answer.