2,259 bytes added
, 19:24, 2 June 2018
A Controlled Vocabulary for Documenting ConTeXt Commands
Mostly for my own edification and understanding; comments appreciated! -Paul
== Syntax ==
Vocabulary:
* Command Name
* Option Block
* Settings Block
* Scope
=== Command Name ===
The '''command name''' is the part of the command that is preceded by a backslash (\).
=== Option Block ===
The '''option block''' is a square bracket ({}) delimited set of comma-separated single-word options (may also have a numerical modifier with an arithmetic operator) included after the command.
Option keywords are not necessarily consistent across all commands.
=== Settings Block ===
The '''settings block''' is a square bracket ({}) delimited set of comma-separated settings in the form of key=value pairs included after the command.
The key=value pairs are consistent across all commands (a bold claim, but so far, true!).
=== Scope ===
The '''scope''' of a command is indicated by the \start and \stop commands for that command, or by curly bracket ({}) delimited content to which the command applies, included after the command.
== Command Kinds ==
The command namespace may be extended by defining new forms of a command to semantically align to a particular use in a text. This is a ''KIND'' of the base command.
Command Kinds in the ConTeXt documentation are traditionally set in ''ITALIC UPPERCASE''.
== Argument Classes ==
Some commands can accept arguments that are of a particular class: a number, or a command, etc.
The documentation uses the following as known argument classes:
IDENTIFIER
: A label, a logical name
REFERENCE
: A label, a logical name
NAME
: A label, a logical name
CHARACTER
: A single character (glyph?) or text.
TEXT
: A piece of literal text.
MARK
: Information about document state (page number, section number)
DIMENSION
: A measure of linear distance. Can be static, dynamic, or computed.
NUMBER
: An integer
COMMAND
: A ConTeXt command.
PATH
: A file path to a file in the local filesystem.
COLOR
: A color name (or specification?)
CSNAME
: A TeX-protected sequence of characters
CONTENT
: Any amount and any kind of ConTeXt content: text, commands, etc.
General placeholders in the ConTeXt documentation are traditionally set in UPPERCASE.