Abstract

This is an Adobe FrameMaker 5.5 template file to be used for fairly short technical documents, i.e. up to 10 pages. This template is the single file version of the the SDLT multi-file book template package, i.e. it contains the same book-independent format definitions.

For short technical documents, that do not require a table of contents or an index, a single file template is more convenient to use than a multi-file book template package. And, with the set of predefined formats being mostly the same in both templates, you as an author have less to learn to be able to use both templates. Sharing the same predefined formats also facilitates the exchange of content between documents prepared in either of the two templates.

1 Where should you begin?

To...	Do..	More info...
Introduce yourself to FrameMaker...	Follow the FrameMaker Overview Follow a Quick Tour Follow the Online Tutorials	Do Help > Overview... from any doc window Go to http://framemaker.cern.ch/ , "Getting Started" (for both b. and c.)
Access available FrameMaker documentation...	Access the Online Help Obtain a printed copy of the FrameMaker 5.5 User Guide	Do Help > Contents... Buy it from COBS ( http://consult.cern.ch/books/ ), or borrow a copy from 1-R-013
Access SDLT documentation...	Read: Guide for using the Software Documentation Layout Templates	http://framemaker.cern.ch/sdlt/guide/ Hard copies from 1-R-017
Edit the title block and the document metadata...	See Section 2, "Editing the title block & the document metadata", below	Warning! Do not replace the metadata user variables with text!
Remove this template text...	Select the text sections and delete!	To select everything: click in text and Edit > Select All in Flow
Format text...	Just type in your text, and tag using only the formats defined the character (f) and paragraph (¶) catalogs	Warning! Ad hoc format overrides are lost during format updates, and make your document unmaintainable!
Format figures, tables, listings...	See Section 3, "Figures, tables, listings", below	See also the corresponding Figures reference page
Use the reference pages...	View > Reference Pages , then page through to one of: DocMetaData FrontMatterTables Figures WWWVariables	Will help you with: Editing doc metadata Samples of frontmatter tables, if needed Formatting figures Customize for WWW
Convert to WWW...	See Section 4, "Converting to HTML", below	Warning! Do not just do Save As... HTML !
To get support...	Email to Docsys.Support@cern.ch	After reading the documentation!

2 Editing the title block & the document metadata

The title block consists of a special sequence of paragraphs, each containing a similarly-named user variable (or a piece of document metadata ). To edit you should only modify the value of these metadata variables. You can do this in either of the 2 ways:

Double-click on each piece of metadata , i.e. on each variable, and then change the variable definition to change its value.
Go the the DocMetaData reference page to see the complete list of related variables and their values. Follow the instructions to modify each one as needed.

The title block paragraphs used in this template sample are only a few of the ones defined here. Feel free to include others, e.g. DocID and DocIssue , or to exclude any that you feel are not appropriate. For a complete list and description of all title block paragraphs, please see the "Cover page" section of the chapter "Editing the front matter", in the SDLT manual.

Warning !
Do not replace the metadata user variables with text!

3 Figures, tables, listings

The simple general way to create a figure, a table or a listing is to:

Create an empty PlaceHolder paragraph
In this paragraph insert a table ( Table > Insert Table... ) using an appropriate predefined table format from the list, e.g. the Fig table format for a normal figure.
In case of figures, you will then need to create an anchored frame into the upper table cell, for the graphical content of the figure. Details and samples of such anchored frames are available on the reference page Figures ( View > Reference Pages ).

The Paranum cross-reference format is used for cross-references to a caption of a figure, table or listing.

For complete documentation on formatting figures, tables and listings, please see the corresponding sections in the chapter "Laying out the content", of the Guide for using the Software Documentation Layout Templates .

4 Converting to HTML

Warning !
Due to limitations (and bugs!) in the Save as... HTML feature of FrameMaker 5.5.6, please follow exactly the following steps to convert your document to HTML.

To save as HTML...

File > Save
File > Save As... , choosing HTML as destination format, and preferably placing generated files in their own subdirectory, e.g. html .
File > Revert to Saved 1
Copy the file SDLT-master.css over the .css file generated by FrameMaker for your HTML document.
View the generated HTML file(s) with a web browser.

To customize the generated HTML...

Modify the variables on the WWWVariables reference page ( View > Reference Pages ), using the descriptions provided.
Repeat the steps above, "To save as HTML...".

A Compatibility with the SDLT book template

This template has includes the mostly the same formats of the front matter, chapter, and appendix templates of the SDLT book template package. The only difference is that all formats are rolled into the same file, and that things relevant only to long documents are removed.

What is in the SDLT book template but not in this template

The document tables in the front matter, i.e. the Document Control Sheet, Status Sheet, Change Record and Distribution List, are not included by default. A copy of them is however available on the reference page FrontMatterTables , from where you can copy and paste any of them.
All predefined set-ups for generated lists, i.e table of contents, lists of figures, tables, and items. are not available. For automatic updating of lists in FrameMaker, a multi-file book is needed.
Level 5 and level 6 heading paragraph tags have been dropped for this template. A short document should definitely not have more than a 4-level hierarchy structure.

Exchanging content between this template and the SDLT book

All the predefined format tag names are the same in both templates. Thus it is very easy to exchange content back and forth between this single file template and the SDLT multi-file book template, as follows:

Select and copy the desired sections from the source document and paste it into the target document.
Re-apply the predefined formats in the target document to the newly copy-and-pasted sections, by doing:
File > Import > Formats...
Make sure that Import from Document: is Current .
Make sure that everything is checked on.
Click on Import .

Re-applying formats is necessary because, although all the tag names of the predefined formats are the same in both templates, some of the format themselves are different.

1. This is to workaround a FrameMaker 5.5.6 bug: if you ever forget this step, the variables on the reference pages will not work anymore. To recover you will simply need to re-import references pages from a fresh copy of the template.

SDLT

Single File Template