Balisage Paper: Graceful Diagramming with SVG plus AVTs

1.1 The reuse/parameterization problem

SVG can draw anything with enough paths (or even a single <path> element, raising and lowering the pen as needed). The most salient barrier to creating novel objects and expressing them as such, is the lack of a way to pass in values on each use, that modify that use.

<use> only allows passing a very small set of predefined properties:

Such values are known as parameters, and are ubiquitous in programming, formal logic, math, markup languages, and elsewhere. They greatly reduce space and complexity. SVG uses parameters heavily for its built-in constructs; users just can't have any for themselves. Consider drawing the unit octagon in SVG:

<polygon points="0.9239,0.3827 0.3827,0.9239 -0.3827,0.9239 -0.9239,0.3827
    -0.9239,-0.3827 -0.3827,-0.9239 0.3827,-0.9239 0.9239,-0.3827" />

This is very general: any figure at all can be drawn. However, humans have concepts and terms for many more specific shapes (and coin new ones regularly). Humans also associate many shapes closely with meanings. Regular polygons are the bread and butter of drawing; yet to get them in SVG involves calculating and repeating all those coordinates.

Most users would have to look up how to get from octagon, radius 1 to the set of points just shown, and would not readily recognize the points as being a unit octagon.^[2]

For developers, the verbose representation is very slightly easier to implement:

def polygon_from_points(points: list[tuple[float, float]]) -> None:
    moveto(points[0])
    for pt in points[1:]:
        lineto(pt)
    lineto(points[0])

versus this for regular polygons:

def regular_polygon(cx: float, cy: float, r: float, n: int) -> None:
    offset = math.radians(90 / n)
    moveto(cx + r * math.cos(offset),
           cy + r * math.sin(offset))
    for k in range(1, n + 1):
        lineto(cx + r * math.cos(2 * math.pi * k / n + offset),
               cy + r * math.sin(2 * math.pi * k / n + offset))

The difference is minor for someone writing graphics code, and they must write similar code anyway — it just goes elsewhere. Having regular_polygon also saves on creating and parsing a long string of points, and fits basic principles of software engineering such as Don't repeat yourself, as well as being more compact and less error-prone.

For power users such as someone writing transforms over the SVG, porting data, or looking at the actual values for any reason, the gain is vast. With just points it takes real work even to identify all the octagons, especially given floating-point number issuess. Just grouping objects into meaningful types is a big win [DeRo20].

Many drawing programs retain shape types internally, but don't exported that data. Inkscape makes heavy use of custom options in a separate namespace, which is similar to our approach below.

1.2 The connection problem

The first problem I consider is that SVG lacks a notion of connecting things to other things per se (cf [DeRo14]). It does support referring to objects by ID for re-use, but this cannot be leveraged for this line should end at that object. Actual attachment is implicit, mainly (a) is drawn by the same <symbol> object, and (b) happens to be located nearby.

1.3 The creeping generality problem

Beyond parameters and ports, SVG has no user-accessible constructs for looping or calculation (other than expressing co-ordinates as percentages of the current viewbox). Rendering some kinds of objects requires multiple operations, such as iterating through a points or path attribute. Another common need is calculating locations relative to the enclosing shape (SVG does have a notion of % of bounding box size).

SVG uses all these concepts inside primitives. Making them user-available, however, is a large design task (as the [Bell18] effort discovered), so the SVG limitation is understandable even if unfortunate. Adding such features to SVG has been discussed, but never actually finalized.

SVG does permit embedding Javascript code that operates on the resulting DOM. However, it runs at load time rather than separately for (say) each <use> of a given <symbol>. XSLT can similarly process SVG code, tokenize points or other attributes, and loop or calculate at transform time, writing out more SVG; but it's not especially easy. MVG instead proposes a very much smaller extension.

1.4 Symbol libraries

SVG decided not to include many predefined shapes. Its inventory includes <rect>, <circle>, <ellipse>, <line>, <polyline>, <polygon>, and <path>. Anything can be drawn somehow, but not always descriptively.

Nearly all drawing apps have many more shapes than SVG, many of which are familiar and intuitive for users. I examined the shape inventories of several drawing apps,, primarily graphviz [GVShapes] and [Gans93], draw.io [Draw], Inkscape [Inkscape], and TikZ [TikZ]. I also considered Canvas, LibreOffice Draw, and PowerPoint.

One could never specify all the shapes humans will invent. But some shapes are common, or even what [Pike67] christened emic: they are not merely a sensory experience, but a more abstract categorial value or symbol.

The good news is that given parameterization and ports only a few shapes enable constructing many others. MVG thus defines several new drawing objects, particularly ones that require iteration, calculation, or testing conditions. For example, <regular_polygon sides=""> needs to iterate sides times and do a calculation each time. Others involve subdividing a main shape regularly.

The initial MVG implementation is a Python pre-processor that transforms custom elements, parameterization, and ports into basic SVG 1.0. It will be placed at https://github.com/sderose/mvg, and is freely re-usable. It takes only a few hundred lines.

I have sought to choose parameters for consistency across shapes even though shapes can be specified in a variety of ways. For example, an ellipse can be specified in any of the ways listed below, but I follow the SVG precedent (listed first):

2.1 Prior work

A lot of conceptual ground has been productively explored by others, some of whom I list here. I have tried to build on such concepts, aiming at a most bang for the least buck compromise.

2.2 Parameter replacement

Parameterization requires three conceptual parts: declaration, referencing/use, and passing.

In XSLT, parameters are declared by full-fledged sub-elements of <xsl:function>. For example:

<xsl:function name="clamp" as="xs:double">
  <xsl:param name="val"  as="xs:double"/>
  <xsl:param name="hi"   as="xs:double"/>
  <xsl:value-of select="min(($val, $hi)) => max(0)"/>
</xsl:function>

For MVG we want parameters on most or all SVG shapes or shape-like objects, and we don't have a <function> element already to hand. For this more limited context, the XSLT form seems to me slightly heavy, especially since the existing drawing objects are the "functions". A more compact syntax suffices: Parameters are declared merely by setting them on the object that is to receive them, with the value there as the default. I have shown initial _ so they cannot collide with SVG attributes (of course, such attributes must be added to one's schema for validation to work). It is a simple matter for an application to add the attributes to the symbol table before interpreting the body:

<symbol id="somegon" _sides="4" _fgcolor="red">
    ...
</symbol>
 

Referring to parameters within the function body (e.g., the <symbol> element) exactly copies XSLT's Attribute Value Templates (AVT) syntax, with curly braces and $:

<symbol id="somegon" _sides="4" _fgcolor="red">
    <polygon sides="{$_sides}" foreground="{$_fgcolor}" />
</symbol>

For most cases MVG does not need a whole AVT evaluator, but only two very constrained specal cases. Thus, MVG developers and users need not implement, integrate, or really even understand XPath, XSLT, or AVTs; just those special cases (on which see Section 2.2.2).

Invocation is just using the parameterized drawing element, setting any non-default parameters by using attributes in the usual way:

<use href="#somegon" _sides="8" _fgcolor="blue"/>

bbLeft   bbRight   bbCenterX
bbTop    bbBottom  bbCenterY
bbWidth  bbHeight

expr    ::= "{" "$" name "}"
        ::= "{" "id($" name ")/@" name "}"

2.3 Port and anchor models

<symbol id="foo">
    <port name="top" x="100%" y="0"/>
    <port name="foo-3" x="10" y="25%"/>
    ...usual SVG...
</symbol>

<port name="port2" angle="NE".../>

<port name="foo" segment="5 30%" />

id(objId)/port[@name = 'NE']/@x

id(objId)/@NE.x

<mvg:connector mvg:crossings="bridge|gap|none"...>

4.1 mvg:rpolygon —

This represents a regular polygon by its center, radius, number of sides, and rotation: @cx, @cy, @r, @sides.

4.2 mvg:roundpolygon —

This represents a polygon (not necessarily regular) but with uniform rounded corners. It is specified like SVG <polygon>, but adding @corner-r to represent the radius for the rounded corners.

4.3 mvg:star —

A star polygon, in which alternating vertices have radii of r-inner and r-outer. @cx, @cy, @n, @r-outer, @r-inner. n should typically be even. Based on Inkscape sodipodi:star.

4.4 mvg:arc —

This is similar to ellipse, but can draw just a portion: a circular or elliptical arc. @cx, @cy, @r, @start-angle, @end-angle. SVG has circle and ellipse but lacks this useful case. Drawn clockwise.

4.5 mvg:smoothcurve —

This draws a smooth spkine curve (such as Catmull-Rom) through @points knots. User specifies knots only; preprocessor computes Bézier control points. This can eliminate many cases where SVG ends up containing of large static coordinate dumps being briefer, more perspicuous, and propertly scalable.

4.6 mvg:wave —

This draws basic sine, cosine, and other periodic curves. @x1 @y1 @x2 @y2, @type (sine | square | sawtooth | triangle), @amplitude, @frequency, @phase. x and y represent placement of the origin. This covers the document shape's bottom edge, but is generally useful in technical work. Phase is measured in degrees. Phase 0 must be defined for each wave type, for example sine rises rightward from (0,0). The conventions I have encountered for the others seem to prefer falling from their maximum amplitude.

type permits x- prefixed values for extension, and such extensions must specify their initial phase state.

4.7 mvg:spiral —

Draw an Archimedean spiral. @cx, @cy, @r-start, @r-end, @turns, @t0 (start fraction, 0–1). Subsumes Inkscape sodipodi:spiral.

4.8 mvg:curly-brace —

This represents the curly braces commonly needed in technical drawing. @x1 @y1 @x2 @y2 (endpoints), @depth (bow depth), @orientation (left | right). Consists of three Bézier curves whose control points are computed from the parameters.

4.9 mvg:tile —

This provides simple iteration across x and/or y. Within a bounding box, repeats a child element at regular intervals of dx and dy. For example:

<mvg:tile x="0" y="0" width="400" height="300"
         dx="50" dy="50"
         nx="8" ny="6"
         odd-row-phase-x="0.5">
  <mvg:ngon sides="6" r="20" cx="0" cy="0" style="fill:none; stroke:#ccc"/>
</mvg:tile>

dx/nx and dy/ny are complementary pairs: specify either spacing or count; the other is derived from the bounding box dimension. If both are given, count takes precedence and spacing is computed.

Phase attributes @phase-x, @phase-y offset the whole pattern relative to the bounding box. @odd-row-phase-x, @even-row-phase-x, @odd-col-phase-y, @even-col-phase-y do this for alternating rows and columns in units of dx/dy, as needed for brick, hexagonal, and some other layouts). Rows and columns count from 1. All phase attributes default to 0.

Basic grids fall out as a special case: a horizontal line child repeated at dy intervals, plus a vertical line child repeated at dx intervals. A minor grid can be handled via two nested mvg:tile elements with different stroke styles.

4.10 itransform

This is somewhat similar to <tile>, but instead of simply moving the sub-object across the referencing object's bounding box, it repeatedly applies a transform. This enables positioning things across an affine path.

4.11 coil (from TikZ)

4.12 mvg:block-arrow —

This provides an (optionally filled) directional arrow shape. @direction takes the same values as the angle parameter of <port>s. @shaft-width, @head-width, @head-depth define basic arrowhead dimension. @tip uses the arrowhead types defined below.

4.13 block_arc (from OOXML)

This is basically like arc (see above), but draws the arc twice, separated by @shaft-width and centered at the given r.

4.14 Line types

SVG <line> already provides extensive control over stroke rendering. Comparison with multiple drawing apps suggested only a few additions, all expressed as mvg: presentation attributes applicable to any stroked element (shapes, connectors, or standalone lines):

@mvg:crossings — controls what happens when connectors cross.^[6] Three values: none (do nothing, the SVG default), gap (open a small break in the lower connector), and bridge (render a half-circle hop). Implementations are encouraged but not required to implement all three; the interaction with routing choice is noted in §2.3.3.

@mvg:stroke-repeat and @mvg:stroke-gap — draws multiple copies of the stroke, to make double, triple, or similar lines. stroke-gap control blank space between the repetitions. The entire set of strokes is centered where a single stroke would be centered. The result if this is used with dashed lines is not defined.

@mvg:corner-radius — generalizes SVG's rx/ry on <rect> to <polygon> and <polyline>, with a single uniform radius (no rx/ry distinction). Deliberately avoids the rx/ry names, which mean something different on <ellipse>.

With these additions, nearly all the line-type capabilities of the surveyed apps are covered.

4.15 Arrowheads

Drawing apps also commonly provide libraries of arrowheads, which can attach to the ends of (at least) lines. My review found high overlap on basic forms, but much variation at the edges. A large share of the variations, however, are easily constructible with general SVG and MVG constructs.

MVG defines but does not require, an <mvg:arrowhead> object that works like SVG <marker> but has settings that can produce a wide range of arrowheads. Arrowhead size is governed by the bounding box and transform on <mvg:arrowhead>, just like SVG <marker>.

The attribute are those of <marker>, plus:

Because Unicode has a huge variety of useful arrows (e.g., U+2190–U+21FF), dingbats, and other shapes, MVG defines the convention that if shape is set to a single Unicode character, that character is used. The 0 rotation has the character readable from the perspective on one standing on the line leading up to it, and scaled to fill the <marker> viewbox.

MVG does not address the fact that graphviz allows stacking a sequence of arrowheads onto a line-end.

Several other arrowhead types I found are addressable by the Unicode-character alternative:

5.1. Connectors

Connectors do not require a new element, but are simply a useful combination of <line> or <polyline> with parameterization, ports, and the routing pragma. For example:

<mvg:line obj1="id1" port1="e"
              obj2="id2" port2="w"
              routing="direct"
              linetype="dashed"
              arrow1="none" arrow2="filled-triangle">
</mvg:line>

<text> objects to serve as labels may be attached to a connector
just as they are to other shapes.

5.2 Labels

SVG <text> objects benefit from parameters and ports, and can simply refer to the object to which they attach instead of setting x and y position manually. It would instead be feasible to express the attachment the other way. However, that would need to apply to many (all?) shapes and grouping objects, and would need a way to do either raw strings, or objects with more structure such as complex formatting properties or multiple <text> parts.

<text> objects in MVG can define ports just like other objects. By default, their ANCHOR port is placed at the ANCHOR of the referenced object (ANCHOR defaults to the center of the relevant bounding box).

5.3 Decorators

A decorator is the MVG term for a shape (perhaps a <symbol> or <marker>) attached to a host shape to create a new (sub-)class of shape. For example, the commonplace folder shape can be constructed (or construed) as a rectangle with an extra rect or round-rect placed somewhere along the top.

Given MVG as already described, decorators are simply a concept; no additional elements are required. Both shapes can be drawn by an enclosing <symbol> or similar, or one can be attached by setting its location using a port or coordinate reference to the host shape. The decorator's own ANCHOR port aligns with the host's target port, and the decorator inherits the host's coordinate system for rendering purposes.

Decorator positioning reuses the port-location grammar of §2.3.1: @attach names the host port; @anchor names the decorator's own contact point (default: anchor port of the decorator, which itself defaults to center). The @scale-lock attribute (§2.2.3) prevents decorators from scaling disproportionately when the host is resized.

No new element type is required. A decorator is any mvg:symbol instance referred to from an @attach attribute on <mvg:use>:

<mvg:use href="#tab" attach="n" anchor="s"
         mvg:width="{$tab-w}" mvg:height="{$tab-h}" />

The preprocessor resolves the port coordinates and emits an SVG <use> at the computed position.