# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Example Paragraphs

H2: Simple Examples

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

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

The result is:

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

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

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

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 verbatim
!block example
# {{Greeting}} outputs a friendly greeting.
sub Greeting {
    print "Hello world\n";
}
!endblock
!endblock

H2: Pure Examples

Example blocks support the {{pure}} parameter.
For example:

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

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

H2: 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:

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

    # Do the work
    # ...
}
!endblock

H2: Formatting Source Code

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

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

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

The result is:

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

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

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}} definitions are used).

H2: File Pretty Printing

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

E:  sdf -2ps -Psh myscript
E:  sdf -2ps -P myapp.c
E:  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.

!end_topic
