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.
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 |
For files, the following extensions should be used:
For variables, the general conventions are:
The general conventions for other symbols are:
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.
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.
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:
Typically, each project has a configuration library which is loaded into each document via the inherit macro.
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:
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.
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 |
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 |
|
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 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 |
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 |
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. |
Tables are usually defined using blocks. The first "record" specifies:
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
Time of day | Appointment |
Morning: | |
10:00 | Dentist |
12:00 | Lunch with friends |
Afternoon: | |
15:00 | Meeting on SDF |