AsciiDoc User Guide

3.Next from the source document project directory (the first three apply to all documents in the directory, the last two are specific to the mydoc.txt document):

asciidoc.conf

xhtml11.conf xhtml11-article.conf mydoc.conf mydoc-xhtml11.conf

4.Finally the file specified by the -f command-line option is loaded:

extra.conf

Tip

Use the asciidoc(1) -v (—verbose) command-line option to see which configuration files are loaded and the order in which they are loaded.

Document Attributes

A document attribute is comprised of a name and a textual value and is used for textual substitution in AsciiDoc documents and configuration files. An attribute reference (an attribute name enclosed in braces) is replaced by it's their corresponding attribute value.

There are four sources of document attributes (from highest to lowest precedence):

•Command-line attributes.

•AttributeEntry, AttributeList, Macro and BlockId elements.

•Configuration file [attributes] sections.

•Intrinsic attributes.

Within each of these divisions the last processed entry takes precedence.

Important

If an attribute is not defined then the line containing the attribute reference is dropped. This property is used extensively in AsciiDoc configuration files to facilitate conditional markup generation.

Attribute Entries

The AttributeEntry block element allows document attributes to be assigned within an AsciiDoc document. Attribute entries are added to the global document attributes dictionary. The attribute name/value syntax is a single line like:

54

AsciiDoc User Guide

:<name>: <value>

For example:

:Author Initials: JB

This will set an attribute reference {authorinitials} to the value JB in the current document. To delete (undefine) an attribute use the following syntax:

:<name>!:

AttributeEntry properties

•The attribute entry line begins with colon — no white space allowed in left margin.

•AsciiDoc converts the <name> to a legal attribute name (lower case, alphanumeric and dash characters only — all other characters deleted). This allows more reader friendly text to be used.

•Leading and trailing white space is stripped from the <value>.

•If the <value> is blank then the corresponding attribute value is set to an empty string.

•Special characters in the entry <value> are substituted. To included special characters use {gt}, {lt}, {amp} attribute references.

•Attribute references contained in the entry <value> will be expanded.

•Attribute entries in the document Header are available for header markup template substitution.

•Attribute elements override configuration file and intrinsic attributes but do not override command-line attributes.

Note

The author attribute as a special case, it also sets the firstname, surname, middlename and authorinitials attributes.

Here's another example:

Which creates these attributes:

55