Changes

Jump to navigation Jump to search
12,656 bytes added ,  22:44, 28 June 2020
First pass; some parts still need to be worked on.


== 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"/>
51

edits

Navigation menu