The SDF Document Development System Ian Clatworthy ([email protected]), Research Architect, Mincom Pty Ltd SDF (Simple Document Format) is a freely available document development system which generates high quality outputs in a variety of formats from a single source. The output formats supported include HTML, PostScript, PDF, man pages, POD, LaTeX, SGML, MIF, RTF, Windows help and plain text. SDF documents are simple to create and maintain, minimising the time spent on documentation. In particular, SDF directly supports the creation and maintenance of large, on-line documentation systems (including intranets) via centralised hypertext management and rule-based hypertext generation. SDF has been completely developed in Perl, a popular and highly portable scripting language. Like Perl, SDF is freely available for commercial and non-commercial use. 1. Overview 1.1 Introduction SDF is a document publishing system which aims to solve some common problems that many software organisations encounter with documentation: 1. How do we support multiple formats (and produce high quality output for each)? 2. How do we reduce the time it takes to create documents? 3. How do we maintain a large on-line documentation system? 4. How can we generate and easily maintain hypertext links? 5. How do we keep the documentation up to date with the code? 6. How can we centrally manage corporate formatting standards? The basic design principles are: 1. Documents should be specified in a logical manner. 2. Make common things easy. 3. Give power users full control when they need it. 4. The architecture should be open and easy to extend. The key feature of SDF is the division of responsibility: • content is supplied as text files or generated where feasible • formatting is generally implied by the semantics of the content or supplied by rules or external templates. SDF consists of the following key components: 1 The SDF Document Development System • SDF - Simple Document Format, a text format for defining documents • sdf - a utility for converting SDF files to other formats. Unlike SGML, XML, HTML and many other markup languages, the SDF language has been designed to be author-friendly, rather than parser-friendly. As a result, most SDF documents look quite similar to plain text email, making them easy-to-write and easy-to-read. 1.2 A Sample SDF Document A sample SDF document is shown below: # Build the title !define DOC_NAME "GalaxyBuilder" !define DOC_TYPE "Discussion Paper" !define DOC_AUTHOR "Joe Bloggs" !build_title H1: Introduction After extensive market research, I believe there is an excellent opportunity for us to develop software for the I<galaxy construction industry>. Potential customers include: * NASA * European Community * China * Japan. Note: The proposed name of the software package to be developed is [[DOC_NAME]]. If you want to suggest a better name, send email to {{EMAIL:[email protected]}}. H2: Software Requirements The key requirements are: ^ support for the design and simulation of galaxies containing up to: - 1000 large planets, or - 5000 small planets + the package needs to be easy to use + the package needs to be well documented. H2: Project Team Exploding galaxies will be B<very> bad for business, so we need the best team possible for this project: !block table Person Role Mary Jones Project Manager Hans Blass Architect Bill Smith Software Engineer !endblock 2 The SDF Document Development System 1.3 A Brief Explanation Comments begin with a # character as the first non-whitespace character on a line. Macros are embedded commands which begin with a ! as the first non-whitespace character on a line. The define macro is used to set variables. The value of a variable can be embedded in paragraph text by using the [[...]] syntax. The DOC_NAME and DOC_TYPE variables are used by the build_title macro which creates: • a cover page (or two) for paper-based outputs • a title header for online outputs. Paragraphs can be tagged in different ways. For the vast majority of SDF documents, the only tags used are: Tag Meaning H1: level 1 heading H2: level 2 heading * item in level 1 bulleted list - item in level 2 bulleted list ^ first item in level 1 ordered list + next item in level 1 ordered list > fixed-width, verbatim text Note: note Phrases can also be tagged in several ways. Any phrase can be tagged using the syntax: {{XYZ:...}} where XYZ is the tag. For single, uppercase character tags like I (Italics) and B (Bold), POD- style syntax is also supported: X<...> where X is the tag. Tables can be specified using the table filter, typically in combination with the block and endblock macros. The first row is the headings. Remaining rows are data. 1.4 Generating Output Formats The sdf command is used to convert SDF to other formats. The general syntax is: sdf [options] file ... 3 The SDF Document Development System If an extension is not given (and a file is not found with that name), an extension of sdf is assumed. The most commonly used option is the -2 option. For example, to convert mydoc.sdf to HTML and PostScript, the respective commands are: sdf -2html mydoc sdf -2ps mydoc These commands create files called mydoc.html and mydoc.ps respectively. To convert mydoc.sdf to a set of HTML topics, the command is: sdf -2topics mydoc This creates the following files: • mydoc.html - the table of contents • mydoc_1.html - the first topic • mydoc_2.html - the second topic. By default, topics are created whenever a level 1 heading is encountered or a file is explicitly included. The -n option can be used to specify a different level for splitting into topics, e.g. sdf -2topics -n2 mydoc 1.5 Requirements SDF requires the following: • Perl 5.003 or later • for generating PostScript, the freely available pod2ps program or SGML-Tools and LaTeX packages. Alternatively, you need a word processor which can import MIF or RTF (Adobe's FrameMaker 5.x is preferred) • for generating PDF, Adobe's Acrobat • for generating Windows Help files, a help compiler (e.g. hcp.exe). 1.6 Architecture The architecture of SDF is given in the diagram below. 4 The SDF Document Development System any text editor Source Formatting SDF files code rules sdf RTF Plain HTML MIF POD SGML (& HPJ) text fmbatch Word HCP pod2... sgml2... Windows PostScript man pages, GNU info, Help Latex, etc. Latex, etc. Acrobat PDF 5 The SDF Document Development System 2. Alternative Systems 2.1 WYSIWYG Tools WYSIWYG (What-You-See-Is-What-You-Get) tools are great for creating small to medium- sized: • World Wide Web documents (i.e. HTML), or • paper-based documents (i.e. PostScript), or • Windows help files. However, the WYSIWYG approach is inefficient when it comes to creating and maintaining large documentation systems, particularly if you want high quality paper-based and on-line outputs. The reasons are: 1. WYSIWYG is meaningless when it comes to supporting multiple formats. For example: – paper documents are formatted on fixed-size pages; on-line documents are formatted as topics displayed in user-sized windows – different browsers may display a given HTML document differently. 2. For good-looking results, the formatting rules need to be tuned for each format. For example, a certain phrase may be: – a hypertext jump within HTML – emphasised using italics for paper-based formats – a pop-up window within Windows help. 3. The content often needs to be tuned for each format. For example, you may wish to describe a given procedure in different ways: – in detail for a paper-based document – terse for on-line help. 4. Centralised management of formatting rules and hypertext generation is essential for minimising the cost and maximising the quality of a large documentation system. By making it too easy for individual authors to customise formatting, WYSIWYG tools often make it harder for workgroups to centrally manage formatting! Nevertheless, WYSIWYG tools are often used in combination with SDF when they save time. For example, diagrams can be created in most packages and imported into SDF documents. 6 The SDF Document Development System 2.2 SGML/XML The SGML/XML approach of specifying documents semantically is an extremely powerful one and SDF uses the same approach whenever possible. However, as SDF does not use document structure rules and DTDs, it is much simpler than SGML. SDF is also more readable than SGML, so high-cost authoring tools are not needed on every desktop, making SDF much cheaper to implement than SGML. Like SDF, XML has built on SGML's good ideas but minimised the overall complexity. However, XML has retained SGML's unfriendly appearance. 2.3 POD In many ways, the system closest to SDF is POD (Plain Old Documentation) which is widely used in the Perl community. Like SDF, POD: • is simple, readable and free • supports a large number of output formats • supports literate programming (i.e. POD documentation can be directly embedded in Perl scripts and libraries) • is built on Perl. Currently, SDF has several advantages over POD: 1. SDF supports more features, e.g.: – tables – figures – formatting within example text – filters, macros and variables (see Language Overview below). 2. SDF is more extensible as sites can add their own: – paragraph and phrase styles – paragraph and phrase attributes – filters, macros, etc. Furthermore, versions 2.000beta10 and later of SDF are POD friendly: • POD can be converted to SDF and vice versa • SDF can be nested inside POD and vice versa • SDF is largely upwardly compatible with POD in terms of syntax and functionality. 7 The SDF Document Development System As a result, POD users can use SDF or migrate to SDF when POD isn't powerful enough. Refer to SDF for POD Users for further details.