XML Workflow: Variations. So Many Variations

Still not giving up on the A-Z Challenge! Just going really slowly this year. I utterly failed on time, but will complete the series!

I’ve been trying to wrap my head around just how many build variations I can have. There are so many variables that can go into how I build out my data sets and documents.

• System, the broadest definition of my data sets. Pathfinder 1e (pf1), Pathfinder 2e (pf2), Low Fantasy Gaming (lfg), Random Table Roller (rtr), among others. I even have a ‘No System’ (nosys). Each has its own taxonomy, and their own data sets and domains.
• Data Set, a subset of the data in the system. Pathfinder 1e has ‘prd’ (Pathfinder Reference Document), ‘pzo’ (Paizo-not-PRD), and ‘3pp’ (third party publishers). These are used mostly to manage data files used to build up domains.
• Domain, a collection of data sets within the system. Pathfinder 1e has ‘prd-only’, ‘3pp+prd’, ‘prd+pzo’, among others.
• Build, defining how the content is presented, and how complete it is. I often have ‘RAF’ (Rough and Fast), ‘WIP’ (Work in Progress), and Final.
  • RAF is basically just the text content.
  • WIP includes some of the value-add components, including the TLDR blocks and the dependency diagrams.
  • Final has everything.

Between them, I have different versions of the various Echelon Reference Series documents, based on Domain and Build.

And now I’m adding a new variable.

• Layout, defining color and style elements to be used in presenting the content.

This means I have three choices to make for these documents: Domain, Build, and Layout.

Let’s see how this will work.

Layout Files

Today, I have only one layout per system, defined in the taxonomy file. This is manageable, even if it does mean a long rebuild when I change formatting instructions. To reduce the build time I’m splitting formatting instructions out, which also allows me to have multiple layouts.

This is going to make my Makefile even bigger! But I think the update-config script won’t be too much more.

Let’s see the various build targets. I’m going to ignore the individual content files for now because they don’t depend on any variations. The aggregation files (index, master) and collation (package) and successors do.

• file.*.wml aggregate information for a data set: files-pf1-prd.index.wml has all index entries for the PF1e PRD sources. Like the individual content files these are building blocks, just bigger ones. Parameters are (system, dataset).
• master.*.wml bring all data sets in a domain together: master-pf1-prdpzo.*.wml has all the information for the PRD+PZO domain, master-pf1-prd.*.wml has all the information for only the PRD domain.
• List, XlsX, AccDB collect all the data objects (feats, spells, etc.). Same rules as master.*.wml.
• LinkGraph aggregates information to build out the dependency graphs. Still data driven, does not need formatting information yet.
• Package collates material from a chosen domain… but has little to do with presentation. It puts things in a particular order, but does not draw or print anything.

So far, so good. No changes needed.

The next ones will need some changes.

• Dependency graphs, up to their inclusion in the PubTeX file, can get by with a single layout definition. I want to see color, but these are not intended for publication: I can use a single definition. I’ll still capture it in a Layout file, but I need only one.
• PubTeX is the biggest application of style information. Document headings and game object headers will have drawing styles (node shapes) and colors. Package has all the objects, PubTeX orders the content with its rendering instructions, TeX actually translates to LaTeX for printing.
  • All content from the specific Package file will have Layout information applied.
  • Any content from the aggregate Position file will have Layout information applied.

Okay, it looks like I’ve really got only two places that need Layout information. Now to figure out how to capture in Makefiles.

Makefile Changes

There are several Makefile changes needed.

• Add Layout stage to the workflow. After some consideration, I’ve decided the Layout file will be easiest to build after the Group stage. The content will be almost the same as as the taxonomy file, except it’s presentation information rather than classification. The taxonomy Helper file is flattened for ease of use for its intended purpose, here I want the hierarchical file.
  • New stage added to the make-rules.xlsx file.
• Single layout is simple, just add a file <sys>-layout to the build, much like <sys>-taxonomy. In fact, this is trivial… but allows me only one layout per system.
• Multiple layout needs me to add another layer to the update-config script, much as I have for domains. Slightly more complex, but not difficult.

Okay, okay… it turns out the entire thing is less complicated than I thought it would be. Sometimes just the act of writing it out clarifies things.

Now to see if I’m right.