SDF 2.000: SDF Quick Reference

Home | Catalog

# SDF Quick Reference

## Table of Contents

1. Overview

1.1. Purpose
1.2. Basic Concepts
1.3. Naming Conventions
1.4. Conversion Commands

2. Simple Document Format

2.1. Initialisation
2.2. Loading Configuration Information
2.3. Document Registers
2.4. Document Titles
2.5. Paragraph Styles
2.6. Phrase Styles
2.7. Macros
2.8. Filters
2.9. Tables

# 1. Overview

## 1.1. Purpose

This guide provides a quick reference to the most commonly used aspects of SDF 2.000. The following manuals may also be useful:

- SDF User Guide - a tutorial-style introduction to SDF
- SDF Reference - detailed reference information on most SDF features.

Everything the average SDF user needs to know for 90% of his or her documents should be provided by this document. Nevertheless, as SDF is highly configurable, your workgroup might regularly use additional commands/styles/etc. to those given below. See your system administrator for details of any local extensions.

## 1.2. Basic Concepts

Term | Description
paragraph | the basic building block of documents
phrase | a section of text delimited by {{ and }} within a paragraph
style | the type of a document, paragraph, phrase or table (e.g. H1)
attribute | a property of a paragraph or phrase (e.g. jump)
macro | a command embedded in a document (e.g. !define)
variable | a named value (e.g. DOC_NAME)
block | a section of text enclosed by block and endblock macros
filter | a rule to use when processing blocks or files (e.g. table)
module | a file containing reusable information
library | a directory containing modules

## 1.3. Naming Conventions

For files, the following extensions should be used:

- sdf - for normal SDF files
- sdm - for SDF modules
- reg - a register of documents.

For variables, the general conventions are:

- lower-case for special characters (e.g. tm)
- edit-case for commonly used objects (e.g. Mincom)
- upper-case for other variables (e.g. DOC_NAME).

The general conventions for other symbols are:

- upper-case for paragraph and phrase styles
- lower-case for other names.

## 1.4. Conversion Commands

The sdf program is typically invoked as follows:

       sdf -2format [options] files

Supported format values are given below.

Format | Description
ps | a PostScript document
html | a HTML document
hlp | Microsoft Windows help input files
doc | a FrameMaker binary file
fvo | a FrameViewer file
txt | a plain text document
rtf | an RTF document
pod | a pod document (the standard for Perl documentation)
book | a PostScript document via a FrameMaker book

If the sdf command is given without any parameters, a concise list of the available options is displayed. The -h option outputs a brief description of each option.

# 2. Simple Document Format

## 2.1. Initialisation

Variables can be initialised on the top line of a document via the init macro. For example:

       !init OPT_STYLE="manual"; OPT_LOOK="infomap"

The supported styles are given below.

Style | Description
document | normal document (default)
manual | user manual
paper | technical paper
memo | memorandum
fax | fascimile
minutes | minutes of a meeting
newslettr | newsletter

The default value for OPT_LOOK is specified in the `sdf.ini` file. The init macro can be used to override the default. sdf's -k option overrides both values.

## 2.2. Loading Configuration Information

The following macros can be used to load configuration information:

- inherit - load a library
- use - load a module.

A library is a directory (under sdf/home) which contains one or more modules. The inherit macro does the following:

1. it adds the directory to sdf's search path
2. it loads a module of the same name from that directory.

Typically, each project has a configuration library which is loaded into each document via the inherit macro.

## 2.3. Document Registers

Each project should have a document register which is stored in TBL format and included into the project configuration library. The fields in the register are given below.

Field | Description
Reference | the document code
Document | the document title
Jump | the filename of the document
Version | the document version number
Status | the document status (e.g. Draft, Review or Final)

The register is useful for several reasons:

1. an online document catalog can be generated from it
2. hypertext jumps to documents can be generated from it
3. it simplifies the building of title pages (see below).

## 2.4. Document Titles

For normal documents, the title page is generated by the build_title macro. The following variables can be defined before build_title is called.

Variable | Description
Recommended: |
DOC_NAME | e.g. SDF
DOC_TYPE | e.g. Quick Reference
Optional: |
DOC_AUTHOR | primary author or document owner
DOC_APPROVE | position of person approving document, if any

Additional authors and approvers can be specified using DOC_AUTHOR2, DOC_AUTHOR3, DOC_APPROVE2 and DOC_APPROVE3. The macros below are also optionally used.

Macro | Description
DOC_RECIPIENTS | table of people, if any, receiving controlled copies
DOC_TRADEMARKS | trademark information

The code, status and version of a document are found from the document register. Alternatively, they can be explicitly specified via the DOC_CODE, DOC_STATUS and DOC_VERSION variables.

## 2.5. Paragraph Styles

Normal styles are terminated by a colon (:) or left bracket ([). Special styles are implicitly terminated.

Tag | Description
Normal styles: |
H1 .. H6 | normal heading at level 1..6
A1 .. A6 | appendix heading at level 1..6
P1 .. P6 | plain heading at level 1..6
Note | a single paragraph note
Special styles: |
. .. ...... | paragraph (or plain list item) at level 1..6
* .. ****** | unordered list at level 1..6
- .. ----- | unordered list at level 2..6
^ .. ^^^^^^ | first entry in an ordered list at level 1..6
+ .. ++++++ | next entry in an ordered list at level 1..6

## 2.6. Phrase Styles

Phrases are enclosed in {{ and }}. Like paragraphs styles, phrase styles are terminated by a colon (:) or left bracket ([). Styles emphasize and/or logically type phrases - hypertext is automatically generated for many of the logically typed phrases.

Tag | Description | Sample Output
Emphasis: |  |
1 | 1st level emphasis | emphasis 1
2 | 2nd level emphasis | emphasis 2
3 | 3rd level emphasis | emphasis 3
A | as-is | some as-is text
B | bold | some bold text
E | example | some example text
I | italic | some italics text
N | normal | some normal text
U | underline | some underline text
Types: |  |
CMD | Command | sdf
DOC | Document | SDF User Guide
EMAIL | email address | ianc@mincom.com
FILE | Filename | `myfile.sdf`
ORG | Organisation | Mincom
PRD | Product | MIMS
REF | Reference | MTR-SDF-0003
SECT | Section | Paragraph Styles
URL | Uniform Resource Locator | http://www.mincom.com

## 2.7. Macros

Macros begin with an exclamation mark (!).

Macro | Arguments | Description
init | variables | initialise variables (on top line)
inherit | library | load a library
use | file [; filter] | load a library module
define | variable [expr] | set a variable
default | variable [expr] | define a variable if it is undefined
build_title |  | build a title page
block | filter | begin a block of text
endblock |  | end a block of text
include | file [; filter] | include another file
import | file [; params] | import a figure

## 2.8. Filters

Filters are named rules for processing blocks or included text.

Filter | Description
table | tabular data
example | fixed-width text (e.g. source code)
title | define a title block for memos, faxes, etc.

## 2.9. Tables

Tables are usually defined using blocks. The first "record" specifies:

- the column headings
- the input format - either delimited or fixed-width.

Note: If the first "non-word" character in the column headings is a space or tab, the columns are assumed to be fixed-width. Otherwise, the character found is used as the delimiter character.

Commonly used parameters are given below.

Attribute | Description
style | type of table (e.g. columns, rows, grid, plain, shade)
format | output format of columns in 10% units
coltags | comma separated list of phrase styles for columns
groups | records ending with : are group headings
title | title for the table

A sample table (and its result) is given below.

    !block table; format=55; style="grid"; groups; title="Diary"
    Time_of_day     Appointment
    Morning:
    10:00           Dentist
    12:00           Lunch with friends
    Afternoon:
    15:00           Meeting on SDF
    !endblock

Diary
Time of day | Appointment
Morning: |
10:00 | Dentist
12:00 | Lunch with friends
Afternoon: |
15:00 | Meeting on SDF

Home | Catalog