Standardize Formatting Across Documents and DTDs with Modular FOSIsSuzanne Napoleon FOSIexpert, LLCwww.FOSIexpert.com

Join the conversation!Event hashtag is #PTCUSER10

The Challenge: Standardize FormattingOrganizations mandate standardized formatting in order to safeguard corporate identity brandingHowever, documents, DTDs, and formatting specs change over timeWhen there are multiple FOSIs, the same edits must be made to all FOSIs affected by the changesThis approach is time-consuming and error-prone

The Solution: Modular FOSIsCommon formatting is coded in FOSI modulesIndividual FOSIs reference the appropriate modules When a module is edited, all FOSIs that reference that module are changedThis approach makes it much easier to maintain standardized formatting over time

The Technical DetailsA FOSI is an SGML document that adheres to the OutSpec DTDSGML file entities can be used in a FOSIA FOSI module is an SGML file entity

The ProcessReview each FOSI and create charsubsets, pseudo-elements, and/or text entities, as appropriate, for any common code within a FOSICompare all FOSIs to determine which share common formatting

The Process, continuedDevelop a naming convention for FOSIs and modules that makes their purpose obviousUse .ent extension for modules to facilitate searching the file systemExamples:basic-charsubsets.entA4-pagesets.entlist-counters.ent

The Process, continuedCode the descs directly in the .fos files:rsrcdescsecdescpagedescstyldescftndesc

The Process, continuedCode FOSI-specific formatting directly in each .fos fileFor example:Code warning.txt=Warning in Book-English.fosCode warning.txt=Warnung in Book-German.fos

The Process, continuedMake as many file entities as needed for the following FOSI components and name them appropriately:hyphrule docdesc charfill charsubsetcounter envdescstringdecl e-i-cfloatloc footnotepageset ftnattsectoken

Create File Entitycreate_file_entity (cfe) creates a file entity with theselected content, prompts for the name of the entity and the file name or Public IC, and inserts the entity into the document

Declare File Entitydeclare_file_entity (dfe) prompts for the name of the entity and the file name or the Public ID for the entity to be created

File Entities Dialog

Entities in .fos Files

Entities in the Tagged FOSI EditorInsert references to the appropriate modules into each .fos file

The Process, continuedCompile each FOSI to incorporate changesChanges are not reflected in the FOSIs until they are compiled

The Process, continuedDocument the modules referenced by each FOSI Be sure to update this documentation whenever you:Modify a moduleAdd or delete references to a module

TipsAlphabetize counters, strings, e-i-cs, charsubsets, etc., before creating FOSI modulesAlphabetize counters, strings, etc., in modulesCompile frequently while developing modulesDetect context errors sooner rather than laterFormat test documents regularly and look for unintended formatting changes

Tips, continuedKeep the documentation up to date: Modular FOSIs are only as good as their documentation

WYSIWYG is last-century technology!

Questions?

For example: Manuals and Bulletins may be authored to the same DTD, but separate FOSIs may be used to format them. User documentation may be authored with a different DTD and formatted with one or more FOSIs that contain some of the same formatting that is in the FOSIs for manuals and bulletins.This is a time- tested approach. For example, Caterpillar began using modular FOSIs in 1995 for 4 types of manuals produced in 14 languages from 4 DTDs using 44 FOSIs and 80 FOSI entities, with 2 publications output in 2 sizes, plus support for draft versions and document fragments. I first presented this topic in 1996. For example, most FOSIs contain charsubsets for block, startline, endline, inline, title, allcaps, bold, etc. Put them in a module and reference the module in the FOSIs. Note that not every FOSI may use the allcaps charsubset, for instance, but it doesnt hurt anything and it is there if needed in the future. Good naming conventions help you search the file system for relevant files.Do not include descs in modules. Coding them in the FOSI allows multiple modules to be referenced in each desc and categories can be intermixed with modules references. Shown in slide to come.To keep things simple, the file name option is used here

To keep things simple, the file name option is used hereDialog options: New, Duplicate, Modify, Delete, Insert (not grayed out when entity is in context), Find, Count Uses, Close, Help.Simple example: Standard and Series A implies Series B, Series C, and beyond.Notice how descs are coded in the FOSI. File entities are intermixed with direct coding.This example keeps things simple, suggesting Series B, Series C, etc. -- it can get as complex as necessary. The Caterpillar FOSIs are an excellent example.Note that it may be desirable to reflect versions in module names. For example: std-eics-v1.ent.Documentation is the key to modular FOSIs. Without documentation, modular FOSIs are a nightmare. It is critical to keep the documentation up to date. During FOSI development, related e-i-cs are often grouped together in the .fos file. However, in the long run, alphabetizing is the preferable approach because it is easier for those who maintain the FOSI in the future and because it facilitates the development of modular FOSIs in the future.

In addition to the eyeball review, you can compare the file sizes of .dvi files to see if they are the same before and after changes.Documentation is the key because many FOSIs are maintained by people who did not develop them.At least one organization had to de-modularize because there was no documentation. Out-of-date documentation = bad karma! 6******