How it works
Read the config
First, Computer Words reads your config file, which tells it which Markdown files you want to include, and in what order. See Defining table of contents structure with
file_hierarchy for details.
Parse the Markdown files
Then, each file is parsed into a tree, with a
CWDocumentNode as the root. These document nodes are then added to a global
Each node has a globally unique ID and a name (i.e. type, kind, label).
This is all stored in a
CWTree object, which allows you to access and mutate the tree in the next step.
Then we apply a processor library to the graph. A library is a mapping of
node_name -> [processor]. A processor is a function
process(tree, node) which mutates the
tree in response to visiting
For example, here's a processor that reverses all text:
The library is applied by traversing the tree in post-order (children before parents). That way, when a node is visited, its subtree is guaranteed to be complete.
If a processor mutates a child of its node, that node is marked "dirty". After each post-order traversal of the whole tree, if any nodes are dirty, the tree is traversed again, and only the dirty nodes' processors will be run.
Supported mutations are documented on
Once the processors have been run until there are no more dirty nodes, it's time to do something with the complete tree.
This is where a writer takes over. The job of a writer is to turn a
CWTree into human-readable output of some kind.
The only writer available right now is the HTML writer. It works by defining a visitor for each node name, where each visitor writes the opening tag, visits its children, and then writes the closing tag.
Since few people will be writing writers, this is the least well documented part of Computer Words right now.