Almost all the content in my publishing workflow is created using Word files. I use styles and some typographical conventions to make it possible for scripted automation to extract meaning from the word files. This section describes how various aspects of that work.
I’ve also recently started working with Excel files as a source, but those are mostly specific to purpose and table-oriented, so don’t really depend on formatting. For instance, in a denaming workbook I might have each worksheet contain words related to a particular theme (deities or iconic characters or places) and how to replace them. Each worksheet is likely to have two columns of content, but I can imagine augmenting this with information and other notes that may be useful to a human but ignored by the denaming process.
Word Styles
The workflow makes heavy use of Word styles to indicate the content type. There are several major groups of styles.
Heading Styles
These replace the built in heading styles. Names originate with LaTeX macro names.
While ‘book’ and ‘issue’ are the normal starting points for published documents, the formatting engine does not require these elements — I can create a PDF containing a single chapter, with no other ‘book’ content or dressing.
doc2Series does not have an outline level in Word for the same reason Word does not give ‘title’ style an outline level: in the uncommon event it is used, it’s right at the start of the document, and there is only one. The workflow does give it an outline level so it will be placed appropriately when building the document hierarchy.
Style | Word Outline | Workflow Outline | Description |
---|---|---|---|
doc1Series | — | 1 | A series of books. Mostly used to set trade dress for the series, no specific document output. (May investigate cross-book indexing though.) |
doc2Book | 0 | 2 | Normal starting point for a book |
doc2Issue | 0 | 2 | Normal starting point for a periodical such as a magazine or journal. |
doc3Article | 1 | 3 | An article such as would be found in a magazine. Might be used in a book of essays. |
doc3Part | 1 | 3 | A collection of chapters within a book. |
doc4Chapter | 2 | 4 | Chapter with a book or part (not all books have parts). |
doc5Section | 3 | 5 | Section within an article or chapter. |
doc6Subsection | 4 | 6 | Subsection within a section. |
doc7Subsubsection | 5 | 7 | Subsubsection within a subsection. |
Table Styles
Tabular information tends to be presented in much the same manner (a table is a table), but because they are well encapsulated, the workflow (ab)use tables for many purposes. Unstyled tables are treated as general purpose tables (equivalent to TableEgd style), but still the workflow has TableEgd style to indicate the table has been specifically reviewed and configured.
‘Colors’ are presented as plural because typically they are presented in two tones, a lighter tone for the table body and a slightly darker tone for headers and footers (header and ‘total row’). Table with ‘borders’ have a thick border in an even darker color.
‘Bordered’ tables actually are single-column tables, and I’m using ‘tables’ just to encapsulate the content, often so I can move it elsewhere (sales copy, sidebar; textboxes tend to stay put). These ‘nontabular tables’ may themselves contain tables or other block items.
Style | Color | Borders | Description |
---|---|---|---|
TableEgd | Browns | no | General purpose table. |
TableEgdDiagram | Greys | no | Aide to render TikZ/PGF diagrams. Most diagrams can be rendered in a matrix (nodes in cells, edges connecting nodes), so this is a means for doing so. |
TableEgdLevels | Oranges | no | Summary information for class features and subfeatures. Typically not rendered in the object directly, instead are used to create the class summary table. |
TableEgdListSpells | Purples | no | Lists spells and levels for objects such s domains. General spell lists are handled differently. DEPRECATED, use reflink connections instead. |
TableEgdSales | Oranges | yes | Sales copy to be presented on the back cover. |
TableEgdSidebar | Purples | yes | Sidebar, usually to be floated to another position. |
TableEgdStatBlock | Blues | no | information to be presented in tabular form in a stat block (mixed with ‘d20Abstract’ paragraphs). |
TableEgdSummary | Greens | no | Most often a class level table, showing what a class gains at each level. Obsolete, changes to the float engine and stat block generation make this redundant. Now I just use TableEgd. |
TableEgdTextbox | Browns | yes | ‘Read aloud’ text box, such as might be used in an adventure module. |
List Styles
There are three broad types of lists, plus one other that is a bit of a kludge. In all cases the lists have levels 1..6, so I’m abbreviating with ‘ListStyle#’ rather than listing all 24 variations.
It is possible to mix and match entries: you can have an unordered list as a sublist of an ordered or enumerated list.
Style | Description |
---|---|
List# | Enumerated list of (label, content), such as might be used for a glossary. The first element in list item is treated as the list item label. List item labels are most often a different format, so this is easy, but if needed there is a ‘label’ inline style that doesn’t change the format but marks the list item label. |
ListOrdered# | Numbered list, such as a list of instructions. |
ListUnordered# | Bullet list, such as a shopping list. |
ListContinue# | A bit of a kludge, this list is only ever used as a sublist (ListContinue1 is never used) for multi-paragraph list entries. |
Game Object Styles
Style | Word Outline | Workflow Outline | Description |
---|---|---|---|
d20Section15 | — | 20 | Section 15 entry, lowest rank so it doesn’t accidentally capture an actual game object. |
d20#Declaration | 4+n | 7+3n | Identifies the type of the objects (overrides, refcopy, etc.) that follow, such as ‘feat’ or ‘spell’ or ‘class’. |
d20#Object | 4+n | 8+3n | Actual game (business) object being defined and described. |
d20#Override | 4+n | 8+3n | Contains formatting instructions for matching objects, overriding the automated layout. Most often used to adjust spacing and column/page breaks. Not included in the definition because I might need a column break for fireball in this document and this document only, it should not be part of the object definition. |
d20#RefCopy | 4+n | 8+3n | Instruction to pull a copy of the referenced object to this location in the document. For instance, this can be an instruction to pull the fighter class definition here, or it could be an instruction to copy all fighter archetype definitions here. |
d20#RefLink | 4+n | 8+3n | Instruction to pull a link to the referenced object to this location in the document. For instance, domain spells use this, as do spell lists in general. |
d20#Section | — | 9+3n | Inserts the named section heading into the object (such as ‘Domain Spells’ and ‘Granted Powers’ in a domain). No outline level in Word because I won’t navigate on this, but does include an outline level in the workflow so hierarchy can be built properly. |
d20#Sidebar | 4+n | 8+3n | Content such as might be used in the Sidebar Reference System. Haven’t decided if this means “use this text when presenting SRS for this item” (i.e. has all the content to put next to this item) or “use this text when this item is flagged for inclusion in another object’s SRS”. |
d20#StatBlock | 4+n | 8+3n | Information to be added to the stat block of the indicated item. Not yet used. |
d20#Supplement | 4+n | 8+3n | Supplementary information to be added to the indicated object. There actually are five potential locations: before the object is output, start of the object (after stat block and TLDR), middle of the object (after object content but before included content), end of the object (after any included content), after the object has been output. |
d20#Tags | 4+n | 8+3n | Assigns tags or keywords to an object, such as marking a feat with ‘dodge bonus’. Done outside the source documents to centralize the file management. Might make tagging a workbook item instead. |
d20#TLDR | 4+n | 8+3n | Summary information about what an object is or does. Object text has the details, this can be very abbreviated. For an odd value of ‘abbreviated’, since sometimes it rolls up the effect of several objects, such as when one object is defined in terms of how it changes a base object (alchemist discoveries, especially mutagens, do this a lot). |
Other Block Styles
There are other block styles (i.e. same level as paragraphs, lists, and tables) that don’t appear in the navigation pane. Most often these block styles package information for presentation with a superior object.
Style | Description |
---|---|
d20Abstract | Stat block content, such as for a spell or monster. |
d20AbstractGroup | Heading within a stat block, superior to stat block. |
d20Attribute | Metadata about a document or game/business object. Used to be stored as attributes in XML, now are egd:meta/* elements because some of them have non-singular cardinality. |
d20Brief | One-liner such as at the top of a feat or in a spell list. Often more flavorful than definitive (as a TLDR is). |
KJDComment | Typically commentary about why I made certain decisions, such as when including or excluding specific content, or changes made to text to correct an evident error. For example, a creature with a bonus ‘Improved Unarmed Attack’ feat (the feat name is ‘Improved Unarmed Strike’). |
LaTeX | Embedded LaTeX instructions… I try to avoid them, but sometimes needed. |
LaTeXIncludeIf | Instruction to include a TeX file only under certain circumstances. Deprecated, appears obsolete (I see no sign it’s actually used anywhere). |
Inline Styles
There are some inline (“character” styles in Word, as opposed to “paragraph” styles) I use.
Style | Description |
---|---|
Label | Used only in enumerated lists, to force a separate element. Most often an enumerated list uses different formatting for the label (such as bold or italics) and this style isn’t needed, but sometimes the label uses the same formatting and cannot be differentiated automatically. |
Ref | Reference to an existing object. If the object name is unique I might stop here, but sometimes I will add hints such as ‘{weapon quality}’ to resolve conflicts. For example, bane could be referring to the spell or to the weapon quality, but ‘bane{weapon quality}‘ is explicit. Some reference types are common enough they have their own styles (see below). |
RefNotRef | Marks text that might be picked up as a reference through other processes as being not actually a reference to another object. “Fly, you fools!” shouldn’t connect to the Fly skill! |
RefSidebar | Identifies a reference sidebar to be presented with this object (probably in the sidebar, possibly as a page footer). Not yet used. |
RefClass | As ‘Ref’, but with a ‘class’ hint. |
RefClassFeature | As ‘Ref’, but with a ‘class feature’ hint. Not often used. |
RefFeat | As ‘Ref’, but with a ‘feat’ hint. |
RefSkill | As ‘Ref’, but with a ‘skill’ hint. |
RefSpell | As ‘Ref’, but with a ‘spell’ hint. |
Text Markup
Game objects use special markers in the heading to indicate metadata about the object. This started by parsing ‘types’ on abilities, such as “Wild Shape (Su)” and grew from there. When I introduced attributes more generally I could have moved this metadata to there, but it was a habit now and it is concise and convenient… if you know the markers and what they mean.
An object can inherit many of these via the declaration or taxonomy. For instance, the archetype taxonomy entry is written ‘Archetype {{class }}race’ and all archetypes will inherit modRefDecl=class and altRefDecl=race (unless they override it), and the archetype declaration starting a set of fighter archetypes would be written ‘Archetype {fighter’ to provide the modRefName.
Mark | Field | Meaning |
---|---|---|
name | All text up to the first marker becomes the object name. | |
: | diff | Differentiates objects with the same names. Deprecated, all object IDs now include their source code explicitly. |
( | types | Feat types, Ex/Sp/Su, Sneak Attack Exclusive, etc. |
(( | ||
((( | ||
) | ||
)) | ||
))) | ||
[ | level | Lowest level a character is likely to get this, based on base attack bonus, skill rank, character or class level, or base saving throw requirements. Does not consider the level a character can meet other requirements such a feats, castable spells, or class features. |
[[ | costToGain | How much the item costs in build resources, such as evolution points. |
[[[ | costToUse | How much it costs to use the object. (Not yet used.) |
] | baseRefName | Name of ‘base object’ this is a variation of. For instance, Mythic Alertness feat is an instance of the Alertness feat. May also be used for spells that are ‘just’ different versions of the same base spell (summon monster spells come to mind). |
]] | baseRefDecl | Type of ‘base object’ this is a variation of. |
]]] | baseRefId | Specific ID of the referenced base object. Rarely used, only when ‘baseRefName baseRefDecl’ is not sufficient to identify the base object. |
{ | modRefName | Name of object modified by this object, such as when an archetype modifies a base class or a subdomain modifies a domain. |
{{ | modRefDecl | Type of object modified by this object. |
{{{ | modRefId | ID of object modified by this object. Rarely used. |
} | altRefName | Additional (‘alternate’) object this object is associated with, providing context for the modification, such as the race associated with a racial class archetype. Might use to associated feats with styles. |
}} | altRefDecl | Type of additional associated object. |
}}} | altRefId | ID of additional associated object. Rarely used. |
< | decl | Object type, overrides preceding declaration. Not often used, but sometimes applied when there are several objects of different types in sequence (i.e. five magic items all of different types). Deprecated because it is so uncommonly used, use an attribute instead. |
<< | ||
<<< | ||
> | parentName | Name of parent object, used to insert new object into an existing object. Deprecated, I think it’s never actually been used. |
>> | parentDecl | Type of parent object. |
>>> | parentRefId | ID of parent object. |