ChordPro directives are used to control the appearance of the printed output. They define meta-data like titles, add new chords, control page and column breaks. Therefore it is not always easy to make a distinction between the semantics of a directive, and the way these semantics are implemented in the ChordPro processing program, the formatter.
For example, the title directive.
{title: Swing Low Sweet Chariot}
The directive name is ‘title’, and its argument is the text ‘Swing Low Sweet Chariot’. This directive defines meta-data, the song title. That is the semantic part. What the formatter does with this meta-data is up to the program and not part of the ChordPro File Format Specification. You can consider directives to be a friendly request, or suggestion, but the actual implementation is left to the formatter. For a meta-data item like the song title it will probably be printed on top of the page and be included in a table of contents, if any.
The Chordpro Reference Implementation provides a default implementation in the style of the original chord program. It can be used as a reference to what a directive is assumed to do. It must however be emphasised that the reference implementation can be configured to use different page styles, fonts, sizes, colours, and so on. Where appropriate, this document refers to the default style.
Many directives have long and short names. For example, the long (full) name for the directive title is ‘title’,
and the short (abbreviated) name is ‘t’. It is, however, advised to use the full name whenever possible, since the abbreviations may lead to confusion or ambiguity if new directives are added.
For directives that take arguments, the arguments are separated from the directive name by a colon : and/or whitespace.
Each song can have meta-data associated, for example the song title. Meta-data are mostly used by programs that help organizing collections of ChordPro songs.
See also Using metadata in texts.
Environment directives always come in pairs, one to start the environment and one to end the environment.
These directives can be used to temporarily change the font, size and/or colour for lyrics and chords. To permanently change these the reference implementation uses much more powerful configuration files.
The following directives are legacy from the old chord program. The modern reference implementation uses much more powerful configuration files for this purpose.
To facilitate using custom extensions for application specific purposes, any directive with a name starting with x_ should be completely ignored by applications that do not handle this directive. In particular, no warning should be generated when an unsupported x_directive is encountered.
It is advised to follow the x_ prefix by a tag that identifies the application (namespace). For example, a directive to control a specific pedal setting for the MobilsSheetsPro program could be named x_mspro_pedal_setting.
Official web site: https://www.chordpro.org/.
Help improving this documentation - visit https://github.com/ChordPro/chordpro/wiki