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.