DECdocument
Using Global Tags
Previous Contents Index

<ICON_FILE>

Specifies a graphics file that accompanies text within the <ICON> and <ENDICON> tags.

Format

<ICON_FILE> (target device
\vertical size
\horizontal size
[\RIGHT])

ARGUMENTS

target device

Specifies a keyword indicating the output device for the graphics file. Keywords are provided both for devices that do (LN03, PS, and Bookreader) and do not (LINE, MAIL, and TERMINAL) support graphics. Each keyword allows you to insert the necessary amount of white space for the specific output device; keywords for devices that do not support graphics allow you to insert blank space in place of an icon. The following table lists the output devices and expected output for each keyword.

Keyword Device Output
BOOKREADER DECwindows screen The specified graphics file is output online using Bookreader.
LN03 LN03 Laser Printer The specified sixel graphics file is output as an icon.
PS PRINTSERVER 40 or
LN03R SCRIPTPRINTER 		The specified POSTSCRIPT graphics file¹ is output as an icon.
LINE
MAIL
TERMINAL 		Line Printer If specified, blank space is output with the file spec argument written in that blank space. Use only one of these three keywords to indicate a monospaced destination.

¹POSTSCRIPT graphics files must conform to the Encapsulated POSTSCRIPT File Format published by Adobe Systems, Inc.

file spec

Specifies the graphics file. No default file type is supplied.

SPACE

This keyword lets you reserve blank space in the output file for an icon. You can use it if you do not use the file spec argument. Use SPACE to reserve space for art that will be pasted in at a later date, or when you expect to process a file for more than one output device, but do not have graphics files for all devices.

vertical size

Specifies the vertical size of the printed graphic in picas (there are 6 picas in an inch and 12 points in a pica). This argument must be a nonnegative integer or decimal number, including zero.

horizontal size

Specifies the width of the printed graphic in picas (there are 6 picas to an inch and 12 points in a pica). This argument must be a nonnegative integer or decimal number, including zero.

RIGHT

This is an optional keyword argument. If you use it, it must come last in the argument list. RIGHT specifies that the graphic image be placed to the right of the text. If you do not specify this argument, the image is placed on the left of the text specified in the <ICON_TEXT> tag.

related tags

restrictions

Valid only in the context of an <ICON> tag.

The output device must support graphics.

DESCRIPTION

The <ICON_FILE> tag specifies a graphics file that accompanies text within the <ICON> and <ENDICON> tags. The specified file should be a graphics file suitable for printing on the specified output device.

If you plan to process your file for more than a single destination, you can use multiple <ICON_FILE> tags to ensure that the appropriate icon will be included for the appropriate destination. An example of this coding is provided in the examples in the <ICON> tag description. If you use multiple <ICON_FILE> tags in this way, you should specify only a single <ICON_FILE> tag for all the monospaced destination keywords (MAIL, TERMINAL, or LINE).

Example

See the examples in the description of the <ICON> tag.

<ICON_TEXT>

Labels the text that accompanies a graphic image that you include with the <ICON_FILE> tag.

Format

<ICON_TEXT> (text [\WRAP])

ARGUMENTS

text

Specifies the text that accompanies the graphic. The text can be as long as you want and can include paragraphs and lists.

WRAP

This is an optional keyword argument. It specifies that the text wrap around the graphic if the text is longer than the graphic.

related tags

restrictions

Valid only in the context of an <ICON> tag.

If you use the WRAP argument, the text cannot contain any <LIST> or <P> tags.

DESCRIPTION

The <ICON_TEXT> tag labels the text that accompanies a graphic image that you include with the <ICON_FILE> tag. The text appears along the side of the icon or wraps around the icon if you specify the WRAP argument and the text is long enough.

Both the <ICON_TEXT> and <ICON_FILE> tags must occur in the context of the <ICON> and <END_ICON> tags.

Example

See the examples in the description of the <ICON> tag.

<INCLUDE>

Specifies the position in a document where you want to include a file for processing.

Format

<INCLUDE> (file spec)

ARGUMENTS

file spec

Specifies the file you want to include.

If you specify a logical name instead, and the source file is an element of a book, you can define the logical name using an <INCLUDES_FILE> tag in the profile of the book. If the source file is not an element of a book, or if the profile does not contain the <INCLUDES_FILE> tag, be sure to define the logical name before processing the file.

related tags

restrictions

Invalid in an argument to a tag.

In a file that contains a book element that you want to process through a bookbuild, make sure to place the book element tag (for example, <CHAPTER>) as the first tag in the file. Place the <INCLUDE> tag after the book element tag.

DESCRIPTION

The <INCLUDE> tag specifies the position in a document where you want to include a file for processing.

Example

The following example shows how to include a file that does the following: 

<INCLUDE>(doc_local_templates:boilerplate.sdml)

If you did not use the file specification doc_local_templates:boilerplate.sdml, but instead used a logical name, the logical name could be equated to the file specification by using the <INCLUDES_FILE> tag in the profile. See the example in the <INCLUDES_FILE> tag description.

<INCLUDES_FILE>

Equates a logical name with a file specification during processing of a profile.

Format

<INCLUDES_FILE> (logical name\file spec)

ARGUMENTS

logical name

Specifies the logical name for the included file. (You can use this name as the argument to an <INCLUDE> tag.)

file spec

Specifies the file specification into which the logical name translates.

related tags

restrictions

Valid only in the context of a <PROFILE> tag.

DESCRIPTION

The <INCLUDES_FILE> tag equates a logical name with a file specification during processing of a profile. You can place the <INCLUDES_FILE> tag in your profile to define a logical name for a file whose contents are included in one of your element files. The first argument to this tag is the logical name for the included file. (You use this name as the argument to the <INCLUDE> tag.) The second argument specifies the actual file specification into which the logical name translates.

You do not need to use the <INCLUDES_FILE> tag if either of the following is true:

The <INCLUDES_FILE> tags follow the <ELEMENT> tag for which they are needed. During a bookbuild, DECdocument establishes the logical name definition for each <INCLUDES_FILE> tag before it actually reads and processes the book element file names in the preceding <ELEMENT> tag. The logical name remains defined during the processing of later book elements.

When a book element is processed by itself (when you use the /PROFILE qualifier on the command line), DECdocument again establishes the logical name definitions that were specified by the <INCLUDES_FILE> tag in the profile.

Example

The following example shows how to use the <INCLUDES_FILE> tag to define a logical name for the file MY_VERY_LONG_TABLE.SDML, which is kept in the directory [mydirectory]. In the book element file ERROR_CHAP.SDML, you include the table with the <INCLUDE>(error_msg_tab) tag. 

<PROFILE>
   .
   .
   .
<ELEMENT>(error_chap.sdml)
<INCLUDES_FILE>(error_msg_tab\mydisk:[mydirectory]my_very_long_table.sdml)
   .
   .
   .
<ELEMENT>(tags_chap.sdml)
<ENDPROFILE>

<INDEX_FILE>

Specifies the position in a book or document where you want to include an index file in the output.

Format

<INDEX_FILE> [(file spec)]

ARGUMENTS

file spec

This is an optional argument. It specifies the name of the index file. Use this argument if you want to include an index file with a name other than the default file name.

The default file name is file spec_index.DVI_device. If you specify a file type, be sure that the device name matches the destination device you specify on the DOCUMENT command line. For example, if you specify file spec_index.DVI_PS, be sure you specify PS as the destination on the command line.

related tags

DESCRIPTION

The <INDEX_FILE> tag specifies the position in a book or document where you want to include an index file in the output. This tag does not produce an index, but instead indicates placement of the index file. An index file is produced when you specify the /INDEX qualifier on the DOCUMENT command line. See Command Summary and Processing Messages for information about using the /INDEX qualifier on the command line.

Using the <INDEX_FILE> tag is highly recommended (but not required) for Bookreader output, because an index is helpful for locating information in a book you create for Bookreader.

It is recommended that you place the <INDEX_FILE> tag in your profile. This ensures correct placement of the index in both printed and Bookreader output.

An index file always receives the file type .DVI _device, where device is the type of output device you specified on the DOCUMENT command line. To generate an index from an individual file that contains an <INDEX_FILE> tag, specify the /INDEX qualifier on the DOCUMENT command line.

If you specify the /INDEX qualifier on the DOCUMENT command line without using the <INDEX_FILE> tag in your profile, an index is generated separately from your document. For more information on generating an index, see Producing Online and Printed Documentation.

Example

See the index in this manual for a sample index. The <INDEX_FILE> tag is placed in the profile file after the last appendix file. See the <PROFILE> tag description for an example of an <INDEX_FILE> tag in a profile.

<INTERACTIVE>

Begins an example dialog between the user and system and enables the <S> and <U> tags to distinguish system text from user text.

Format

<INTERACTIVE> (code)


or

<INTERACTIVE> [(
  • [KEEP]\[WIDE]
  • \[MAXIMUM]]
)]

interactive code or text



.
.
.

<ENDINTERACTIVE>

ARGUMENTS

code

Specifies a code fragment you want to insert into your text.

If you do not specify this argument, you must use <ENDINTERACTIVE> as the terminating tag.

KEEP

This is an optional keyword argument. It specifies that the example is not to be broken across pages; that is, if the example does not fit on the current page, it will be placed on the next page. If the example itself does not fit on an entire single page of output, it will be broken anyway. This keyword has no effect for Bookreader output.

WIDE

This is an optional keyword argument. It specifies that the width of the example exceeds the document's default width for text, and, depending on the doctype, is interpreted as follows:

MAXIMUM

This is an optional keyword argument. It specifies that the text of the code example is adjusted to a smaller point size in order to fit within the boundaries of the left and right margins of the page. You can use this keyword in conjunction with WIDE to indicate that the example may require additional adjustment to fit within the boundaries of the page. You should use this keyword with discretion, and it may not be suitable in all doctypes.

Note
You can use the KEEP, WIDE, and MAXIMUM keywords together or separately and in any order in the argument list.

related tags

restrictions

You cannot use indexing tags (<X> and <Y> tags) in the context of an <INTERACTIVE> tag.

You cannot use tab characters to format interactive examples; use spaces instead.

You cannot use text element tags, such as <P>, <LIST>, or <NOTE>, in the context of an <INTERACTIVE> tag.

required terminator

<ENDINTERACTIVE> --- Required if you do not specify an argument to the <INTERACTIVE> tag.

DESCRIPTION

The <INTERACTIVE> tag begins an example dialog between the user and system and enables the <S> and <U> tags to distinguish system text from user text. If your interactive example is longer than a few lines, use the <VALID_BREAK> tag to indicate the acceptable points for a page break within that example.

Example

This example shows how to use the tags to create an interactive example. Note that you should specify whatever space follows the system prompt within the <S> tag. 

<P>If you do not specify the full command line, DCL will prompt 
you for the missing information. For example, if you do not specify an 
input file and an output file when you enter the COPY command, you will 
be prompted as follows: 
<INTERACTIVE>
<S>($ )<U>(COPY) 
<S>($_From: )<U>(INTERACT.SDML) 
<S>($_To: )<U>(NEWFILE.SDML) 
<ENDINTERACTIVE>

This example produces the following output:

If you do not specify the full command line, DCL will prompt you for the missing information. For example, if you do not specify an input file and an output file when you enter the COPY command, you will be prompted as follows: 


$ COPY
$_From: INTERACT.SDML
$_To: NEWFILE.SDML

<KEEP>

Specifies that a string of text should not be broken across a line of output.

Format

<KEEP> (text)

ARGUMENTS

text

Specifies the text string you want kept on the same line of output.

related tags

DESCRIPTION

The <KEEP> tag specifies that a string of text should not be broken across a line of output. Use this tag to specify a string of text you want kept on the same line of output.

Examples

In the following example, the file specification is specified as an argument to the <KEEP> tag so that it will not be broken across a line.
#1 

<P> 
The complete file specification is: <KEEP>(DISK$:[SMITH.TRIPS.EXPENSES]MILEAGE.TXT)

This example produces the following output:

The complete file specification is: DISK$:[SMITH.TRIPS.EXPENSES]MILEAGE.TXT

The following example defines a text element symbol name using an en dash and specifies that the line should not break between the en dash and the 11 when you refer to the symbol.

#2 

<define_symbol>(vax11\<delayed><keep>(vax--11)<enddelayed>)

You refer to the symbol with the <REFERENCE>(vax11) tag, which produces the following output:

VAX--11

<KEYWORD>

Labels a word that you want to distinguish typographically.

Format

<KEYWORD> (word)

ARGUMENTS

word

Specifies the word you want to distinguish.

related tags

DESCRIPTION

The <KEYWORD> tag labels a word that you want to distinguish typographically. The default action of the <KEYWORD> tag outputs the keyword in boldface. As formatted output, the <KEYWORD> tag may appear similar to the <EMPHASIS> tag with the BOLD argument. By using separate tags to label different kinds of information, however, you are free to change the format of any one kind of information without affecting the others.

What constitutes a keyword is something about which both editor and writer must agree. Use the <KEYWORD> tag consistently within a document and across a document set.

Example

The following example shows how to use the <KEYWORD> tag. 

<P>A <KEYWORD>(field) is a set of contiguous bytes in a logical record.

This example produces the following output:

A field is a set of contiguous bytes in a logical record.

<LANGUAGE>

Causes text that is automatically generated by DECdocument (such as "Example", "Figure", "Table", and so on) to be output in the language you specify. It also causes text to be hyphenated and index entries to be sorted according to the rules of the language you specify.

Format

<LANGUAGE> (
  • CANADIAN
  • DANISH
  • DUTCH
  • ENGLISH
  • FINNISH
  • FRENCH
  • GERMAN
  • ITALIAN
  • NORWEGIAN
  • PORTUGUESE
  • SPANISH
  • SWEDISH
)

ARGUMENTS

language-x

Specifies the language. English is the default language. Note that CANADIAN specifies the French Canadian language.

restrictions

You can use this tag only once in a file; subsequent occurrences of the tag are ignored.

You must place this tag at the beginning of your file or immediately after the <PROFILE> tag in a profile.

DESCRIPTION

The <LANGUAGE> tag causes text that is automatically generated by DECdocument (such as "Example", "Figure", "Table", and so on) to be output in the language you specify. It also causes text to be hyphenated and index entries to be sorted according to the rules of the language you specify.

To use the default foreign language text, use the <LANGUAGE> tag with the argument of your choice. You can change the default foreign language text as follows:

  1. To modify the output for individual use only, copy DOC$STANDARD_FORMATS:TEX$LANGUAGE_MODULES.TEX into a directory and define the logical name DOC$PERSONAL_FORMATS to point to that directory. For example: 


    $ DEFINE DOC$PERSONAL_FORMATS DISK1:[MYDIR]

    To modify the output for all users on the system, copy DOC$STANDARD_FORMATS:TEX$LANGUAGE_MODULES.TEX into a directory and define the logical name DOC$LOCAL_FORMATS to point to that directory.

  2. Edit this local copy of TEX$LANGUAGE_MODULES.TEX by uncommenting the line that inputs the language you want to change. In the following example, the line that inputs the Danish language file has been uncommented, so that a local copy of TEX$DANISH_MODULE.TEX will be used instead of the default version. 


    %\input doc$$dormats:tex$canadian_module.tex 
\input doc$$dormats:tex$danish_module.tex    % enables your Danish changes 
%\input doc$$dormats:tex$dutch_module.tex

  3. The text for the supported languages is contained in the following files. Copy the file you wish to change into a local directory and edit the file for local language changes.
    • TEX$CANADIAN_MODULE.TEX
    • TEX$DANISH_MODULE.TEX
    • TEX$DUTCH_MODULE.TEX
    • TEX$ENGLISH_MODULE.TEX
    • TEX$FINNISH_MODULE.TEX
    • TEX$FRENCH_MODULE.TEX
    • TEX$GERMAN_MODULE.TEX
    • TEX$ITALIAN_MODULE.TEX
    • TEX$NORWEGIAN_MODULE.TEX
    • TEX$PORTUGUESE_MODULE.TEX
    • TEX$SPANISH_MODULE.TEX
    • TEX$SWEDISH_MODULE.TEX
  4. You can modify any of the text strings by entering new text within the braces for a specific macro.

    The hyphenation patterns for the supported languages are contained in the file TEX$EXCEPTIONS.TEX. The default version of this file, which resides in DOC$STANDARD_FORMATS, is invoked when the text formatter begins processing. You can modify the hyphenation of any word as follows:

    • To change the hyphenation for individual use only, copy DOC$STANDARD_FORMATS:TEX$EXCEPTIONS.TEX into a directory, define the logical name DOC$PERSONAL_FORMATS to point to that directory, and edit the file.
    • To change the hyphenation for all users on the system, copy DOC$STANDARD_FORMATS:TEX$EXCEPTIONS.TEX into a directory, define the logical name DOC$LOCAL_FORMATS to point to that directory, and edit the file.

    DECdocument searches for a copy of TEX$LANGUAGE_MODULES.TEX and TEX$EXCEPTIONS.TEX in the order listed below, and uses the first copy of each file that it encounters:

    1. DOC$PERSONAL_FORMATS---for individual use
    2. DOC$LOCAL_FORMATS---for local use
    3. DOC$STANDARD_FORMATS---the default version

Examples

The following example shows how to code a file using the <LANGUAGE> tag.
#1 

<LANGUAGE>(FRENCH) 
<CHAPTER>(Le Tour De France) 
<P> La plus longue course de bicyclettes du monde a lieu en France chaque anneé au 
debút de l'été: c'est le Tour de France.

The following example is part of the English language section of TEX$EXCEPTIONS.TEX, to which you add the hyphenation exception in the format shown.

#2 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
% English 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
 
\gdef\ENGLexceptions{ 
\hyphenation{ 
as-so-ciate 
as-so-ciates 
dec-li-na-tion 
oblig-a-tory 
} 
}

Previous Next Contents Index