Difference between revisions of "pm39 interface analysis"

From Wiki
Jump to navigation Jump to search
(First pass; some parts still need to be worked on.)
 
Line 26: Line 26:
 
The interface file is made up of a number of `cd:interface` elements that describe a hierarchy based on source files.
 
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**.  
+
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**.
+
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:
 
Each stanza can refer to one of a number of different kinds of entities:
Line 36: Line 36:
 
* 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
  
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.
  
 
There are 4028 stanzas in the interface file, as reported by:
 
There are 4028 stanzas in the interface file, as reported by:

Revision as of 22:48, 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:

xml sel -N cd=http://www.pragma-ade.com/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.com/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.com/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.com/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.com/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.com/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
  • 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:

xml sel -N cd=http://www.pragma-ade.com/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.com/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.

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:

xml sel -N cd=http://www.pragma-ade.com/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.com/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.

The scope Attribute

I am not sure what the scope attribute indicates.

10 stanzas have the scope attribute, as reported by:

xml sel -N cd=http://www.pragma-ade.com/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

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:

xml sel -N cd=http://www.pragma-ade.com/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.

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:

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

...no stanzas have this attribute signature.

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