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

# 3.2. Example Paragraphs

## 3.2.1. Simple Examples

Example paragraphs are displayed in a fixed-width font (e.g. Courier). Unlike most other paragraphs, spaces and tabs immediately after the paragraph tag are not ignored in example paragraphs. The tags used are:

- E - fixed-width text
- V - verbatim, fixed-width text (embedded symbols are ignored).

For example:

    E:# {{Greeting}} outputs a friendly greeting.
    E:sub Greeting {
    E:    print "Hello world\n";
    E:}

The result is:

    # Greeting outputs a friendly greeting.
    sub Greeting {
        print "Hello world\n";
    }

## 3.2.2. Shorthand Notation

As verbatim, fixed-width text is very common in software documentation, ">" is provided as a shorthand for "V:". For example:

    ># {{Greeting}} outputs a friendly greeting.
    >sub Greeting {
    >    print "Hello world\n";
    >}

The result is:

    # {{Greeting}} outputs a friendly greeting.
    sub Greeting {
        print "Hello world\n";
    }

## 3.2.3. Large Examples

Large examples are usually defined using the example or verbatim filters like this:

    !block example
    # {{Greeting}} outputs a friendly greeting.
    sub Greeting {
        print "Hello world\n";
    }
    !endblock

## 3.2.4. Wide Examples

If an example block has unwanted line breaks, the wide parameter should be specified. Wide examples use a wider text area (and a smaller font, if necessary) so that 80 characters can fit onto each line. For example:

    !block example; wide
    sub SaveTheWorld {                  # This routine provides world peace
        local($param1, param2) = @_;    # Input parameters

        # Do the work
        # ...
    }
    !endblock

The result is:

    sub SaveTheWorld {                  # This routine provides world peace
        local($param1, param2) = @_;    # Input parameters

        # Do the work
        # ...
    }

## 3.2.5. Formatting Source Code

Blocks of source code can be nicely formatted via the lang parameter to the example filter. For example:

    !block example; lang='Perl'
    sub hello {
        local($planet) = @_;

        # Output a nice message
        print "hello $planet!\n";
    }
    !endblock

The result is:

    sub hello {
        local($planet) = @_;

        # Output a nice message
        print "hello $planet!\n";
    }

For convenience, if a programming language is used as a filter (and a filter of that name doesn't exist), SDF implicitly calls the example filter for you with the relevant lang parameter.

There is built-in support for numerous languages including Perl, C, C++, Java, Delphi, CORBA IDL and shell. New language definitions can be easily added (<CMD>vgrind</CMD> definitions are used).

## 3.2.6. File Pretty Printing

Pretty printing of source code files is directly supported by sdf's -P option. For example:

      sdf -2ps -Psh myscript
      sdf -2ps -P myapp.c
      sdf -2ps -P -n5 mylib.pl

The language to use can be specified as a parameter. The default language is derived from the extension of the file. The -n option adds line numbers at the frequency given. The default frequency is 1. i.e. every line.