Unstructured FrameMaker Basics: Formatting Admonitions Part 1

Category: Tech Writer

Admonition text are sections of a document that add/explain details about a particular chapter or part. They are generally formatted as a separate block of text and categorized as either Note, Important, Caution, Warning and Tip although the captions/conventions vary according to the author and publication style guide. They generally break the flow of text and can be distracting when used too often, though they are indispensable for highly complex work such as documentation for developers and engineering specifications. Admonition blocks/lists can include a colorful customized icon like those found in the excellent Fedora Project documentation or a black and white icon such as those found in Wiley books. 

Admonition example from the Fedora Project documentation

Document generators such as Asciidoc and XML/XSLT tool chains using Docbook, xsltproc, SAX and DITA take care of formatting and adding the icon but in unstructured FrameMaker, writers will have to create a paragraph or table style specifically for admonition paragraphs, blocks, or lists. Creating admonitions in WYSIWYG applications such as Adobe InDesign and CorelDraw is easy since all you need is to Place the icon image next to a resized text frame. However, unless you anchor the icon to a text frame (which isn't really recommended for image-intensive documentations), managing the flow of text in InDesign can be tricky. FrameMaker, in contrast, is based on anchored objects though users who are accustomed to InDesign's click and drag approach may find FrameMaker's roundabout approach frustrating at first.

Admonition paragraphs

Admonition paragraphs are nothing more than text formatted/positioned differently from the main text flow. Admonition paragraphs focus on one technical point only and shouldn't be too long. To create an admonition paragraph with a caption:

1.  With your insertion point in the paragraph you want to format, click the Commands button and then New Format... in Paragraph Designer.

2. In the New Format window, enter a Tag name and click Create.

3. Click the Basic button and enter 0.5" in the Left indent. Most writers prefer text blocks to be flush to the right like most of the text but if you prefer to isolate the paragraph completely, add 0.5" on the Right indent also.

4. Enter a pt value in the Above Pgf and Below Pgf items. This adds white space between the note and the rest of the text and breaks up long narratives.

5. Click Update All or Apply.

If you prefer to add additional formatting to the Note/Important/Warning/Caution caption, create a separate Character tag using the Character Designer.

Admonition Paragraphs with Icons

Small icons highlight the section and attract the reader's attention. However, they are often unnecessary in more serious documents. They are acceptable for consumer user manuals, however, since they make the documentation friendlier to readers and more colorful.


Admonition example from the Samsung S4 manual.

Note: For sections in this article using an icon, I'll be using images I created using CorelDraw X5 and exported as an EPS for FrameMaker.

To add an icon to an admonition paragraph:

1. Place the insertion point at the beginning of the paragraph.

2. Click File then Import. Navigate to the image file and select either Import By Reference or Copy Into Document.

3.  Click Import. 

4. Using your mouse pointer, select the image frame. 

5. Click Special and then Anchored Frame.

6. In the Anchored Frame pod, change the Anchoring Position to Run into Paragraph. Change Alignment to Left.

7. Using your mouse pointer, select the image inside the frame. Hold down SHIFT and drag the handles to resize the icon. Select the frame and resize the frame as well.

8. If you want to retain the paragraph's alignment, resize the image frame so the text aligns as before. Since the text runs around the image, adjusting the Tabs won't help so adjusting the image frame is a good workaround to achieve an aligned text.




Note: To reuse the icon and the resized image frame, just select the image frame using the mouse pointer, copy, and then paste on to the next admonition paragraph.

Continued in Unstructured FrameMaker Basics: Formatting Admonitions Part 2