DECdocument
Producing Online and
Printed Documentation
Previous Contents Index

3.2.1 The DECdocument Graphics Editor

You can create your figures using the DECdocument Graphics Editor that comes with DECdocument. This utility creates figures for use in Bookreader books, as well as in printed books. Refer to Graphics Editor User's Guide for Motif to learn how to use the DECdocument Graphics Editor.

3.2.2 Making Figures Formal or Informal

To make a figure formal, supply a caption and a symbol argument to the <FIGURE> tag. When you specify a caption, DECdocument automatically assigns a number to the figure. A figure with a caption, and therefore, with a number, is called a formal figure, and is included in the table of contents. A figure without a caption, and therefore, without a number, is called an informal figure.

When you specify a symbol name as the second argument, you can use the <REFERENCE> tag to refer to the figure's symbol name, thereby always producing the correct figure number and caption.

Figures are numbered sequentially throughout each chapter. Except for in the REPORT doctype¹, you cannot control figure numbering; it is an attribute of the overall doctype and design.

3.2.3 Figure Elements

A figure element comprises the actual contents of a formal or informal figure. Choose the figure element tag based on the type of figure. Valid tags are shown in Table 3-4.

A figure can consist of more than one type of figure element. For example, you can label a small graphic file and some text that accompanies it by using a <FIGURE_FILE> and a <SAMPLE_TEXT> tag. 


    <FIGURE>(How to Load a Tape\tape_fig) 
    <FIGURE_FILE>(LN03\mydisk:[mydirectory]tape_fig.six\10) 
    <SAMPLE_TEXT>
    <P>This figure illustrates how to load a tape...
    <ENDSAMPLE_TEXT>
    <ENDFIGURE>

The output of this example would be a formal figure titled "How to Load a Tape." The figure in [MYDIRECTORY]TAPE_FIG.SIX would be included, along with the sample text explaining the figure.

3.2.4 Controlling Figure Attributes

You can control the following figure attributes:

3.2.4.1 Controlling Figure Margins

By default, the left margin of the figure lines up with the left margin of text, regardless of whether the text immediately preceding the figure is indented.

You can extend the figure into the left margin (for printed output only). The caption remains aligned with the text. To move the figure into the left margin, use the WIDE attribute as the last argument to the <FIGURE_FILE> tag, as shown. 


 
    <FIGURE_FILE>(PS\filename.PS\5.5\WIDE)
If the figure is formal, and you want to align the caption with the figure (that has been extended into the left column), use the WIDE attribute to the <FIGURE_ATTRIBUTES> tag along with the WIDE attribute to the <FIGURE_FILE>, as shown. 


 
    <FIGURE>(A Wide Figure\wide_symbol) 
    <FIGURE_ATTRIBUTES>(WIDE) 
    <FIGURE_FILE>(PS\filename.PS\5.5\WIDE) 
    <FIGURE_FILE>(LN03\filename.LN03\7.2\WIDE) 
    <FIGURE_FILE>(BOOKREADER\filename.DECW$BOOKFIG\5.5) 
    <ENDFIGURE>

The body of a figure (that is, the set of tags that specify the content of the figure) is processed independently of the <FIGURE> tag and its caption. For example, some writers use the <FIGURE> tag to formalize examples so that they can refer to them from anywhere in a document.

Example 


 
    <FIGURE>(Status Message\stat_fig) 
    <FIGURE_ATTRIBUTES>(WIDE) 
    <CODE_EXAMPLE>(WIDE) 
    %SYSTEM-S-SUCCESS, YOU HAVE SUCCESSFULLY COMPLETED ALL THE EXERCISES 
    <ENDCODE_EXAMPLE> 
    <ENDFIGURE>

The WIDE attribute specified in both the <FIGURE_ATTRIBUTES> tag and in the <CODE_EXAMPLE> tag ensures that the caption aligns with the code example text.

Output
Figure n--n: Status Message 


__________________________________________________________________________ 
 
%SYSTEM-S-SUCCESS, YOU HAVE SUCCESSFULLY COMPLETED ALL THE EXERCISES 
__________________________________________________________________________

3.2.4.2 Controlling Page Breaks in Figures

A figure may consist of one or more individual elements. For example, two or more graphics may make up a single figure, monospaced examples may be mixed with graphics in a single figure, or a figure may consist of a monospaced example that is more than a page in length. In such instances, you should be aware of the rules for controlling page breaks in figures.

By default, the text formatter makes the following assumptions about a figure:

You can use the attribute keywords KEEP and MULTIPAGE in figures as follows:

Note
These attributes have no effect in a book displayed by Bookreader. DECdocument places informal figures where you have coded them. Formal figures will automatically pop up in separate windows.

If a figure that requires more than one page is coded without the MULTIPAGE attribute, the text formatter issues a message and breaks the figure according to the following rules:

You can use the <PAGE> tag in figures to control the page breaking explicitly. However, when you control page breaks in this manner, you may have unexpected results when you process the input file for a different output device.

3.2.5 Including Graphics Files

Table 3-5 describes the tags that are used for including graphics in source files. Examples of each tag can be found in Using Global Tags.

Table 3-5 Tags for Including Graphics Files
Tag Description
<ICON> Enables a small graphics file to be placed to the right or the left of your text, with several restrictions. See Using Global Tags for information.
<ICON_FILE> Identifies the graphics file to be included in your text. You must use this tag in the context of the <ICON> and <ENDICON> tags.
<ICON_TEXT> Identifies the text to accompany an icon file. You must use this tag in the context of the <ICON> and <ENDICON> tags.
<ENDICON> Terminates the <ICON> tag.
<FIGURE_FILE> Includes a separate figure file. Valid only within the context of the <FIGURE> and <ENDFIGURE> tags.

An example of how to include graphics files follows:

Example 


    <FIGURE>(Keyboard Illustration) 
    <FIGURE_ATTRIBUTES>(Keep\Wide)
    <FIGURE_FILE>(LN03\mydisk:[mydirectory]keyboard.six\10\WIDE) 
    <FIGURE_FILE>(PS\mydisk:[mydirectory]keyboard.ps\10\WIDE) 
    <FIGURE_FILE>(BOOKREADER\mydisk:[mydirectory]keyboard.brf\10) 
    <ENDFIGURE>

This example shows a figure file that includes a graphics file. Note the three pieces of information you must provide in the <FIGURE_FILE> tag: the type of output, the file specification, and the size (in picas) of the figure. The WIDE qualifier is optional.

Each <FIGURE_FILE> tag specifies a different input file and a different output device. You may be writing a book that will be processed for both printed and Bookreader display. When you create illustrations and process them for the different output devices, call them into your SDML file by using an independent <FIGURE_FILE> tag for each one. The previous example identifies three different file types and three different output devices: LNO3, PS (POSTSCRIPT), and BOOKREADER (online).

Output
Figure n--n: Keyboard Illustration

Note

¹ See Using Doctypes and Related Tags for more information on the REPORT doctype.

3.3 Examples

An example is often used to display an excerpt of a programming or command language, the interaction between a user and the system, and so on. You can produce informal or formal examples with DECdocument. Each type requires its own set of tags. If you make an example formal, it appears in the table of contents and can be referenced from anywhere in the document.

3.3.1 Making Examples Informal

To create an informal example, type your text or code excerpt between <CODE_EXAMPLE> and <ENDCODE_EXAMPLE> tags. An informal example follows:

Example 


    <CODE_EXAMPLE>
    $! 
    $!   The next two lines redefine the cmd. line prompt to be the node 
    $!   name's initial. 
    $! 
    $ NODE :=='F$LOGICAL("SYS$NODE")' 
    $ SET PROMPT="''F$EXTRACT(1,1,NODE)':" 
    $! 
    <ENDCODE_EXAMPLE>

Output 


$! 
$!   The next two lines redefine the cmd. line prompt to be the node 
$!   name's initial. 
$! 
$ NODE :=='F$LOGICAL("SYS$NODE")' 
$ SET PROMPT="''F$EXTRACT(1,1,NODE)':" 
$!

3.3.2 Making Examples Formal

To create a formal example, use the caption and symbol arguments with the <EXAMPLE> tag. You can include a specified file in your example by using the <EXAMPLE_FILE> tag, or leave space for an example to be pasted in later by using the <EXAMPLE_SPACE> tag. Terminate a formal example with the <ENDEXAMPLE> tag.

You can only use text in a formal example that you label with <CODE_EXAMPLE>, <INTERACTIVE>, <S>, and <U> tags. You cannot use tables, lists, paragraphs, and other text elements in a formal example. See the <EXAMPLE_SEQUENCE> tag description in Using Doctypes and Related Tags for information about how to construct an example sequence that can include a variety of text elements.

You could make the example shown in Section 3.3.1 into a formal example as follows:

Example 


    <EXAMPLE>(Login Commands\login_exam) 
    <CODE_EXAMPLE>
    $! 
    $!   The next two lines redefine the cmd. line prompt to be the node 
    $!   name's initial. 
    $! 
    $ NODE :=='F$LOGICAL("SYS$NODE")' 
    $ SET PROMPT="''F$EXTRACT(1,1,NODE)':" 
    $! 
    <ENDCODE_EXAMPLE>
    <ENDEXAMPLE>

Output

Example n--n: Login Commands 


__________________________________________________________________________ 
 
$! 
$!   The next two lines redefine the cmd. line prompt to be the node 
$!   name's initial. 
$! 
$ NODE :=='F$LOGICAL("SYS$NODE")' 
$ SET PROMPT="''F$EXTRACT(1,1,NODE)':" 
$! 
__________________________________________________________________________

The <FIGURE> tags and the <EXAMPLE> tags are similar in function, providing alternate ways to label (for cross-referencing purposes) a distinct type of example. See Section 3.2.4 for an explanation of how attributes are processed and how to control page breaks in multipage examples (the information in that section applies to both figures and examples).

You can use any of the tags listed in Table 3-6 inside a formal example.

Table 3-6 Example Tags
Tag Description
<EXAMPLE> Begins an example.
<CODE_EXAMPLE> Begins an example of programming source code.
<ENDCODE_EXAMPLE> Ends a code example.
<EXAMPLE_ATTRIBUTES>(KEEP) Specifies that the example will not float.
<EXAMPLE_ATTRIBUTES>(WIDE) Specifies a wide format for the example's caption.
<EXAMPLE_FILE> Causes the entire contents of the specified file to be included in your source file.
<EXAMPLE_SPACE> Leaves space for an example to be pasted in during production.
<INTERACTIVE> Begins an example of interactive dialog. Enables the <S> and <U> tags to distinguish system text from user text.
<ENDINTERACTIVE> Ends the interactive dialog.
<S> Labels the system text of an interactive example.
<U> Labels the user text of an interactive example.
<VALID BREAK> Indicates an acceptable page-breaking point in a long example.
<CALLOUT> or <CO> Labels a callout in an example.
<ENDEXAMPLE> Ends an example.

3.4 Considerations for Bookreader Display

When you write a document to be viewed by Bookreader, you need to consider how DECdocument displays your graphics. DECdocument can automatically display formal tables, figures, and examples in separate windows that are popped up in Bookreader. To pop up these graphics, use the hotspot feature. Hotspots are regions in the windows that you click on with your mouse to access cross-referenced topics such as graphics.

When your book contains formal tables, figures, and examples, make sure you introduce the element with a <REFERENCE> tag that contains the element's symbol name as the argument. The <REFERENCE> tag actually becomes the hotspot that the user clicks on to pop up the window. Without the hotspot, the window is only accessible from the table of contents. See Chapter 4 for information on using the <REFERENCE> tag with symbol name arguments.

3.4.1 Preparing Informal Tables, Figures, and Examples for Bookreader Display

If you have tables, figures, and examples that you determine are small enough to be integrated within the text and do not need table of contents entries, you can consider them informal. Leave the coding the same as for printed output, except under these circumstances:

To solve the text formatter limit problem or the size problem, do one of the following:

  1. Make the table, figure, or example formal by adding the following:
  2. Use the <ONLINE_POPUP> tag. See Section 2.6.4.
  3. Use the <ONLINE_CHUNK> tag. See Section 2.6.1.

    The <ONLINE_POPUP> tag is not limited to tables, figures, and examples; you can use it with any segment of text, including the <INTERACTIVE>, <DISPLAY>, <EXC>, and <EXI> tags.¹ Be careful not to overuse the online popup feature, as too many popups may hinder the document's readability.

    To use the <ONLINE_POPUP> tag, follow these rules:

    If you omit an <ENDONLINE_POPUP> tag, DOCUMENT displays the following error message: 


     
    %TAG-E-TAGNOTEND, tag <ONLINE_POPUP>, line 35, file 
       $DUA1:[ANDERSON]TEST.SDML; 
       Tag <ONLINE_POPUP> from line 15 not terminated

    The following example specifies an informal table will be popped up in a separate window:

    Example 


        <ONLINE_POPUP>(table) 
    <TABLE>
    .
    .
    .
    <ENDTABLE>
    <ENDONLINE_POPUP>

    The next example shows how the <ONLINE_POPUP> and <ENDONLINE_POPUP> tags should be used within and not around tags that generate headings.

    Example 


        <HEADN>(Introduction\intro_sym) 
    <ONLINE_POPUP>(Example) 
    <CODE_EXAMPLE>
    .
    .
    .
    This is the text within the code example. 
    .
    .
    .
    <ENDCODE_EXAMPLE>
    <ENDONLINE_POPUP>
    .
    .
    .
    <HEADN>(Next Section\next_sec) 
    .
    .
    .

    Note

    ¹ The <DISPLAY>, <EXC>, and <EXI> tags are specific to the SOFTWARE doctype; the <INTERACTIVE> tag is global.

    Previous Next Contents Index