Changes

Jump to navigation Jump to search
m
Text replacement - "pragma-ade.com" to "pragma-ade.nl"
* 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:
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v 'count(//cd:interface/cd:interface/cd:command)' context-en.xml
</pre>
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@file])' context-en.xml
</pre>
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v '//cd:interface/cd:interface/cd:command[not(@file)]/@name' context-en.xml
</pre>
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@level])' context-en.xml
</pre>
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v '//cd:interface/cd:interface/cd:command[not(@level)]/@name' context-en.xml
</pre>
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@name])' context-en.xml
</pre>
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 ===
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@type])' context-en.xml
</pre>
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@variant])' context-en.xml
</pre>
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 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:
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@generated])' context-en.xml
</pre>
This attribute is significant for indicating this stanza describes a generated command.
 
=== The begin and end Attributes ===
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@begin and @end])' context-en.xml
</pre>
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:
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@scope])' context-en.xml
</pre>
* 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 an 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:
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v 'count(//cd:interface/cd:interface/cd:command[@coreprimitive])' context-en.xml
</pre>
<pre>
xml sel -N cd=http://www.pragma-ade.comnl/commands -t -v 'count(//cd:interface/cd:interface/cd:command/cd:arguments)' context-en.xml
</pre>
;`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: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[|l|p|]`}}
;`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 ====
;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?
{{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.
;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.
;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.
;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:
;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"/> )
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 ====
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.
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 ===
...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:
...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 ==
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? ===
(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? ===
...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 ==
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">

Navigation menu