Difference between revisions of "pm39 interface analysis"
(→Things to Ponder: Found a counter case!) |
m (Text replacement - "pragma-ade.com" to "pragma-ade.nl") |
||
(28 intermediate revisions by 2 users not shown) | |||
Line 2: | Line 2: | ||
== Introduction == | == 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. | 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. | ||
Line 20: | Line 22: | ||
http://xmlstar.sourceforge.net | 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. | + | ...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 == | == Vocabulary and Other Assumptions == | ||
Line 35: | Line 37: | ||
* a paired command, which describes the start and stop commands for a section | * a paired command, which describes the start and stop commands for a section | ||
* a class, with enumerated instances of that class that are available by default as part of the distribution | * a class, with enumerated instances of that class that are available by default as part of the distribution | ||
+ | {{note|fourth option: an example (dummy) of a potential generated instance. these are the ones with variant{{=}}example*}} | ||
Commands may or may not also be indicated as '''environments''', which describe a set of generated commands. | Commands may or may not also be indicated as '''environments''', which describe a set of generated commands. | ||
+ | {{note|this is the same as a 'paired command'.}} | ||
There are 4028 stanzas in the interface file, as reported by: | There are 4028 stanzas in the interface file, as reported by: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command)' context-en.xml |
</pre> | </pre> | ||
Line 77: | Line 81: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@file])' context-en.xml |
</pre> | </pre> | ||
Line 83: | Line 87: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v '//cd:interface/cd:interface/cd:command[not(@file)]/@name' context-en.xml |
</pre> | </pre> | ||
Line 103: | Line 107: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@level])' context-en.xml |
</pre> | </pre> | ||
Line 109: | Line 113: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v '//cd:interface/cd:interface/cd:command[not(@level)]/@name' context-en.xml |
</pre> | </pre> | ||
Line 121: | Line 125: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@name])' context-en.xml |
</pre> | </pre> | ||
Line 223: | Line 227: | ||
Note for the DITA rendering of the interface: if these are space separated, they can be parsed out into separate `category` elements. | Note for the DITA rendering of the interface: if these are space separated, they can be parsed out into separate `category` elements. | ||
+ | {{note|I always thought these were full strings, but you could be right about space separation}} | ||
=== The type Attribute === | === The type Attribute === | ||
Line 231: | Line 236: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@type])' context-en.xml |
</pre> | </pre> | ||
Line 255: | Line 260: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@variant])' context-en.xml |
</pre> | </pre> | ||
Line 301: | Line 306: | ||
A value of `instance` is important for interpreting the kind of stanza. | A value of `instance` is important for interpreting the kind of stanza. | ||
+ | {{note|AFAICT, the values are CDATA on the xml level. In general, they are there to allow for a unique stanza in cases where not all calling conventions can be expressed in a single stanza. The two exceptions are the CDATA values prefixed with `instance` and `example`. The `example` cases are when there is the ''potential'' for a command instance, but there are no predefined instances in the actual distribution. The `instance` indicates cases where there ''are'' predefined instances. | ||
+ | |||
+ | |||
+ | Processing note: I do not trust the `instance` prefix in my processing, I check for the existence of `<cd:constant>` children in the `<cd:instances>` child tag. However, I am not sure if this is needed. I have not run tests on the XML to verify that the prefix `instance` and child `<cd:instances>` always exist together, I just assumed that testing in actual instances was better than relying on a CDATA argument value}} | ||
=== The generated Attribute === | === The generated Attribute === | ||
The `generated` attribute indicates if the stanza is describing a set of commands. | The `generated` attribute indicates if the stanza is describing a set of commands. | ||
+ | {{note|not necessarily a set of commands, it could be a single command (or environment)}} | ||
138 stanzas have the `generated` attribute, as reported by: | 138 stanzas have the `generated` attribute, as reported by: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@generated])' context-en.xml |
</pre> | </pre> | ||
Line 325: | Line 335: | ||
This attribute is significant for indicating this stanza describes a generated command. | This attribute is significant for indicating this stanza describes a generated command. | ||
− | |||
=== The begin and end Attributes === | === The begin and end Attributes === | ||
Line 334: | Line 343: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@begin and @end])' context-en.xml |
</pre> | </pre> | ||
Line 340: | Line 349: | ||
It does not appear that these are required attributes. | It does not appear that these are required attributes. | ||
+ | {{note|they have default values of `start` and `stop`, and are only relevant for stanzas with `type{{=}}environment` }} | ||
=== The scope Attribute === | === The scope Attribute === | ||
I am not sure what the `scope` attribute indicates. | I am not sure what the `scope` attribute indicates. | ||
+ | |||
+ | {{note|scoped commands are only defined 'meaningfully' inside specific environments. For example, `\item` only works properly inside of commands defined by `\defineitemgroup`.}} | ||
10 stanzas have the `scope` attribute, as reported by: | 10 stanzas have the `scope` attribute, as reported by: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@scope])' context-en.xml |
</pre> | </pre> | ||
Line 361: | Line 373: | ||
* formula | * formula | ||
* itemgroup | * itemgroup | ||
+ | |||
+ | {{note|the possible value list may grow in the future? It could be that some of the row/cell commands in some of the table environments only meaningfully exist within their table environments. Also, there may appear new commands in the future that have a specific scope}} | ||
It does not appear that this is a required attribute. | It does not appear that this is a required attribute. | ||
Line 366: | Line 380: | ||
=== The coreprimitive Attribute === | === The coreprimitive Attribute === | ||
− | I | + | I am not sure what the `coreprimitive` attribute indicates. |
+ | |||
+ | {{note|Neither am I. Perhaps this is a new idea?}} | ||
+ | |||
3 stanzas have the `coreprimitive` attribute, as reported by: | 3 stanzas have the `coreprimitive` attribute, as reported by: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@coreprimitive])' context-en.xml |
</pre> | </pre> | ||
Line 426: | Line 443: | ||
<pre> | <pre> | ||
− | xml sel -N cd=http://www.pragma-ade. | + | xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command/cd:arguments)' context-en.xml |
</pre> | </pre> | ||
Line 445: | Line 462: | ||
;`cd:content` | ;`cd:content` | ||
: Mixed content? | : Mixed content? | ||
+ | {{note|I would define this as 'generic content'}} | ||
;`cd:delimiter` | ;`cd:delimiter` | ||
: A piece of text (a command?) that is used to mark arguments. | : A piece of text (a command?) that is used to mark arguments. | ||
+ | {{note|Yes, a command. The name attribute gives the command name. These are literal required commands that are used as argument separators.}} | ||
;`cd:dimension` | ;`cd:dimension` | ||
: A quantity of linear measure. | : A quantity of linear measure. | ||
Line 453: | Line 472: | ||
;`cd:position` | ;`cd:position` | ||
: (unknown) | : (unknown) | ||
+ | {{note|positions are an old subsystem for absolute placement that is not used a lot, since it has since been superseded by layers and overlays. you'll have to look at `pack-pos.mkiv` to get an idea for how it works.}} | ||
;`cd:index` | ;`cd:index` | ||
: (unknown) | : (unknown) | ||
+ | {{note|this is a list index entries. They are mentioned separately because index entries have a sub-syntax of their own}} | ||
;`cd:text` | ;`cd:text` | ||
: (unknown) | : (unknown) | ||
+ | {{note|Generic horizontal mode content. The sole occurrence of this is in `\setwidthof`.}} | ||
;`cd:apply` | ;`cd:apply` | ||
: (unknown) | : (unknown) | ||
+ | {{note|these are apply lists, which define jump tables. Syntactically, apply lists are like key{{=}}value lists, except they use `{{=}}>` as separator instead of `{{=}}`. Have a look at the [[System_Macros/Action_Processing]] page for more details.}} | ||
;`cd:template` | ;`cd:template` | ||
: (unknown) | : (unknown) | ||
+ | {{note|table column definition templates, like for `\starttable[|l|p|]`}} | ||
;`cd:angles` | ;`cd:angles` | ||
: (unknown) | : (unknown) | ||
+ | {{note|`\type` and `\typ` also allow a call with double angle brackets, like this: `\type<stuff>>`}} | ||
;`cd:string` | ;`cd:string` | ||
: (unknown) | : (unknown) | ||
+ | {{note|an argument that is explicitly a bare string, for string comparisons}} | ||
==== cd:keywords ==== | ==== cd:keywords ==== | ||
Line 478: | Line 504: | ||
;delimiters | ;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? | : The type of delimiters requested for the argument. Values found in the interface are `none`, `braces` ({}), and `parenthesis`. Square brackets ([]) are the implied default? | ||
+ | {{note|yes, square brackets default}} | ||
;list | ;list | ||
: ? | : ? | ||
+ | {{note|`list{{=}}yes` means this is defines a comma-separated list. if missing, this defines a single keyword option}} | ||
;optional | ;optional | ||
: The argument is optional. | : The argument is optional. | ||
Line 509: | Line 537: | ||
;prefix | ;prefix | ||
: ? | : ? | ||
+ | |||
+ | {{note|This one I am not quite sure about, but I interpret `method`, `prefix` and `type` like this: | ||
+ | |||
+ | ;method{{=}}range | ||
+ | : the argument is specified as `prefix`, followed by `:`, followed by `type` | ||
+ | ;method{{=}}apply | ||
+ | : the argument is specified as `prefix`, followed by `->`, followed by `type` | ||
+ | ;method{{=}}factor | ||
+ | : the argument is specified as `prefix`, followed by `*`, followed by `type` | ||
+ | ;method{{=}}none | ||
+ | : the argument is specified as `prefix`, followed by `type` | ||
+ | |||
+ | The values of both `prefix` and `type` can be one of the predefined `cd:XXXXX` value types, or a literal string like `*` or `all`. | ||
+ | |||
+ | A useful example is in [[Command/setupreferencestructureprefix]] | ||
+ | |||
+ | }} | ||
The `cd:inherit` element acts as a pointer to the options of a donor command by command name. The `cd:inherit` element uses the `name` attribute to indicate the donor command. | The `cd:inherit` element acts as a pointer to the options of a donor command by command name. The `cd:inherit` element uses the `name` attribute to indicate the donor command. | ||
Line 526: | Line 571: | ||
;list | ;list | ||
: ? | : ? | ||
+ | {{note|`list{{=}}yes` means this is defines a comma-separated list. if missing, this defines a single key-value option (which I think never actually happens)}} | ||
;optional | ;optional | ||
: The argument is optional. | : The argument is optional. | ||
Line 553: | Line 599: | ||
;list | ;list | ||
: ? | : ? | ||
+ | {{note|`list{{=}}yes` means this is defines a comma-separated list. if missing, this defines a single parameter}} | ||
As reported by the Xpath expression: | As reported by the Xpath expression: | ||
Line 581: | Line 628: | ||
;prefix | ;prefix | ||
: ? | : ? | ||
+ | {{note|see above for method/prefix/type}} | ||
(Note: there is one instance of a possible type on Line 38818: <cd:constant defult="yes" type="stop"/> ) | (Note: there is one instance of a possible type on Line 38818: <cd:constant defult="yes" type="stop"/> ) | ||
Line 596: | Line 644: | ||
</pre> | </pre> | ||
− | ....no | + | ....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. | ||
+ | |||
+ | {{note|Based on email exchange with Wolfgang: | ||
+ | |||
+ | ==== instance generators ==== | ||
+ | |||
+ | instances are generated by a generator command. Currently, I find the generator command as follows: | ||
+ | |||
+ | * take the value of the `name` attribute at the top level of the stanza | ||
+ | * prepend `define` | ||
+ | * look for a replacement in the following table | ||
+ | <pre> | ||
+ | local corrections = { | ||
+ | definefloats = 'definefloat', | ||
+ | definebox = 'definehbox', | ||
+ | definectxfunction = 'installctxfunction', | ||
+ | definectxfunctiondefinition = 'startctxfunctiondefintion', | ||
+ | definefence = 'definemathfence', | ||
+ | definelabel = 'definelabelclass', | ||
+ | definelanguage = 'installlanguage', | ||
+ | definesynonym = 'definesynonyms', | ||
+ | definesorts = 'definesorting', | ||
+ | } | ||
+ | </pre> | ||
+ | * the result is the generator command for all the instances in the stanza | ||
+ | }} | ||
+ | |||
+ | ==== cd:variable ==== | ||
+ | |||
+ | (I'm not sure what this is meant to indicate, but it seems to correlate with examples? -pm39) | ||
+ | |||
+ | {{note|my guess is that these are leftovers. But see also the discussion about `variant{{=}}example` on the wiki mailing list}} | ||
+ | |||
+ | ==== 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 === | === 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 == | == 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. | ||
+ | |||
+ | {{note|see above for special cases of generator commands that are not exactly `\define''stem''`}} | ||
+ | |||
+ | 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. | ||
+ | |||
+ | {{note|Example stanzas are for instances that ''could'' be generated, but of which there are no examples in the ConTeXt distribution. `description` and `effect` are good examples of this type of stanza. While there are the associated commands `\definedescription` and `\defineeffect`, ConTeXt itself never bothers to the define any instances}} | ||
+ | |||
+ | === 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. | ||
+ | |||
+ | {{note|the existence of \setup''stem'' is not a given, but yes there could be others as well. Many of these commands are created by some code that is embedded in the `\defineXXX` generated by `\installcommandhandler`, but environments can also be created 'manually' by a pair of `\def` commands, like for example the `\startluacode` environment. | ||
+ | |||
+ | The only guaranteed defined commands for any ''environment'' is the pair of start/stop commands}} | ||
+ | |||
+ | An environment does not necessarily create the command: | ||
+ | |||
+ | * \''stem'' | ||
+ | |||
+ | ...but I'm not sure if it never does. | ||
+ | |||
+ | {{note|Hans is quite meticulous in creating these standalones even in the manual generation cases if it makes sense to have that standalone command, but some them are missing for sure, e.g. `\buffer`}} | ||
+ | |||
+ | == 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 (with 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!) | ||
+ | {{note|should be both or neither, I assume. But whether it is an environment is decided by type{{=}}environment}} | ||
+ | # 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. | ||
+ | |||
+ | {{note|`begin` and `end` are nothing but overrides for the implied values `start` and `stop`}} | ||
== Things to Ponder == | == Things to Ponder == | ||
+ | |||
+ | === What does an environment imply for command generation? === | ||
+ | |||
+ | What commands are available as a result of an environment? | ||
+ | |||
+ | {{note|only the `\start` and `\stop` are guaranteed (but perhaps with different prefixes cf `begin` and `end` attributes.)}} | ||
+ | |||
+ | === 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 `\bar` relates to mathematics, while the instances of the `\bar` class are a series of prefix + stem command names.) | ||
+ | |||
+ | {{note|yes, I firmly believe you are right}} | ||
+ | |||
+ | === 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 | ||
+ | |||
+ | * `command` | ||
+ | |||
+ | ....elements, it may make sense to describe stanzas with the following elements: | ||
+ | |||
+ | * `command` | ||
+ | * `class` | ||
+ | |||
+ | ...and possibly: | ||
+ | |||
+ | * `example` | ||
+ | |||
+ | A further disambiguation that might be useful is the addition of: | ||
+ | |||
+ | * `pair` | ||
+ | |||
+ | ...elements, to explicitly mark elements that generate commands with prefixes and stems. | ||
+ | |||
+ | {{note|I have missed something somewhere, because this remark is unclear to me. }} | ||
+ | |||
+ | {{note|This may or may not be what you're asking: | ||
+ | |||
+ | Instead of having every stanza be represented by a <cd:command> element, instead do (taking your notes into consideration): | ||
+ | |||
+ | <cd:command> | ||
+ | (Describes a command) | ||
+ | </cd:command> | ||
+ | |||
+ | <cd:class> | ||
+ | (describes a class) | ||
+ | </cd:class> | ||
+ | |||
+ | <cd:environment> | ||
+ | (describes an environment, with or without overrides) | ||
+ | </cd:environment> | ||
+ | |||
+ | ...? | ||
+ | |||
+ | This way, the thing being described by the stanza is explicit... | ||
+ | |||
+ | }} | ||
+ | |||
+ | ::::Right, I see. I certainly would not mind, but it will depend on Wolfgang (who is the actual maintainer) and Hans (who is using the xml files for various distribution-related things [[User:Taco|Taco]] ([[User talk:Taco|talk]]) 16:15, 30 June 2020 (CEST) | ||
== Apendicies == | == Apendicies == | ||
Line 638: | Line 1,018: | ||
Line 38818: <cd:constant defult="yes" type="stop"/> | Line 38818: <cd:constant defult="yes" type="stop"/> | ||
+ | |||
+ | === Missing "file" attribute === | ||
+ | |||
+ | : Line 14799 - <cd:command category="background rules" level="system" name="doifelseframed"> | ||
+ | |||
+ | === Missing "level" attribute === | ||
+ | |||
+ | : Line 934 - <cd:command file="back-ini.mkxl" name="setupoutput"> | ||
+ | : Line 27165 - <cd:command category="structure notes" file="strc-not.mkvi" name="postponingnotes" type="environment"/> | ||
+ | : Line 37044 - <cd:command category="language" file="scrp-ini.mkvi" name="script" type="environment"> |
Latest revision as of 08:29, 2 July 2022
Contents
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.
I used the interface file context-en.xml
:
- file name
- context-en.xml
- date collected
- 2020-06-27
- size
- 1685184
- md5
- 48edfd4fb6e71aee7a49023f0527a461
I used xmlstarlet:
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
The interface file is made up of a number of cd:interface
elements that describe a hierarchy based on source files.
Inside this hierarchy of interface elements are a set of cd:command
elements. I'm going to refer to these elements as stanzas.
Some commands are instances of a more general idea of functionality. I'm going to refer to the parent elements of instances as classes.
Each stanza can refer to one of a number of different kinds of entities:
- a command
- a paired command, which describes the start and stop commands for a section
- a class, with enumerated instances of that class that are available by default as part of the distribution
NOTE: fourth option: an example (dummy) of a potential generated instance. these are the ones with variant=example* |
Commands may or may not also be indicated as environments, which describe a set of generated commands.
NOTE: this is the same as a 'paired command'. |
There are 4028 stanzas in the interface file, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command)' context-en.xml
Attributes Used in The Root Element of a Stanza
Root elements of a stanza can have one of several available attributes. The patterns of some of these attributes give hints to the function or purpose of the stanza.
From the following XPath expression:
distinct-values(//cd:interface/cd:interface/cd:command/@*/name())
...we have a list of 11 attributes found attached to root elements of stanzas in the interface:
- file
- level
- name
- category
- type
- variant
- generated
- begin
- end
- scope
- coreprimitive
(Note that we also appear to have two misspellings of "category"; see #misspelled_category)
The file Attribute
The file
attribute specifies the source file that defines the command.
4027 stanzas have the file
attribute, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@file])' context-en.xml
One command does not have the file
attribuite, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v '//cd:interface/cd:interface/cd:command[not(@file)]/@name' context-en.xml
... is: doifelseframed
.
The level Attribute
The value of the level
attribute loosely specifies how the command is part of the typesetting system.
The level
attribute has three possible values in the interface:
- style
- document
- system
Commands with a level of style
or document
are expected to be used by people using ConTeXt to prepare documents; commands with the level of system
are internal commands with an expected audience of programmers and implementors who need to know about ConTeXt internals.
4025 stanzas have the level
attribute, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@level])' context-en.xml
The three commands that do not have the level
attribute, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v '//cd:interface/cd:interface/cd:command[not(@level)]/@name' context-en.xml
...are setupoutput
, postponingnotes
, and script
.
The name Attribute
The name
attribute specifies the name associated with the stanza, and may refer to a command, a stem for a command pair or environment, or a class.
4028 stanzas have this attribute, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@name])' context-en.xml
There is no stanza in the interface without this attribute in its root element.
The category Attribute
The category
attribute specifies the category (or categories?) assigned to a given stanza.
As reported by the Xpath expression:
distinct-values(//cd:interface/cd:interface/cd:command/@category)
...there are 79 discrete values for categories used in the interface:
- mathematics
- alignment
- attribute
- background
- background colors
- background conditional
- rules
- rules colors
- graphics
- structure
- conditional
- buffer conditional
- buffer
- buffer lua
- buffer verbatim
- fonts
- catcode
- characters
- characters fonts
- language
- colors
- colors conditional
- tables
- float tables
- counter
- counter language
- counter conditional
- system
- language alignment
- fonts colors
- xml
- pdf conditional
- pdf background rules
- pdf background
- structure conditional
- structure lua
- structure conditional xml
- rules metapost
- background layout
- background layout metapost
- structure fonts counter
- structure background
- structure counter
- fonts conditional
- background rules
- background rules mathematics
- graphics conditional
- graphics buffer
- graphics structure
- layout
- whitespace
- whitespace layout
- symbols
- fonts whitespace
- language conditional
- background metapost
- layout conditional
- tables buffer
- lua
- structure layout
- mathematics alignment
- mathematics tables
- graphics metapost
- graphics metapost fonts
- graphics metapost conditional
- structure notes
- structure notes conditional
- background fonts colors
- bibliography
- bibliography conditional
- references
- references conditional
- symbols conditional
- symbols graphics
- xml conditional
- xml language
- verbatim
- verbatim conditional
....although if these are space-separated, there is overlap.
Note: this analysis does not include stanzas with misspelled category attributes.
Note for the DITA rendering of the interface: if these are space separated, they can be parsed out into separate category
elements.
NOTE: I always thought these were full strings, but you could be right about space separation |
The type Attribute
At the root level of a stanza, the type
attribute can indicate the type of the stanza.
369 stanzas have the type
attribute, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@type])' context-en.xml
It does not appear that this is a required attribute.
As reported by the Xpath expression:
distinct-values(//cd:interface/cd:interface/cd:command/@type)
At the root level of the stanza, the type
element has one possible value:
- environment
This attribute is significant for indicating this stanza describes an environment.
The variant Attribute
The variant
attribute specifies more information about the type of the stanza, and may be used to disambiguate stanzas.
3299 stanzas have the variant
attribute, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@variant])' context-en.xml
It does not appear that this is a required attribute.
As reported by the Xpath expression:
distinct-values(//cd:interface/cd:interface/cd:command/@variant)
...31 discrete values are used in the interface for the variant
attribute:
- argument
- instance
- example
- page
- list
- direct
- interactionmenu
- button
- name
- 1
- 2
- 3
- matrix
- example:title
- string
- preset
- command
- assignment
- item
- symbol
- none
- combination
- instance:assignment
- collector
- layer
- userdata
- alternative
- instance:ownnumber
- instance:argument
- angles
- example:angles
A value of instance
is important for interpreting the kind of stanza.
NOTE: AFAICT, the values are CDATA on the xml level. In general, they are there to allow for a unique stanza in cases where not all calling conventions can be expressed in a single stanza. The two exceptions are the CDATA values prefixed with instance and example . The example cases are when there is the potential for a command instance, but there are no predefined instances in the actual distribution. The instance indicates cases where there are predefined instances.
|
The generated Attribute
The generated
attribute indicates if the stanza is describing a set of commands.
NOTE: not necessarily a set of commands, it could be a single command (or environment) |
138 stanzas have the generated
attribute, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@generated])' context-en.xml
It does not appear that this is a required attribute.
As reported by the Xpath expression:
distinct-values(//cd:interface/cd:interface/cd:command/@generated)
...the generated
element has one possible value:
- yes
This attribute is significant for indicating this stanza describes a generated command.
The begin and end Attributes
The begin
and end
attributes indicate the strings that must be prepended to the command stem to create the command pair.
41 stanzas have both begin
and end
attributes, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@begin and @end])' context-en.xml
(This is also the number of stanzas that have either of these attributes.)
It does not appear that these are required attributes.
NOTE: they have default values of start and stop , and are only relevant for stanzas with type=environment
|
The scope Attribute
I am not sure what the scope
attribute indicates.
NOTE: scoped commands are only defined 'meaningfully' inside specific environments. For example, \item only works properly inside of commands defined by \defineitemgroup .
|
10 stanzas have the scope
attribute, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@scope])' context-en.xml
As reported by the Xpath expression:
distinct-values(//cd:interface/cd:interface/cd:command/@scope)
...the scope
element has two possible values:
- formula
- itemgroup
NOTE: the possible value list may grow in the future? It could be that some of the row/cell commands in some of the table environments only meaningfully exist within their table environments. Also, there may appear new commands in the future that have a specific scope |
It does not appear that this is a required attribute.
The coreprimitive Attribute
I am not sure what the coreprimitive
attribute indicates.
NOTE: Neither am I. Perhaps this is a new idea? |
3 stanzas have the coreprimitive
attribute, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@coreprimitive])' context-en.xml
As reported by the Xpath expression:
distinct-values(//cd:interface/cd:interface/cd:command/@coreprimitive)
...the coreprimitive
element has one possible value:
- yes
It does not appear that this is a required attribute.
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:
count(//cd:interface/cd:interface/cd:command/*/name(.))
3560 of the stanzas contain more structure, with details about the command or class.
According to the Xpath expression:
distinct-values(//cd:interface/cd:interface/cd:command/*/name(.))
...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:
count(//cd:interface/cd:interface/cd:command/cd:arguments/@*/name(.))
....no cd:argument
elements have attributes.
3333 stanzas have an arguments substructure, as reported by:
xml sel -N cd=http://www.pragma-ade.nl/commands -t -v 'count(//cd:interface/cd:interface/cd:command/cd:arguments)' context-en.xml
As reported by the Xpath Expression:
distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/*/name(.))
...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?
NOTE: I would define this as 'generic content' |
cd:delimiter
- A piece of text (a command?) that is used to mark arguments.
NOTE: Yes, a command. The name attribute gives the command name. These are literal required commands that are used as argument separators. |
cd:dimension
- A quantity of linear measure.
cd:triplet
- A description of a color.
cd:position
- (unknown)
NOTE: positions are an old subsystem for absolute placement that is not used a lot, since it has since been superseded by layers and overlays. you'll have to look at pack-pos.mkiv to get an idea for how it works.
|
cd:index
- (unknown)
NOTE: this is a list index entries. They are mentioned separately because index entries have a sub-syntax of their own |
cd:text
- (unknown)
NOTE: Generic horizontal mode content. The sole occurrence of this is in \setwidthof .
|
cd:apply
- (unknown)
NOTE: these are apply lists, which define jump tables. Syntactically, apply lists are like key=value lists, except they use => as separator instead of = . Have a look at the System_Macros/Action_Processing page for more details.
|
cd:template
- (unknown)
NOTE: table column definition templates, like for \starttable[
|
cd:angles
- (unknown)
NOTE: \type and \typ also allow a call with double angle brackets, like this: \type<stuff>>
|
cd:string
- (unknown)
NOTE: an argument that is explicitly a bare string, for string comparisons |
cd:keywords
As reported by the Xpath expression:
distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:keywords/@*/name())
...cd:keywords
elements accept the following attributes:
- delimiters
- The type of delimiters requested for the argument. Values found in the interface are
none
,braces
({}), andparenthesis
. Square brackets ([]) are the implied default?
NOTE: yes, square brackets default |
- list
- ?
NOTE: list=yes means this is defines a comma-separated list. if missing, this defines a single keyword option
|
- optional
- The argument is optional.
As reported by the Xpath expression:
distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:keywords/*/name(.))
...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:
distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:keywords/cd:constant/@*/name())
...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: This one I am not quite sure about, but I interpret method , prefix and type like this:
The values of both A useful example is in Command/setupreferencestructureprefix
|
The cd:inherit
element acts as a 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:
distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:assignments/@*/name())
...cd:assignments
elements accept the following attributes:
- delimiters
- The type of delimiters requested for the argument. Values found in the interface are
none
,braces
({}), andparenthesis
. Square brackets ([]) are the implied default? - list
- ?
NOTE: list=yes means this is defines a comma-separated list. if missing, this defines a single key-value option (which I think never actually happens)
|
- optional
- The argument is optional.
As reported by the Xpath expression:
distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:assignments/*/name(.))
...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:
distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:assignments/cd:parameter/@*/name())
...a cd:parameter
element can accept two attributes:
- name
- The name of the key in the key=value pair.
- list
- ?
NOTE: list=yes means this is defines a comma-separated list. if missing, this defines a single parameter
|
As reported by the Xpath expression:
distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:assignments/cd:parameter/*/name(.))
...a cd:parameter
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:
distinct-values(//cd:interface/cd:interface/cd:command/cd:arguments/cd:assignments/cd:parameter/cd:constant/@*/name())
...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: see above for method/prefix/type |
(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:
count(//cd:interface/cd:interface/cd:command/cd:sequence/@*/name(.))
....no cd:sequence elements have attributes.
As reported by the Xpath expression:
distinct-values(//cd:interface/cd:interface/cd:command/cd:sequence/*/name(.))
...sequence elements can contain the following child elements:
- cd:instance
- cd:variable
- cd:string
cd:instance
As reported by the Xpath expression:
count(//cd:interface/cd:interface/cd:command/cd:sequence/cd:instance)
...91 sequence substructures have an instance child.
As reported by the Xpath expression:
//cd:interface/cd:interface/cd:command[@variant="instance"]/cd:sequence/cd:instance
....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.
NOTE: Based on email exchange with Wolfgang:
instance generatorsinstances are generated by a generator command. Currently, I find the generator command as follows:
local corrections = { definefloats = 'definefloat', definebox = 'definehbox', definectxfunction = 'installctxfunction', definectxfunctiondefinition = 'startctxfunctiondefintion', definefence = 'definemathfence', definelabel = 'definelabelclass', definelanguage = 'installlanguage', definesynonym = 'definesynonyms', definesorts = 'definesorting', }
|
cd:variable
(I'm not sure what this is meant to indicate, but it seems to correlate with examples? -pm39)
NOTE: my guess is that these are leftovers. But see also the discussion about variant=example on the wiki mailing list
|
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:
<cd:command category="whitespace" file="spac-ver.mkiv" level="system" name="inhibitblank"/>
This stanza has no internal structure.
This stanza is not:
- An environment.
- A variant.
- Generated.
\blank
The \blank
stanza looks like this:
<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>
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:
<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>
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 \definestem
command.
NOTE: see above for special cases of generator commands that are not exactly \definestem
|
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:
<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>
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:
<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>
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.
NOTE: Example stanzas are for instances that could be generated, but of which there are no examples in the ConTeXt distribution. description and effect are good examples of this type of stanza. While there are the associated commands \definedescription and \defineeffect , ConTeXt itself never bothers to the define any instances
|
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:
- \startstem
- \stopstem
- \setupstem
...and possibly others.
NOTE: the existence of \setupstem is not a given, but yes there could be others as well. Many of these commands are created by some code that is embedded in the \defineXXX generated by \installcommandhandler , but environments can also be created 'manually' by a pair of \def commands, like for example the \startluacode environment.
The only guaranteed defined commands for any environment is the pair of start/stop commands |
An environment does not necessarily create the command:
- \stem
...but I'm not sure if it never does.
NOTE: Hans is quite meticulous in creating these standalones even in the manual generation cases if it makes sense to have that standalone command, but some them are missing for sure, e.g. \buffer
|
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 (with the valueinstance
)? - Does the stanza have a
cd:instances
element, with non-zero children?
- Is the
- Does the stanza describe a pair?
- Is either or both of the
begin=
orend=
attributes extant? (Hopefully both!)
- Is either or both of the
NOTE: should be both or neither, I assume. But whether it is an environment is decided by type=environment |
- 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.
NOTE: begin and end are nothing but overrides for the implied values start and stop
|
Things to Ponder
What does an environment imply for command generation?
What commands are available as a result of an environment?
NOTE: only the \start and \stop are guaranteed (but perhaps with different prefixes cf begin and end attributes.)
|
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 \bar
relates to mathematics, while the instances of the \bar
class are a series of prefix + stem command names.)
NOTE: yes, I firmly believe you are right |
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
command
....elements, it may make sense to describe stanzas with the following elements:
command
class
...and possibly:
example
A further disambiguation that might be useful is the addition of:
pair
...elements, to explicitly mark elements that generate commands with prefixes and stems.
NOTE: I have missed something somewhere, because this remark is unclear to me. |
NOTE: This may or may not be what you're asking:
Instead of having every stanza be represented by a <cd:command> element, instead do (taking your notes into consideration): <cd:command> (Describes a command) </cd:command> <cd:class> (describes a class) </cd:class> <cd:environment> (describes an environment, with or without overrides) </cd:environment> ...? This way, the thing being described by the stanza is explicit...
|
Apendicies
Attributes that are Likely Misspellings of "category"
- catehory
- Line 861 - <cd:command catehory="pdf" file="back-ini.mkiv" level="style" name="setupbackend">
- Line 3361 - <cd:command catehory="pdf" file="scrn-but.mkvi" level="style" name="definebutton">
- Line 3374 - <cd:command catehory="pdf" file="scrn-but.mkvi" level="style" name="setupbutton">
- Line 3409 - <cd:command catehory="pdf" file="scrn-but.mkvi" generated="yes" level="document" name="button" variant="example">
- Line 3428 - <cd:command catehory="pdf" file="scrn-but.mkvi" level="document" name="button">
- Line 3441 - <cd:command catehory="pdf" file="scrn-but.mkvi" level="style" name="overlaybutton">
- Line 3448 - <cd:command catehory="pdf" file="scrn-but.mkvi" level="style" name="overlaybutton" variant="direct">
- Line 3455 - <cd:command catehory="pdf" file="scrn-but.mkvi" level="style" name="MPmenubuttons">
- Line 3462 - <cd:command catehory="pdf" file="scrn-fld.mkvi" level="style" name="overlayrollbutton">
- Line 3472 - <cd:command catehory="pdf" file="scrn-fld.mkvi" level="style" name="definepushbutton">
- Line 3482 - <cd:command catehory="pdf" file="scrn-fld.mkvi" level="style" name="pushbutton">
- Line 3492 - <cd:command catehory="pdf" file="scrn-fld.mkvi" level="style" name="definepushsymbol">
- Line 3504 - <cd:command catehory="pdf" file="scrn-fld.mkvi" level="style" name="rollbutton" variant="interactionmenu">
- Line 3520 - <cd:command catehory="pdf" file="scrn-fld.mkvi" level="style" name="rollbutton" variant="button">
- catgeory
- Line 19207 - <cd:command catgeory="fonts whitespace" file="typo-pnc.mkic" level="style" name="defineperiodkerning">
- Line 19220 - <cd:command catgeory="fonts whitespace" file="typo-pnc.mkic" level="style" name="setupperiodkerning">
- 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"/>
Attributes that are Likely Misspellings of "default"
Line 38818: <cd:constant defult="yes" type="stop"/>
Missing "file" attribute
- Line 14799 - <cd:command category="background rules" level="system" name="doifelseframed">
Missing "level" attribute
- Line 934 - <cd:command file="back-ini.mkxl" name="setupoutput">
- Line 27165 - <cd:command category="structure notes" file="strc-not.mkvi" name="postponingnotes" type="environment"/>
- Line 37044 - <cd:command category="language" file="scrp-ini.mkvi" name="script" type="environment">