CERN Accelerating science

The SDLT: separate layout and content templates

The Software Documentation Layout Templates (SDLT), produced in IT/IPT, are a generic and comprehensive set of Adobe FrameMaker 5.5 templates, for formatting technical software documentation. Sample material for different types of document is provided separately, as content templates, themselves formatted using the SDLT. Figure 1 shows the working model for this scheme. This separation (of layout and content templates) offers the following advantages:

• Visual consistency across the various documents for a project can be achieved in a manageable way, and requires the maintenance of only one set of layout templates.
• Simplification of the production and maintenance of content-only templates: adding a template for a particular document type requires only the creation of a content template, consisting only of content-specific sample material.
• If a content template for a particular document type does not yet exist, third parties have the liberty and the means to create it, as required by their project.

Some features of the SDLT are:

• comprehensive predefined formats for all typical software documentation material;
• predefined formats for cover, front matter, table of contents, automatically updated lists, chapters, appendices, and index;
• documents may be composed of a single FrameMaker file (convenient for shorter documents) or as multi-file FrameMaker books (for longer documents requiring automatically updated table of contents, index, etc.);
• customizable automatic conversion to the Web;
• comprehensive user documentation.

Figure 1 Specific project documents (3) are produced by editing templates obtained by combining the corresponding content template (2) with the software documentation layout templates (1).

Predefined formats in the SDLT

Figure 2 A detail of the FrameMaker paragraph catalogue for the SDLT chapter template, showing paragraph tag names for list items, level 1, 2 and 3.

The SDLT define catalogues of tagged format definitions for paragraphs, characters, master pages, reference pages, cross-references, variables and tables¹.

A big problem in the design of templates is keeping the number of defined formats (i.e. the number of options for the editor) to a minimum while still providing the authors with all they need. To keep the number of "visible" formats small, each SDLT template file contains only the formats required by that template file - for example, the front matter and chapter template each contain a different set of predefined formats, but each only contain what is necessary to format the front matter and chapters, respectively. Even so, if we consider only paragraph formats, there are about 82 definitions in the chapter template, and more than 150 collectively in all the template files.

The names used for the format tags are carefully chosen, as these are crucial for template usability. Figure 2 shows a sample of paragraph tag names - for list items, level 1, 2 and 3.

Here is a non-exhaustive list of the formatting possibilities offered in the SDLT:

Figures, tables and listings There are dedicated predefined formats (as a FrameMaker table) for each of the several defined types of figures, tables, and listings. Each type of object has its own automatically numbered caption, independent of the other two. Special paragraph definitions provide the necessary formatting flexibility, e.g. source lines in listings may be just plain or automatically numbered (to be able to refer to specific lines) and table cell headings may be aligned top, bottom, left or right.

Variables as document metadata Information about the document, such as the title, authors, status, version, etc., that are used throughout the document (such as in the running headers and footers) are defined as FrameMaker user variables. All defined metadata variables are also collected in a special reference page, named DocMetaData, where an editor can view, as well as modify, all current variable settings in one glance.

Items with attributes A special collection of paragraph formats implements the content model for an item: an item is a generic content unit that may have an identifier, a title, an expanded statement and any number of other attributes. A user requirement is an example of such an item. Furthermore, the editor has the option to automatically include a short-list of all items throughout a document, for quick reference, as a separate chapter or appendix.

Master pages Master pages define how the page is organized - the size and position of text columns, running headers and footers, any background images (such as a logo), etc. By default, the Left and Right master pages are used, but an additional Landscape page definition allows editors to insert a landscape-oriented page anywhere in the document, e.g. for extra wide tables or figures.

Reference pages FrameMaker reference pages are versatile "resource repositories" for the editor. Typically, they hold repeatedly used graphics, but the SDLT uses reference pages for several other purposes: a DocMetaData reference page (mentioned above) collects all user-defined variables containing information about the document; samples of standard tables that may be used in the front matter, such as the Document Control Sheet or the Document Change Record, are kept in a FrontMatterTables reference page; a Figures reference page contains sample material useful for formatting figures; a WWWVariables reference page holds user-defined variables that customize how the document is converted to the Web.

Delivering documents as PDF or HTML

FrameMaker documents can be saved as PDF or HTML, for distribution, using FrameMaker's built-in Save As... features. The SDLT are prepared so that all the automatically generated lists, such as the table of contents and index, become hypertext lists in the generated PDF document. The HTML version of a document may be customized via a set of user-defined variables, as mentioned above. Some aspects that the editor can easily control in this way are: the break-up of the document into separate HTML files; consistent navigation options on each HTML page; "context" links at the top of all pages; signature at the bottom of all pages.

Availability and support

Adobe FrameMaker, a complete and integrated publishing tool, is available site-wide at CERN on various UNIX platforms, PCs running Microsoft Windows and Macintoshes. Document files are freely interchangeable between the three platforms. The full SDLT distribution is available from the SDLT Web pages. The single file version of the SDLT is also included in all the central FrameMaker installations, as one of the CERN templates (thus available from within FrameMaker, under File > New... ). Help on issues concerning the usage of FrameMaker and/or SDLT is available through e-mail.

http://framemaker.cern.ch/

http://framemaker.cern.ch/sdlt/

http://framemaker.cern.ch/sdlt/guide/

Docsys.Support@cern.ch