Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

# 5.14. example Filter

## Interface

The general syntax is:

      !block example[; parameters]
      ...
      !endblock

The parameters are:

Name | Type | Rule
skipheader | boolean |
lang | string |
wide | boolean |
listitem | integer |
pure | boolean |

See Understanding Filter Interfaces, if necessary.

## Description

The example filter is used to specify a section of fixed-width text. Unlike the verbatim filter, embedded SDF symbols (like {{) are relevant.

The skipheader parameter is useful when an external file is being included as an example, but you do not want the header comment in the example. The lang parameter, if any, is used to determine the commenting conventions. If no language is specified, comments are assumed to start with a # and be terminated by the end of line.

The lang parameter can be used to pretty-print programming languages. In practice, this means:

- comments are output in italics
- keywords are output in bold.

Note: The langdefs filter is used to configure the information the pretty-printing feature needs to know. A large number of languages are predefined in the `stdlib/langdefs.sdm` file.

The wide parameter can be used to ensure that at least 80 characters are output on a line before it is wrapped.

The listitem parameter can be used to specify that this block of text is part of a list. The value is the logical indent of the list (e.g. 1, 2, etc.).

The pure parameter can be used to escape special SDF symbols (like {{) embedded within the text.

## Examples

    # Include myfile.c but exclude the copyright, revision history, etc.
    !include "myfile.c"; example; skipheader; lang='c'

    # Pretty-print the same file
    !include "myfile.c"; example; wide; lang='c'