pm39 command controlled vocab

From Wiki
Jump to navigation Jump to search

A Controlled Vocabulary for Documenting ConTeXt Commands

Mostly for my own edification and understanding; comments appreciated! -Paul

Syntax

Vocabulary:

  • Command Name
  • Setups
  * Option Block
  * Settings Block
  • Scope

Command Name

The command name is the part of the command that is preceded by a backslash (\).

Setups

After the command name, there can be zero or more setup blocks. Setup blocks can either be used for options (single keywords) or settings (key/value p[airs). Options and settings may not be mixed in a setup block.

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

Vocabulary:

  • KIND

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

Vocabulary:

  • IDENTIFIER
  • REFERENCE
  • NAME
  • CHARACTER
  • TEXT
  • MARK
  • DIMENSION
  • NUMBER
  • COMMAND
  • PATH
  • COLOR
  • CSNAME
  • CONTENT

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.