AsciiDoc User Guide

Table behaviour is also influenced by the following [miscellaneous] configuration file entries:

textwidth

The page width (in characters) of the source text. This setting is compared to the the table ruler width when calculating the relative size of character ruler tables on the output page.

pagewidth

This integer value is the printable width of the output media. Used to calculate colwidth and tablewidth substitution values.

pageunits

The units of width in output markup width attribute values.

Table definition behavior

•The output markup generation is specifically designed to work with the HTML and CALS (DocBook) table models, but should be adaptable to most XML table schema.

•Table definitions can be “mixed in” from multiple cascading configuration files.

•New table definitions inherit the default table definition ([tabledef-default]) so you only need to override those conf file entries that require modification when defining a new table type.

Filters

Filters are external shell commands used to process Paragraph and DelimitedBlock content; they are specified in configuration file Paragraph and DelimitedBlock definitions.

There's nothing special about the filters, they're just standard UNIX filters: they read text from the standard input, process it, and write it to the standard output.

Attribute substitution is performed on the filter command prior to execution — attributes can be used to pass parameters from the AsciiDoc source document to the filter.

Warning

Filters can potentially generate unsafe output. Before installing a filter you should verify that it can't be coerced into generating malicious output or exposing sensitive information.

Note

Filter functionality is currently only available on POSIX platforms (this includes Cygwin).

Filter Search Paths

If the filter command does not specify a directory path then asciidoc(1) searches for the command:

65

AsciiDoc User Guide

•First it looks in the user's $HOME/.asciidoc/filters directory.

•Next the /etc/asciidoc/filters directory is searched.

•Then it looks in the asciidoc(1) ./filters directory.

•Finally it relies on the executing shell to search the environment search path ($PATH).

Filter Configuration Files

Since filters are normally accompanied by a configuration file containing an example filter Paragraph or filter DelimitedBlock definition.

asciidoc(1) auto-loads all .conf files found in the user's $HOME/.asciidoc/filters directory and the asciidoc(1) ./filters subdirectory.

Code Filter

AsciiDoc comes with a simple minded code-filter for highlighting source code keywords and comments. You'll find this example in the AsciiDoc distribution ./filters subdirectory (read the

./filters/code-filter-readme.txt file for instructions).

The following example highlights Python keywords in the block's content:

.Code filter example [python]

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

''' A multi-line comment.''' def sub_word(mo):

''' Single line comment.'''

word = mo.group('word') # Inline comment if word in keywords[language]:

return quote + word + quote else:

return word

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Outputs:

Example 3. Code filter example

'''A multi-line comment.'''

def sub_word(mo):

''' Single line comment.'''

word = mo.group('word') # Inline comment if word in keywords[language]:

return quote + word + quote else:

return word

66