XML Workflow: Groundwork for Next Steps

I have a strategy and updated workflow diagram, but now to figure out the actual plumbing.

This post is mostly me thinking out loud, so don’t feel bad if it doesn’t make sense yet. That will come.

Better LinkGraph

First, I need better metadata in my diagrams.

Known:

• Every diagram is based on a game object. Whether a feat or a prestige class or whatever, all are ‘d20:object’ elements.
• Each node is based on a game object.
• Each game object has a ‘business key’, an XML ID that looks like ‘object-type.object-name/parent-type.parent-name:publisher!source”. For instance, ‘feat.alertness:prd!crb’ (doesn’t have a parent, so that bit is left out). A trifle unwieldy, but works almost always (99%+ of the time).

I will need for each diagram and node (i.e. for each object):

• A surrogate key of unique value by game object and consistent size and value within a build.
  • The surrogate key will be used in rendering for placement and to simplify node definitions.
  • The surrogate key does not need to persist between builds.
• Rendering instructions (TikZ/DOT style/color, tweaks) to be applied to each node.

The simplest approach is to assign a surrogate key after loading the data store in LinkGraph stage. I was assigning to diagrams and nodes later, but it’s easier to do it on object load. I’ve been using “‘n’ plus a four-letter ‘number’ based on object position in data store. When identifying the nodes and edges in each diagram, these fields can be attached to the diagram and node elements.

Rendering Pictures

After the diagrams are specified in the LinkGraph stage, they get output to DOT format. The output of this operation is stored in the ‘Pics’ file, that identifies the file paths and object IDs. This needs to change a little.

• Content can be simplified. Each entry in this file can be reduced to:
  • Object business key (XML ID) needed.
  • Path to file (prefix directory and extensions can be added when needed).
  • Object surrogate key (five-letter string) not needed, but I may keep it anyway.
• Generated output files for each diagram:
  • DOT file with full detail (‘pretty’, or at least human-readable diagrams). Should use DOT rendering instructions (colors). HREF field for hyperlinks is to SVG file (the only format that uses hyperlinks).
  • DOT file with minimal detail (surrogate key and business key. May use DOT rendering instructions (colors). HREF field contains object business key (won’t be used as a link but is a convenient place to cache). HREF might also contain formatting information from object definitions and taxonomy.
  • JSON file from minimal detail DOT file… which looks like it will contain more than I originally expected.
    • I can make another pass when rendering to TikZ, but I will have already had the information in hand. Probably easier to capture at that time than to do so later.
    • I could use SVG, but I really don’t want to spend the time deciphering it. The JSON format will be quicker and easier for me.
  • Position file that aggregates the parsed JSON file details so I can render the diagrams using TikZ.
    • Each diagram from the LinkGraph file will have a diagram here.
    • Each object referred to in a diagram will have a node definition (surrogate key, business key, TikZ rendering details). These node definitions will be shared across the build.
      • Diagrams explicitly defined (i.e. manually crafted) will supersede automated diagrams.
    • Diagram elements will have
      • A matrix identifying the node in each cell, if any, and col sep and row sep.
      • A list of edges and edge options, connecting the nodes.

That’s a lot to think about.

Override Information

I mentioned already that manually crafted diagrams supersede automated ones. I don’t want to have to do that when I just have small tweaks.

• For nodes, often I’ll want to just adjust the width slightly. This will usually be global for the object.
• For edges, most often I want to change how the edges leave and enter nodes in a specific diagram.

It will be easier overall to put these in a common location. Updating all the underlying objects would get arduous. This is much the same reason I have centralized TLDR files.

Integrating the Results

Once I have the final diagram specifications (automated plus tweaks, or manually created), I can apply them in my books. This should be simple.

• Look up the diagram by object business key (XML ID) — manual first, then automated.
• Insert into PubTeX file.
• On converting to LaTeX, convert XML diagram to TikZ format.

Simple, but many steps to get there.

Closing Comments

Despite the number of things I need to do, none of it should be particularly difficult. Having the steps figured out first will help me.