18.3 Using FrameMaker

In the directory $PTOLEMY/doc/samples, the following files can be found:

title.doc: A sample cover page.
documents.doc: A sample document (very similar to this chapter).
documentsTOC.doc: The table of contents for the document.
documents.book: A book file that unites the above three documents.

These documents can be used as models or templates for creating new documents that are to be inserted in The Almagest or are to stand alone. Use documents.doc as a template for most applications. It defines the paragraph and character styles visible in this chapter.

By convention, except for the sample document, we do not distribute the FrameMaker files for the entire Almagest. Instead, we distribute the PostScript ¹ code produced by Frame. The makefiles used to print manual, therefore, simply assume that the PostScript files are up to date. It is up to you to ensure this. You must also ensure that the index files corresponding to the PostScript code are up to date. The section below explains how to generate these.

18.3.1 Index Entries

We use FrameMaker to generate the indexes for each manual. Different index markers are used to denote different uses of the term bein indexed. For example, the definition of a star gets a different FrameMaker marker than a simple reference to the star. In the index file the page number of the definition will be in bold, the page number of the reference will be in a regular font.

To use the Ptolemy group markers, the following X resources should be modified in the file $FMHOME/fminit/usenglish/Maker.us:

Maker*marker.10: IndexReference
Maker*marker.11: IndexExamplle
Maker*marker.12: IndexDefinition
Maker*marker.13: IndexStarRef
Maker*marker.14: IndexStarEx
Maker*marker.15: IndexStarDef
Maker*marker.24: HTMLStart
Maker*marker.25: HTMLEnd

These resources cause the named index markers to appear in the list of markers.

To make an index entry in a FrameMaker document, select the text you wish to appear in the index, and select the FrameMaker command Special-Marker (Esc-s-m). Then choose one of the above six types of index entries, using the following guidelines:

IndexReference: Generic index entry
IndexExample: An example of the usage of a particular feature.
IndexDefinition: The definition of a term.
IndexStarRef: A generic reference to a star.
IndexStarEx: An example of the usage of a star. For example if the text that describes the SDF butterfly demo would have a index entry that looks like: butterfly (SDF demo).
IndexStarDef: The definition of a star. This entry is normally automatically generated when a star is compiled, so you will probably not encounter any occasion to use it directly. The text that defines the SDF Ramp star would have the marker text: Ramp (SDF block)

Avoid index entries beginning with very generic words in the Ptolemy vocabulary, like Ptolemy, star, galaxy, or domain. Of course, if you are writing some explanation of these basic terms, then an index entry is appropriate. Before entering index entries for a star, look in the documentation for similar stars to get an idea of the subject terms that have already been used and might be related. Be sure to follow the same capitalization rules as the existing index entries (i.e. Ramp (SDF block), not Ramp (SDF Block)).

Currently we use Quadralay's WebWorks to convert Framemaker documents to html. You can use HTMLStart to indicate text that should be present in the html output as a link. Use a HTMLEnd on the end of the text of the text that represents the link. The text of the first HTMLStart contains the filename or URL:

http://ptolemy.eecs.berkeley.edu

The HTMLEnd is placed at the end of the text you want underlined in the html version.Here is a sample link to http://ptolemy.eecs.berkeley.edu.

The markers are not printed when the FrameMaker document is printed. WebMaker converts the text delimited by the markers into HTML hypertext links.

When you print your document, you should generate the index file that will be used to print the overall index. To do this, select File/Generate, and within the ensuing dialog box, select List/List of Markers. In the dialog box that results from this, be sure all of the above index markers are included, and then accept the default filename suffix "LOM". The dialog box should look like this:

When you click OK, you will get a new file with a list of markers in a format acceptable to the Ptolemy index generation software. This file should be saved in "Text only" form. By convention, we name the index file using the document name with the suffix ".index".

18.3.2 Special fonts and displays

By convention, Ptolemy documentation uses a special font for C++ class names. In the FrameMaker template, the corresponding format is named Class.

For a display entirely set in this font,
use the "Commands" paragraph format, as shown here.
You can use "meta-Return" to force carriage returns where you want them without getting a new paragraph.

Note that if you use the Commands paragraph format, you should be sure to change any slanted double quotes " " to straight quotes ", by typing Control-Shift-". In general, commands don't have slanted double quotes, hence the need to convert them to straight quotes.
Star and Target parameters, such as the SDF loopScheduler target parameter, are always in italic, use the Emphasis font format.
The names of stars and demos should be in the Class format.
If a string is to be taken literally, it should be in the ProgramCode character format. An example would be that the default of the loopScheduler target parameter is 1. Strings such as YES, NO, TRUE and FALSE, that are used as values to parameters should also be in the ProgramCode format.
The first line of a dialog with a computer should use the Commands paragraph format. Each successive line should use the CommandsCont paragraph format. The text the computer would print should be in the ProgramCode character format, the text the user would type should be in the ProgramUser character format.
If a string is only an example and to be substituted with a proper value, it should be in ProgramVariable character format.
To include images of palettes in documents, see "Capturing a screen image" on page 2-41.

¹ PostScript is a registered trademark of Adobe Systems Inc.