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 (vgrind 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.