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'