Templates for EPICS Documentation
Jackie Wallis
Table of Contents
Argonne National Laboratory
Advanced Photon Source
March 1995
The main reason for needing documentation templates is to maintain a consistent document look, especially when documentation is being written by many authors. For the APS EPICS project, there is also the need to be able to easily translate documents to hypertext, so documents can be put on the World-Wide Web for access by all EPICS users.
Described below are three basic templates for APS documentation. Suggested page and heading count limits are approximate and intended to give the author a general idea of which template would fit the document best.
ShortMemo
The first template is called `ShortMemo' and is designed for documents under 15 pages long. If your document has roughly this many pages, and less than 10 first level headings, then this is the template you should be using.
This template comes in two varieties. `ShortMemoNumbered' numbers the second and third level headings. `ShortMemo' is the one that produced this document and does not number the sub-headings. Which template to use is up to the personal preference of the author.
MediumMemo
The second template is called `MediumMemo' and is intended for documents that are too large for the `ShortMemo' format, but too small to be made into a chaptered book. The major difference between this and the `ShortMemo' template is that this template includes a brief (first level headings only) table of contents on the first page of the document, directly under the author's name and address. This table of contents allows the reader to easily locate a particular section of the document.
This document also comes in two flavors, numbered and un-numbered, called `MediumMemoNumbered' and `MediumMemo'.
Book
The third template type is actually a set of templates to be used when creating a multi-chapter book. The template set includes:
- TitlePage
- TableOfContents
- Chapter and ChapterNumbered
- Glossary
- Reference
- Index
This template set should be used when the material to be presented is too much for a `MediumMemo' format. Each chapter of the document should be placed in a separate file (chapter numbers are automatically updated when TOC is updated). Separated chapter files enables the FrameMaker to HTML converter to translate the document for easiest viewing.
It is not necessary to use all the book templates if your document does not need them, they are provided for your convenience. The minimum template set used would include: TitlePage, TableOfContents and several using the Chapter template.
Template Location
For APS users, the templates exist in the `NewEpics' directory of the template list in FrameMaker. For other users, download the templates from the APS Templates WWW page and access as desired.
Example Paragraphs
Each of the templates contain text giving examples of all the paragraph types and how they would typically be used. Once you understand the layout of the template, delete this text and enter the text of the document, applying paragraph tags as desired.
Two warnings should always be kept in mind when using these templates for documents that are to be translated into hypertext:
- Don't make new paragraph tags or rename existing paragraph tags
- Change/over-ride paragraph formats carefully
Both of these things can be easily done and are perfectly acceptable to FrameMaker. The problems resulting when the translation to hypertext is attempted are further explained below.
Don't Make/Rename Tags
The paragraph tags in the APS templates have been carefully named to avoid errors when the FrameMaker to HTML converter is run. New paragraph tags should not be added to the ones available, nor should existing tags be renamed to something else. One of two things typically happen if tags are added/changed:
- The paragraph tag names will be flagged as errors when the converter is run and will have to be manually changed to a recognized tag.
- Or, the converter will recognize the tag name and convert it to a paragraph type, but not necessary the one intended.
Change Format Carefully
The layout and look of the FrameMaker document is independent of the format of the HTML document. Therefore it is possible to change the look of the FrameMaker document without effecting the hypertext document, as long as the paragraph tag names remain the same. However, one of the main reasons for having templates in the first place is for a consistency of document look. All the APS templates look the same.
The paragraph formats presented should be able to fulfill almost all of your documentation needs. However, if it becomes necessary to over-ride a paragraph format, remember that all paragraphs of the same name will be translated into HTML the same way, regardless of the FrameMaker over-rides that were set. In other words, paragraph formats that are over-ridden will often lead to unexpected results when translated to HTML.