| Previous | Contents | Index |
The ONLINE doctype is for creating Bookreader documentation.
The ONLINE doctype has a dynamic design, in that it produces documentation that you see, not as printed copy, but as a screen display when you use Bookreader. In general, use the ONLINE keyword to process your documents for Bookreader. If you are creating an online manual, military specification, or software reference document, use MANUAL.ONLINE, MILSPEC.ONLINE, or SOFTWARE.ONLINE, respectively. For any of these doctypes, use the same tags described in this chapter. All of the online designs produce documentation in the default style of the specific doctype. For example, SOFTWARE.ONLINE produces documentation that looks like SOFTWARE.REFERENCE.
All online designs display an online document in a 5.9 x 6.6 -inch format with numbered headings and ragged right margin. These designs are solely for online display with Bookreader.
Online tags only function if you use Bookreader. Their presence in your documents is ignored when you process printed outputs. However, they are required to produce a Bookreader book.
Coding for online books does not differ much from coding for printed books, but presenting a book online creates a new set of visual considerations. Whether preparing existing SDML files for Bookreader or creating new SDML files, one of your primary concerns is the visual aspect of the finished book. You need to think about how the book will look when viewed with Bookreader.
For these reasons, the DECdocument documentation set includes
Producing Online and Printed Documentation. That guide is specifically written to help you prepare
documents for both printed and online versions.
8.1 ONLINE Doctype Tag Reference
This part of this chapter contains reference information on all the tags available in the ONLINE doctype.
Labels portions of a template that should not appear in the online help file.
<BOOK_ONLY>
None.
- <HELP_ONLY>
Used only in a reference template used to generate a help file.
<ENDBOOK_ONLY>
The <BOOK_ONLY> tag labels portions of a template that should not appear in the online help file. This tag affects only processing associated with the creation of a help file and does not affect the formatting of the text.
The following example shows how to use the <BOOK_ONLY> tag.
<OVERVIEW> Invokes the Librarian Utility to create, modify, or describe an object, macro, help, text, or shareable image library. <book_only> For a complete description of the Librarian Utility, including information about the LIBRARY command and its qualifiers, see the <tag>(reference>(VMS_UTILITIES_REF). <endbook_only <tag>(endoverview> |
This example shows how to use the<BOOK_ONLY> tag. The presence of the tag has no effect on the processing of the text unless you are producing a help file. If you are producing a help file, the text between the <BOOK_ONLY> and <ENDBOOK_ONLY> tags is deleted. When processed as a text file, this example produces the following output:
Invokes the Librarian Utility to create, modify, or describe an object, macro, help, text, or shareable image library.For a complete description of the Librarian Utility, including information about the LIBRARY command and its qualifiers, see the VMS_UTILITIES_REF.
Outputs a BOOK entry for a Bookreader bookshelf file.
<BOOK_REF> (symbol name\file spec)
symbol name
Specifies the symbol that is associated with the title of the book.Symbol names must not exceed 31 characters and must only include alphabetic letters, numbers, or underscores. Do not begin a symbol name with an underscore.
Define this symbol in either your source file or a symbol definition file (using the <DEFINE_BOOK_NAME> tag). If you define it in a symbol definition file, include it using the /SYMBOLS qualifier on the DOCUMENT command line.
file spec
Specifies the book file specification that points to the book_filename.DECW$BOOK file. The file type is not required; the default of .DECW$BOOK is assumed.
- <SHELF_CREATE>
- <SHELF_REF>
Valid only in the context of the <SHELF_CREATE> tag.
The <BOOK_REF> tag outputs a BOOK entry for a Bookreader bookshelf file. This entry is a pointer to an existing book file. Do not use the directory or file type information unless you are including books or shelves outside the directory where you are building the customized bookshelf file. This tag has no effect for printed ouput. See Producing Online and Printed Documentation for more information on building bookshelves.
See the example in the discussion of the <SHELF_CREATE> tag.
For Bookreader documentation, the <EXTENSION> tag highlights language extensions to standards or other information; it displays the extension text as slightly shaded.
<EXTENSION> [(text)]
or<EXTENSION>
text
.
.
.
<ENDEXTENSION>
text
Specifies short pieces of text (for example, single words, short phrases, or a sentence or two) for highlighting.
<ENDEXTENSION> ---Required if you do not provide an argument to the <EXTENSION> tag.
For Bookreader documentation, the <EXTENSION> tag highlights language extensions to standards or other information; it displays the extension text as slightly shaded. You can turn off the shading through the View menu on the text window. This tag has no effect for printed output.
The following example shows how to use the <EXTENSION> tag.
| #1 |
|---|
<P>This sentence contains one highlighted <EXTENSION>(word). |
This example produces the following online output:
This sentence contains one highlighted word.
The following example shows how to use the <EXTENSION> tag and the <ENDEXTENSION> tag for an extended piece of text.
| #2 |
|---|
<EXTENSION>
<P>By using certain tags,
you can highlight an entire paragraph. This feature is
useful for emphasizing a particular piece of information
in an online book.
<ENDEXTENSION>
|
This example of text produces the following online output:
By using certain tags, you can highlight an entire paragraph. This feature is useful for emphasizing a particular piece of information in an online book.
Be sure to code the <P> tag inside the <EXTENSION> tag or the first character in your paragraph is indented one space.
Changes any text into a hotspot for Bookreader documentation. For printed documentation, this tag generates the text you specify followed by a reference (in parentheses) to the section, chapter, or table, and so on.
<HOTSPOT> (symbol name [\text])
symbol name
Specifies the name of a symbol assigned in a text element tag (for example, <HEADN> or <TABLE>).The following tags require a symbol name for a book you create for Bookreader:
- <APPENDIX>
- <CHAPTER>
- <CHEAD>
- <EXAMPLE>
- <FIGURE>
- <HEAD>
- <HEADN>
- <PREFACE>
- <PREFACE_SECTION>
- <SUBHEADN>
- <TABLE>
- <COMMAND>
- <ROUTINE>
- <SDML_TAG>
- <SET_TEMPLATE_COMMAND>
- <SET_TEMPLATE_ROUTINE>
- <SET_TEMPLATE_STATEMENT>
- <SET_TEMPLATE_TAG>
- <STATEMENT>
- <SUBCOMMAND>
The first 11 tags are listed in Using Global Tags.
The following tags, listed in Using Global Tags, accept a symbol name, but do not require one, for both printed books and books you create for Bookreader:
- <FRONT_MATTER>
- <GLOSSARY>
- <PART>
- <MATH>
The following tags accept a symbol name for a printed book; the tags are ignored for books you create for Bookreader:
- <REF_NOTE>
- <SECTION>
Symbol names must not exceed 31 characters and must only include alphabetic letters, numbers, or underscores. Do not begin a symbol name with an underscore.
text
This is an optional argument. It specifies the text you want to use as the hotspot for Bookreader output. If you do not use this argument, the title of the Bookreader topic you are referring to is used as the hotspot.For printed output, the text you specify is generated followed by a reference (in parentheses) to the section, chapter, or table, and so on.
- <REFERENCE>
- <SET_ONLINE_TOPIC>
DESCRIPTION
The <HOTSPOT> tag changes any text into a hotspot for Bookreader documentation. For printed documentation, this tag generates the text you specify followed by a reference (in parentheses) to the section, chapter, or table, and so on.
EXAMPLES
The following example shows how to use the <HOTSPOT> tag with the optional text argument for books displayed by Bookreader:
#1
<HEAD1>(Introduction\intro) <P> The section <HOTSPOT>(cat_section\cats) discusses cats. . . . <HEAD1>(All About Cats\cat_section)This example produces the following Bookreader output:
The section []cats discusses cats.
The following example shows how to use the <HOTSPOT> tag without the optional text argument for books displayed by Bookreader:
#2
<HEAD1>(Introduction\intro) <P> The section <HOTSPOT>(cat_section) discusses cats. . . . <HEAD1>(All About Cats\cat_section)This example produces the following Bookreader output:
The section []All About Cats discusses cats.
The following example shows how to use the <HOTSPOT> tag with the optional text argument for printed books:
#3
<HEAD1>(Introduction\intro) <P> The section <HOTSPOT>(cat_section\cats) discusses cats. . . . <HEAD1>(All About Cats\cat_section)This example produces the following Bookreader output:
The section (see Section n.n) discusses cats.
The following example shows how to use the <HOTSPOT> tag without the optional text argument for printed books:
#4
<HEAD1>(Introduction\intro) <P> The section <HOTSPOT>(cat_section) discusses cats. . . . <HEAD1>(All About Cats\cat_section)This example produces the following Bookreader output:
The section []All About Cats (see Section n.n) discusses cats.
<HELP_ONLY>
Identifies text that you want to include only in Help output and not in printed or Bookreader output.
Syntax
<HELP_ONLY>
ARGUMENTS
None.
- <BOOK_ONLY>
- <SET_HELP_LEVEL>
<ENDHELP_ONLY>
The <HELP_ONLY> tag identifies text that you want to include only in Help output and not in printed or Bookreader output.
The following example shows how to use the <HELP_ONLY> tag.
<HELP_ONLY> <P>When RSX... <ENDHELP_ONLY> <P>When the operating system... <HELP_ONLY> <P>When RSTS... <ENDHELP_ONLY> |
This example shows how to code a file so that the text between the <HELP_ONLY> and <ENDHELP_ONLY> tags is included only in the Help (.HLP) file and not in printed or Bookreader output. In this case, the paragraphs that begin with "When RSX" and "When RSTS" would be included only in the .HLP file. The following paragraph would appear only in the printed or Bookreader output:
When the operating system...
Allows you to override the default multi-level Help output and keep the Help output at a single level. This tag affects only the <COMMAND> and <SUBCOMMAND> tags of the SOFTWARE doctype.
<KEEP_HELP_LEVEL>
None.
- <BOOK_ONLY>
- <HELP_ONLY>
- <SET_HELP_LEVEL>
<ENDKEEP_HELP_LEVEL>
The <KEEP_HELP_LEVEL> tag allows you to override the default multi-level Help output and keep the Help output at a single level. This tag affects only the <COMMAND> and <SUBCOMMAND> tags of the SOFTWARE doctype.Remember that each word in a command is a different Help level, by default. The <KEEP_HELP_LEVEL> tag concatenates all elements of its argument and places the entire argument at a single level. For example, if you have a command called SET TERMINAL and you do not want a Help file with SET at level-1 and TERMINAL at level-2, which is the default, but want both SET and TERMINAL at level-1, use the <KEEP_HELP_LEVEL> and <ENDKEEP_HELP_LEVEL> tags to enclose the command.
The following example shows how to use the <KEEP_HELP_LEVEL> tag.
<COMMAND_SECTION> <KEEP_HELP_LEVEL> <COMMAND>(SET TERMINAL) <ENDKEEP_HELP_LEVEL> . . . <COMMAND>(SET QUEUE) . . . <COMMAND>(SET PASSWORD) . . . <ENDCOMMAND_SECTION> |
This example shows how to use the <KEEP_HELP_LEVEL> and <ENDKEEP_HELP_LEVEL> tags to cause the enclosed command to be output as level-1 in the Help (.HLP) file. This example produces the following levels in the .HLP file:
1 SET_TERMINAL 1 SET 2 QUEUE 2 PASSWORD
For Bookreader documentation, the <LMF> tag marks the beginning of the tag sequence that specifies the License Management Facility (LMF) information for the document.
<LMF> (
)
- book symbol name
- multibook license identifier
book symbol name
Specifies the symbol name for the book, which you must define using the <DEFINE_BOOK_NAME> tag.multibook license identifier
Refers to a single set of LMF tags, which specify the licensing information for an entire documentation set or group of documents. This argument must match the argument to the <LMF_INFO> tag.
- <LMF_ALTNAME>
- <LMF_INFO>
- <LMF_PRODUCER>
- <LMF_PRODUCT>
- <LMF_RELEASE_DATE>
- <LMF_VERSION_NUMBER>
You can specify only one set of LMF tags per document.The <LMF> tag must precede the <LMF_INFO> tag.
<ENDLMF>
For Bookreader documentation, the <LMF> tag marks the beginning of the tag sequence that specifies the License Management Facility (LMF) information for the document. You can specify the LMF tags in any order between the <LMF> and <ENDLMF> tags. The <LMF> tag has no effect for printed output.The exact form of the LMF information is case- and punctuation-dependent. All the LMF information you supply as arguments to the LMF tags must match what exists in the LMF database.
To view books with the Bookreader, you must have installed at least one of the products specified in the <LMF_PRODUCT> and <LMF_ALTNAME> tags. Specify the primary product license in the <LMF_PRODUCT> field. Then, specify one or more alternate licenses for the book by using separate <LMF_ALTNAME> tags for each alternate product license.
You must specify all the LMF tags between the <LMF> and <ENDLMF> tags, except in the following cases:
- You must specify the <LMF_INFO> tag after the <LMF> tag, but the <LMF_INFO> tag does not have to fall within the <LMF> and <ENDLMF> tags.
- You do not have to specify the <LMF_ALTNAME> tag at all, although if you do not, you receive a warning-level message.
Make sure that if you do not have a specific release date and version number, you supply an empty field (that is, zero) to both the <LMF_RELEASE_DATE> and <LMF_VERSION_NUMBER> tags.
You can code the LMF tags in either the front matter file, the profile file, or in a symbols file that you process using the /SYMBOLS qualifier on the DOCUMENT command line. Consider storing the LMF tags in a central symbols file to make obtaining and updating the information easier.
The following example shows how to use the <LMF> tag in your front matter file.
| #1 |
|---|
<FRONT_MATTER>(front) <DEFINE_BOOK_NAME>(book_symbol\User's Guide) . . . <LMF>(book_symbol) <LMF_PRODUCER>(DEC) <LMF_PRODUCT>(VAX-VMS) <LMF_RELEASE_DATE>(30-June-1990) <LMF_VERSION_NUMBER>(V3.0) <LMF_ALTNAME>(FORTRAN) <LMF_ALTNAME>(PASCAL) <ENDLMF> <TITLE_PAGE> <LMF_INFO>(book_symbol) <TITLE>(User's Guide) . . . <ENDTITLE_PAGE> <ENDFRONT_MATTER> |
This example shows a complete set of LMF tags for a single document.
The following example shows how to use the <LMF> tag in a source file or in a symbols file.
| #2 |
|---|
Code in a symbols file: <DEFINE_BOOK_NAME>(his_book\User's Guide) <LMF>(many_books) <LMF_PRODUCER>(DEC) <LMF_PRODUCT>(FORTRAN) <LMF_VERSION_NUMBER>(0) <LMF_RELEASE_DATE>(0) <LMF_ALTNAME>(ANOTHER_NAME) <ENDLMF> Code in a source file: <FRONT_MATTER>(front) <TITLE_PAGE> <DEFINE_SYMBOL>(product_name\VAX FORTRAN) <TITLE>(User's Guide) <LMF_INFO>(many_books) <ORDER_NUMBER>(AA-12345-BC) <ellipsis> <ENDTITLE_PAGE> <ENDFRONT_MATTER> |
This example shows, for an entire documentation set or any group of documents, how to use the <LMF> and <LMF_INFO> tags to access the same set of LMF tags for all the documents. Notice that you can use a symbols file to list all the LMF information, and then use the <LMF_INFO> tag in your front matter file to access the licensing information from the symbols file.
| Previous | Next | Contents | Index |