12,656 bytes added
, 22:44, 28 June 2020
== Introduction ==
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
Commands may or may not also be indicated as **environments**, which describe a set of generated commands.
There are 4028 stanzas in the interface file, as reported by:
<pre>
xml sel -N cd=http://www.pragma-ade.com/commands -t -v 'count(//cd:interface/cd:interface/cd:command)' context-en.xml
</pre>
== 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:
<pre>
distinct-values(//cd:interface/cd:interface/cd:command/@*/name())
</pre>
...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:
<pre>
xml sel -N cd=http://www.pragma-ade.com/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@file])' context-en.xml
</pre>
One command does not have the `file` attribuite, as reported by:
<pre>
xml sel -N cd=http://www.pragma-ade.com/commands -t -v '//cd:interface/cd:interface/cd:command[not(@file)]/@name' context-en.xml
</pre>
... 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:
<pre>
xml sel -N cd=http://www.pragma-ade.com/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@level])' context-en.xml
</pre>
The three commands that do not have the `level` attribute, as reported by:
<pre>
xml sel -N cd=http://www.pragma-ade.com/commands -t -v '//cd:interface/cd:interface/cd:command[not(@level)]/@name' context-en.xml
</pre>
...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:
<pre>
xml sel -N cd=http://www.pragma-ade.com/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@name])' context-en.xml
</pre>
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:
<pre>
distinct-values(//cd:interface/cd:interface/cd:command/@category)
</pre>
...there are 79 discrete values for categories used in the interface:
* mathematics
* alignment
* attribute
* background
* background colors
* background conditional
* rules
* rules colors
* graphics
* structure
* pdf
* 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.
=== 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:
<pre>
xml sel -N cd=http://www.pragma-ade.com/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@type])' context-en.xml
</pre>
It does not appear that this is a required attribute.
As reported by the Xpath expression:
<pre>
distinct-values(//cd:interface/cd:interface/cd:command/@type)
</pre>
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:
<pre>
xml sel -N cd=http://www.pragma-ade.com/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@variant])' context-en.xml
</pre>
It does not appear that this is a required attribute.
As reported by the Xpath expression:
<pre>
distinct-values(//cd:interface/cd:interface/cd:command/@variant)
</pre>
...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.
=== The generated Attribute ===
The `generated` attribute indicates if the stanza is describing a set of commands.
138 stanzas have the `generated` attribute, as reported by:
<pre>
xml sel -N cd=http://www.pragma-ade.com/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@generated])' context-en.xml
</pre>
It does not appear that this is a required attribute.
As reported by the Xpath expression:
<pre>
distinct-values(//cd:interface/cd:interface/cd:command/@generated)
</pre>
...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:
<pre>
xml sel -N cd=http://www.pragma-ade.com/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@begin and @end])' context-en.xml
</pre>
(This is also the number of stanzas that have either of these attributes.)
It does not appear that these are required attributes.
=== The scope Attribute ===
I am not sure what the `scope` attribute indicates.
10 stanzas have the `scope` attribute, as reported by:
<pre>
xml sel -N cd=http://www.pragma-ade.com/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@scope])' context-en.xml
</pre>
As reported by the Xpath expression:
<pre>
distinct-values(//cd:interface/cd:interface/cd:command/@scope)
</pre>
...the `scope` element has two possible values:
* formula
* itemgroup
It does not appear that this is a required attribute.
=== The coreprimitive Attribute ===
I an not sure what the `coreprimitive` attribute indicates.
3 stanzas have the `coreprimitive` attribute, as reported by:
<pre>
xml sel -N cd=http://www.pragma-ade.com/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@coreprimitive])' context-en.xml
</pre>
As reported by the Xpath expression:
<pre>
distinct-values(//cd:interface/cd:interface/cd:command/@coreprimitive)
</pre>
...the `coreprimitive` element has one possible value:
* yes
It does not appear that this is a required attribute.
== Elements Used in a Stanza ==
=== Elements Used ===
(Forthcoming)
=== Structures ===
(Forthcoming)
=== Attributes ===
(Forthcoming)
== Kinds of Stanzas ==
(Forthcoming)
== Things to Ponder ==
It is not clear how the `begin` and `end` attributes interact with the `environment` attribute. However, according to:
<pre>
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>
...no stanzas have this attribute signature.
== Apendicies ==
=== <span id="misspelled_category"></span>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"/>