Changes

....no `cd:sequence` elements have attributes.

As reported by the Xpath expression: <pre>distinct-values(To //cd:interface/cd:interface/cd:command/cd:sequence/*/name(.))</pre> ...sequence elements can contain the following child elements: * cd:instance* cd:variable* cd:string ==== cd:instance ==== As reported by the Xpath expression: <pre>count(//cd:interface/cd:interface/cd:command/cd:sequence/cd:instance)</pre> ...91 sequence substructures have an instance child. As reported by the Xpath expression: <pre>//cd:interface/cd:interface/cd:command[@variant="instance"]/cd:sequence/cd:instance</pre> ....84 of these stanzas have the `variant` attribute set to `instance` in the command element. Having a combination of an `cd:instance` element and `variant="instance"` attribute strongly correlates with the stanza describing a class. The `cd:instance` element carries an attribute of `value`, which maps to the replaceable stem of the class.  ==== cd:variable ==== (I'm not sure what this is meant to indicate, but it seems to correlate with examples? -pm39) ==== cd:string ==== The `cd:string` element indicates a piece of text that is a particle of the command name of an instance, and is appended to the stem to create the full command name of an instance. `cd:sequence` elements can have zero, one, or two `cd:string` elements. Up to one `cd:string` element can appear either before or after the `cd:instance` element. The `cd:string` element carries an attribute of `value`, which maps to the affix text that should be continued)added to command name for instances of the class. The string is added in prefix or postfix depending on where the `cd:string` element is ordered within the `cd:sequence` element.

The purpose of this analysis is to help support automatic translation of the ConTeXt interface files into a topic-based DITA documentation set. As a result, it appears the ConTeXt interface stanzas describe at least two, and possible three, different things., and an additional feature axis. === Command Stanzas === Some stanzas describe ``commands``.  This can be straightforward, with a one to one relationship between the stanza and a command.  As my sample cases for this kind of stanza, I have the `\inhibitblank` stanza and the `\blank` stanza. Some command stanzas describe pairs of commands; using `begin` and `end` attributes to indicate prefixes, these stanzas explicitly describe commands which bracket content. The contents of `cd:argument`, if extant, only apply to the command with the `begin` prefix. As my sample case for this kind of stanza, I have the `TD` stanza.  ==== `\inhibitblank` ==== The `\inhibitblank` stanza looks like this: <xmlcode><cd:command category="whitespace" file="spac-ver.mkiv" level="system" name="inhibitblank"/></xmlcode> This stanza has no internal structure. This stanza is not: * An environment.* A variant.* Generated.  ==== `\blank` ==== The `\blank` stanza looks like this: <xmlcode> <cd:command category="whitespace" file="spac-ver.mkiv" level="document" name="blank"> <cd:arguments> <cd:keywords list="yes" optional="yes"> <cd:constant type="preference"/> <cd:constant type="samepage"/> <!-- cd:constant elements removed for clarity --> <cd:constant type="cd:dimension"/> <cd:constant type="cd:name"/> </cd:keywords> </cd:arguments> </cd:command></xmlcode> This stanza has internal structure: a argument of type ''options'', with a list of available keywords. This stanza is not: * An environment.* A variant.* Generated.  ==== `TD` ==== The `TD` stanza looks like this: <xmlcode><cd:command begin="b" category="tables" end="e" file="tabl-ntb.mkxl" level="document" name="TD" type="environment"> <cd:arguments> <cd:assignments list="yes" optional="yes"> <cd:parameter name="nx"> <cd:constant type="cd:number"/> </cd:parameter> <!-- cd:parameter elements removed for clarity --> <cd:parameter name="action"> <cd:constant type="cd:reference"/> </cd:parameter> <cd:inherit name="setupTABLE"/> </cd:assignments> </cd:arguments> </cd:command></xmlcode> This stanza has internal structure: a argument of type ''settings'', with a list of available keys and values for each key. This stanza is: * An environment. This stanza is not: * A variant.* Generated. === Class Stanzas === Some stanzas describe ``classes``.  These stanzas describe a series of ''instances'' of the class; a series of commands that share the class' setups and details. Instances that are offered as part of the standard distribution are captured as a series of chile `cd:constant` elements, with the instance name expressed as the value associated with the `value` attribute of the `cd:constant` element. Classes imply that the user may generate their own instances, creating specialized instances of the class with the appropriate `\define''stem''` command.  As my sample case for this kind of stanza, I have the `\itemgroup` stanza. There are two stanzas with the name `itemgroup`.  The first stanza for `name="itemgroup"` looks like this: <xmlcode> <cd:command category="structure" file="strc-itm.mkvi" generated="yes" level="document" name="itemgroup" type="environment" variant="instance"> <cd:sequence> <cd:instance value="itemgroup"/> </cd:sequence> <cd:arguments> <cd:keywords list="yes" optional="yes"> <cd:inherit name="setupitemgroup"/> </cd:keywords> <cd:assignments list="yes" optional="yes"> <cd:inherit name="setupitemgroup"/> </cd:assignments> </cd:arguments> <cd:instances> <cd:constant value="itemize"/> </cd:instances> </cd:command></xmlcode> This stanza has the attribute and value of `generated="yes"`. This implies that the commands are created automatically as part of the standard distribution. This stanza also has the attribute and value of `variant="instance"`, and has a `cd:instances` element with more than zero child elements. This implies that this stanza describes a ''class''.  The second stanza for `name="itemgroup"` looks like this: <xmlcode> <cd:command category="structure" file="strc-itm.mkvi" level="document" name="itemgroup" type="environment"> <cd:arguments> <cd:keywords> <cd:constant type="cd:name"/> </cd:keywords> <cd:keywords list="yes" optional="yes"> <cd:inherit name="setupitemgroup"/> </cd:keywords> <cd:assignments list="yes" optional="yes"> <cd:inherit name="setupitemgroup"/> </cd:assignments> </cd:arguments> </cd:command></xmlcode> The second stanza describes a simple `itemgroup` command, with an environment. === Example Stanzas === I'm not sure how the example stanzas work, yet. From the label, I expect them to be more towards documentation than implementation, but I don't know. === Environments === Stanzas can have an additional intrinsic of describing an ''environment'', indicated by the `type` attribute having the value `environment`. I believe this creates a family of related commands around the environment: * \start''stem''* \stop''stem''* \setup''stem'' ...and possibly others. An environment does not necessarily create the command: * \''stem'' ...but I'm not sure if it never does. == Results == If we want to use the interface file to build a complete command set, the procedure is: #. Does the stanza describe a class? * Is the `variant="instance"` attribute extant (Forthcomingwith the value `instance`)? * Does the stanza have a `cd:instances` element, with non-zero children?#. Does the stanza describe a pair? * Is either or both of the `begin=` or `end=` attributes extant? (Hopefully both!)#. Does the stanza describe a command? * Does the stanza not describe a class? * Does the stanza not describe a pair? * Does the stanza not have a `variant` attribute? Orthogonal to this, a stanza may describe an environment, if the `type="environment"` attribute is extant (with the value `environment`). This implied further automatically generated commands based ont he command stem, but interactions with commands, pairs, and classes is unclear.