SDF 2.001: SDF User Guide: A simple example

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

# 1.3. A simple example

## 1.3.1. A sample SDF document

A sample SDF document is shown below:

    # Build the title
    !define DOC_NAME           "GalaxyBuilder"
    !define DOC_TYPE           "Discussion Paper"
    !define DOC_AUTHOR         "Joe Bloggs"
    !build_title

    H1: Introduction

    After extensive market research, I believe there is
    an excellent opportunity for us to develop software
    for the I<galaxy construction industry>. Potential
    customers include:

    * NASA
    * European Community
    * China
    * Japan.

    Note: The proposed name of the software package to be
    developed is [[DOC_NAME]]. If you want to suggest a
    better name, send email to {{EMAIL:joe@bloggs.com}}.

    H2: Software Requirements

    The key requirements are:

    ^ support for the design and simulation of galaxies
      containing up to:
      - 1000 large planets, or
      - 5000 small planets
    + the package needs to be easy to use
    + the package needs to be well documented.

    H2: Project Team

    Exploding galaxies will be B<very> bad for business,
    so we need the best team possible for this project:

    !block table
    Person          Role
    Mary Jones      Project Manager
    Hans Blass      Architect
    Bill Smith      Software Engineer
    !endblock

Note: This document (called `mydoc.sdf`) is provided in the `doc/paper` directory of the SDF distribution.

## 1.3.2. A brief explanation

Comments begin with a # character as the first non-whitespace character on a line.

Macros are embedded commands which begin with a ! as the first non-whitespace character on a line. The define macro is used to set variables. The value of a variable can be embedded in paragraph text by using the [[...]] syntax.

The DOC_NAME and DOC_TYPE variables are used by the build_title macro which creates:

- a cover page (or two) for paper-based outputs
- a title header for online outputs.

Paragraphs can be tagged in different ways. For the vast majority of SDF documents, the only tags used are:

Tag | Meaning
H1: | level 1 heading
H2: | level 2 heading
* | item in level 1 bulleted list
- | item in level 2 bulleted list
^ | first item in level 1 ordered list
+ | next item in level 1 ordered list
> | fixed-width, verbatim text
Note: | note

Phrases can also be tagged in several ways. Any phrase can be tagged using the syntax:

      {{XYZ:...}}

where XYZ is the tag. For single, uppercase character tags like I (Italics) and B (Bold), POD-style syntax is also supported:

      X<...>

where X is the tag.

Tables can be specified using the table filter, typically in combination with the block and endblock macros. The first row is the headings. Remaining rows are data.