Filters

Prev

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.


	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.


	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:

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).


	A full featured source code highlighter filter (`source-highlight-filter.conf`) using GNU source-highlight can be found in the AsciiDoc distribution `./examples/source-highlight-filter` directory. GNU source-highlight generates nicely formatted source code for most common programming languages.

Example 2. Shell source file source-highlight-filter example

#!/bin/bash
#
# rc file for automount using a Sun-style "master map".
# We first look for a local /etc/auto.master, then a YP
# map with that name
#

FLAGS="defaults 21"
DAEMON=/usr/sbin/automount
prog=`basename $DAEMON`
initdir=/etc/init.d