This chapter presents some of the difference between FrameBuilder and FM+SGML. Also, this chapter provides tips (arranged alphabetically) on working with structure.
Please send items for inclusion in this list to scox@rsn.hp.com. Updates regarding current tips should also be sent to scox@rsn.hp.com.
This section highlights differences between FM+SGML and FrameBuilder.
Some of the more notable important differences about FM+SGML are:
Other differences include:
NOTE: If you remove the structure from a FM+SGML document, you will lose all cross-references because cross-references go to elements--not paragraph tags.
This section provides various tips and tricks for working in structured documents.
Your book's structure view may show an element named <BOOK-COMPONENT>. This element appears when files are added to a structured book.
To validate the book's structure:
Assuming the added file is structured correctly and placed in the book in the right position, the book's structure will be valid when generation completes.
Custom auto-numbering is lost online. These constructs must be changed to regular text.
For example, if you have compiler error messages that are
auto-numbered with the string fc:, each of those paragraphs
must be converted.
Auto-numbered paragraphs that are part of the template, such as bullet lists and numbered lists, work as expected online.
In general, you should not use custom auto-numbering--it is an override of the template. If however you have a legitimate need for using your own auto-numbering paragraphs, contact Peter Cash (x4389) to see if your change can be included in the template. You will also need stylesheet changes and may have to use book-specific stylesheets.
The conversion table is not guaranteed to cover every possible situation--you may have to contact Peter Cash (x4389) to add rows to properly handle your books.
See the current conversion table to determine what the table wraps.
In FM+SGML, cross-references go to elements--not paragraph tags. See the "Procedure for validating" section on page 11 for a procedure to fix cross-references.
Frame cross-references are hyperlinks online.
Question marks appear online in place of cross-references if the cross-reference is not resolved in FM+SGML.
To delete text in FM+SGML, both the text and its element must be deleted. For example, if you find yourself deleting a paragraph marker that keeps reappearing, then delete the <Para> element in the structure view.
Keep an eye on the structure view to ensure that you are deleting everything that needs deleting. If you prefer, you can do your deleting in the structure view itself.
If the text to be deleted is not the only text in the element, the element does not have to be deleted.
Because formatting of text in FM+SGML files is done by elements, there is a close relationship between the appearance of a document in FM+SGML and the same document in DynaText and PinPoint.
The stylesheet used by DynaText and PinPoint determines how the online docs look based on the element wrappers.
FM+SGML adds an element--if possible --when you press ENTER; otherwise, you will hear a beep indicating that FM+SGML cannot insert an element for you. However, you are generally prompted to choose an element at that time. The element can be selected using the Element Catalog or by typing the element's name followed by ENTER. See the "Keyboard shortcuts" section on page 34 for a quick way to insert elements.
Hardspaces do not exist online: any hardspaces in your document are automatically converted to regular spaces.
Using keyboard macros to manipulate a structured document can make the validation process (and editing in general) go much more quickly.
Use CTRL-z as a prefix to all macro triggers for macros that you define--this prefix avoids overriding any of Frame's keyboard shortcuts.
View your macros by displaying your macro file, which is a plain text file. The optional comment you make after recording a macro appears as the macro's title in this file.
Typically, your macro file will be in your /fminit directory (or your home directory if you do not have an fminit directory) on the machine where you use FM+SGML. The file is named fmMacros.
Macros cannot be undone. Only the very last step in the macro can be undone.
The macros cannot record moving or clicking of the mouse--Frame's foundation of keyboard shortcuts easily makes up for this fact though.
To create a macro that repeats n times:
To create a macro that calls a repeating macro:
If you try in FM+SGML to define a new macro that calls an repeating macro, you will invoke and be trapped in the repeating macro.
Shortcuts are needed to define useful macros. They also reduce the need to move a hand from the keyboard to the mouse.
Listings of the keyboard shortcuts can be found in the FrameMaker+SGML Quick Reference and in FM+SGML's online help window by clicking on Shortcuts in the menu bar.
Some of the more commonly used keyboard shortcuts are
Inserts <element> at the current cursor location
Wraps the highlighted element inside <element>
Changes the highlighted element to <element>
Highlights the current paragraph
Highlights the current word
Highlights the current sentence
Finds the next occurrence of the entity which the Find dialog is currently set to locate
The shortcuts CTRL-n (where n is 1,2, or 3) require you to specify an element. When you enter one of these shortcuts, the rectangle at the lower left-hand corner of your document window becomes highlighted--this rectangle serves as your prompt to select an element.
You select an element by performing one of the following tasks:
For those lists in FM+SGML that are wrapped using the <ItemizedList> element, the Mark attribute of that element determines whether the list is a Bullet list, Plain list, Box list, or Check list.
To change the attributes of an element,
See the Chapter template to determine how to wrap various lists.
Definition lists are implemented using the <VariableList> element. You change margins in a <VariableList> element by changing the value of the TermLength attribute.
Insert markers in a structured document by inserting the corresponding element. Inserting the element causes FM+SGML to prompt you for the marker information.
Use the following elements to obtain monospace fonts:
ComputerOutput |
Data presented to the user by a computer. OpenBook equivalent: VoiceComputer |
UserInput |
Data entered by the user. OpenBook equivalent: VoiceUser |
ProgramListing |
A listing of program source. OpenBook equivalent: ExampleBlockVerbatim |
A structured file cannot be restructured. That is, if you have a structured document in which particular items did not get wrapped the first time, then changing your conversion table and regenerating structure for the structured document will not wrap those items. To take advantage of changes in the conversion table, remove structure, then re-structure.
NOTE: If you remove the structure from a FM+SGML document, you will lose all cross-references because cross-references go to elements--not paragraph tags.
If you are running FM+SGML on your workstation, you will have to edit the sgmlapps.doc so that it points to the right applications. The lines below (taken from the sgmlapps.doc file on icarus) are the lines you will need to update; these lines are on the first page of the sgmlapps.doc file.
Read/write rules:/work/packages/frame/fmsgml/fminit/usenglish/sgml/docbook/app/rules
DTD for export:/work/packages/frame/fmsgml/fminit/usenglish/sgml/docbook/app/dtd
Template for import:/work/packages/frame/fmsgml/fminit/usenglish/sgml/docbook/app/template
SGML declaration:/work/packages/frame/fmsgml/fminit/usenglish/sgml/docbook/app/sgmldcl
If you would like to open the Ramer templates by selecting File -> New -> Convex/ -> ... from FM+SGML running on your workstation, you must first execute the following command sequence:
% cd /.../frame/fmsgml/fminit/usenglish/Templates
% ln -s /usr/spool/globdata/etc/FrameTemplates/FMSGML/ Convex
Contact Peter Cash (x4389) for information on running FM+SGML locally.
Searching an entire book in DynaText or PinPoint is one advantage of having successfully put a book online. By being able to easily search your book, you can locate possible inconsistencies in terminology and punctuation, among other items.
The appearance of online documents is governed by our stylesheets. For example, the vertical spacing before a <Para> element is determined in the stylesheets. File a viper bug (as described in the web page PinPoint Style Issues and Bugs) to request stylesheet changes.
The following sections may assist you in creating your online tables.
Use the <InformalTable> element with the NORULES Table Tag to hide a table.
To select NORULES, put your cursor in the table you wish to hide, open the Table Designer by selecting Table -> Table Designer. Choose the Table Tag by clicking on the triangle next to the Table Tag field, which is in the top-left corner of the Table Designer.
You can preserve line breaks by using soft returns (SHIFT-RETURN) inside a <LiteralLayout> element.
You can preserve paragraphs in a single table cell by using <Para> elements for each paragraph.
Cell straddling does not work online; avoid this construct or use conditional text to maintain hard copy and online versions of the tables.
DynaText and PinPoint stylesheets support only the ALL and NORULES table tags. See the section "Hidden tables" section on page 38 for more information on table tags.
Use the <Table> element for tables with titles. Use the <InformalTable> element for untitled tables.
Do not use tabs in any file that is going online.
The templates for FM+SGML documents are available from the menu bar (on icarus and idiom) by selecting File -> New -> Convex/ -> desired_template. You can also get template files (on any machine) from /usr/spool/globdata/etc/FrameTemplates/FMSGML/.
If your questions are not answered by this document, contact one of the following people:
Mail your comments on this doc to scox@rsn.hp.com