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


3.2. Example Paragraphs


3.2.1. Simple Examples

The tag used for example (i.e. fixed-width) paragraphs is usually E. For example:

E:sub Greeting {
E:  print "Hello world\n";
E:}

The result is:

sub Greeting {
    print "Hello world\n";
}

As fixed-width text is very common in software documentation, SDF provides "=" as a shorthand for "E:". For example:

=sub Greeting {
=    print "Hello world\n";
=}

Unlike most other paragraphs, spaces and tabs immediately after the paragraph tag are not ignored in example paragraphs.

Large examples are usually defined using the block and endblock macros as follows:

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

3.2.2. Pure Examples

Example blocks support the pure parameter. For example:

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

SDF uses special symbols (like {{ and }}) to delimit phrases inside paragraphs. The pure parameter "escapes" these symbols so that the text is included exactly as it is.


3.2.3. 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. A typical result is:

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

    # Do the work
    # ...
}

3.2.4. 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.5. 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.


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