|Previous:||Desktop Publishing||(See printing version)|
|Next:||TeX and XML-related news|
Mario Ruggier , IT/IPT
A software project requires the production of numerous documents, e.g. documents for the User Requirements, Design and Architecture, Configuration Management, Test Plan, Project Plan, and so on. An inconsistent visual style across these different documents will make life harder for both the reader (the end-user of the documents), to whom style inconsistencies are just a hindrance to comprehension, and the editor, who would need to waste some effort to continually devise new ways to format each different document. Furthermore, inconsistent tagging between documents will increase the difficulty to exchange, reuse or generally adapt content units - a content unit could be a single paragraph, a figure with caption, or even an entire section or chapter.
A template is the most effective tool to achieve consistency. In addition, templates minimize the editor's effort, improve collaborative authoring, allow for automatic document conversions, facilitate the reuse or adaptation of information, and preserve the capability to globally update document formats and definitions.
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:
The SDLT define catalogues of tagged format definitions for paragraphs, characters, master pages, reference pages, cross-references, variables and tables1.
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.
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.
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.
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.
|FrameMaker at CERN:|
|SDLT Web Pages:|
|SDLT User's Guide:|
1. FrameMaker allows also the definition of catalogues for custom colours and mathematical elements.
For matters related to this article please contact the author.Cnl.Editor@cern.ch