Home | Catalog

SDF Quick Reference

MTR-SDF-0003.001 (Final)
Ian Clatworthy
1 March 1998


Table of Contents


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:

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:

For variables, the general conventions are:

The general conventions for other symbols are:

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:

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:


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