AsciiDoc User Guide

•A [specialwords] section entry of the form name=word1 [word2…] adds words to existing name entries.

•A [specialwords] section entry of the form name undefines (deletes) all existing name words.

•Since word list entries are processed as Python regular expressions you need to be careful to escape regular expression special characters.

•By default Special Words are substituted before Inline Macros, this may lead to undesirable consequences. For example the special word foobar would be expanded inside the macro call http://www.foobar.com[]. A possible solution is to emphasize whole words only by defining the

word using regular expression characters, for example \bfoobar\b.

•If the first matched character of a special word is a backslash then the remaining characters are output without markup i.e. the backslash can be used to escape special word markup. For example the special word \\?\b[Tt]en\b will mark up the words Ten and ten only if they are not preceded by a backslash.

Replacements

[replacements] configuration file entries specify find and replace text and are formatted like:

find_pattern=replacement_text

The find text can be a Python regular expression; the replace text can contain Python regular expression group references.

Use Replacement shortcuts for often used macro references, for example (the second replacement allows us to backslash escape the macro name):

#NEW#=image:./images/smallnew.png[New!]

\\#NEW#=#NEW#

Replacement behavior

•The built-in replacements can be escaped with a backslash.

•If the find or replace text has leading or trailing spaces then the text should be enclosed in quotation

(") characters.

•Since the find text is processed as a regular expression you need to be careful to escape regular expression special characters.

•Replacements are performed in the same order they appear in the configuration file [replacements] section.

Configuration File Names and Locations

Configuration files have a .conf file name extension; they are loaded implicitly (using predefined file

52

AsciiDoc User Guide

names and locations) or explicitly (using the asciidoc(1) -f (—conf-file) command-line option).

Implicit configuration files are loaded from the following directories in the following order:

1.The /etc/asciidoc directory (if it exists).

2.The directory containing the asciidoc executable.

3.The user's $HOME/.asciidoc directory (if it exists).

4.The directory containing the AsciiDoc source file.

The following implicit configuration files from each of the above locations are loaded in the following order:

1.asciidoc.conf

2.<backend>.conf

3.<backend>-<doctype>.conf

Where <backend> and <doctype> are values specified by the asciidoc(1) -b (—backend) and -d

(—doctype) command-line options.

Finally, configuration files named like the source file will be automatically loaded if they are found in the source file directory. For example if the source file is mydoc.txt and the —backend=html4 option is used then asciidoc(1) will look for mydoc.conf and mydoc-html4.conf in that order.

Implicit configuration files that don't exist will be silently skipped.

The user can explicitly specify additional configuration files using the asciidoc(1) -f (—conf-file) command-line option. The -f option can be specified multiple times, in which case configuration files will be processed in the order they appear on the command-line.

For example, when we translate our AsciiDoc document mydoc.txt with:

$ asciidoc -f extra.conf mydoc.txt

Configuration files (if they exist) will be processed in the following order:

1.First default global configuration files from the asciidoc program directory are loaded:

asciidoc.conf

xhtml11.conf

2.Then, from the users home ~/.asciidoc directory. This is were you put customization specific to your own asciidoc documents:

asciidoc.conf

xhtml11.conf xhtml11-article.conf

53