DECdocument
DECdocument
Tutorial and
Application Guide


Previous Contents Index

A.4 Common Errors

There are some common types of errors that are often made when the SDML text file is created and/or edited. Here are some of the most common errors:


Appendix B
Tags and Doctypes - Other Manuals

This manual has shown you how to use many of the DECdocument tags to create several different document types that are printed and displayed. Some of the tags have additional features and can be used for other doctypes. Also, there are other global tags and doctype-specific tags that were not described at all. For example, there are special tags that are used when you create online documentation (documentation that can be viewed with Bookreader).

The following sections describe some of the manuals in the DECdocument documentation set and what information they contain.

B.1 Reference Manuals

There are three manuals that contain detailed information on the DECdocument tags and on the different doctypes that can be created. The manuals contain tag usage and document examples. These manuals are:

There are two manuals that are very helpful as reference guides. These manual are:

B.2 Graphics

If you are using the DECwindows Motif interface, you can use the Graphics Editor to create graphics for your documents. The manual:
contains information on how to use the Graphics Editor to create graphics and graphics files that can be incorporated into PostScript (PS) and Bookreader (DECW$BOOK) files.

You use the <FIGURE> and <ICON> tags to put graphics files into your documentation. The first four manuals listed above contain information on these tags.


Appendix C
User Notes

You can use these pages for notes.


Glossary

This glossary was taken, in part, from the Producing Online and Printed Documentation manual. Many of the terms in this glossary are used in this manual. Terms, not used, are listed for informational purposes.

Conventions

Terms that refer to other glossary entries are marked in the glossary definitions by italics.


argument: Additional processing information that you supply to an SDML tag. An SDML tag can have optional arguments, required arguments or no arguments. For example, in <LIST>(numbered), NUMBERED is the argument.

ARTICLE: The doctype keyword that you use to create articles. This doctype has one design that creates two-column documents.

bookbuild: The process of using DECdocument to build a book using a group of SDML files that are listed in a profile file. You must include each SDML file in the profile file using the <ELEMENT> tag. See also book element.

book element: A major section of a document marked by an SDML tag, such as the <CHAPTER> or <FRONT_MATTER> tag. A book element is a chapter, a part, or some other major element whose contents are contained in a single SDML file. You specify this SDML file as an argument to the <ELEMENT> tag in a profile file you use to do a bookbuild.

Bookreader: An online information access tool. DECdocument allows you to create online documents that can be read with Bookreader. Bookreader is also the DOCUMENT command line destination for processing a file for Bookreader.

Bookreader library: A repository of online books (with DECW$BOOK file types) within a bookshelf (where the books have a DECW$BOOKSHELF file type). You open the bookshelf to locate an online book to read.

bookshelf: Repository of individual online books that you can read within the Bookreader library.

command template: A template available in the SOFTWARE doctype for documenting commands.

conditionalized SDML file: A single SDML file that you code to process source material, based on a condition keyword that you specify either as an argument to the /CONDITION qualifier or as an argument to the <SET_CONDITION> tag. Conditionalized text and tags in the SDML file begin with the <CONDITION> tag and end with the <ENDCONDITION> tag.

context-sensitive tag: An SDML tag that is valid only within the context of other SDML tags; for example, the <TABLE_ROW> tag is only valid within the context of the <TABLE> tag (between the <TABLE> and <ENDTABLE> tags). Using context-sensitive tags outside their context results in DECdocument processing errors.

cross-reference file: A file that contains a list of the symbol names used in the SDML files during a bookbuild. The cross-reference file is automatically generated during a bookbuild and is given the same file name as the input file specified on the command line, but with a file type of XREF.

design: A specialized form of a doctype. You specify the design keyword immediately after the doctype keyword and separate it by a period (.); for example, SOFTWARE.REFERENCE and MANUAL.GUIDE.

destination: The keyword that you enter on the command line that specifies the output device; for example, PS, TERM or MAIL.

device converter: The DECdocument processor that converts a file created by the DECdocument text formatter into a file to be output on a specified destination device, such as the PostScript printer.

device converter input file: A file created by the DECdocument text formatter to be processed by the device converter. This file is the default input file when you process a document with the /NOTAG_TRANSLATOR and /NOTEXT_FORMATTER qualifiers on the command line.

doctype: The keyword you enter on the command line to specify the type of document you want to create; for example, a letter, a software manual or an article. A doctype can have several different designs contained within it; if so, you specify a design as a keyword following the doctype keyword and separate it from the doctype keyword by a period (.).

doctype-independent tag: See global tag.

doctype-specific tag: An SDML tag that is valid for a single DECdocument doctype; for example, the <SALUTATION> tag in the LETTER doctype. Tags that are available in all doctypes, such as the <LIST> tag, are referred to as doctype-independent tags or global tags.

element: See book element.

element build: A bookbuild in which only one book element from the profile is processed.

file type: A term that distinguishes one type of file from another and comes after the period (.) in a file specification; for example, the SDML file that you create has the file type SDML, and the file that the tag translator creates has the file type TEX.

fill: Making all lines (consisting of characters and spaces) equal length in a given area, such as a paragraph.

float: Indicates that if there is not enough room on the current page for an example or figure, the text processor will fill the current page with the text from the source file that follows the <EXAMPLE> or <FIGURE> tag sequence and place the example or figure at the top of the next page of output.

footer: A string of text that runs along the bottom of a page, sometimes referred to as a running foot.

formal example: An example with a caption and a number that is listed in the table of contents and that can be cross-referenced with the <REFERENCE> tag.

formal figure: A figure with a caption and a number that is listed in the table of contents, and that can be referenced with the <REFERENCE> tag.

formal table: A table with a caption and a number that is listed in the table of contents, and that can be referenced with the <REFERENCE> tag.

GENERAL: The doctype keyword that you can use to create 8.5 X 11 inch format manuals and books and miscellaneous output.

global tag: An SDML tag that is available in all the DECdocument doctypes; for example, the <LIST> tag. Tags that are restricted to a single doctype are referred to as doctype-specific tags.

informal example: An example without a number and a caption, that is not listed in the table of contents and that cannot be cross-referenced.

informal figure: A figure without a number and a caption, that is not listed in the table of contents and that cannot be cross-referenced.

informal table: A table without a caption, without a number and that is not listed in the table of contents.

input file specification: The file specification you enter on the command line. This file can be an SDML file, a text formatter input file, a device converter input file or a printable file.

intermediate file: A file produced during the middle stages of DECdocument processing. Typically, intermediate files are deleted at the end of DECdocument processing; however, you can use the /KEEP qualifier on the command line to specify that such files be retained.

justified text: Text aligned against both the right and left margins.

keyword: A word in the DCL command line that specifies one element of the DECdocument command syntax. Unlike the keyword argument, you can truncate a keyword to save keystrokes. For example, to use the doctype keyword SOFTWARE.POCKET_REFERENCE, you can enter SOF.POC.

keyword argument: An SDML tag argument that you must spell exactly as shown (case is not important).

left-justified text: Text aligned against the left margin.

LETTER: The doctype keyword that you use to create both letters and memorandums.

listing file: A text file containing information about DECdocument processing that is produced when you specify the /LIST qualifier on the command line. This file has the file name of the input file specified on the command line and a default file type of LIS.

MANUAL: The doctype keyword that you use to create 7 X 9 inch format and 8.5 X 11 inch format books. This doctype has four designs for producing books: MANUAL.GUIDE, MANUAL.PRIMER, MANUAL.REFERENCE and MANUAL.ONLINE.

map file: A text file containing an ordered list of the files processed by the tag translator that is produced when you specify the /MAP qualifier on the command line. This file has the file name of the input file specified on the command line and a default file type of MAP_LIS.

markup language: A page description language that you use to "markup" text elements in an input file for processing by a document processor. SDML is the markup language used by DECdocument.

master index: An index that is created from the indexes of two or more related books. DECdocument creates a master index when you specify the /MASTER_INDEX qualifier on the command line. You can only create a master index for a printed book.

MILSPEC: The doctype keyword that you use to create military documents that conform to MIL-STD-490A or U.S. Department of Defense Data Item Descriptions that conform to DOD-STD-2167 and DOD-STD-2167A. This doctype has three designs: MILSPEC.SECURITY, for producing military documents with security classifications; MILSPEC.DRAFT, for producing double-spaced draft documents; and MILSPEC.ONLINE for producing military documentations to be displayed by Bookreader.

nested list: A list embedded within another list. The <LIST> tag and its argument(s) begins the nested list after any <LE> tag of the outer list.

nested table: A table embedded within another table and beginning with its own <TABLE> tag.

ONLINE: The doctype keyword that you use to create text that is readable on your screen. This doctype has these designs: MANUAL.ONLINE, SOFTWARE.ONLINE, MILSPEC.ONLINE and ONLINE_BOOKSHELF.

online chunk: The smallest unit of information that Bookreader can access from the table of contents, the index or other sections that take a symbol name.

online topic: A collection of chunks of information that Bookreader can access.

OVERHEADS: The doctype keyword that you use to create pages with large, bold text that copies well and is easy to see. From these you make slides for either overhead projectors or 35mm projectors.

printable file: A file that has been successfully processed by the device converter for a particular output device; for example, a file with the extension .PS is a printable file formatted for the PostScript printer.

profile file: The file that controls the bookbuilding process. This file lists each of the SDML files included in the bookbuild as arguments to <ELEMENT> tags.

REPORT: The doctype keyword that you use to create general-purpose documents, such as reports and formal outlines. This doctype has two designs for one or two-column printing: REPORT, REPORT.TWOCOL.

right-justified text: Text aligned against the right margin.

SDML: Abbreviation for the Standard Digital Markup Language, the generic markup language used to mark up or "tag" text elements in an SDML file. See also SDML tag.

SDML file: A user-created text file that is marked up with SDML tags for processing by DECdocument. This file is the default input file for DECdocument and has a default file type of SDML.

SDML tag: The basic component of the SDML language that is used to identify text elements in the SDML file. Tags are words or abbreviations enclosed in angle brackets (<>), for example, <TABLE> and <LIST>.

SOFTWARE: The doctype keyword and doctype that you use to document software. This doctype has seven designs for documentation ranging from advertising brochures and small pocket guides to large reference manuals. These designs are SOFTWARE.BROCHURE, SOFTWARE.GUIDE, SOFTWARE.HANDBOOK, SOFTWARE.POCKET_REFERENCE, SOFTWARE.REFERENCE (the default doctype), SOFTWARE.SPECIFICATION and SOFTWARE.ONLINE.

source file: Any file used as input into one of the four stages of DECdocument processing. To avoid confusion, the term "source file" is not used in the DECdocument documentation; instead, each type of DECdocument source file is given a specific name: SDML file, text formatter input file, device converter input file or printable file.

subelement: An individual file that is part of a book element.

subelement build: A bookbuild in which only a single file that is included into a book element is processed.

symbol name: The name you assign to a text element that you use to cross-reference manual titles, chapters, sections, tables, figures and examples within a single manual or among several manuals. Symbol names are stored in the cross-reference file.

tag: See SDML Tag.

tag translator: The DECdocument processor that translates an SDML file containing text and tags into an input file for the text formatter.

terminating tag: A tag that you must use to close the context of a tag; for example, <LIST> requires <ENDLIST> as the terminating tag.

text element: Individually treated portions of text identified by SDML tags in an SDML file. Examples of text elements and the SDML tags that identify them are chapters (<CHAPTER>), lists (<LIST>), tables (<TABLE>), examples (<EXAMPLE>), figures (<FIGURE>), paragraphs (<P>) and first-level headings (<HEAD1>).

text formatter: The DECdocument processor that formats a text formatter input file into a device converter input file.

text formatter input file: A file created by the DECdocument tag translator as an input file for the text formatter. This file is the default input file when you process a document with the /NOTAG_TRANSLATOR qualifier on the command line.

topic: See online topic.

topic window: A window provided by Bookreader that displays the books and shelves of books that you can open and read.


Index Contents