SDF Reference - Internodeiangeri/sdfng/docs/2.001/ref/re_sdf.pdfSDF 2.001 SDF Reference

SDF 2.001

SDF Reference

SDF 2.001MTR-SDF-0004.001

ii 25-May-99© Ian Clatworthy

Copyright Copyright © 1999, Ian Clatworthy

All rights reserved.

You are free to copy and distribute this manual as often as you like. Ifparts of this manual are included in commercial products such as booksand magazine articles, creditmust be given to the author.

Trademarks FrameMaker, FrameViewer, Acrobat, PDF and PostScript are registeredtrademarks of Adobe Systems Incorporated.

Windows is a registered trademark of Microsoft Corporation.

Unix is a registered trademark of X/Open Company Ltd.

Infomation Mapping is a registered trademark of Information Mapping,Incorporated.

Other trademarks are the property of their respective owners.

Tools This document was generated using SDF 2.001.

SDF 2.001MTR-SDF-0004.00125-May-99 iii© Ian Clatworthy

Table of ContentsAbout This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

1 Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1organisations Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2products Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3references Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4terms Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

2 Document Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

3 Escape Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

4 File Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1INI Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2SDG Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3TBL Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

5 Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1about Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3abstract Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4address Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5appendix Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6ascii_graphic Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7box Filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8changed Filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9comment Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10datestrings Filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11default Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12define Filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14end Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16example Filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17front Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19get Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20hlp_header Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21hlp_window Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22inline Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23langdefs Filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24namevalues Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25nofill Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26note Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27

SDF 2.001MTR-SDF-0004.001

iv 25-May-99© Ian Clatworthy

plain Filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29pod Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30quote Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-31script Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-32sdf Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-33sections Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-34simple Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-35table Filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-36title Filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-40topics Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-41verbatim Filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-43

6 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1block Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3build_title Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4catalog Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5class Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6clear Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7continued Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8default Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10define Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11else Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12elseif Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13elsif Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14end_topic Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15endblock Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16endif Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17endmacro Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18execute Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19export Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20getcli Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21getcode Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22getdoc Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23if Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24import Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25include Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26inherit Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27init Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-28insert Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29jumps Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30

SDF 2.001MTR-SDF-0004.00125-May-99 v© Ian Clatworthy

line Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31macro Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-32message Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-33off Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34on Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35output Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36perlapi Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37restrict Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-38script Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-39slide_down Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-40slide_up Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-41subsections Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-42undef Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-43use Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44

7 Paragraph Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

8 Paragraph Styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

9 Phrase Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

10 Phrase Styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

11 Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1sdf - SDF Conversion Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2sdfapi - API Extraction Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-11sdfbatch - Batch Processing Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-13sdfcli - Command Line Interface Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-17sdfget - Documentation Extraction Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-19sdftest - Execute SDF Regression Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-23sdngen - SDF Tuning File Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-24prn2ps - PostScript Conversion Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-26

12 Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1AppendText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2FindFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3FormatTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5PrependText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7

13 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1Conversion Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2Document Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3File Information Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4

SDF 2.001MTR-SDF-0004.001

vi 25-May-99© Ian Clatworthy

Miscellaneous Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5

A Understanding Class Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2Building the Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3Filtering and Sorting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5

B Understanding Filter Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1Data Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2

C Understanding Macro Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .C-1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .C-1Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .C-3

D Command Line Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .D-1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .D-1Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .D-3Commonly Used Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .D-6

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index-1

About This Manual

SDF 2.001MTR-SDF-0004.00125-May-99 vii© Ian Clatworthy

About This Manual

Purpose This manual is a reference for SDF - a documentation system forsoftware developers.

Scope This manual contains detailed reference material on most SDF features.

The following documents may also be of interest:

• The SDF Document Development System - an overview of thearchitecture and features

• SDF User Guide - a tutorial style introduction to the key features

• SDF Quick Reference - a concise summary of the most frequentlyused SDF features

• SDF Guru Guide - information on extending SDF.

Amendments Suggested enhancements and corrections to SDF and its documentationcan be forwarded [email protected].

Note: This manual documents version 2.001 of SDF.

About This Manual

SDF 2.001MTR-SDF-0004.001

viii 25-May-99© Ian Clatworthy

ClassesOverview

SDF 2.001MTR-SDF-0004.00125-May-99 1-1© Ian Clatworthy

Chapter 1. Classes

OverviewThe classes available are summarised below.

Further details on these are provided below.

Name Purpose

references references/documents

terms terms/definitions

organisations organisations

products products

Classesorganisations Class

SDF 2.001MTR-SDF-0004.001

1-2 25-May-99© Ian Clatworthy

organisations Class

Interface The general syntax is:

!block organisations [; parameters] table of objects !endblock

The object attributes are:

SeeUnderstanding Class Interfaces, if necessary.

Description Theorganisations filter is used to declare and/or format objects in theorganisations class. The attributes supported are:

Examples See theobjects.sdm file within SDF'sstdlib directory.

Field Category Rule

Name mandatory

Long optional

Jump optional

Attribute Description

Name the organisation name

Jump the organisation URL, if any

Classesproducts Class


products Class


!block products [; parameters] table of objects !endblock



Description Theproducts filter is used to declare and/or format objects in theproductsclass. The attributes supported are:

Examples See theobjects.sdm file within SDF'sstdlib directory.

Field Category Rule

Name mandatory

Jump optional


Name the product name

Jump the product URL, if any

Classesreferences Class

SDF 2.001MTR-SDF-0004.001


references Class


!block references [; parameters] table of objects !endblock



Description Thereferences filter is used to declare a set of references and matchingdocuments. It can also be used to build a table of references within adocument.

The attributes supported are:

Examples See thesdf.sdm anddocument.reg files within SDF'ssdf directory.

Field Category Rule

Reference mandatory

Document optional

Jump optional

Version optional

Status optional


Reference the document code

Document the document name

Version the document version

Status the document status

Jump the URL, if any

Classesterms Class


terms Class


!block terms [; parameters] table of objects !endblock



Description Theterms filter is used to declare and/or format objects in theterms class.The attributes supported are:

Examples A configuration file may have the following declaration of terms:

!block terms; data Term Definition SDF Simple Document Format SQL Structured Query Language !endblock

These can then be inserted into a document as follows:

!block terms Term Definition SDF SQL WWW World Wide Web !endblock

Field Category Rule

Term mandatory

Definition optional

Jump optional


Term the term name

Definition the explanation for the term

Classesterms Class

SDF 2.001MTR-SDF-0004.001


Note that the definition for a term already declared will be inserted ifnone is provided. Furthermore, new terms (like WWW above) can beinserted and added to the configured ones.

Document Styles


Chapter 2. Document Styles

The document styles available are summarised below.

For HTML output, the general styles are all the same. For PostScriptoutput, they typically differ as follows:

• document - single-sided, busy cover page, busy headers/footers, tableof contents

• manual - double-sided, simple cover page, simple header/footers,table of contents

• paper - single-sided, no cover page (just a centered title), simpleheader/footers, no table of contents.

Style Purpose

General:

document a normal document

manual a manual

paper a technical paper

Administration:

admin generic administration document

fax a fascimile

memo a memorandum

newslttr a newsletter

minutes minutes of a meeting

Miscellaneous:

listing a source code listing

Document Styles

SDF 2.001MTR-SDF-0004.001


Escape Characters


Chapter 3. Escape Characters

The escape characters available are summarised below. Escape charactersare entered in paragraphs using either theE or CHAR phrase styles.

Escape Characters

SDF 2.001MTR-SDF-0004.001


Symbol Description Output

Syntax related:

lt less-than <

gt greater-than >

2{ double left brace {{

2} double right brace }}

2[ double left bracket [[

2] double right bracket ]]

Special symbols:

amp ampersand &

bullet bullet •

c copyright ©

cent cent ¢

dagger dagger †

doubledagger double dagger ‡

emdash em-dash —

endash en-dash –

emspace em-space

enspace en-space

lbrace left brace {

lbracket left bracket [

nbdash non-breaking hyphen -

nbspace non-breaking space

nl newline

pound pound £

quot double quote "

r registered trademark ®

rbrace right brace }

rbracket right bracket ]

tab tab

tm trademark ™

yen yen ¥

Escape Characters


International:

Aacute capital A, acute accent Á

aacute small a, acute accent á

Acirc capital A, circumflex accent Â

acirc small a, circumflex accent â

AElig capital AE diphthong (ligature) Æ

aelig small ae diphthong (ligature) æ

Agrave capital A, grave accent À

agrave small a, grave accent à

Aring capital A, ring Å

aring small a, ring å

Atilde capital A, tilde Ã

atilde small a, tilde ã

Auml capital A, dieresis or umlaut mark Ä

auml small a, dieresis or umlaut mark ä

Ccedil capital C, cedilla Ç

ccedil small c, cedilla ç

Eacute capital E, acute accent É

eacute small e, acute accent é

Ecirc capital E, circumflex accent Ê

ecirc small e, circumflex accent ê

Egrave capital E, grave accent È

egrave small e, grave accent è

Euml capital E, dieresis or umlaut mark Ë

euml small e, dieresis or umlaut mark ë

Iacute capital I, acute accent Í

iacute small i, acute accent í

Icirc capital I, circumflex accent Î

icirc small i, circumflex accent ê

Igrave capital I, grave accent È

igrave small i, grave accent ì

Iuml capital I, dieresis or umlaut mark Ï

iuml small i, dieresis or umlaut mark ï


Escape Characters

SDF 2.001MTR-SDF-0004.001


Ntilde capital N, tilde Ñ

ntilde small n, tilde ñ

Oacute capital O, acute accent Ó

oacute small o, acute accent ó

Ocirc capital O, circumflex accent Ô

ocirc small o, circumflex accent ô

Ograve capital O, grave accent Ò

ograve small o, grave accent ò

Oslash capital O, slash Ø

oslash small o, slash ø

Otilde capital O, tilde Õ

otilde small o, tilde õ

Ouml capital O, dieresis or umlaut mark Ö

ouml small o, dieresis or umlaut mark ö

Uacute capital U, acute accent Ú

uacute small u, acute accent ú

Ucirc capital U, circumflex accent Û

ucirc small u, circumflex accent û

Ugrave capital U, grave accent Ù

ugrave small u, grave accent ù

Uuml capital U, dieresis or umlaut mark Ü

uuml small u, dieresis or umlaut mark ü

yuml small y, dieresis or umlaut mark ÿ


File FormatsOverview


Chapter 4. File Formats

OverviewThe file formats used are summarised below.


Note: sdm, sds andsdn files are normal SDF files used for normalmodules, style modules and tuning modules respectively.

Name Purpose

INI defines initialisation data

SDG defines formatting rules forsdfget

TBL defines a table

File FormatsINI Format

SDF 2.001MTR-SDF-0004.001


INI Format

Purpose INI files are used to store simple configuration information for scripts.

Description An INI file contains of a series of sections. Each section begins with aheader enclosed in '[' and ']'. Comment lines begin with ';' or '#' as the firstnon-whitespace character. Blank lines before a section or at the end of asection are ignored.

Examples A sample file is:

[Drivers]Format Library Subroutine Bookmif sdf2mif.pl MifFormat MifBookraw sdf2raw.pl RawFormat

[PostProcessing]ps = &SdfBatch("-pfile")doc = &SdfBatch("-sdoc -Sd")

File FormatsSDG Format


SDG Format

Purpose SDG files are used to format information extracted from source code bysdfget.

Description An SDG is a table ofKey-Format pairs. For example:

Key Format - "Key\t\tDescription\n" * sprintf("%-15.15s\t%s\n", $key, $data)

The first line specifies the layout of the table and is required. An item isonly printed if it has a description. TheKey field can be one of thefollowing:

• an item name

• a minus (-) character, indicating free text

• an asterix (*) character, indicating all remaining items

TheFormat field is a Perl expression.$key and$data are used to indicatethe key and description of the current item respectively. Other availablesymbols are:

• $dir - directory component of current file

• $base - base component of current file

• $ext - extension component of current file

• $short - base & extension components of current file

Examples The SDG file used to format topics within the SDF documentation is:

Key Format- "!use 'sdgmacs'\n!SDG_BEGIN\n"Title "H1[id=\"$short\"] $short - $data\n\n"Purpose "H2: $key\n\n$data\n\n"Interface "H2: $key\n\n$data\n\n"- "!SDG_DESCRIPTION_PRE\n"Description "H2: $key\n\n$data\n\n"- "!SDG_DESCRIPTION_POST\n"Notes "H2: $key\n\n$data\n\n"Examples "H2: $key\n\n$data\n\n"Limitations "H2: Limitations and futuredirections\n\n$data\n\n"See_also "H2: See also\n\n$data\n\n"Authors "H2: $key\n\n$data\n\n"- "!SDG_END\n"

File FormatsTBL Format

SDF 2.001MTR-SDF-0004.001


TBL Format

Purpose TBL format is a text-based format for storing tabular data.

Overview The basic rules are:

• blank lines and comment lines are ignored,

• the first data line specifies the record format,

• each remaining data line specifies a single record.

Comment lines begin with # as the first non-whitespace character.

Record Formats For a given table, all records have the same format. The record format iseither:

• delimited - fields are separated by a special character, or

• fixed-width - fields are defined by column positions.

An example of delimited format is given below.

# A simple TBL exampleName:Age:Phone:AddrBill:42:397 1234:14 Smith St, New FarmSarah:37:892 4321:105 Brown St, ChelmerJoe:44:365 7890:6 Royal Av, Buranda

An example of fixed-width format is given below.

# A simple TBL exampleName Age Phone AddrBill 42 397 1234 14 Smith St, New FarmSarah 37 892 4321 105 Brown St, ChelmerJoe 44 365 7890 6 Royal Av, Buranda

Note: Tabs in fixed-width records are assumed to be 8 spaces wide.

Input FormatSpecification

The first data line is called theinput format specification. It specifies:

• the name and order of the fields in each record

• the record format - delimited or fixed-width

Field names can contain:



• alphanumeric characters (A-Z, a-z, 0-9)

• the underscore character (_)

If the first character after the first field name is a space or tab, the formatis assumed to befixed width. Otherwise, the format isdelimited withfields separated by the special character found.

Multi-line Fields Generally, each data line specifies a single record. However, if the lastfield begins with the sequence '<<', then it is a multi-line field terminatedby the first line beginning with '>>'. Multi-line fields are supported byboth record formats.

Within a multi-line field, blank lines and lines starting with # are treatedas part of that field. i.e. it is not possible to embed a comment line withina multi-line field.

An example of a table containing multi-line fields is given below.

# A simple TBL example with multi-line fieldsName Age Phone AddrBill 42 397 1234 <<14 Smith StNew Farm QLD 4005>>Sarah 37 892 4321 <<105 Brown StChelmer QLD 4068>>Joe 44 365 7890 <<6 Royal AvBuranda QLD 4102>>

SpecialCharacters inFields

For delimited fields:

1. If a field contains the delimiter character or the double quotecharacter, it must be enclosed in double quotes.

2. A double quote character within a field is represented by two doublequotes.

3. Leading whitespace is kept.

4. Trailing whitespace is kept.

For fixed-width fields:

1. Leading whitespace is kept.

2. Trailing whitespace is removed.


SDF 2.001MTR-SDF-0004.001


Note: Multi-line fields are enclosed by the << and >> symbols so none ofthe rules above apply to them.

FiltersOverview


Chapter 5. Filters

OverviewThe filters available are summarised below.

Name Purpose

General:

table tabular data

note a note

quote a quotation

abstract the abstract for a paper

title title block for a memo, fax or minutes

Line based:

example fixed-width text (e.g. source code)

verbatim fixed-width text, ignoring embedded symbols

ascii_graphic fixed-width text, wide enough for ASCII graphics

nofill a set of lines

address an address

Components:

front front section of a document

about about section of a document

appendix change headings to appendix style

plain change headings to plain style

Formatting:

box surround a region of text with a box

changed mark a block of text as changed

sections paragraphs are sections

namevalues format a set of name-value pairs (e.g. as used in atitle block)

sdf apply arbitrary phrase attributes to text

pod embedded POD

File processing:

comment ignore text

topics include a set of sub-topics

FiltersOverview

SDF 2.001MTR-SDF-0004.001



inline embed text into target format (e.g. HTML)

script execute text as a Perl script

end process text at the end

get extract embedded documentation

Configuration:

langdefs define vgrind-like language definitions

define define a block of variables

default provide defaults for a block of variables

simple generic filter for building others

datestrings define strings used within dates

Help:

hlp_header table of jumps at the top of a help topic

hlp_window contents of a help popup window

Name Purpose

Filtersabout Filter


about Filter


!block about ... !endblock

SeeUnderstanding Filter Interfaces, if necessary.

Description Theabout filter is used when including a topic as an "about" sectionwithin a document. Typically, this implies:

• the headings are converted to plain headings and slid down one level

• the headings (except those initially at level 1) are removed from thetable of contents.

Examples A typical book might look like this:

!init OPT_STYLE="manual"

!define DOC_NAME"A Sample Book"!build_title

!include "myabout.sdf" ; about!include "chapter1.sdf"!include "chapter2.sdf"!include "chapter3.sdf"!include "appendx1.sdf" ; appendix

A typical about topic looks like this:

H1: About this manual

H2: Purpose

This manual provides information on ...

H2: Scope

This manual contains information on ...

Filtersabstract Filter

SDF 2.001MTR-SDF-0004.001


abstract Filter


!block abstract ... !endblock


Description Theabstract filter is used to specify an abstract for a technical paper. Thistypically implies:

• for PostScript, the text is italics and indented from both margins

• for HTML, the text is given an appropriate heading.

Examples A typical paper starts like this:

!init OPT_STYLE="paper"!define DOC_NAME"Internet Management Tools"!define DOC_AUTHOR"I. M. Wise"!build_title

!block abstractThe internet is out of control. This paper ...

# more paragraphs go here

!endblock

H1: Introduction

# The interesting stuff goes here

Filtersaddress Filter


address Filter


!block address ... !endblock


Description Theaddress filter is used to format an address. This typically implies:

• for PostScript, the paragraphs have no space between them

• for HTML, the paragraphs are given ADDRESS tags.

Examples A typical letter starts like this:

!block addressMr I.M. Lucky13 Horseshoe DriveBrisbane Q 4001!endblock

Filtersappendix Filter

SDF 2.001MTR-SDF-0004.001


appendix Filter


!block appendix ... !endblock


Description Theappendix filter is used when including a topic as an "appendix"section within a document, i.e. normal headings are converted toappendix headings.




!include "chapter1.sdf"!include "chapter2.sdf"!include "chapter3.sdf"!include "appendx1.sdf" ; appendix

Filtersascii_graphic Filter


ascii_graphic Filter


!block ascii_graphic ... !endblock


Description Theascii_graphic filter is used to specify a section of text as a diagram.

Filtersbox Filter

SDF 2.001MTR-SDF-0004.001


box Filter


!block box [; parameters] ... !endblock

The parameters are:


Description Thebox filter is used to box a region of text. Thelines parameter can beused to treat each line as a line within a paragraph - without this, thecontents is treated as normal SDF.

The other parameters have the same meanings as they do for thetablefilter.

Limitations &Future Directions

Some of the output drivers (e.g. the MIF driver) do not support nestedtables, so tables within the box may be ignored.

Name Type Rule

align string

listitem integer

narrow boolean

wide boolean

lines boolean

bgcolor string

fill integer

Filterschanged Filter


changed Filter


!block changed ... !endblock


Description Thechanged filter is used to mark a section of text as changed.

Examples To add change bars to a section of text:

!block changedThis text has been changed.

And so has this.!endblock


At the moment, this filter only works when generating FrameMakerdocuments.

Filterscomment Filter

SDF 2.001MTR-SDF-0004.001


comment Filter


!block comment [; parameters] ... !endblock


Description Thecomment filter is used to temporarily ignore a block of text.

Examples !block commentIgnore me!endblock

Filtersdatestrings Filter


datestrings Filter


!block datestringstable

!endblock

The table fields are:


Description Thedatestrings filter can be used to change the strings used within a date.The fields within the table are:

• Symbol - the matching symbol name (without the $) from theFormatTime subroutine

• Values - a Perl string containing a whitespace-separated list of values.

Examples !block datestringsSymbol Valuesmonth "January February March April May June JulyAugust September October November December"smonth "Jan Feb Mar Apr May Jun JulAug Sep Oct Nov Dec"weekday "Monday Tuesday Wednesday Thursday FridaySaturday Sunday"sweekday "Mon Tue Wed Thu FriSat Sun"ampm "am pm"AMPM "AM PM"!endblock

Field Category Rule

Symbol key <month|smonth|weekday|sweekday|ampm|AMPM>

Values optional

Filtersdefault Filter

SDF 2.001MTR-SDF-0004.001


default Filter


!block default [; parameters]table

!endblock

The parameters are:



Description Thedefault filter is a convenient way of calling thedefault macro forseveral variables.

Thefamily parameter is often used to specify a common prefix.

Theexport parameter can be used to export the variables to the targetdocument system. See theexport macro for further details on variableexporting.

Examples !block defaultName ValueCOMPANY_NAME ACME MiningCOMPANY_PHONE 1234 5678!endblock

A simpler version is:

Name Type Rule

family string <\w+>

export boolean

Field Category Rule

Name key <\w+>

Value optional

Filtersdefault Filter


!block default; family= "COMPANY"Name ValueNAME ACME MiningPHONE 1234 5678!endblock

Filtersdefine Filter

SDF 2.001MTR-SDF-0004.001


define Filter


!block define [; parameters]table

!endblock

The parameters are:



Description Thedefine filter is a convenient way of calling thedefine macro forseveral variables.

Thefamily parameter is often used to specify a common prefix.

Theexport parameter can be used to export the variables to the targetdocument system. See theexport macro for further details on variableexporting.

Examples !block defineName ValueCOMPANY_NAME ACME MiningCOMPANY_PHONE 1234 5678!endblock

A simpler version is:

Name Type Rule

family string <\w+>

export boolean

Field Category Rule

Name key <\w+>

Value optional

Filtersdefine Filter


!block define; family= "COMPANY"Name ValueNAME ACME MiningPHONE 1234 5678!endblock

Filtersend Filter

SDF 2.001MTR-SDF-0004.001


end Filter


!block end ... !endblock


Description Theend filter is used to add a section of SDF onto the end of thedocument. This is particularly useful in configuration files when youwant to:

• load a "exit" configuration module

• provide defaults for variables not provided by authors within adocument.

When several sections are added to the end using this macro, the sectionsare processed in a first-in-last-out order.

Examples !block endLine:N[align=Center] END OF DOCUMENT!endblock

Filtersexample Filter


example Filter


!block example [; parameters] ... !endblock

The parameters are:


Description Theexample filter is used to specify a section of fixed-width text. Unliketheverbatim filter, embedded SDF symbols (like {{) are relevant.

Theskipheader parameter is useful when an external file is beingincluded as an example, but you do not want the header comment in theexample. Thelang parameter, if any, is used to determine thecommenting conventions. If no language is specified, comments areassumed to start with a # and be terminated by the end of line.

The lang parameter can be used to pretty-print programming languages.In practice, this means:

• comments are output in italics

• keywords are output in bold.

Note: The langdefs filter is used to configure the information the pretty-printing feature needs to know. A large number of languages arepredefined in thestdlib/langdefs.sdm file.

Name Type Rule

skipheader boolean

lang string

wide boolean

listitem integer

pure boolean

Filtersexample Filter

SDF 2.001MTR-SDF-0004.001


Thewide parameter can be used to ensure that at least 80 characters areoutput on a line before it is wrapped.

Thelistitem parameter can be used to specify that this block of text is partof a list. The value is the logical indent of the list (e.g. 1, 2, etc.).

Thepure parameter can be used to escape special SDF symbols (like {{)embedded within the text.

Examples# Include myfile.c but exclude the copyright, revisionhistory, etc.!include "myfile.c" ; example; skipheader; lang= 'c'

# Pretty-print the same file!include "myfile.c" ; example; wide; lang= 'c'

Filtersfront Filter


front Filter


!block front ... !endblock


Description Thefront filter includes text as is. It is provided for backwardscompatibility with older versions of SDF when the "front" section of aFrameMaker book needed to be placed into a separate SDF file.

Examples None.

Filtersget Filter

SDF 2.001MTR-SDF-0004.001


get Filter


!block get [; parameters] ... !endblock

The parameters are:


Description Theget filter is used to extract embedded documentation. The parametersmap to the options forsdfget.

Name Type Rule

report string

rule string

filename string

inverse boolean

Filtershlp_header Filter


hlp_header Filter


!block hlp_headertable

!endblock



Description Thehlp_header filter is used to define a table of jumps within the non-scrolling region of a Windows help topic.

Field Category Rule

Text key

Kind optional <popup|jump>

Filtershlp_window Filter

SDF 2.001MTR-SDF-0004.001


hlp_window Filter


!block hlp_window ... !endblock


Description Thehlp_window filter is used to define the contents of a popup windowfor Windows help files.

Filtersinline Filter


inline Filter


!block inline [; parameters] ... !endblock

The parameters are:


Description The inline filter is used to pass a section of text directly to a targetdocumentation system.

Thetarget parameter is used to specify which target system thenominated text is to be passed to. The default target ishtml.

Theexpand parameter can be used to request expansion of SDFexpressions (enclosed in [[ and ]]) within the text.

Examples To embed HTML within an SDF document:

!block inline add arbitrary HTML here ...!endblock

SDF expressions can be expand like this:

!define VERB "is"...!block inline; expand<P>This HTML [[VERB]] expanded.!endblock

Name Type Rule

target string <\w+>

expand boolean

Filterslangdefs Filter

SDF 2.001MTR-SDF-0004.001


langdefs Filter


!block langdefs ... !endblock


Description Thelangdefs filter is used to configure programming language propertiesused by SDF's pretty-printing support. The contents is one or morevgrind definitions.

Examples Seelangdefs.sdm within SDF'sstdlib directory.

Filtersnamevalues Filter


namevalues Filter


!block namevalues [; parameters]table

!endblock

The parameters are:



Description Thenamevalues filter is used to format a table of name-value pairs. Eachname is output in bold. For PostScript output, the names are placed in thesidehead.

Examples !block namevaluesName ValueDescription: Find the maximum of two numbersModule: generalAuthor: Joe Bloggs!endblock

The result is:

Description: Find the maximum of two numbers

Module: general

Author: Joe Bloggs

Name Type Rule

format string

Field Category Rule

Name optional

Value optional

Filtersnofill Filter

SDF 2.001MTR-SDF-0004.001


nofill Filter


!block nofill ... !endblock


Description Thenofill filter is used to format a set of lines, i.e. lines are separated bynewline characters.

Note: Theaddress filter may be a better choice that nofill in certain cases.Unlike nofill, address is mapped to ADDRESS tags when HTML isgenerated. (It's then up to the browser to decide how the address isformatted.)

Examples !block nofillMr I.M. LuckyB.Sc. (Computing)B.Fun. (Eating)!endblock

The output is:

Mr I.M. LuckyB.Sc. (Computing)B.Fun. (Eating)

Filtersnote Filter


note Filter


!block note [; parameters] ... !endblock

The parameters are:


Description Thenote filter is used to specify a note. Thelabel parameter can be usedto specify a label. The default label is "Note:".

Examples !block note; label='Example:'And some text inside

a multi-line note!endblock

The result is:

Example:And some text inside

a multi-line note

If you want the label to have a line to itself, leave the first line blank likethis:

!block note

And some more text inside

another multi-line note!endblock

The result is:

Name Type Rule

label string

Filtersnote Filter

SDF 2.001MTR-SDF-0004.001


Note:

And some more text inside

another multi-line note

Filtersplain Filter


plain Filter


!block plain ... !endblock


Description Theplain filter is used when including a topic as an "plain" sectionwithin a document, i.e. normal headings are converted to plain headings.




!include "chapter1.sdf"!include "chapter2.sdf"!include "chapter3.sdf"!include "glossary.sdf" ; plain

Filterspod Filter

SDF 2.001MTR-SDF-0004.001


pod Filter


!block pod [; parameters] ... !endblock

The parameters are:


Description Thepod filter is used to nest POD text within an SDF document.

Themain parameter is used to specify that the first paragraph after"=head1 NAME" is the document name. This parameter is usedinternally by thesdf program when it needs to convert a POD documentto another format.

Examples Some examples are:

# Insert some pod!block pod

A normal POD paragraph.

And some verbatim text.!endblock

# Get pod from a file!include "perlre.pod" ; pod

# Get pod from standard output!execute "getpod 'hello.c'" ; pod

Name Type Rule

main boolean

Filtersquote Filter


quote Filter


!block quote ... !endblock


Description Thequote filter is used to format a quotation. This typically implies:

• for PostScript, the text is italics and indented from both margins

• for HTML, the text is given an appropriate style.

Filtersscript Filter

SDF 2.001MTR-SDF-0004.001


script Filter


!block script ... !endblock


Description Thescript filter can be used to embed arbitrary Perl source code withinan SDF document. This is useful for many things including:

• declaring Perl subroutines implementing SDF filters and macros

• accessing databases

• updating log files.

Examples !block scriptprintf STDERR "Hello world!\n" ;!endblock


As arbitrary sections of Perl can be included and executed, the code canpotentially cause harm. At the moment, the ability to update external filesfrom within an SDF document is seen as afeature. However, a version ofSDF which restricts the embedded Perl to "safe" operations would benice.

Filterssdf Filter


sdf Filter


!block sdf [; parameters] ... !endblock


Description Thesdf filter can be used to apply an arbitrary set of paragraph and/orphrase attributes to a section of text.

Examples To add change bars to a section of text, the sdf filter can be used incombination with thechanged attribute as follows:

!block sdf; changedThis text has been changed.

And so has this.!endblock

Filterssections Filter

SDF 2.001MTR-SDF-0004.001


sections Filter


!block sections ... !endblock


Description Thesections filter is used to create section jumps for html and hlpoutputs: for these formats, the text of each paragraph (excludingpunctuation) is assumed to be the title of a section within this document.For other outputs, the text is unchanged.

ExamplesThere are lots of new things in this version including:

!block sections. Topics mode. HTML headers and footers!endblock

Further details are given below.

Filterssimple Filter


simple Filter

Interface !block simple [; parameters ]...!endblock

The parameters are:

Description Thesimple filter is typically used as a building block for other filters. Itprovides a simple way of specifying the before (pre), per-line (exec) andafter (post) actions.

Note: As creating new filters is not something that the average SDF usersdoes, this filter is really provided to make life easier for advanced SDFusers and SDF administrators.

Examples !on filter "testcases";; \ $name='simple'; \ $params.=';pre="!testcaseStart"'; \ $params.=';post="!testcaseEnd"'

Name Description

pre Perl code to execute before the block

exec executed for each line with $line containing the text line

post Perl code to execute after the block

Filterstable Filter

SDF 2.001MTR-SDF-0004.001


table Filter


!block table [; parameters] ... !endblock

The parameters are:

Name Type Rule

align string

bgcolor string

bmargin integer

cellpadding integer

cellspacing integer

colaligns string

coltags string

colvaligns string

delete string

footings integer

format string

groups string

headings integer

keepindents boolean

landscape string

listitem integer

lmargin integer

narrow boolean

niceheadings boolean

nocalcs boolean

noheadings boolean

objects string

oncell string

parseline string

placement string

Filterstable Filter



Description Thetable filter specifies a table inTBL format. A brief description ofeach parameter is given below. A tutorial-style introduction to SDF'stable features is also provided in theSDF User Guide.

rmargin integer

select string

sort string

style string

tags string

title string

tmargin integer

type string

where string

wide boolean

wrap integer

Name Type Rule

Parameter Description

align alignment of table: one of Left, Center, Right, Inner,Outer

bgcolor background colour for a table (HTML only)

bmargin default bottom margin for table cells (MIF only)

cellpadding padding size for table cells (HTML only)

cellspacing spacing size between table cells (HTML only)

colaligns a comma-separated list of horizontal alignments values(Left, Center, Right) for columns; alternatively, asingle word containing the letters L, C and R

coltags a comma-separated list of phrase styles to apply tocolumns

colvaligns a comma-separated list of vertical alignments values(Top, Middle, Bottom, Baseline) for columns;alternatively, a single word containing the letters T, M,B and L

delete a comma-separated list of columns to delete

Filterstable Filter

SDF 2.001MTR-SDF-0004.001


Examples A typical table is:

footings the number of footing rows at the end of the table

format a comma-separated list of column width specifications;alternatively, a single number where each digitrepresents 10% of the space available to the table

groups pattern of group-style rows (default is /:$/)

headings the number of heading rows at the top of the table

landscape display the table in landscape mode (MIF only)

listitem the list indent level (e.g. 1) of this table

lmargin default left margin for table cells (MIF only)

narrow if set, the table will only be as wide as required;otherwise the table will span the available space

niceheadings set to 0 to disable _ to space conversion in headings

nocalcs set to 0 to disable calculation processing within a table

noheadings suppress headings in output

objects alias for coltags (coltags is preferred)

oncell Perl code to execute for each cell (internal use only!)

parseline column headings parsing line (if not the first row in thetext)

placement vertical placement of table: one of Float, Pagetop,Columntop, Lefttop, Righttop (MIF only)

rmargin default right margin for table cells (MIF only)

select a comma-separated list of columns to display

sort a comma-separated list of columns to sort the datarows by

style overall look of the table

tags alias for coltags (coltags is preferred)

title table caption

tmargin default top margin for table cells (MIF only)

type alias for style (style is preferred)

where an expression to filter the data rows with

wide table straddles the side head area of the page

wrap the number of data rows to display in a physical row

Parameter Description

Filterstable Filter


!block table; format=55; style= "grid" ; groups;title= "Diary"Time_of_day AppointmentMorning:10:00 Dentist12:00 Lunch with friendsAfternoon:15:00 Meeting on SDF!endblock

The result is:

Table 5-1. Diary

Time of day Appointment

Morning:

10:00 Dentist

12:00 Lunch with friends

Afternoon:

15:00 Meeting on SDF

Filterstitle Filter

SDF 2.001MTR-SDF-0004.001


title Filter


!block title [; parameters] ... !endblock

The parameters are:


Description Thetitle filter is used to build the title block for memos, faxes, etc.

Thetype parameter can be used to override the document type. ForPostScript output, the value is displayed in a box above the rest of thetitle.

Thetoc parameter is used to request a table of contents. The value is thelevel of headings to include in the contents.

Theformat attribute is used to fine tune the layout of the columns withinthe table for format where a table is used (e.g. plain text).

Examples !block titleName ValueDate: [[DATE:DOC_MODIFIED]]To: Joe Bloggs, Sue Brown, Maree JonesCopy: David SmithFrom: Neil ArmstrongSubject: Solar System InformationRef. No: XY.002/GUI/96!endblock

Name Type Rule

type string

toc integer

format string

Filterstopics Filter


topics Filter


!block topics [; parameters]table

!endblock

The parameters are:



Description Thetopics filter is used to include a set of sub-topics into a document. ForPostScript, this implies that the heading levels on topics included as sub-topics are adjusted accordingly. For HTML and Windows help files, thisimplies that hypertext jumps are inserted to the topics.

This filter expects a table of data inTBL format. The only field typicallyprovided isTopic - the name of the file containing the topic, excluding the.sdf extension. The other fields are used by SDF internally during thegeneration of HTML topics.

Name Type Rule

intro string

noslide boolean

data boolean

Field Category Rule

Topic mandatory

Label optional

Level optional

Next optional

Prev optional

Up optional

Filterstopics Filter

SDF 2.001MTR-SDF-0004.001


The intro parameter can be used to specify SDF text to be output beforethe hypertext jumps. This text is not output for formats where the topicsare simply included, e.g. PostScript.

Thenoslide parameter stops the heading levels of the topics being sliddown.

Thedata parameter is used to specify that the table is topics data and nooutput should be generated. This parameter is used by SDF internallyduring the generation of HTML topics.

ExamplesThe subroutines are documented below.

!block topics; intro= 'H2: Subroutines'Topicmysub1mysub2!endblock

Filtersverbatim Filter


verbatim Filter


!block verbatim [; parameters] ... !endblock

The parameters are:


Description Theverbatim filter is used to specify a section of fixed-width text. Unliketheverbatim filter, embedded SDF symbols (like {{) are treated likenormal text.

Theskipheader parameter is useful when an external file is beingincluded as an example, but you do not want the header comment in theexample. Thelang parameter, if any, is used to determine thecommenting conventions. If no language is specified, comments areassumed to start with a # and be terminated by the end of line.

Thewide parameter can be used to ensure that at least 80 characters areoutput on a line before it is wrapped.

Thelistitem parameter can be used to specify that this block of text is partof a list. The value is the logical indent of the list (e.g. 1, 2, etc.).

Examples# Include myfile.c but exclude the copyright, revisionhistory, etc.!include "myfile.c" ; verbatim; skipheader; lang= 'c'

Name Type Rule

skipheader boolean

lang string

wide boolean

listitem integer

Filtersverbatim Filter

SDF 2.001MTR-SDF-0004.001


MacrosOverview


Chapter 6. Macros

OverviewThe macros available are summarised below.

Name Purpose

General:

build_title build a title page

block begin a block of text

endblock end a block of text

include include another file

execute include output from a command

Variables:

init initialise variables (before loading configurationfiles)

define set a variable

default set a variable (if not already set)

undef clear a variable

export export a variable to the format driver (and/ormark it for later exporting)

restrict declare a restricted family of variables

Figures:

import import an external object (e.g. figure)

clear reset text wrapping around a figure

Libraries:

inherit inherit entities from a library

use load a library module

Macros:

macro begin a macro definition

endmacro end a macro definition

insert call a macro

Classes:

class define a class of objects

catalog build a catalog from objects already loaded

MacrosOverview

SDF 2.001MTR-SDF-0004.001



Conditional text:

if begin conditional text

elsif begin a conditional section

else begin alternative section

endif end conditional text

elseif same as elsif

Event processing:

on specify processing for an event

off disable processing previously specified

File processing:

output dynamically change the output file used

script execute a line of Perl

message output a message during execution

line change message parameters

slide_down decrease heading levels (e.g. H2 -> H3)

slide_up increase heading levels (e.g. H2 -> H1)

Extraction:

getdoc extract documentation embedded in source code

getcode extract source code (i.e. non-documentation)from a file

getcli extract command-line interface information

perlapi extract API information from a Perl library

Miscellaneous:

jumps generates lines of jumps

subsections specify the subsections for a topic

continued continue a heading from a previous page

end_topic mark the end of a topic

Name Purpose

Macrosblock Macro


block Macro


! block filter [; params]

The arguments are:

SeeUnderstanding Macro Interfaces, if necessary.

Description Theblock macro marks the beginning of a "block" of text. The block isended by theendblock macro.

Examples

Name Type Default Rule

filter filter

params rest _NULL_

Macrosbuild_title Macro

SDF 2.001MTR-SDF-0004.001


build_title Macro


! build_title


Description Thebuild_title macro create a title page or section for documents andpapers.

Examples

Macroscatalog Macro


catalog Macro


! catalog class mask [; params]

The arguments are:


Description Thecatalog macro build a catalog from objects already loaded.

Theclass parameter specifies the class name. As it is defined as a symbolrather than a string type, the name is given without quotes and it is space-separated from the following parameter.

Themask parameter can be used to filter the objects as shown below:

Remaining parameters are passed through to the class filter.

Examples Display some interesting attributes ofreferences with a Status of'Review':

!catalog references 'Status:Review'; compact; \ columns="PDF,2:Reference,DOC:Document,Version"


class symbol

mask string

params rest _NULL_

Mask Description

empty string no filtering - display all objects

cited display just the cited objects

abc.* display the objects with (short) names matching thepattern, i.e. names beginning with abc

xyz:abc display the objects where attributexyz matches thepattern, i.e.xyz is exactly equal toabc

Macrosclass Macro

SDF 2.001MTR-SDF-0004.001


class Macro


! class name styles [; ids] [; properties]

The arguments are:


Description Theclass macro declares a class of objects.

Examples


name symbol

styles string

ids string Name,Long

properties

string Jump

Macrosclear Macro


clear Macro


! clear [type]

The arguments are:


Description Theclear macro resets text wrapping around a figure.

Examples !import "mylogo"; align="right"Some text.!clear


html is the only target which currently supports wrapping text aroundfigures.


type string All <Left|Right|All>

Macroscontinued Macro

SDF 2.001MTR-SDF-0004.001


continued Macro


! continued style [; suffix]

The arguments are:


Description Thecontinued macro continues a heading from a previous page, providedthe target format is page-based, i.e. nothing is output for html or hlpformats.

The first parameter is the heading style to repeat. The second parameter isthe suffix to append the text from the repeated heading. The default suffixis ", {{N:Continued}}".

Examples A typical example is:

H2: Solving world peace

H3: Procedure

The steps are given below.

...

!continued 'H2'!continued 'H3'; ' (Continued)'

Some more procedure text.

In the example above, the macros effectively produce:

H2[notoc;noid;continued] Solving world peace,{{Continued}}H3[notoc;noid;continued] Procedure {{(N:Continued)}}


style string

suffix string , Continued

Macroscontinued Macro


Note: This macro does not cause a new page. Typically, a rule (i.e. eventprocessing) is used to trigger new pages at the necessary paragraphstyles.

Macrosdefault Macro

SDF 2.001MTR-SDF-0004.001


default Macro


! default name [value]

The arguments are:


Description Thedefault macro sets a variable if it does not already have a value.

Examples


name symbol

value string 1

Macrosdefine Macro


define Macro


! define name [value]

The arguments are:


Description Thedefine macro sets a variable to a value.

Examples


name symbol

value string 1

Macroselse Macro

SDF 2.001MTR-SDF-0004.001


else Macro


! else


Description Theelse macro delimits sections within conditional text.

Examples

Macroselseif Macro


elseif Macro


! elseif value

The arguments are:


Description Theelseif macro delimits sections within conditional text. It is identicalin operation to theelsif macro.

Examples


value condition

Macroselsif Macro

SDF 2.001MTR-SDF-0004.001


elsif Macro


! elsif value

The arguments are:


Description Theelsif macro delimits sections within conditional text. It is identical inoperation to theelseif macro.

Examples


value condition

Macrosend_topic Macro


end_topic Macro


! end_topic


Description This macro marks the end of a topic.

Examples


Hopefully, this macro will disappear real soon now.

Macrosendblock Macro

SDF 2.001MTR-SDF-0004.001


endblock Macro


! endblock


Description Theendblock macro marks the end of a "block" of text. The block isstarted by theblock macro.

Examples

Macrosendif Macro


endif Macro


! endif


Description Theendif macro marks the end of a conditional text section.

Examples

Macrosendmacro Macro

SDF 2.001MTR-SDF-0004.001


endmacro Macro


! endmacro


Description Theendmacro macro marks the end of a user-defined macro.

Examples

Macrosexecute Macro


execute Macro


! execute cmd [; filter] [; params]

The arguments are:


Description Theexecute macro executes the nominated command and includes theoutput within the document. A filter may optionally be applied to theoutput before it is included.

Examples


cmd string

filter filter sdf

params rest _NULL_

Macrosexport Macro

SDF 2.001MTR-SDF-0004.001


export Macro


! export name

The arguments are:


Description Theexport macro ensures that the target documentation system receivesthe value of the nominated variable each time it changes. If the variable iscurrently defined, the target system is immediately notified of its value.

Examples


name symbol

Macrosgetcli Macro


getcli Macro


! getcli


Description Thegetcli macro extracts the command-line interface for a scriptfollowing SDF's command-line conventions.

Examples

Macrosgetcode Macro

SDF 2.001MTR-SDF-0004.001


getcode Macro


! getcode filename [; filter] [; params]

The arguments are:


Description Thegetcode macro extracts the "non-documentation" from source code.

Examples


filename string

filter filter _NULL_

params rest _NULL_

Macrosgetdoc Macro


getdoc Macro


! getdoc filename [; filter] [; params]

The arguments are:


Description Thegetdoc macro extracts embedded documentation from source codeusing thesdfget command.

Examples


filename string


params rest _NULL_

Macrosif Macro

SDF 2.001MTR-SDF-0004.001


if Macro


! if value

The arguments are:


Description The if macro marks the beginning of a conditional text section.

Examples


value condition

Macrosimport Macro


import Macro


! import filename [; params]

The arguments are:


Description The import macro imports a figure. If the filename is not given anextension, the extension is found using the search rules below.

Thetitle argument can be used to add a figure title.

SeeFigures within theSDF User Guide for further details.

Examples


filename string

params rest _NULL_

When generating The search order is

PostScript epsi, eps, wmf, mif, gif

HTML jpeg, jpg, png, gif

Windows Help bmp

Macrosinclude Macro

SDF 2.001MTR-SDF-0004.001


include Macro


! include filename [; filter] [; params]

The arguments are:


Description The include macro is used to include another file into an SDF document.

Examples


filename string


params rest _NULL_

Macrosinherit Macro


inherit Macro


! inherit library

The arguments are:


Description The inherit macro is used to inherit configuration information from alibrary. Typically, a library inherits from another library and then addssome new things.

Examples


library string

Macrosinit Macro

SDF 2.001MTR-SDF-0004.001


init Macro


! init [vars]

The arguments are:


Description Theinit macro is used on the top line of a document to initialise variablesbefore the configuration libraries are loaded.

Examples


vars rest _NULL_

Macrosinsert Macro


insert Macro


! insert macro [; missing]

The arguments are:


Description The insert macro is used to insert the output ofmacro into an SDFdocument.missing determines the action if the macro isn't found:

• ok - do nothing

• warning - report a warning

• error - report an error.

Note: In early versions of SDF, this macro was used to call user-definedmacros. In SDF 2.000 or later, user-defined macros can be called usingthe same syntax as built-in macros.

Examples # Insert the text of macro XXX if it's defined!insert 'XXX'

# Insert the text of macro XXX; output an error if it'snot defined!insert 'XXX' ; 'error'

# Same as the previous example!XXX


macro string

missing string ok <ok|error|warning>

Macrosjumps Macro

SDF 2.001MTR-SDF-0004.001


jumps Macro


! jumps labels [; layout]

The arguments are:


Description The jumps macro generates lines of jumps to headings.

Examples Typical usage is:

!jumps "Purpose,Usage,,Description,Examples"

This will create two jump lines: the first hasPurpose andUsage; thesecond hasDescription andExamples.


labels string

layout string Center <Left|Center|Right|left|center|right>

Macrosline Macro


line Macro


! line lineno [; filename] [; context]

The arguments are:


Description The line macro can be used to change the line number output within errorand warning messages.

Examples


lineno integer

filename string _NULL_

context string line

Macrosmacro Macro

SDF 2.001MTR-SDF-0004.001


macro Macro


! macro name

The arguments are:


Description Themacro macro marks the beginning of a user-defined macro.

Examples


name symbol

Macrosmessage Macro


message Macro


! message text [; type]

The arguments are:


Description Themessage macro can be used to output messages during execution.

Examples


text string

type string Object <Object|Warning|Error|warning|error>

Macrosoff Macro

SDF 2.001MTR-SDF-0004.001


off Macro


! off type id

The arguments are:


Description Theoff macro disables an event.

SeeEvent Processing in theSDF User Guide for further details.

Examples To be completed ...


type symbol <paragraph|phrase|macro|filter|table>

id eventid <\w+>

Macroson Macro


on Macro


! on type mask ; [id] ; code

The arguments are:


Description Theon macro specifies a rule to execute on certain events.

SeeEvent Processing in theSDF User Guide for further details.

Examples To be completed ...


type symbol <paragraph|phrase|macro|filter|table>

mask string

id eventid _NULL_ <\w+>

code rest

Macrosoutput Macro

SDF 2.001MTR-SDF-0004.001


output Macro


! output outfile

The arguments are:


Description Theoutput macro dynamically changes the output file being used. It canbe used in the following ways:

1. output "filename"

2. output ">filename"

3. output "-"

The first form changes the output file to be filename. The second formappends the output onto the filename given. The third form closes the(current) output file, if any.

Examples To be completed...


html is the only target which currently supports this macro.


outfile string

Macrosperlapi Macro


perlapi Macro


! perlapi filename [; filter] [; params]

The arguments are:


Description Theperlapi macroextracts the API ofa Perl 4 librarywhich followsSDF's codingconventions.

Examples


filename string


params rest _NULL_

Macrosrestrict Macro

SDF 2.001MTR-SDF-0004.001


restrict Macro


! restrict name

The arguments are:


Description Therestrict macro declares a restricted family of variables. If a variablebegins with a restricted prefix, then it must be declared via thedefinefilter.

This feature aims to catch errors caused by authors using a bad variablename. For example, if an author types

!define DOC_NAMe "My Document"

but meant to type

!define DOC_NAME "My Document"

then an error will be raised as DOC_NAMe is an unknown variablewithin the DOC family.

Examples


name string

Macrosscript Macro


script Macro


! script code

The arguments are:


Description Thescript macro executes a single line of Perl code.

Examples


code rest

Macrosslide_down Macro

SDF 2.001MTR-SDF-0004.001


slide_down Macro


! slide_down


Description Theslide_down macro moves subsequent headings down one level.

Examples

Macrosslide_up Macro


slide_up Macro


! slide_up


Description Theslide_up macro moves subsequent headings up one level.

Examples

Macrossubsections Macro

SDF 2.001MTR-SDF-0004.001


subsections Macro


! subsections labels [; prefix] [; layout]

The arguments are:


Description Thesubsections macro specifies the subsections in a topic.

Examples Typical usage is:

H1: MyApp !subsections "Purpose,Usage,Description,Examples"

In this case, thesubsections macro changes theid generated for theheadings listed to:

MyApp - heading

For HTML, it will also generate a line of jumps to the headings.


html is currently the only target for which a jump line is generated.


labels string

prefix string Topic <Topic|Noprefix|noprefix>

layout string Left <Left|Center|Right|None|left|center|right|none>

Macrosundef Macro


undef Macro


! undef name

The arguments are:


Description Theundef macro undefines a variable.

Examples


name symbol

Macrosuse Macro

SDF 2.001MTR-SDF-0004.001


use Macro


! use filename [; filter] [; params]

The arguments are:


Description Theuse macro loads a (library) module.

Examples


filename string

filter filter sdf

params rest _NULL_

Paragraph Attributes


Chapter 7. Paragraph Attributes

The paragraph attributes available are summarised below.PhraseAttributes can also be used as paragraph attributes.

Name Purpose

Margins:

left left margin indent (in points)

first first line indent (in points)

right right margin indent (in points)

align either Full, Left, Right or Center

Positioning:

top either Page (the default), Column, LPage or RPage

sp_before space before this paragraph

sp_after space after this paragraph

keep_prev keep this paragraph with the previous one

keep_next keep this paragraph with the next one

Miscellaneous:

label prefix label (e.g. Note:)

obj define this paragraph as an object with a given tag

noevents disable event processing for this object

nopb disable the implicit page break, if any

notoc remove this heading from the table of contents

Help specific:

hlp.context context in the HPJ file

hlp.topic topic in the HPJ file

hlp.header include this paragraph in the non-scrolling region

hlp.window paragraph is part of the contents in a popup window

hlp.endwindow paragraph is the last one in a popup window

Paragraph Attributes

SDF 2.001MTR-SDF-0004.001


Paragraph Styles


Chapter 8. Paragraph Styles

The paragraph styles available are summarised below.

The following special styles are also available.

Name Purpose

Headings:

Hn normal heading at leveln (1..6)

An appendix heading at leveln (1..6)

Pn plain heading at leveln (1..6)

Lists:

Ln plain list item or paragraph at leveln (1..6)

LFn first entry in an ordered list at leveln (1..6)

LNn next entry in an ordered list at leveln (1..6)

LUn unordered list item at leveln (1..6)

Notes:

Note a single paragraph note

NB start of a multi-paragraph note

NE end of a multi-paragraph note

Miscellaneous:

E example text (i.e. fixed width)

V verbatim text (i.e. fixed width, ignore escapes)

E80 wide example text

Line horizontal line

N normal text

NV name-value pair (i.e. hanging indent)

PB page break

Sign signature for a memo, etc.

Paragraph Styles

SDF 2.001MTR-SDF-0004.001


Symbol Purpose

> verbatim text

* .. ****** unordered list item at level 1..6

- .. ----- unordered list item at level 2..6

^ .. ^^^^^^ first entry in an ordered list at level 1..6

+ .. ++++++ next entry in an ordered list at level 1..6

. .. ...... plain list item or paragraph at level 1..6

Phrase Attributes


Chapter 9. Phrase Attributes

The phrase attributes available are summarised below.

Name Purpose

Formatting:

family font family

size font size

color text colour

bold enable bold

italics enable italics

underline enable underline

changed enable change bars

Objects:

expand replace an object name with its longer form

shrink replace an object name with its shorter form

Hypertext:

id define a hypertext target

jump define a hypertext jump (i.e. URL)

Indexes:

index define an index entry

index_type specify the index type

Help specific:

hlp.popup jump to a popup window

Phrase Attributes

SDF 2.001MTR-SDF-0004.001


Phrase Styles


Chapter 10. Phrase Styles

The phrase styles available are summarised below.

Tag Description Sample Output

Emphasis:

1 1st level emphasis (default) emphasis 1

2 2nd level emphasis emphasis 2

3 3rd level emphasis emphasis 3

Formatting:

N normal some normal text

I italic some italic text

B bold some bold text

U underline some underline text

EX example some example text

Types:

EMAIL email address [email protected]

F (or FILE) Filename myfile.sdf

SECT Section Paragraphs

URL Uniform Resource Locator http://www.mincom.com

Classes:

DOC document title SDF User Guide

REF reference (document code) MTR-SDF-0002

ORG organisation Mincom

PRD product MIMS

Specials:

E (or CHAR) escape (i.e. special character) ©

S spaces are non-breaking section 2.1

IMPORT name of a figure to import

URLs:

http

ftp

telnet

news

Phrase Styles

SDF 2.001MTR-SDF-0004.001


Note: When emphasising text, it is generally better to use an emphasisstyle rather than a formatting style as the best way of doing so depends onthe output format.

gopher

wais

https

snews

Tag Description Sample Output

ProgramsOverview


Chapter 11. Programs

OverviewThe programs available are summarised below.

sdf is typically invoked as follows:

sdf -2 format [options] files

Supportedformat values include the following:

Further details on the programs are provided below.

Name Purpose

sdf convert SDF files to other formats

sdfapi extract theApplication Programming Interface fromsource code

sdfbatch generate FrameMaker batch files

sdfcli extract theCommand Line Interface from a utility

sdfget extract documentation embedded in source code

sdftest execute SDF regression tests

sdngen build an SDF tuning module from a FrameMaker template

prn2ps convert Windows PostScript to Unix PostScript

Format Description

ps a PostScript document

html a HTML document

hlp Microsoft Windows help input files

fvo a FrameViewer file

txt a plain text document

rtf an RTF document

book a book (PostScript)

Programssdf - SDF Conversion Utility

SDF 2.001MTR-SDF-0004.001


sdf - SDF Conversion Utility

Purpose sdf converts SDF files to other document formats.

Usage usage : sdf [+alias] [-h[help]] [-o[out_ext]] [-l[log_ext]] [-O[out_dir]] [-2 format] [-D variable,..] [-n split_level] [-f flag,..] [-I include_path,..] [-p[prefilter]] [-a parameters] [-P[plang]] [-N[line_numbers]] [-g[get_report]] [-r report] [-L locale] [-k look] [-s style] [-S page_size] [-c config] [-u uses,..] [-H head_level] [-K head_look] [-d driver] [-y post_filter] [-z post_process,..] [-t target] [-v[verbose]] [-T trace_levels,..] [-w width] [-Y library_path,..] sdf_file ...purpose: convert an sdf file to another formatversion: 2.001 (SDF 2.001)

The options are:

Option Description

-h display help on options

-o output file extension

-l log file extension

-O output to input file's (or explicit) directory

-2 the output format you want

-D define variables

-n heading level to autosplit into topics

-f define flags (i.e. DOC_* variables)

-I search path for include files, templates, etc.

-p pre-filter input file from each argument

-a parameters for the pre-filter

-P pre-filter as a programming language

-N number lines in pretty-printed source code

-g pre-filter using sdfget with the report specified

-r report to run on the SDF to transform it beforeformatting

-L locale



The aliases are:

-k look library

-s style of document

-S page size for paper documents

-c configuration library

-u modules to use

-H initial heading level

-K heading look (H, A or P)

-d format driver - default is expand

-y filter to post-filter the output with

-z list of post processing actions to do

-t logical target format

-v verbose mode

-T debugging trace levels

-w width for text-based outputs

-Y search path for libraries

Alias Description

mc generate a MIMS chapter

ms generate a MIMS spec

mt generate a MIMS topic

sdf2doc_fm generate Frame binary format via FrameMaker

sdf2dvi_sgml

generate DVI format via SGML

sdf2fvo_fm generate FrameViewer format via FrameMaker

sdf2hlp_mif

generate Windows Help input files via MIF

sdf2html_ generate a HTML document

sdf2html_dir

generate an SDF directory in HTML

sdf2html_fm

generate a HTML document via FrameMaker

sdf2html_topics

generate HTML topics

Option Description


SDF 2.001MTR-SDF-0004.001


sdf2htx_ generate MIMS HTX format

sdf2info_sgml

generate GNU info format via SGML

sdf2latex_ generate LaTeX

sdf2latex_pod

generate LaTeX format via POD

sdf2latex_sgml

generate LaTeX format via SGML

sdf2lyx_sgml

generate a LyX file via SGML

sdf2man_pod

generate Man page format via POD

sdf2mf6_ generate MIMS F6 help format

sdf2mif_ generate Frame MIF format

sdf2pdf_html

generate PDF via HTML

sdf2pdf_mif

generate PostScript and PDF via FrameMaker

sdf2pod_ generate POD format

sdf2ps_fm generate PostScript via FrameMaker

sdf2ps_fmbook

generate PostScript via a FrameMaker book

sdf2ps_html

generate PostScript via HTML

sdf2ps_pod generate PostScript via POD

sdf2ps_sgml

generate PostScript via SGML

sdf2rtf_fm generate RTF format via FrameMaker

sdf2rtf_mif generate RTF format via MIF

sdf2rtf_sgml

generate RTF format via SGML format

sdf2sdf_expand

generate expanded SDF

sdf2sdf_raw

generate raw SDF

Alias Description



Description The -h option provides help. If it is specified without a parameter, a briefdescription of each option is displayed. To display the attributes for anoption, specify the option letter as a parameter.

By default, generated output goes to standard output. To direct output to afile per input file, use the -o option to specify an extension for outputfiles. If the -o option is specified without a parameter, an extension ofoutis assumed.

Likewise, error messages go to standard error by default. Use the -loption to create a log file per input file. If the -l option is specifiedwithout a parameter, an extension oflog is assumed.

By default, generated output and log files are created in the currentdirectory. Use the -O option to specify an explicit output directory. If the-O option is specified without a parameter, the input file's directory isused.

The -2 option is a convenient way of specifying the alias (collection ofoptions) which generates the output you want. e.g.

sdf -2html abc

is equivalent to:

sdf +sdf2html abc

The -D option is used to define variables. These are typically used forcontrolling conditional text and substituting text which changes. Theformat used is:

-Dvariable1=value1,variable2=value2

A flag is a shorthand way of specifying variables in the DOC family. i.e. -ftoc=3 is equivalent to -DDOC_TOC=3. The format of the -f option is:

-fflag1=value1,flag2=value2

If a variable or flag is specified without a value, 1 is assumed.

sdf2sgml_ generate SGML format

sdf2txt_ generate plain text format

sdf2txt_fm generate plain text format via FrameMaker

sdf2txt_pod generate plain text format via POD

Alias Description


SDF 2.001MTR-SDF-0004.001


To generate HTML topics, the command is:

sdf -2topics abc

By default, this will create sub-topics for each heading already in aseparate file. It will alsoautosplit level 1 headings into sub-topics. The -noption can be used to control which level headings are split at:

• 1 autosplits on level 1 headings (the default)

• 2 autosplits on level 2 headings

• 3 autosplits on level 3 headings

• 0 disables autosplitting.

Include files are searched for in the current directory, then in thedirectories given by the -I option, then in the default library directory.

By default,sdf is configured toprefilter files with certain extensions. Forexample:

sdf mytable.tbl

is equivalent to executingsdf on a file which only contains:

!include "mytable.pl"; table

The -p option can be used to explicitly prefilter files or to override thedefault prefilter used. If a parameter is not provided, the prefilter isassumed to betable.

The -a option can be used to specify parameters for the prefilter. Forexample:

sdf -aformat='15,75,10' mytable.tbl

The -P option prefilters the input files as programming languages. Theparameter is the language to use. If none is provided, the extension isassumed to be the language name. For example:

sdf -P myapp.c

is equivalent to executingsdf on a file which only contains:

!include "myapp.c"; example; wide; lang='c'

The -N option adds line numbers at the frequency given. The defaultfrequency is 1. i.e. every line.

The -g option prefilters the input files by executingsdfget using thedefault report (default.sdg). To change the report used, specify the report



name as the parameter. If the report name doesn't include an extension,sdg is assumed.

Note: sdfget searches for reports in the current directory, then in thestdlib directory within SDF's library directory.

The -r option runs the nominated SDR report on each input beforeformatting. In other words, SDR reports provide a mechanism for:

• analysing the SDF just before it would be formatted, and

• replacing that SDF with the output of the report (also SDF) so that thefinal output is a nicely formatted report.

For example, thesdf_dir report generates a directory (tree) of thecomponents (files) included in an SDF document. Reports are stored insdr files and are searched for using the usual rules.

The -L option can be used to specify alocale. The default locale name isspecified insdf.ini . Locale naming follows POSIX conventions (i.e.language_country), so the locale name for American english isen_us.The information for each locale is stored in thelocale directory, so you'llneed to have to look in there to see what locales are available. (As thedefault locale can be set insdf.ini , this isn't as ugly as it first sounds.)

Note: At the moment, a locale file simply contains a list of languagespecific strings. Ultimately, it should be extended to support localisationof date and time formats.

The -k option is used to specify alook. The default look library isspecified insdf.ini .

The -s option can be used to specify a documentstyle. Typical values are:

• document - a technical document

• memo - a memo

• fax - a facsimile

• minutes - minutes of a meeting.

The -S option is used to specify the page size. Values supported include:


SDF 2.001MTR-SDF-0004.001


Additional page sizes can be configured insdf.ini . To specify a rotatedversion of a named page size, append anR. For example, A4R implies awidth of 29.7cm and a height of 21cm. A custom page size can also bespecified using the format:

{{width}}x{{height}}

wherewidth andheight are the respective sizes in points.

The -c option is used to specify a configuration library.

A list of modules to use can be specified via the -u option.

The initial heading level to start on can be specified via the -H option.This is useful if you want to preview how a topic will be displayedwithout regenerating the complete document. If a topic begins with alevel 1 heading (e.g. H1) and you wish to format it as a document (i.e. thelevel 1 text becomes the DOC_NAME forbuild_title), use the -H optionwith a value of 0.

The look of headings can also be adjusted. By default, H-style headingsare numbered, A-style headings are lettered and P-style headings areplain. To force a particular style for all headings, the -K option can beused. Sensible parameter values are H, A and P although other valuesmay work depending on what paragraph styles are configured at yoursite.

The -d option is used to specify the format driver. Values supportedinclude:

• expand - format as expanded text (the default)

Name Width Height Comment

global 21.0cm 11.0in will fit on either A4 or letter

A3 29.7cm 42.0cm

A4 21.0cm 29.7cm

A5 14.8cm 21.0cm

B4 25.7cm 36.4cm

B5 17.6cm 25.0cm

letter 8.5in 11.0in

legal 8.5in 14.0in

tabloid 11.0in 17.0in



• mif - Maker Interchange Format

• pod - Plain Old Documentation (as used by Perl).

Additional drivers can be configured insdf.ini .

The -y option can to used to specify a post-filter.

The -z option can be used to specify a list of post-processing actions youwant to execute on each output file after it is generated. The actionssupported include:

• ps - generate PostScript

• doc - generate a Frame (binary) file

• fvo - generate a Frame View-Only file

• txt - generate a text file

• rtf - generate an RTF file

• clean - delete the output file (must be last).

Additional actions can be configured insdf.ini . By convention, thegenerated files are given the same names as the action keywords.

The -t option is used to specify the logical target format. If none isspecified, the default is the first post processing action, if any. Otherwise,the default is the format driver name.

The -v option enables verbose mode. This is useful for debuggingproblems related to post processing. In particular, post processing actionscontaining the patternclean are skipped in verbose mode. You can alsoswitch off the post processing messages by using a verbose value of -1.Values higher than 1 switch on additional trace messages as follows:

2 - show how names of files and libraries are resolved

3 - show the directories searched for libraries

4 - show the directories searched for modules

5 - show the directories searched for normal files.

The -T option can be used to switch on debug tracing. The parameter is acomma-separated list of name-value pairs where each name is atracinggroup and each value is the level of tracing for that group. To get the traceoutput provided by the -v option, one can use theuser group like this:

sdf -Tuser=2 ...


SDF 2.001MTR-SDF-0004.001


This is slightly different from the -v option in that intermediate files arenot implicitly kept. Additional tracing groups will be added over time(probably one per output driver).

The -w option is used to specify the width for text-based outputs.

The -z, -D, -f and -I options are list options. i.e. multiple values can beseparated by commas and/or the options can be supplied multiple times.

Examples Convertmydoc.sdf to a technical document in mif format, output ismydoc.mif :

sdf -2mif mydoc.sdf

Convertmydoc.sdf to online documentation in FrameViewer format,output ismydoc.fvo :

sdf -2fvo mydoc.sdf

Convertmydoc.sdf to online documentation in HTML, output ismydoc.html :

sdf -2html mydoc.sdf

The following command will build the reference documentation for aSDF module in HTML:

sdf -2html abc.sdm

Limitations andfuture directions

Many of the default post processing (-z) actions only works on Unix asFrameMaker for Windows does not support batch conversion.

Topics mode has several limitations:

• only documents in the current directory can be converted

• all sub-topics must also be in the current directory.

Programssdfapi - API Extraction Utility


sdfapi - API Extraction Utility

Purpose sdfapi extractsApplication Programming Interface information from(Perl) source code.

Usage usage : sdfapi [-h[help]] [-o[out_ext]] [-l[log_ext]] [-O[out_dir]] [-f fmt_tag] [-p[pattern]] [-s sym_type,..] [-j] file ...purpose: extract the API from a (perl) libraryversion: 2.000 (SDF 2.001)

The options are:




By default, generated output and log files are created in the currentdirectory. Use the -O option to specify an explicit output directory. If the

Option Description





-f output format tag

-p only symbols matching pattern

-s only symbols of these types

-j add SDF-style hypertext jumps from each symbol

Programssdfapi - API Extraction Utility

SDF 2.001MTR-SDF-0004.001


-O option is specified without a parameter, the input file's directory isused.

The format of the output can be controlled using the -f option. Supportedformats arestd andconcise. The default isstd. std format is:

require "abc.pl";

$myvar = ...

$result =&myfunc($myparams);

concise format has fewer blank lines and uses 1 line per symbol.

A comma-separated list of symbol types to output can be specified usingthe -s option. Supported symbol types are:

• sub - subroutines

• var - variables

The default is to extract all symbols.

The -p option is used to extract only a subset of the symbols. If notsupplied, the pattern is symbols beginning with a letter. If suppliedwithout an option, the pattern defaults to all symbols. If perl libraries usethe coding convention that symbols beginning with underscore areprivate, then -p_ can be used to extract the private symbols.

The -j option can be used to request SDF-style hypertext jumps be addedfor each symbol. The jump target islib_sym where:

• lib is the library name

• sym is the symbol name.


The only language currently supported is Perl.

It would be useful to extract messages from the scripts too. This wouldrequire a new utility calledsdfmsg say, which searched through thesource (including libraries) forAppMsg andAppExit calls.

Internally, it may be better to implement formats via routines. This wouldgive better control over output. e.g. it would be up to the routine to decideif it wanted to output the 'require' header.

Programssdfbatch - Batch Processing Utility


sdfbatch - Batch Processing Utility

Purpose sdfbatch is a preprocessor forfmbatch, FrameMaker's command-linedriven batch processing utility.

Usage usage : sdfbatch [+alias] [-h[help]] [-f fmt_file] [-F fmt_what] [-u] [-p[print_doc]] [-P paper_size] [-s[save_ext]] [-S save_fmt] [-n] [-t timeout] frame_file ...purpose: generate fmbatch input fileversion: 2.000 (SDF 2.001)

The options are:

The aliases are:

Description Given a set of FrameMaker documents,sdfbatch can be used to:

• change the formatting of the documents (alaUse Formats From)

• update the documents (i.e. cross-references, etc.)

• print the documents

Option Description


-f formats file

-F formats to import

-u update documents

-p print documents

-P paper size name

-s save extension

-S save file format

-n output the batch file (instead of calling fmbatch)

-t timeout for printer driver to generate ps

Alias Description

fm2ps convert Frame files to PostScript


SDF 2.001MTR-SDF-0004.001


• save the documents in a nominated file format

The -h option provides help. If it is specified without a parameter, a briefdescription of each option is displayed. To display the attributes for anoption, specify the option letter as a parameter.

To change formatting, use the -f option to specify the file to import theformats from. The -F option can be used to specify what formats areimported. The argument to the -F option is a set of the characters in thetable below.

By default, all formats are imported.

To update documents, use the -u option.

To print documents, use the -p option. If a parameter is not provided, thefile will be printed to the default printer. To print to a PostScript file,specify the "file" keyword as the parameter. Alternatively, the parameteris the name of aprint settings file.

When generating a PostScript file, the paper size can be specified usingthe -P option. The default value isglobal. The paper size name is actuallymapped to aprint settings file calledpaper_size.fmver in thestdlib

library directory.fmver is typically either fm4 or fm5, depending onwhich version of FrameMaker you are using.

Character Meaning

p Paragraph formats

f Font formats

l Page layouts

c Cross references

v Variables

r Reference page contents

t Table formats

x Conditional text

k Color

m math

B Preserve manual page breaks

O Preserve other formatting overrides



To save documents, use the -s option. By default, this saves each file. Tochange the extension, supply an argument to the -s option.

To specify a different format, use the -S option. Possible values are:

• m - MIF

• a - line-oriented ASCII

• t - paragraph-oriented ASCII

• d - Frame document

• l - View-Only Frame document

• - - file's current format [default]

Take care with the file extension - any existing files will be replacedwithout warning.

The -n option causes the generatedfmbatch file to be output. i.e. fmbatchis not called. This option is useful for debugging.

The -t option enables the user to tune the time-out used when waiting forthe print driver to generate a PostScript file. The default value is 300seconds (i.e. 5 minutes).

A combination of the f, u, p and s options can be supplied if more thatone operation is required per file. For example, you may wish to importformats and then save the resultant file. For each file, the operations arealways done in the following order:

1. formatting

2. updating

3. printing

4. saving

Note: Not all of the values documented for the -F and -S options may besupported in Frame versions before 4.0 and additional values may besupported in future versions. As such, the values supplied to these optionsare simply embedded in the generatedsdfbatch file. i.e. no checking isdone on the value. This behaviour is considered a feature.

Examples To format and print a set of files:


SDF 2.001MTR-SDF-0004.001


sdfbatch -fmyfmts.doc -p *.doc

To convert mif files to binary files:

sdfbatch -sdoc -Sd *.mif

To copy Frame variables from a file to a set of files:

sdfbatch -fvariable.mif -Fv -s *.doc

Programssdfcli - Command Line Interface Utility


sdfcli - Command Line Interface Utility

Purpose sdfcli extracts command line interface (CLI) information fromapplications and formats it into SDF.

Usage usage : sdfcli [-h[help]] [-o[out_ext]] [-l[log_ext]] [-O[out_dir]] [-w wrap] utility ...purpose: format a utility's command line interface intoSDFversion: 2.000 (SDF 2.001)

The options are:





Option Description





-w column at which to wrap option specifications

Programssdfcli - Command Line Interface Utility

SDF 2.001MTR-SDF-0004.001


sdfcli executes each argument with a -h flag and converts the resultantoutput to nicely formatted SDF. An argument of "-" specifies that the helpshould be read from standard input.

Formatting is done as follows:

1. lines are tagged asExample paragraphs, with the first line formattedto wrap option usage specifications nicely

2. if a line is found that starts with 'options:', it is replaced with aBodyparagraph saying "The options are:", and the following lines areformatted as a table of codes and descriptions

3. if a line is found that starts with 'aliases:', it is replaced with aBodyparagraph saying "The aliases are:", and the following lines areformatted as a table of names and descriptions

4. each option code in the table is formatted as a hypertext jump to a tagcalledcmd_opt where:

– cmd is the command name

– opt is the option code

The -w option specifies at what column to wrap option specifications.The default is 50 - this is the best for output imported into the Mincomtemplates.


The table formats used are hard coded.

Programssdfget - Documentation Extraction Utility


sdfget - Documentation Extraction Utility

Purpose sdfget extracts documentation embedded in source code.

Usage usage : sdfget [-h[help]] [-o[out_ext]] [-l[log_ext]] [-O[out_dir]] [-f formatting_filename] [-g[get_rule]] [-r[rpt_file]] [-s scope] [-i] [-v[verbose]] file ...purpose: extract documentation embedded in source codeversion: 2.000 (SDF 2.001)

The options are:




Option Description





-f filename to use when formatting the output

-g rule to use to get documentation

-r report file

-s scope of documentation to be extracted

-i only output lines not extracted

-v verbose mode


SDF 2.001MTR-SDF-0004.001



The -f option can be used to specify a filename to use when formattingthe output. This is useful when the text is coming from the standard inputstream.

Theget-rule nominates the formatting of the embedded documentation tobe extracted. All currently defined get-rules assume the documentation isin comment blocks in one of the following formats:

>>section_title1:: text of section 1, line 1 text of section 1, line ..

>>section_title2:: text of section 2, line 1 text of section 2, line .. >>END::

>>section_title3:: text of section 3

The first form is most commonly used. In this format, the text in a sectionextends until the end of the current "comment block" or the start of thenext section, whichever comes first. The second form (i.e. explicitlyspecifying where the section ends) is useful if you wish to add somenormal comments (i.e. non-documentation) which you do not wantextracted. If the text is short, the third form can be used. Regardless of theformat, if a section is found which is already defined, the text of thesection is concatenated onto the existing text. This permits thedocumentation for each entity to be specified immediately above where itis defined in the source code.

The -g option specifies theget-rule to use. The available get-rules differon the prefix expected at the front of each line as shown below.

Rule Prefix

perl #

cpp //

c * or /*

fortran c (with 5 preceding spaces)

eiffel --

bat rem



Within C code, a trailing space is required after the characters above. Forother languages, a trailing space is optional. Within FORTRAN code, the"c" character must be preceded by exactly 5 spaces. For other languages,zero or more whitespace characters are permitted before the charactersabove.

For example, embedded documentation within C code looks like:

/* >>Purpose:: * This library provides a high level interface * to commonly used network services. */

If the -g option is not specified,perl is the default get-rule. If the -goption is specified without a parameter, the extension in lowercase of thefilename (or theformatting filename if the text is coming from standardinput) is used to guess the get_rule as shown below.

A report filename can be specified using the -r option. If the name doesn'tinclude an extension, sdg is assumed. Reports provide a mechanism for:

• selectively extracting sections, and

• rudimentary reformatting (e.g. to SDF)

If no report is specified, all sections are output in the following format:

section_title1 section_text1

section_title2 section_text2

If -r is specified on its own,default.sdg is assumed. This report selectsthe set of sections (within the SDF documentation standards) which formthe user documentation and formats them into SDF. Details on the reportformat are specified below. Reports are searched for in the currentdirectory, then in thestdlib directory within SDF's library directory.

Rule Extensions

cpp cpp, c++, cc, hpp, hpp, h, java, idl

c c

fortran fortran, for, f77, f

eiffel eiffel, ada

bat bat, cmd


SDF 2.001MTR-SDF-0004.001


The -s option can be used to specify the scope of the documentation to beextracted. (This is an experimental feature and may change so most usersshould avoid using it.)

The -i option outputs only those lines which the get-rule did not match.This option is useful for extracting non-documentation from a file to givejust the code.

Note: The -r option is ignored if -i is specified.

The -v option enables verbose mode. This is useful for seeing which ruleis being used for each file.

Examples To extract the user documentation from a SDF application written in C++(xyz, say) and save it intoxyz.sdf :

sdfget -gcpp -r -osdf xyz.cpp


It would be nicer if the get-rule was always guessed from the filenameextension but changing the default from perl could break existing scripts.Therefore, get-rule guessing must be explicitly enabled by specifging the-g option without a parameter.

Programssdftest - Execute SDF Regression Tests


sdftest - Execute SDF Regression Tests

Purpose sdftest executes the regression tests provided with SDF.

Usage sdftest

Description This program is typically run just after SDF has been installed to checkthat the installation succeeded. However, users should be able to run it atany time to confirm that everything is still ok.

This program works by iterating over thesdf files in thetest directorywhere SDF is installed. For each file calledxx.sdf, it generatesxx.out andxx.log files containing the output and error logs, respectively. These filesare then validated against the expected files in thechecked directory.

Note: Generated files which are ok are deleted. However, if a test fails,the file which failed is not deleted, so a user can then usediff , say, toanalyse what the problem is.


This program only provides regression testing on the core SDF engine. Inparticular, it doesn't provide regression testing on the drivers used togenerate each of the different output formats (e.g. HTML, PostScript).

Programssdngen - SDF Tuning File Generator

SDF 2.001MTR-SDF-0004.001


sdngen - SDF Tuning File Generator

Purpose sdngen extracts SDF template information from a FrameMaker template.

Usage usage : sdngen [-h[help]] [-o[out_ext]] [-l[log_ext]] [-O[out_dir]] [-p para_root] [-f font_root] [-t tbl_root] [-e existing_template] file ...purpose: generate an SDF template from a Frame oneversion: 2.000 (SDF 2.001)

The options are:





Option Description





-p default parent for a paragraph format

-f default parent for a font format

-t default parent for a table format

-e existing template file

Programssdngen - SDF Tuning File Generator


The -p option can be used to specify the root paragraph format fromwhich others are derived. The default paragraph root isBody.

The -f option can be used to specify the root font (i.e. phrase) formatfrom which others are derived. The default font root isEmphasis.

The -t option can be used to specify the root table format from whichothers are derived. The default table root isFormat A.

As formats often appear in families (e.g. Heading1, Heading2, etc.),sdngen will use the (alphabetically) previous format as the parent if itmakes a better parent (i.e. there are less differences) than the default one.

If a template already exists, it can be specified using the -e option. In thiscase,sdngen will get as much information as it can from that fileincluding:

• the root format for each type

• the order of formats within a type

• the parent for each format.

Within each type, formats which are unknown in the existing template areoutput after those that are known.

Examples To generate an SDF tuning file file:

sdngen -osdn mytemplate.mif

This will create a template file calledmytemplate.sdn .

Programsprn2ps - PostScript Conversion Utility

SDF 2.001MTR-SDF-0004.001


prn2ps - PostScript Conversion Utility

Purpose prn2ps converts Windows PostScript to Unix PostScript. The input tothis program is typically generated by printing to a PostScript printerconnected to the FILE: logical device. The output can be converted toEncapsulated PostScript using GhostScript'sp2epsi program.

Usage usage : prn2ps [-h[help]] [-o[out_ext]] [-l[log_ext]] [-O[out_dir]] prn_file ...purpose: convert Windows PostScript to Unix PostScriptversion: 2.000 (SDF 2.001)

The options are:





For each input file, the output is generated by:

• deleting thePageSize information

Option Description







• deleting the control-D at the end of the file.

Examples To generate an Encapsulated PostScript file from Windows PostScript:

prn2ps -ops myfig.prn ps2epsi myfig.ps


If ps2epsi doesn't like the output, you may need to use another printerdriver to generate the input. On Windows NT 4.0, theCanon PS-IPUColor Laser Copier v52.3 driver works most of the time.


SDF 2.001MTR-SDF-0004.001


SubroutinesOverview


Chapter 12. Subroutines

OverviewThe subroutines available are summarised below.


Name Purpose

FormatTime format a date-time value

AppendText within theon macro, appends text after the current line

PrependText within theon macro, prepends text before the currentline

FindFile override this if you need custom searching rules

SubroutinesAppendText

SDF 2.001MTR-SDF-0004.001


AppendText

Purpose AppendText is used within a paragraph event handler to add SDF after aparagraph.

Interface &AppendText(@sdf)

Description

The argument is the list of SDF paragraphs to append.

Examples To append a line after each level 1 heading:

!on paragraph 'H1';; &AppendText('Line:')

SubroutinesFindFile


FindFile

Purpose This routine is used to search for include files, imported objects,configuration modules and templates.

Interface $fullname = &FindFile($filename, $image);

Description If filename is not found,fullname should be an empty string. If the file isfound, the pathname of the file is returned, otherwise the empty string isreturned. Ifimage is true, a target-specific set of extensions is searchedfor, complete with implicit image format conversion.

Examples The default implementation is:

sub FindFile {local ($filename, $image) = @_;local ($fullname);

# Get the list of directories to searchuse Cwd;my @dirs = ('.');my $dir = $var{'DOC_DIR'};push (@dirs, $dir) if $dir ne cwd();push (@dirs, @include_path, "$'sdf_lib/stdlib", $'sdf_lib);

# Do the searchif ($image) {

my $context = $var{'OPT_TARGET'};my @exts = @{$'SDF_IMAGE_EXTS{$context} || $'SDF_IMAGE_EXTS{'ps'}};return &'NameFindOrGenerate($filename, \@dirs, \@exts, $context);

}else {

return &'NameFind($filename, @dirs); }}

In order to tightly integrate SDF with certain development environments,it is occasionally necessary to override this routine in a configurationmodule. For example:

!block scriptsub FindFile { local($filename, $image) = @_; local($fullname);

# Search using our SCM $fullname = &'SearchSCM($filename, $image);

SubroutinesFindFile

SDF 2.001MTR-SDF-0004.001


# Return result return $fullname;}!endblock

SubroutinesFormatTime


FormatTime

Purpose This routine is used to format a date-time quantity into a human readableform.

Interface $result = &FormatTime($fmt, $var);

Description The first parameter is either a format string or the name of a variablecontaining a format string. The second parameter is the name of thevariable to be formatted. The variable's value is a number of secondssince January 1, 1970.

The building blocks used in the format strings are given below.

Symbol Description Example

$day day number in month 6 or 22

$day0 day number in month zero-padded

06 or 22

$month month name January

$smonth abbreviated month name Jan

$monthnum month number (1..12) 6 or 12

$monthnum0 month number zero-padded(01..12)

06 or 12

$year year 1995

$syear abbreviated year 95

$weekday weekday name Monday

$sweekday abbreviated weekday name Mon

$hour hour (1..24) 6 or 14

$hour0 hour zero-padded (01..24) 06 or 14

$shour hour (1..12) 6 or 12

$shour0 hour zero-padded (01..12) 06 or 12

$ampm am or pm am

$AMPM AM or PM PM

SubroutinesFormatTime

SDF 2.001MTR-SDF-0004.001


Commonly used formats are defined in the variables given below.

Examples To format the 'last modified' date-time for a document:

&FormatTime('FMT_FULL', 'DOC_MODIFIED')

To format the year when conversion started (for copyright reasons, say):

&FormatTime('$year', 'DOC_START')

$minute minute (0..59) 0 or 42

$minute0 minute zero-padded (00..59) 00 or 42

$second second (0..59) 0 or 42

$second0 second zero-padded (00..59) 00 or 42

Variable Value

FMT_FULL $day $month $year, $hour:$minute0.$second0

FMT_TIME $hour:$minute0.$second0

FMT_DATE $day $month $year

FMT_CONCISE $day0-$smonth-$syear

Symbol Description Example

SubroutinesPrependText


PrependText

Purpose PrependText is used within a paragraph event handler to prepend SDFbefore a paragraph.

Interface &PrependText(@sdf)

Description

The argument is the list of SDF paragraphs to prepend.

Examples To prepend a line before each level 1 heading:

!on paragraph 'H1';; &AppendText('Line:')

SubroutinesPrependText

SDF 2.001MTR-SDF-0004.001


VariablesOverview


Chapter 13. Variables

OverviewThe categories of predefined variables are:

1. Conversion variables

2. Document variables

3. File variables

4. Miscellaneous variables.

Date-time variables are in units ofseconds since January 1, 1970. Toformat a time, use theFormatTime subroutine.

Further details on each group of variables are provided below.

VariablesConversion Variables

SDF 2.001MTR-SDF-0004.001


Conversion Variables

Purpose These variables control the conversion process.

Interface

Description The init-only variables can only be set viasdf's -D option or via theinitmacro on the top line of a file.

Theprocessing variables control the processing of SDF text before it ispassed to a format driver for conversion.

DEFAULT_TAB_SIZE is used when tabs are converted to spaces withinSDF files.

Name Type Purpose

Init-only:

OPT_CONFIG string the configuration library

OPT_LOOK string the look library

OPT_STYLE string the type of a document

OPT_TARGET string target format

OPT_NUMBER integer line numbering frequency (whenpretty-printing programminglanguages)

Processing:

DEFAULT_TABLE_STYLE

string default style for tables (initiallycolumns)

DEFAULT_TAB_SIZE

integer default tab size (initially 8)

VariablesDocument Variables


Document Variables

Purpose These variables are related to the document SDF is currently processing.

InterfaceName Type Purpose

Control:

DOC_TOC integer table of contents level

DOC_TWO_SIDES

boolean build a two-sided document

Book controls:

DOC_LOF boolean build a list of figures

DOC_LOT boolean build a list of tables

DOC_IX boolean build an index

Information:

DOC_PATH string the full pathname of the currentdocument

DOC_DIR string the directory of the currentdocument

DOC_BASE string the base (filename) of the currentdocument

DOC_EXT string the extension of the currentdocument

DOC_SHORT string the base and extension of thecurrent document

DOC_START datetime the time document conversionstarted

DOC_MODIFIED datetime the most recent modification timeof files visited so far

VariablesFile Information Variables

SDF 2.001MTR-SDF-0004.001


File Information Variables

Purpose These variables provide information on the file SDF is currentlyprocessing.

InterfaceName Type Purpose

FILE_PATH string current pathname (e.g./doc/sdf/mydoc.sdf)

FILE_DIR string directory of current filename (e.g./doc/sdf)

FILE_BASE string base component of currentfilename (e.g.mydoc)

FILE_EXT string extension of current filename (e.g.sdf)

FILE_MODIFIED datetime time when this file was lastmodified

VariablesMiscellaneous Variables


Miscellaneous Variables

Purpose These variables are generally useful.

Interface

Description Thecharacter variables are the preferred way of including the respectivesymbols. A format-specific configuration file can override the defaultdefinitions of these symbols.

Theenvironment variables can be used to find out which version of SDFis executing and where it is installed.

Name Type Purpose

Characters:

c string copyright character

tm string trademark character

rtm string registered trademark character

nbsp string non-breaking space

Environment:

SDF_VERSION string product version string (e.g. 2.000beta1)

SDF_HOME string library/configuration directory

Expressionformats:

FORMAT_UPPER string convert a string to uppercase

FORMAT_LOWER

string convert a string to lowercase

FORMAT_FULL string format to a complete date-timeformat

FORMAT_TIME string format to a time only

FORMAT_DATE string format to a date only

FORMAT_CONCISE

string format to a concise date only

FORMAT_YEAR string format to a 4-digit year

VariablesMiscellaneous Variables

SDF 2.001MTR-SDF-0004.001


Theexpression format variables define bits of Perl code to formatvariables or expressions. They can be defined in a configuration file -your system adminstrator may wish to configure date formatting to suitlocal conventions.

Understanding Class InterfacesOverview

SDF 2.001MTR-SDF-0004.00125-May-99 A-1© Ian Clatworthy

Appendix A. Understanding Class Interfaces

Overview

General Syntax The general syntax for declaring and/or formatting a table of objects inthe class is shown first. By convention, the filter is shown using theblockandendblock macros, although filters can also be used with other macros,including include andexecute.

Object Attributes The attributes supported for each class are listed in a table with thefollowing columns:

• Field - the field name

• Category - key, mandatory or optional

• Rule - the pattern, if any, used to validate the value.

Understanding Class InterfacesParameters

SDF 2.001MTR-SDF-0004.001

A-2 25-May-99© Ian Clatworthy

Parameters

Overview All class filters support the set of parameters listed below.

Name Type Description

data boolean define objects but do not display them

cited boolean number these objects as the cited ones (for [1]style references)

root string string to prepend to Jump attribute, if any

columns string comma-separated list of attributes to display intable

style string table style to use (the default isplain)

compact boolean display in a compact table, (make cellpaddingand cellspacing both equal to zero)

wide boolean use sidehead when formatting on paper

headings boolean display the column headings

where string filter the rows using the nominated expression

sort string comma-separated list of columns to sort by

colaligns string a comma-separated list of horizontalalignments values (Left, Center, Right) forcolumns; alternatively, a single wordcontaining the letters L, C and R can be usedfor the value

colvaligns string a comma-separated list of vertical alignmentsvalues (Top, Middle, Bottom, Baseline) forcolumns; alternatively, a single wordcontaining the letters T, M, B and L can beused for the value

select string a comma-separated list of columns to display

delete string a comma-separated list of columns to delete

wrap integer number of logical rows to place on a physicalrow

Understanding Class InterfacesBuilding the Columns


Building the Columns

Using the columnsParameter

Thecolumns parameter is a comma-separated list of:

[tag":"]attribute["&"view]

where:

• tag is a phrase style (or expression format)

• attribute is the name of an attribute of the class

• view is a view to apply to the object when looking up or calculatingthat attribute (seeObject Views below).

To remember the syntax for applying an object view, think of C's bit-masking operator, &.

Examples are given below:

CalculatedAttributes

Some class filters support calculated attributes, so the total set ofattributes you can place in thecolumns parameter can be quite large. Forexample, forreferences, an unknown attribute which is sequence ofuppercase letters is assumed to be a file extension and the generatedattribute is an icon providing a jump to that file, if any. For example, if areference has aJump attribute ofxyz.html, then the PDF attribute is animage (pdf.gif) which provides a jump toxyz.pdf.

Object Views On some occasions, it can be very useful if the value placed in a columnis a variation of an attribute, rather than the attribute itself. For example,thereferences class supports an attribute called PS which is an image(postscript.gif) with a jump toxyz.ps (assuming theJump attribute isxyz.html). But what if the PostScript file is in a different place to theHTML file? In this case, you need to use an objectview.

Column Description

Code output the Code attribute

2:Code output the Code using the 2 (emphasised) phrasestyle

BUG:Code output the Code using the BUG phrase style

CONCISE:Date output the Date attribute using the CONCISEformat

Understanding Class InterfacesBuilding the Columns

SDF 2.001MTR-SDF-0004.001


For example, theSDF Document Catalog provides access to SDF'sdocuments in several formats:

• PDF and PostScript, stored on SDF's web site

• HTML, stored locally.

This catalog was created by using the followingcolumns parameter:

columns='PDF&website,PS&website,DOC:Document,Date,Pages'

wherewebsite is a file containing the following:

prefix_Jump=http://www.mincom.com/mtr/sdf/

The name of a view is either a file or a directory:

• If the name of a view is a file, then the view is loaded from that file.The format is a same as a set of name-value pairs in anINI file.

• If the name of a view is a directory, then a view withprefix_Jump=name/ is returned.

Within a view, the parameters supported are:

• prefix_xxx - prefix for attributexxx

• suffix_xxx - suffix for attributexxx.

Note: If it proves helpful, I'm happy to expand this list to include othertypes of parameters likedefault_xxx andvalue_xxx, say.

Understanding Class InterfacesFiltering and Sorting


Filtering and Sorting

Filter Expressions Thewhere attribute takes an expression which is evaluated for eachrecord. Special symbols available are:

For example:

!define MODULE_CODE "XYZ" ... !include "../document.reg"; references; compact; \ where='$o{"Reference"} =~ /$var{"MODULE_CODE"}/'; \ columns="PS,REF:Reference,DOC:Document,CONCISE:Date"

Sorting sort takes a comma-separated list of column names to sort on. If nocolumns are specified, the data is sorted using all columns in the order inwhich they appear. All sorting is done alphabetically - numeric sorting isnot supported.

Using the deleteParameter

Thedelete parameter is particularly useful if you want to sort or filter atable (using thesort andwhere parameters, respectively) using columnswhich you don't want in the output. For example:

# Load the bug tracking module !use "bugtrack"

# Display the open bugs, sorted by priority H1: Open Defects !include 'bugs.reg'; bugs; headings; \ columns='Code,BUGTITLE:Title,Status,Priority';\ where='$o{"Status"} eq "Open"'; \ sort='Priority'; \ delete='Status'

Note: The order of the parameters to a class filter are not important,although the order above best reflects the processing.

Symbol Meaning

$_ the current record

$o{"xyz"} the value of column xyz

$var{"abc"} the value of variable abc

Understanding Class InterfacesFiltering and Sorting

SDF 2.001MTR-SDF-0004.001


In the case above, thecolumns parameter builds a data table which is thenfiltered and sorted. Note that theStatus andPriority attributes arerequired in the columns as those attributes are required to do the filteringand sorting. However, as the heading tell the user that this is the table ofopen defects, we don't need/want theStatus attribute in the output, so wedelete it.

Filtering Using thecatalog Macro

Another way of building the table above is to use thecatalog macro likethis:

# Load the bug tracking module !use "bugtrack"

# Load the bug data !include 'bugs.reg'; bugs; data

# Display the open bugs, sorted by priority H1: Open Defects !catalog bugs 'Status:Open'; headings; \ columns='Code,BUGTITLE:Title,Priority'; \ sort='Priority'

In this case, the filtering is done before the data reaches the class filter, sothings are easier once the data has been loaded.

Understanding Filter InterfacesOverview

SDF 2.001MTR-SDF-0004.00125-May-99 B-1© Ian Clatworthy

Appendix B. Understanding Filter Interfaces

Overview

General Syntax The general syntax for using each filter is shown first. By convention, thefilter is shown using theblock andendblock macros, although filters canalso be used with other macros, includinginclude andexecute.

Parameters If a filter has one or more optional parameters, these are listed in a tablecontaining the following columns:

• Name - the parameter name

• Type - the parameter type


Parameter Typesand Rules

Parameter types and rules follow the same conventions as macroargument types and rules. Refer toUnderstanding Macro Interfaces fordetails.

Understanding Filter InterfacesData Tables

SDF 2.001MTR-SDF-0004.001

B-2 25-May-99© Ian Clatworthy

Data Tables

Table Fields Providing data to a filter via a table is a common idiom in SDF as usingtables makes it easy to add additional columns later on.

If a filter expects a table of data inTBL format, the fields in the table ofdata are listed in a table containing the following columns:

• Field - the field name

• Category - key, mandatory or optional


Table FieldCategories

The supported table field categories are explained below.

Validating TableFields

As validating table fields can reduce performance quite a bit, thesdfprogram doesn't validate them by default. To enable table field validation,use the -v option like this:

sdf -v99 ...

Typically, this is only needed when a filter isn't working as you'd expect.

Category Description

key a unique value must be provided for each row

mandatory a value must be provided for each row

optional a value is optional

Understanding Macro InterfacesOverview

SDF 2.001MTR-SDF-0004.00125-May-99 C-1© Ian Clatworthy

Appendix C. Understanding Macro Interfaces

Overview

General Syntax The general syntax for using this macro is shown first, including the orderof the arguments, if any.

Arguments If a macro has one or more arguments, these are listed in a tablecontaining the following columns:

• Name - the argument name

• Type - the argument type

• Default - the default value, if any


Argument Types The supported set of argument types are:

The special types are needed for some of SDF's built-in macros includingdefine, include, on andif - they are rarely needed for normal macros.

Default Values For default values within argument tables:

• the empty string means there is no default

Type Description

Common:

string a string

integer an integer

boolean either 1 or 0

Special:

symbol a symbolic name

filter a filter name

rest the rest of the arguments

eventid an event tag

condition a logical expression

Understanding Macro InterfacesOverview

SDF 2.001MTR-SDF-0004.001

C-2 25-May-99© Ian Clatworthy

• the symbol _NULL_ means the default is the empty string.

Understanding Macro InterfacesRules

SDF 2.001MTR-SDF-0004.00125-May-99 C-3© Ian Clatworthy

Rules

Rule Types If you wish, arguments can be validated using a rule. Rules are either:

• Patterns

• General Perl Expressions.

Patterns A pattern is a Perl regular expression which the argument value ismatched against. Patterns are enclosed in angle brackets to differentiatethem from normal Perl expressions. Typical patterns are given in the tablebelow.

General PerlExpressions

More complex rules are required when:

• the regular expression does not apply to the whole value

• the regular expression is case-insensitive.

In these cases, a general Perl expression can be used as the rule. Withinthe expression, $_ is the value of the argument. Examples are:

Note: A pattern is simply a short-hand notation for the general Perlexpression below:

/^(pattern)$/

Pattern notation is provided as it makes rules easier to read and write.(Pattern-style validation typically covers 80% or more of validation rules

Pattern Explanation

<\w+> one or more characters in A-Z, a-z, 0-9 and '_'

<\d{4}> a 4 digit number

<on|off> a string which is either "on" or "off"

<XMIT-.*> a string which begins with "XMIT-"

Expression Explanation

/\d/ a digit exists somewhere in the string

/^(on|off)$/i value is either "on" or "off" (case insensitive)

Understanding Macro InterfacesRules

SDF 2.001MTR-SDF-0004.001

C-4 25-May-99© Ian Clatworthy

so improving the readability of patterns has a large impact on the overallreadability.)

Command Line GuidelinesOverview

SDF 2.001MTR-SDF-0004.00125-May-99 D-1© Ian Clatworthy

Appendix D. Command Line Guidelines

Overview

General Usage Utilities have the following general usage:

utility [options] arguments

Typically, arguments is a set of filenames. If more than one file isspecified, each filename is echoed to standard error as it is processed.

Options can either be:

• short style - these begin with a '-' character, or

• long-style - these begin with the character sequence '--'.

To obtain a concise summary of a utility's usage, execute it without anyparameters. For example:

$ hoopyusage : hoopy [-h[help]] [-o[out_ext]] [-l[log_ext]] [-tthing,..] file ...purpose: do lots of hoopy things to filesversion: 1.000$ _

Exit Codes The exit code returned to the operating system is dependent on theseverity of any errors encountered during execution. The pre-defined exitcodes are linked to message types as summarised below.

Arguments The set of options is implicitly terminated by the first argument. i.e. thefirst symbol which does not begin with either '-' or '--'. To specify anargument which would otherwise be treated as an option, it is sometimesnecessary to explicitly terminate the options using the '--' symbol.

Code Message Description

0 n/a everything succeeded

8 warning a possible problem was identified

16 error an error was found

24 abort processing could not continue on a file

32 fatal the application terminated abnormally

64 failed an internal error occurred

Command Line GuidelinesOverview

SDF 2.001MTR-SDF-0004.001

D-2 25-May-99© Ian Clatworthy

Unless stated otherwise for a particular utility, '+' can be used to specifythat standard input contains a list of arguments. This feature isparticularly useful for passing complex arguments to scripts on systemswith poor support for command line quoting.

If the arguments are files, '-' can be used to indicate standard input.

Providing DefaultOptions

Default options for a utility can be specified in an environment variableof the form:

nameOPTS

For example, ifhoopy supported a -R option for specifying a directory tosearch for report files in, then the user may wish to define this directory inan environment variable so that they do not need to specify it each time.This could be done by adding the following to their.profile:

HOOPYOPTS=-R/home/me/etc/reports export HOOPYOPTS

Command Line GuidelinesOptions


Options

Option Types Several types of options are supported as outlined in the table below.

For parameter-optional options, the option parameter typically defaults toa particular value if the option is supplied without a parameter. Forexample, the extension of output files can be specified using the -ooption. The default value of this parameter-optional option is 'out'. Theseries of examples below illustrates this.

1. To send output to standard output:

hoopy *.dat

2. To send output to .out files:

hoopy -o *.dat

3. To send output to .new files:

hoopy -onew *.dat

As for arguments, '-' can be specified to indicate standard input foroptions expecting a filename.

List Options Some options havelist parameters. These options can be specifiedseveral times and/or multiple list elements can be separated withcommas. For example, the following are all equivalent:

hoopy -ta,b,c *.dat hoopy -ta -tb,c *.dat hoopy -ta,b -tc *.dat hoopy -ta -tb -tc *.dat

In addition to simple lists, lists of name-value pairs are also supported. Inthis case, the name and value are separated by a '=' or ':' character.

Note: on MS-DOS and OS/2, '=' causes problems so ':' must be used.

Option type Usage message format

parameter-less [-x]

parameter-required [-x thing]

parameter-optional [-x[thing]]


SDF 2.001MTR-SDF-0004.001


If only the name is given, the value is assumed to be 1. For example, thefollowing are equivalent:

mycmd -ftbl_dir=../tables -fverbose=1 *.dat mycmd -ftbl_dir=../tables -fverbose *.dat mycmd -ftbl_dir:../tables -fverbose *.dat

Ordering is not important for name-value lists but may be important fornormal lists. In either case, within a usage message, list options areindicated as follows:

[-t thing,..]

Option Styles There are two parameter styles:short andlong. Short style is typicallyused on the command line. Long style is useful to improve readability inshell scripts.

In short style:

• options are specified by a single character

• a set of parameter-less options can be clustered

• between the option character and the parameter:

– whitespace is optional for a parameter-required option

– whitespace isnot permitted for a parameter-optional option

In long style:

• the name can be abbreviated provided it is still unique

• a '=' or ':' is used to separate the option name from the parameter

Examples are:

hoopy --out *.dat

and

hoopy --out=new *.dat

Option NamingConventions

Long option names should be selected for maximum readability. Ingeneral, the short name should be the first letter of the long name.

For list options which specify a set of directories to search in:

• the long name should end in '_path'

• the short name should be a capital letter



If applicable, the capital letter used should be taken from the relatedoption. For example, if the -r option is used to specify a report file, the -Roption should be the list of directories to search for the report in.

Command Line GuidelinesCommonly Used Options

SDF 2.001MTR-SDF-0004.001


Commonly Used Options

Overview There are 3 options available for most utilities:

• -o[out_ext]

• -l[log_ext]

• -h[help]

RedirectingStandard Outputand StandardError

By default, generated output goes to standard output. To direct output to afile per input file, use the -o option to specify an extension for outputfiles. If the -o option is specified without a parameter, an extension ofoutis assumed. Likewise, error messages go to standard error by default. Usethe -l option to create a log file per input file. If the -l option is specifiedwithout a parameter, an extension oflog is assumed.

For a small number of scripts, there is never a need for output or errorfiles per argument. In this case, the -o and -l options are not available.

Obtaining Help The -h option provides help and is always available. To obtain a concisedescription of each option, use the help option with no parameter. Forexample:

$ sdfget -husage : sdfget [-h[help]] [-o[out_ext]] [-l[log_ext]] [-g get_rule] [-r[rpt_file]] [-i] file ...purpose: extract documentation embedded in source codeversion: 2.000 (SDF 2.000beta9)options:-h, --help display help on options-o, --out_ext output file extension-l, --log_ext log file extension-g, --get_rule rule to use to get documentation-r, --rpt_file report file-i, --inverse only output lines not extracted

Obtaining Help ona Given Option

Detailed help on a given option can be obtained by specifying the optioncode as a parameter to the -h option. For example:

$ sdfget -hgusage : sdfget [-h[help]] [-o[out_ext]] [-l[log_ext]] [-g get_rule] [-r[rpt_file]] [-i] file ...purpose: extract documentation embedded in source codeversion: 2.000 (SDF 2.000beta9)Detailed help on option: -g,--get_rule

Attribute ValueHelp rule to use to get documentation



Type STRParameter yesInitial perlLegal table, perl, cpp, c, eiffel, fortran

Obtaining SpecialHelp

The help option can also be used to obtain other useful information byspecifying a special keyword as the parameter. The keywords supportedare:

• .parts - display name & version of components (and exit)

• .time - display execution time (when exiting)

• .calltree - display the internal sequence of subroutines leading toutility exit

This type of information is useful when developing scripts but is rarelyneeded by end-users.


SDF 2.001MTR-SDF-0004.001


SDF 2.001MTR-SDF-0004.00125-May-99 Index-1© Ian Clatworthy

Index

Symbols!block 5-4, 5-5, 5-9, 5-10, 5-12, 5-13, 5-14,

5-15, 5-16, 5-23, 5-25, 5-26, 5-30,5-32, 5-33, 5-34, 5-39, 5-40, 5-42

!build_title 5-3, 5-4, 5-6, 5-29!define 5-3, 5-4, 5-6, 5-23, 5-29!endblock 5-4, 5-5, 5-9, 5-10, 5-12, 5-13,

5-14, 5-15, 5-16, 5-23, 5-25, 5-26,5-30, 5-32, 5-33, 5-34, 5-39, 5-40,5-42

!execute 5-30!include 5-3, 5-6, 5-18, 5-29, 5-30, 5-43!init 5-3, 5-4, 5-6, 5-29!insert 6-29"$'sdf_lib/stdlib" 12-3"A Sample Book" 5-3, 5-6, 5-29"appendx1.sdf" 5-3, 5-6"chapter1.sdf" 5-3, 5-6, 5-29"chapter2.sdf" 5-3, 5-6, 5-29"chapter3.sdf" 5-3, 5-6, 5-29"COMPANY" 5-13, 5-15"Diary" 5-39"getpod 'hello.c'" 5-30"glossary.sdf" 5-29"grid" 5-39"Hello world!

" 5-32"I. M. Wise" 5-4"Internet Management Tools" 5-4"is" 5-23"manual" 5-3, 5-6, 5-29"myabout.sdf" 5-3"myfile.c" 5-18, 5-43"paper" 5-4"perlre.pod" 5-30# Do the search 12-3# Get pod from a file 5-30# Get pod from standard output 5-30# Get the list of directories to search 12-3# Insert some pod 5-30# Insert the text of macro XXX if it's de-

fined 6-29# more paragraphs go here 5-4# Pretty-print the same file 5-18# Same as the previous example 6-29# The interesting stuff goes here 5-4$ D-6$base 4-3$data 4-3$dir 4-3$ext 4-3$key 4-3$short 4-3'.' 12-3'c' 5-18, 5-43'error' 6-29'H2

Subroutines' 5-42'XXX' 6-29(Continued) 6-8.calltree D-7.parts D-7.profile D-2.sdf 5-41.time D-7/doc/sdf 13-4/doc/sdf/mydoc.sdf 13-4

Numerics-2 11-2

A-a 11-2abc 6-5about 5-1, 5-3abstract 5-1, 5-4Acrobat iiaddress 5-1, 5-5, 5-26Administration

2-1Adobe iiAfternoon

SDF 2.001MTR-SDF-0004.001

Index-2 25-May-99© Ian Clatworthy

5-39Alias 11-3, 11-13align 7-1An 8-1appendix 5-1, 5-6AppendText 12-1, 12-2AppExit 11-12Application Programming Interface 11-1,

11-11AppMsg 11-12Appointment 5-39ascii_graphic 5-1, 5-7Attribute 1-2, 1-3, 1-4, 1-5attribute A-3autosplit 11-6

Bblock 6-1, 6-3, 6-16, A-1, B-1Body 11-18, 11-25bold 9-1Book controls

13-3box 5-1, 5-8build_title 6-1, 6-4, 11-8

C-c 11-3Canon PS-IPU Color Laser Copier v52.3

11-27catalog 6-1, 6-5, A-6Category 1-2, 1-3, 1-4, 1-5, 5-11, 5-12,

5-14, 5-21, 5-25, 5-41, A-1, B-2changed 5-1, 5-9, 5-33, 9-1CHAR 3-1Character 11-14character 13-5Characters

13-5checked 11-23class 6-1, 6-5, 6-6Classes

6-1, 10-1clean 11-9

clear 6-1, 6-7cmd 11-18cmd_opt 11-18Code D-1color 9-1Column A-3columns 13-2, A-3, A-4, A-6Command Line Interface 11-1Comment 11-8comment 5-1, 5-10Common

C-1Components

5-1concise 11-12Conditional text

6-2Configuration

5-2Continued 6-8continued 6-2, 6-8Control

13-3

D-D 11-2-d 11-3data 5-42datestrings 5-2, 5-11Default 6-3, 6-5, 6-6, 6-7, 6-8, 6-10, 6-11,

6-13, 6-14, 6-19, 6-20, 6-22, 6-23,6-24, 6-25, 6-26, 6-27, 6-28, 6-29,6-30, 6-31, 6-32, 6-33, 6-34, 6-35,6-36, 6-37, 6-38, 6-39, 6-42, 6-43,6-44, C-1

default 5-2, 5-12, 6-1, 6-10default.sdg 11-21DEFAULT_TAB_SIZE 13-2default_xxx A-4define 5-2, 5-14, 6-1, 6-11, 6-38, C-1delete A-5delimited 4-4, 4-5Description 1-2, 1-3, 1-4, 1-5, 3-2, 5-35,


5-37, 6-5, 6-30, 10-1, 11-1, 11-2,11-3, 11-11, 11-13, 11-17, 11-19,11-24, 11-26, 12-5, A-2, A-3, B-2,C-1, D-1

diff 11-23doc 11-9document 2-1, 11-7document.reg 1-4

EE 3-1, 8-1-e 11-24E80 8-1else 6-2, 6-12, 12-3elseif 6-2, 6-13, 6-14elsif 6-2, 6-13, 6-14Emphasis 11-25

10-1emphasis 1 10-1emphasis 2 10-1emphasis 3 10-1en_us 11-7end 5-2, 5-16end_topic 6-2, 6-15endblock 6-1, 6-3, 6-16, A-1, B-1endif 6-2, 6-17endmacro 6-1, 6-18Environment

13-5environment 13-5error 6-29Event Processing 6-34, 6-35Event processing

6-2Example 11-18, 12-5example 5-1, 5-17Examples 6-30execute 6-1, 6-19, A-1, B-1expand 5-23, 9-1, 11-8Explanation C-3export 5-12, 5-14, 6-1, 6-20Expression C-3expression format 13-6

Expression formats 13-5

Extensions 11-21Extraction

6-2

F-F 11-13-f 11-2, 11-11, 11-13, 11-19, 11-24family 5-12, 5-14, 9-1fax 11-7feature 5-32Field 1-2, 1-3, 1-4, 1-5, 5-11, 5-12, 5-14,

5-21, 5-25, 5-41, A-1, B-2Figures 6-25

6-1File processing

5-1, 6-2filename 12-3FindFile 12-1first 7-1fixed width 4-5fixed-width 4-4fmbatch 11-13, 11-15fmver 11-14Format 4-3, 11-1format 5-40, 11-1Format A 11-25FormatTime 5-11, 12-1, 13-1Formatting

5-1, 9-1, 10-1formatting filename 11-21FrameMaker ii, 11-1, 11-10, 11-13, 11-24FrameViewer ii, 11-1, 11-10front 5-1, 5-19fullname 12-3fvo 11-9

G-g 11-2, 11-19General

2-1, 5-1, 6-1get 5-2, 5-20

SDF 2.001MTR-SDF-0004.001


getcli 6-2, 6-21getcode 6-2, 6-22getdoc 6-2, 6-23get-rule 11-20global 11-14

H-H 11-3-h 11-2, 11-11, 11-13, 11-17, 11-19, 11-24,

11-26heading 6-42Headings

8-1Height 11-8height 11-8Help

5-2Help specific

7-1, 9-1hlp.context 7-1hlp.endwindow 7-1hlp.header 7-1hlp.popup 9-1hlp.topic 7-1hlp.window 7-1hlp_header 5-2, 5-21hlp_window 5-2, 5-22Hn 8-1hoopy D-2HTML 5-2, 5-4, 5-5, 5-23, 5-31, 5-41, 11-1,

11-6html 5-23, 6-7, 6-36, 6-42http

//www.mincom.com 10-1Hypertext

9-1

I-I 11-2-i [email protected] 10-1id 6-42, 9-1if 6-2, 6-24, 12-3, C-1

image 12-3import 6-1, 6-25include 6-1, 6-26, A-1, B-1, C-1index 9-1index_type 9-1Indexes

9-1Information

13-3inherit 6-1, 6-27INI 4-1, A-4init 6-1, 6-28, 13-2Init-only

13-2init-only 13-2inline 5-2, 5-23input format specification 4-4insert 6-1, 6-29International

3-3intro 5-42italics 9-1

J-j 11-11Jump A-3jump 9-1jumps 6-2, 6-30

K-K 11-3-k 11-3keep_next 7-1keep_prev 7-1Key 4-3key A-1, B-2Key-Format 4-3

L-L 11-2-l 11-2, 11-11, 11-17, 11-19, 11-24, 11-26label 5-27, 7-1lang 5-17, 5-43


langdefs 5-2, 5-17, 5-24langdefs.sdm 5-24left 7-1LFn 8-1lib 11-12lib_sym 11-12Libraries

6-1Line 8-1line 6-2, 6-31Line based

5-1lines 5-8list parameters D-3listitem 5-18, 5-43Lists

8-1Ln 8-1LNn 8-1local 12-3locale 11-7log 11-5, 11-11, 11-17, 11-19, 11-24,

11-26, D-6long D-4long-style D-1look 11-7LUn 8-1

Mmacro 6-1, 6-29, 6-32Macros

6-1main 5-30mandatory A-1, B-2manual 2-1Margins

7-1Mask 6-5mask 6-5Meaning 11-14, A-5memo 11-7Message D-1message 6-2, 6-33

Microsoft ii, 11-1mif 11-9MIMS 10-1Mincom 10-1, 11-18minutes 11-7Miscellaneous

2-1, 6-2, 7-1, 8-1missing 6-29Morning

5-39MTR-SDF-0002 10-1must iimy 12-3mydoc 13-4mydoc.fvo 11-10mydoc.html 11-10mydoc.mif 11-10mydoc.sdf 11-10myfile.sdf 10-1mytemplate.sdn 11-25

N-N 11-2N 8-1-n 11-2, 11-13n 8-1Name 1-1, 4-1, 5-1, 5-8, 5-12, 5-14, 5-17,

5-20, 5-23, 5-25, 5-27, 5-30, 5-35,5-36, 5-40, 5-41, 5-43, 6-1, 6-3, 6-5,6-6, 6-7, 6-8, 6-10, 6-11, 6-13, 6-14,6-19, 6-20, 6-22, 6-23, 6-24, 6-25,6-26, 6-27, 6-28, 6-29, 6-30, 6-31,6-32, 6-33, 6-34, 6-35, 6-36, 6-37,6-38, 6-39, 6-42, 6-43, 6-44, 7-1,8-1, 9-1, 11-1, 11-8, 12-1, 13-2,13-3, 13-4, 13-5, A-2, B-1, C-1

name D-2namevalues 5-1, 5-25NB 8-1NE 8-1ne 12-3noevents 7-1nofill 5-1, 5-26

SDF 2.001MTR-SDF-0004.001


nopb 7-1noslide 5-42not D-4Note 8-1note 5-1, 5-27Notes

8-1notoc 7-1NV 8-1

O-O 11-2, 11-11, 11-17, 11-19, 11-24, 11-26-o 11-2, 11-11, 11-17, 11-19, 11-24, 11-26obj 7-1Object Views A-3Objects

9-1objects.sdm 1-2, 1-3off 6-2, 6-34ok 6-29on 6-2, 6-35, 12-1, C-1opt 11-18Option 11-2, 11-11, 11-13, 11-17, 11-19,

11-24, 11-26Option type D-3optional A-1, B-2organisations 1-1, 1-2out 11-5, 11-11, 11-17, 11-19, 11-24,

11-26, D-6Output 3-2output 6-2, 6-36

P-P 11-2, 11-13-p 11-2, 11-11, 11-13, 11-24p2epsi 11-26PageSize 11-26paper 2-1paper_size 11-14Paragraphs 10-1Parameter 5-37parameters 5-35Pattern C-3

pattern C-3PB 8-1PDF iiPerl 5-2, 5-32, 6-2, 11-9, 11-11, 11-12perl 11-21perlapi 6-2, 6-37Phrase Attributes 7-1plain 5-1, 5-29, A-2Pn 8-1pod 5-1, 5-30, 11-9Positioning

7-1PostScript ii, 5-4, 5-5, 5-31, 5-41, 11-1,

11-14prefilter 11-6Prefix 11-20prefix_Jump=name/ A-4prefix_xxx A-4PrependText 12-1, 12-7print settings 11-14Priority A-6prn2ps 11-1, 11-26Processing

13-2processing 13-2products 1-1, 1-3ps 11-9ps2epsi 11-27pure 5-18Purpose 1-1, 2-1, 4-1, 5-1, 6-1, 6-30, 7-1,

8-1, 8-2, 9-1, 11-1, 12-1, 13-2, 13-3,13-4, 13-5

push 12-3

Qquote 5-1, 5-31

RR 11-8-r 11-2, 11-19references 1-1, 1-4, 6-5, A-3restrict 6-1, 6-38return 12-3


right 7-1RTF 11-1rtf 11-9Rule 1-2, 1-3, 1-4, 1-5, 5-8, 5-11, 5-12,

5-14, 5-17, 5-20, 5-21, 5-23, 5-25,5-27, 5-30, 5-36, 5-40, 5-41, 5-43,6-3, 6-5, 6-6, 6-7, 6-8, 6-10, 6-11,6-13, 6-14, 6-19, 6-20, 6-22, 6-23,6-24, 6-25, 6-26, 6-27, 6-28, 6-29,6-30, 6-31, 6-32, 6-33, 6-34, 6-35,6-36, 6-37, 6-38, 6-39, 6-42, 6-43,6-44, 11-20, 11-21, A-1, B-1, B-2,C-1

S-S 11-3, 11-13-s 11-3, 11-11, 11-13, 11-19Sample Output 10-1script 5-2, 5-32, 6-2, 6-39SDF ii, vii, 4-1, 11-1, 11-2, 11-17, 11-18,

11-21, 11-22, 12-2, 12-3, 12-7,13-2, 13-3, 13-4

sdf 1-4, 5-1, 5-30, 5-33, 11-1, 11-2, 11-6,11-23, 13-2, 13-4, B-2

SDF Document Catalog A-4SDF Guru Guide viiSDF Quick Reference viiSDF User Guide vii, 5-37, 6-25, 6-34, 6-35,

10-1sdf.ini 11-7, 11-8, 11-9sdf.sdm 1-4sdf_dir 11-7sdfapi 11-1, 11-11sdfbatch 11-1, 11-13, [email protected] viisdfcli 11-1, 11-17, 11-18sdfget 4-1, 4-3, 5-20, 6-23, 11-1, 11-6,

11-7, 11-19sdfmsg 11-12sdftest 11-1, 11-23SDG 4-1sdm 4-1sdn 4-1

sdngen 11-1, 11-24, 11-25sdr 11-7sds 4-1seconds since January 1, 1970 13-1section 2.1 10-1sections 5-1, 5-34short D-4short style D-1shrink 9-1Sign 8-1simple 5-2, 5-35size 9-1skipheader 5-17, 5-43slide_down 6-2, 6-40slide_up 6-2, 6-41some bold text 10-1some example text 10-1some italic text 10-1some normal text 10-1some underline text 10-1sort A-5sp_after 7-1sp_before 7-1Special

C-1Special symbols

3-2Specials

10-1Status A-6std 11-12stdlib 1-2, 1-3, 5-24, 11-7, 11-14, 11-21stdlib/langdefs.sdm 5-17Style 2-1style 11-7sub 11-12, 12-3subsections 6-2, 6-42suffix_xxx A-4sym 11-12Symbol 3-2, 5-11, 8-2, 12-5, A-5Syntax related

3-2

SDF 2.001MTR-SDF-0004.001


T-T 11-3-t 11-3, 11-13, 11-24table 5-1, 5-8, 5-11, 5-12, 5-14, 5-21, 5-25,

5-36, 5-37, 5-41, 11-6Tag 10-1tag A-3target 5-23TBL 4-1, 4-4, 5-37, 5-41, B-2terms 1-1, 1-5test 11-23The SDF Document Development System

viiThe search order is 6-25Time of day 5-39title 5-1, 5-40, 6-25toc 5-40top 7-1Topic 5-41topics 5-1, 5-41tracing group 11-9txt 11-9Type 5-8, 5-12, 5-14, 5-17, 5-20, 5-23,

5-25, 5-27, 5-30, 5-36, 5-40, 5-41,5-43, 6-3, 6-5, 6-6, 6-7, 6-8, 6-10,6-11, 6-13, 6-14, 6-19, 6-20, 6-22,6-23, 6-24, 6-25, 6-26, 6-27, 6-28,6-29, 6-30, 6-31, 6-32, 6-33, 6-34,6-35, 6-36, 6-37, 6-38, 6-39, 6-42,6-43, 6-44, 13-2, 13-3, 13-4, 13-5,A-2, B-1, C-1

type 5-40Types

10-1

U-u 11-3, 11-13undef 6-1, 6-43underline 9-1Understanding Class Interfaces 1-2, 1-3,

1-4, 1-5Understanding Filter Interfaces 5-3, 5-4,

5-5, 5-6, 5-7, 5-8, 5-9, 5-10, 5-11,

5-12, 5-14, 5-16, 5-17, 5-19, 5-20,5-21, 5-22, 5-23, 5-24, 5-25, 5-26,5-27, 5-29, 5-30, 5-31, 5-32, 5-33,5-34, 5-37, 5-40, 5-41, 5-43

Understanding Macro Interfaces 6-3, 6-4,6-5, 6-6, 6-7, 6-8, 6-10, 6-11, 6-12,6-13, 6-14, 6-15, 6-16, 6-17, 6-18,6-19, 6-20, 6-21, 6-22, 6-23, 6-24,6-25, 6-26, 6-27, 6-28, 6-29, 6-30,6-31, 6-32, 6-33, 6-34, 6-35, 6-36,6-37, 6-38, 6-39, 6-40, 6-41, 6-42,6-43, 6-44, B-1

Unix ii, 11-10URLs

10-1Usage 6-30Usage message format D-3use 6-1, 6-44, 12-3Use Formats From 11-13user 11-9

VV 8-1-v 11-3, 11-19Value 12-6value_xxx A-4Values 5-11var 11-12Variable 12-6Variables

6-1verbatim 5-1, 5-17, 5-43vgrind 5-24view A-3

W-w 11-3, 11-17warning 6-29website A-4When generating 6-25where A-5wide 5-18, 5-43Width 11-8


width 11-8Windows ii, 5-22, 11-10

XX/Open iixx.log 11-23xx.out 11-23xx.sdf 11-23xxx A-4xyz 6-5, 11-22xyz.html A-3xyz.pdf A-3xyz.ps A-3xyz.sdf 11-22

Y-Y 11-3-y 11-3

Z-z 11-3

Documents

SDF Reference - Internodeiangeri/sdfng/docs/2.001/ref/re_sdf.pdfSDF 2.001 SDF Reference