# ChordPro directives

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 Program 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 program 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.

# Arguments and attributes

For directives that take arguments, the arguments are separated from the directive name by a colon : and/or whitespace, as can be seen above with the title directive. Some directives require more than a single argument. For these, a syntax familiar to HTML attributes is used, e.g.

{image: src="myimage.jpg" scale="50%"}

You can use pairs of single and pairs of double quotes, the result is the same.

Some directives with a single argument will also take an attribute instead. For example, the following variants of start_of_verse are the same:

{start_of_verse Verse 1}
{start_of_verse label="Verse 1"}

It is always best to use the variant with explicit attributes. It is less confusing, robust, and future-proof.

Note: In this documentation attributes are often denoted with the less correct term properties. This will be straightened out in the future.

# Preamble directives

# Meta-data directives

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.

# Formatting directives

# Environment directives

Environment directives always come in pairs, one to start the environment and one to end it.

# Delegated environment directives

These environment directives turn their content into something else, usually an image, and embed the result in the ChordPro output.

# Chord diagrams

# Transposition

# Fonts, sizes and colours

These directives can be used to temporarily change the font, size and/or colour for lyrics, chords, and more. 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.

# Custom extensions

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 MobileSheetsPro program could be named x_mspro_pedal_setting.

# Conditional directives

All directives can be conditionally selected by postfixing the directive with a dash (hyphen) and a selector.

If a selector is used, ChordPro first tries to match it with the instrument type (as defined in the config file). If this fails, it tries to match it with the user name (as defined in the config file). Finally, it will try it as a meta item, selection will succeed if this item exists and has a ’true’ value (i.e., not empty, zero, false or null). Selection can be reversed by appending a ! to the selector.

For example, to define chords depending on the instrument used:

{define-guitar:  Am base-fret 1 frets 0 2 2 1 0 0}
{define-ukulele: Am base-fret 1 frets 2 0 0 0}

An example of comments depending on voices:

{comment-alto:  Very softly!}
{comment-tenor: Sing this with power}

When used with sections, selection applies to everything in the section, up to and including the final section end directive:

{start_of_verse-soprano}
...anything goes, including other directives...
{end_of_verse}

Note that the section end must not include the selector.