I've finally put together some code that makes it much easier to translate notation into HTML. I've used it to typeset a bunch of things already and it has greatly improved my efficiency in this regard. Briefly, here's how it works:
- Techniques are collected into Analytic Martial Arts Notation (AMAN) documents. The documents are XML-based and optimized for hand-composition.
- Each individual technique has a notation block which represents the notation proper.
- The entire thing can be run through a set of typesetting scripts to produce HTML suitable for stand-alone publication or pasting into a blog.
Details of the document format and notation syntax follows.
Document Format
Here's a small sample document which execerises all the features I've developed to date:
<doc>
<title>Title</title>
<commentary>
A Demonstration of the AMAN document format.
</commentary>
<actions>
OB = Outward Block
SK = Snap Kick
</actions>
<regions>
T = Temple
S = Stomach
</regions>
<definitions>
<definition name="block_kick">
SK,,
OB,,
</definition>
</definitions>
<techniques>
<technique>
<format columns="2"/>
<englishname>Technique 1</englishname>
<phonetic>TEK NEEK WUN</phonetic>
<commentary>
A technique demonstrating the features of AMAN.
</commentary>
<notation>
RP,,,1
block_kick
,"Bow",
</notation>
<notes>
<note id="1">
Extended explanation of annotation 1.
</note>
</notes>
</technique>
</techniques>
</doc>
The document is enclosed in a single element, "<doc>" in this case, which is required for compatibility with XML::Parser. This outermost element is ignored and can be whatever suits your fancy. Each document has the following attributes:
- title: A descriptive title.
- commentary: An optional, free-form text string describing the overall contents of the document.
- actions: A newline-separated block of <action symbol>/<description> pairs. This is one of the places where I've broken the XML standard a bit in order to make hand-composition easier.
- regions: Like the actions element but contains <region>/<description> pairs. This element is optional since a collection of techniques may not make use of region specifiers.
- definitions: An optional element enclosing one or more definition elements.
- definition: The document may optionally include one or more definitions. These are named chunks of notation which can be interpolated into the techniques defined within the document. This feature is generally designed to assist with the transcription of longer forms which may have recurring sequences of moves.
- techniques: Encloses one or more technique elements.
technique Elements
Each technique element describes one technique, where "technique" can be read as "sequence of moves which the author wants to group together for whatever reason". A technique may be as short or as long as necessary and has the following elements:
- format: An optional directive use to pass formatting hints on to whatever typesetter you're using. The one which I've written, AMAN::HTMLFormatter, will produce a single column per notation block when columns equals 1, otherwise it produces a two-column, side-by-side layout.
- commentary: An optional, free-form text string providing commentary on the technique.
- notation: A block of AMAN; see description below.
- notes: An optional element enclosing one or more note elements.
- note: A free-form text string with associated ID. This was specifically developed as a footnoting mechanism with the ID referring back to one or more lines in the associated notation block via annotation column. However, there's no enforcement of this relationship, so this is a good place for general notes as well.
notation Elements
Each notation element contains a block of AMAN in a parser-friendly (and, hopefully, human-friendly) format. This block contains one or more lines, each of which has a left, center, and right portion separated by commas. A fourth column containing a text string may optionally be included to annotate the line.
Each section (left, center, and right) of a line is composed of 0 or more atoms. These atoms may be any of the following:
- jump: A jump.
- release: Instructs the performed to release eir grip on eir opponent/weapon.
- A direction keyword indicating motion of the dan tien in the indicated direction. The direction keywords are: left, right, forward, back, forwardleft, forwardright, backleft, and backright.
- look (<direction keyword>): Indicates the performer should focus eir attention on the indicated region.
- <turnleft|turnright> [ ( <integer> ) ]: Denotes a left or right turn. An integer may optionall be included in parentheses following the keyword, indicating a turn of number degrees; 90° is assumed if this modifier is omitted.
- "<literal string>": Indicates that a literal string should be inserted into the notation block at that location.
- <action specifier> [ ( [ grapple|grip ] [ <diection keyword> ] [ <region specifier> ] ) ]: Describes a strike/block/grapple; most of the atoms in a technique will use this form. An arbitrary string of characters is assumed to be an action specifier if it is not a keyword or literal string. Each specifier may optionally be followed by a list of modifiers enclosed in parentheses:
- grapple | grip: May be used to indicate that the action is a grapple or a weapon grip; a standard strike is assumed if these keywords are omitted.
- <direction keyword>: Indicates the direction of application of the action. The default direction of application is assumed if no direction modifier is provided. Does not apply to grip actions.
- <region specifier>: An aribtrary character string denoting a region.
A complete grammar with a more detailed description can be found in NotationParser.pm.
Getting Started
The code and more details on how it works can be found here. The easiest way to get an idea of how all this works in practice is to take a look at the posts where I've presented typeset material along with source files:
- Studio X: Sparring Techniques: Rank 1 Revisited
- Studio X: Sparring Techniques: Rank 2 Revisited
- Studio X: Sparring Techniques: Rank 3 Revisited
- Studio X: Sparring Techniques: Rank 4 Revisited
- Studio X: Sparring Techniques: Short Forms Rank 1
- Studio X: Sparring Techniques: Short Forms Rank 2
I hope this is useful to y'all; have fun.
