Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog
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
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.
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 # ... }
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 (
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