5.14. example Filter


The general syntax is:

  !block example[; parameters]

The parameters are:

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

See Understanding Filter Interfaces, if necessary.


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.


# 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'