51
edits
Changes
Jump to navigation
Jump to search
(Forthcoming)As reported by the Xpath expression:
=== Structures ===<pre>distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:assignments/cd:parameter/*/name(.))</pre>
(Forthcoming)...a `cd:parameter` element can contain one or more `cd:constant` elements and/or `cd:inherit` elements.
=== Attributes ===
It is not clear how === What does an environment imply for command generation? === What commands are available as a result of an environment? === What does a class imply for command generation? === Does a class generate just the commands described by the children of the `cd:instances` element? (Experience with `\bar` implies yes: the literal command `begin\bar` and relates to mathematics, while the instances of the `end\bar` attributes interact with class are a series of prefix + stem command names.) === Expanding the Element Vocabulary? === Given that the stanzas are describing different things, it may be worth the effort to expand the element vocabulary for the stanzas. Instead of just * `environmentcommand` attribute . However...elements, according it may make sense todescribe stanzas with the following elements: * `command`* `class` ...and possibly: * `example`
<pre>A further disambiguation that might be useful is the addition of:xml sel -N cd=http://www.pragma-ade.com/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@begin and @end and @environment])' context-en.xml</pre>* `pair`
→Results: fixed up list formatting
== Introduction ==
Note: this is very much a first and working draft!
This analysis of the ConTeXt interface is an effort to understand how different kinds of commands are expressed, to help support the effort of generated a DITA document set.
http://xmlstar.sourceforge.net
...to gather and process most of data from `context-en.xml`; for the queries that required XPath 2.0+ features, I used Xmplify.app.
== Vocabulary and Other Assumptions ==
It does not appear that this is a required attribute.
== Elements Used Structures == This section is incomplete: I am focusing on element structures that will help parse the interface file into the DITA documentation set. According to the Xpath expression: <pre>count(//cd:interface/cd:interface/cd:command/*/name(.))</pre> 3560 of the stanzas contain more structure, with details about the command or class. According to the Xpath expression: <pre>distinct-values(//cd:interface/cd:interface/cd:command/*/name(.))</pre> ...these stanzas with interior structure have at least one of the following child elements: * `cd:arguments`* `cd:sequence`* `cd:instances` === Arguments === Stanzas may have an `cd:arguments` substructure, to describe command arguments. As reported by the Xpath expression: <pre>count(//cd:interface/cd:interface/cd:command/cd:arguments/@*/name(.))</pre> ....no `cd:argument` elements have attributes. 3333 stanzas have an arguments substructure, as reported by: <pre>xml sel -N cd=http://www.pragma-ade.com/commands -t -v 'count(//cd:interface/cd:interface/cd:command/cd:arguments)' context-en.xml</pre> As reported by the Xpath Expression: <pre>distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/*/name(.))</pre> ...argument structures support the following child elements: ;`cd:keywords`: Setups of options - keywords separated by a comma.;`cd:assignments`: Setups of settings - key=value pairs, separated by a comma.;`cd:csname`: A ConTeXt command name.;`cd:content`: Mixed content?;`cd:delimiter`: A piece of text (a command?) that is used to mark arguments.;`cd:dimension`: A quantity of linear measure.;`cd:triplet`: A description of a color.;`cd:position`: (unknown);`cd:index`: (unknown);`cd:text`: (unknown);`cd:apply`: (unknown);`cd:template`: (unknown);`cd:angles`: (unknown);`cd:string`: (unknown) ==== cd:keywords ==== As reported by the Xpath expression: <pre>distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:keywords/@*/name())</pre> ...`cd:keywords` elements accept the following attributes: ;delimiters: The type of delimiters requested for the argument. Values found in the interface are `none`, `braces` ({}), and `parenthesis`. Square brackets ([]) are the implied default?;list: ?;optional: The argument is optional. As reported by the Xpath expression: <pre>distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:keywords/*/name(.))</pre> ...a `cd:keywords` element can contain one or more `cd:constant` elements and/or `cd:inherit` elements. The `cd:constant` element defines a single keyword. As reported by the Xpath expression: <pre>distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:keywords/cd:constant/@*/name())</pre> ...can have four possible attributes: ;type: The label or name of the option.;default: Whether ("yes") or not this constant is a default.;method: ?;prefix: ? The `cd:inherit` element acts as a Stanza pointer to the options of a donor command by command name. The `cd:inherit` element uses the `name` attribute to indicate the donor command. ==== cd:assignments ==== As reported by the Xpath expression: <pre>distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:assignments/@*/name())</pre> ...`cd:assignments` elements accept the following attributes: ;delimiters: The type of delimiters requested for the argument. Values found in the interface are `none`, `braces` ({}), and `parenthesis`. Square brackets ([]) are the implied default?;list: ?;optional: The argument is optional. As reported by the Xpath expression: <pre>distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:assignments/*/name(.))</pre> ...a `cd:assignments` element can contain one or more `cd:parameter` elements and/or `cd:inherit` elements. A `cd:inherit` element at this level acts as a pointer to the settings of a donor command by command name. The `cd:inherit` element uses the `name` attribute to indicate the donor command. The `cd:parameter` element defines the structure of a key and associated values. As reported by the Xpath expression: <pre>distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:assignments/cd:parameter/@*/name())</pre> ...a `cd:parameter` element can accept two attributes:
;name: The name of the key in the key=== Elements Used ===value pair.;list: ?
The `cd:constant` element defines a single keyword. As reported by the Xpath expression: <pre>distinct-values(Forthcoming//cd:interface/cd:interface/cd:command/cd:arguments/cd:assignments/cd:parameter/cd:constant/@*/name())</pre> ...can have four possible attributes: ;type: The label or name of the option.;default: Whether ("yes") or not this constant is a default.;method: ?;prefix: ? (Note: there is one instance of a possible type on Line 38818: <cd:constant defult="yes" type="stop"/> ) A `cd:inherit` element at this level acts as a pointer to the options of a donor command by command name. The options of the donor command are used as values for the associated key. The `cd:inherit` element uses the `name` attribute to indicate the donor command. === Sequence === Stanzas may have an `cd:sequence` substructure, to describe command arguments. As reported by the Xpath expression: <pre>count(//cd:interface/cd:interface/cd:command/cd:sequence/@*/name(.))</pre> ....no cd:sequence elements have attributes. As reported by the Xpath expression: <pre>distinct-values(//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 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. === Instances === The `cd:instances` element contains one or more `cd:constant` elements, each of which describes an instance of the class named by the stanza. The stem values of the instances are indicated by the `value` attribute.
== Kinds of Stanzas ==
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.
== Things to Ponder ==
...no stanzas have this attribute signatureelements, to explicitly mark elements that generate commands with prefixes and stems.
== Apendicies ==
=== <span id="misspelled_category"></span>Attributes that are Likely Misspellings of "Category?category" ===
;catehory
: Line 19232 - <cd:command catgeory="fonts whitespace" file="typo-pnc.mkic" level="style" name="setperiodkerning">
: Line 19240 - <cd:command catgeory="fonts whitespace" file="typo-pnc.mkic" level="style" name="resetperiodkerning"/>
=== <span id="misspelled_default"></span>Attributes that are Likely Misspellings of "default" ===
Line 38818: <cd:constant defult="yes" type="stop"/>
