| Previous | Contents | Index |
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:
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:
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.
You can use these pages for notes.
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.
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 |