More About Algorithmic Markup

The Graphviz plugin accepts an unusual dialect of markup which is really a computer algorithm for visiting pages and drawing what it finds. We'll explain this in simple terms that should get one going quickly.

It is good to start the description of any new computer language with instructions for printing "Hello World".

This shows the name of the current page as a single node.

Create a page named Hello World and add a Graphviz plugin with this markup. This says, pay attention to where the plugin is at, HERE, and add a NODE to the graph representing that place.

Notice that the second line is indented. We normally indent with two space for each new level of indentation.

The first line says this markup uses the special markup keywords we describe here to find places in the wiki and draw pictures of them. Digraph means "directional graph" with arrow heads on the lines. A graph consists of shapes and lines which are called nodes and edges in the Graphviz vernacular.

Let's say we add some links to the hello world page by writing a paragraph which links to pages that might be named Peace and Love. Internal links appear in double-square brackets.

We don't need to actually create these pages in order to say that there are links to Peace and Love. Likewise if we want to show the links present on any page we can do that with the LINKS keyword that finds internal links enclosed in double-square brackets.

If we revise the Graphviz plugin on the Hello World page to add the LINKS keywords, then our graph will show arrows from Hello World to Peace and to Love. There will be three nodes and two directed edges.

We can draw undirected graphs where the edges don't have arrowheads. Notice two changes.

We can ask that identical edges not be duplicated in the diagram even if we add them multiple times.

Graphviz orders nodes into ranks top to bottom based on the edges that connect them. Change this option first thing to have it draw left to right. This works better for diagrams that are wider than they are tall.

Graphviz has other layout algorithms that may be useful in special cases. If a diagram has no important top or bottom a mass and tension style layout may work better. pdf

Each time we indent our keywords further establish a new context for extending our diagram. Each time we say NODE or show an edge, ->, we are adding to our diagram based on where we are right then.

The LINKS keyword finds links that might lead new places. We can explore those places by indenting more keywords under the LINKS.

Each keyword establishes the context for the keywords indented underneath it. HERE says as as long as I am here, I might as well fetch the page here. If there isn't a page yet, HERE skips the markup indented underneath it.

HERE NODE will only draw a node if there is a page by the name established in the context above it.

The BACKLINKS keyword searches the neighborhood for pages that link to the current context.

One can move through a wiki without drawing nodes and edges based on what it finds.

You might see keywords arranged this way if the the algorithm were to find pages a couple of links away and then start drawing nodes and edges. But without drawing eventually, what's the point of traveling.

A simple reminder: Lines that include NODE can draw, those without can't. This rule is helpful understanding where to add shape and color.

We can be more specific about where on a page we are looking for links. Between the time we fetch a page with HERE and look for links with LINKS we can choose some subset of paragraphs here where we want to look for links. Maybe that paragraph begins "See also ..."

This variation of markup we have already seen will look for links only on paragraphs here that begin "See also".

The / / marks bound a "regular expression" string match where ^ means starts-with and the rest are required characters. See RegExp Metacharacters

The Graphviz input language, dot, offers many options for shape, style and color of both nodes and edges. We include these in markup between lines that begin with keywords. Options applying to nodes or edges begin with these words in lowercase. language options

We often begin by choosing square shapes filled with pastel colors.

As we link further into the wiki we may choose another color to emphasize our new kind of pages.

Notice that HERE creates a new context and we begin that context with the dot color we choose for new nodes encountered at that level.

Our favorite fillcolors are palegreen, lightblue, bisque and gold. If you find a Graphviz diagram you like, double-click to edit and see what shapes and colors it uses.

Graphviz has its own rules for how options extend over the nodes subsequently created. We accommodate it by running all of the keywords at one indent before entering and processing keyword contexts at deeper indents.

Start every new diagram with just a few lines of markup just as we have here. Test this in place with pages and links you understand. Avoid pages with too many links or add WHERE keywords to select only the important ones.

Add new keywords in the context of ones you already understand. If new keywords don't work at first try simpler ones just to get something to draw. If things get really messed up, fork an earlier working version from Journal history.

If you think you have a diagram working, try dragging it into new locations in the federation and see how it works there. If a drawing fails completely look for console.log messages in the browser's debugger.

It can be confusing to get colors to apply correctly. Try adding a distinguishable shape or color at each indent level and then removing those that seem unnecessary.

A more complete list of keywords with more precise definitions can be found in Graphviz Markup Semantics. Start here first.

You can look through the federation for where Graphviz plugins are used and then try to make sense of the markup that works for them.

Algorithmic markup is improving regularly. Be sure you have a recent release of the plugin.