Digital PDFs

XX-F1DE5-BC

December 2000

24 pages

Original

0.4MB

Document:	Document An In-House Technical Documentation System
Order Number:	XX-F1DE5-BC
Revision:
Pages:	24
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/vax_document/dec_internal/Document_An_In-House_Technical_Documentation_System.pdf

OCR Text

DOCUMENT
AN IN-HOUSE
TECHNICAL DOCUMENTATION SYSTEM

DOCUMENTATION PRODUCTION
FOUR MAIN GROUPS ARE INVOLVED
• WRITERS
• PRODUCTION PERSONNEL
• EDITORS
• READERS
EACH GROUP HAS A SET OF OBJECTIVES
A SUCCESSFUL DOCUMENTATION PRODUCTION SYSTEM
MUST MEET THOSE OBJECTIVES

DOCUMENTATION PRODUCTION
OBJECTIVES OF THE READER
·• ACCURATE AND COMP~ETE
• EASY TO READ (TYPOGRAPHICALLY)
-·FONTS
- WHITE SPACE
• EASY TO FIND INFORMATION
- SPATIAL ORGANIZATION (A.K.A. FORMATTING)
- INDEX, TOC, ACCURATE XREFS, EXAMPLES,
TABLES, FIGURES

DOCUMENTATION PRODUCTION
OBJECTIVES OF THE WRITER
• EASY TO ENTER INFORMATION
• ACCURATE & TIMELY FEEDBACK AS TO FORMAT
• EASY TO INCORPORATE CONTENT CHANGES
• EASY TO MAINTAIN (2ND, 3RD GENERATION
UPDATES)
• AUTOMATION OF TEDIOUS TASKS

- INDEX
-

TOC
XREF GENERATION

DOCUMENTATION PRODUCTION.
OBJECTIVES OF THE PRODUCTION GROUP
• QUICK TURNAROUND
• STREAMLINED, WELL-DEFINED PRODUCTION
PROCESS
• EASY TO ACCOMMODATE WRITERS' /EDITORS'
FORMATIING REQS.
• WELL DEFINED, DOCUMENTED FORMATS
·• EASY TO INCORPORATE LAST MINUTE CONTENT
CHANGES
• AUTOMATION OF TEDIOUS TASKS
- PAGINATION
- PASTING IN RUNNING HEADS, FEET

- ART
-

PAGE NUMBERING

DOCUMENTATION PRODUCTION
OBJECTIVES OF THE EDITOR
• ACCURATE & TIMELY FEEDBACK AS TO FORMAT
• QUICK TURNAROUND IN PRODUCTION
• OUTPUT SHOULD BE HIGH QUALITY AND APTLY
FORMATTED
• INFORMATION SHOULD BE WELL ORGANIZED

DOCUMENTATION PRODUCTION
HISTORICAL PROBLEMS
• OUTPUT QUALITY NOT. STATE-OF-THE-ART
• FORMATTING LANGUAGES DIFFICULT TO LEARN
AND USE
• CENTRALIZED MAINTENANCE OF FILES
CUMBERSOME
• TRACKING OF DOCUMENTS (AMONG WRITERS,
EDITORS, PRODUCTION GROUP) INEFFICIENT

DOCUMENTATION PRODUCTION
HISTORICAL PROBLEMS
•

FORMAT CONSISTENCY DIFFICULT TO ENFORCE

•

ACCOMMODATING NEW OR COMPLEX
FORMATS NOT EASY

·•

FINAL PRODUCTION TIME-CONSUMING:
-

MANUAL PAGINATION

MANUAL PASTE-UP OF TABLES AND EXAMPLES

MANUAL INDEXING

DOCUMENT:
THE SOLUTION
MAJOR COMPONENTS OF lHE SYSTEM
•

SDML

•

TEXMAC

• TeX
•

CMS/DOC

SDML
THE SOFTWARE DOCUMENTATION MARKUP LANGUAGE
• HIGH-LEVEL, STRUCTURALLY ORIENTED "TAGS"
• GLOBAL TAGS FOR GENERAL USE

•

<TABLE>
<CCl>EXAJIPLE>

<BEAD2>

<ILIST>

<ULIST>

<TWOCDIJ.IST>

TEMPLATES FOR RIGIDLY STRUCTURED ELEMENTS

<VMS_ROUTINE>(name\full-name)
<ROUTINE_TYPE>(keyword)
<OVERVIEW>

<comment>(SYS, RMS, RTL, etc.)
<comment>{Overview paragraph)

<ENDOVERVIEW>
<FORMAT>
<FORMAT>{routine\args, ••• )
<FRTN>{routine) <FARGS>{argl, arg2, arg3, ••• )
<JSB ENTRIES>
<JSB>{name)

<co:mment>(Optional section)

<ENDFORMAT>
<RETURNS>(vms-usage\type\access\mechanism[\additional-info])
<RETTEXT>
<comment>(Text optional)
<ENDRETTEXT>
<comment>(Required only if <rettext> is specified)
<ARGDEFLIST>

<co:mment>(Argument definition list)

<ARGITEM>(name\vms-usage\type\access\mechanism[\additional-info])
<ARGDEF>Description of argument •••
<ARGI TEM> { •••
<ARGDEF>

<comment>(repeat for each argument)

<comment>(Description of routine)

<co:mment>(Return status definition list)

<RSDEFLIST>
<RSITEM>{status\meaning)

<comment>(Repeat for each possible status)

<RSITEM>{\)
<ENDRSDEFLIST>
<EXAMPLES>[(EXAMPLE)]
<EXC>

<EXI>

<comment>(Numbered examples)

Run-Time Library Routines
LIBSBBCCI

LIB$BBCCl-Test and Clear Bit vvith
Interlock
·
UBSBBCCI tests and clears a selected bit under memory interlock.
UBSBBCCI makes the VAX BBCCI instruction available as a callable
procedure.

FORMAT

LIBSBBCCI position ,base

RETURNS

VMS Usage:
type:
access:
mechenism:

longword_.j,nalgnecl
aligned bit string
write only
by value

State of the bit before it wu cleared by UBSBBCC; 1 if the bit wu previously
set and 0 if the bit was pnviously dear.

ARGUMENTS position
VMS U•ge: longworcLaigned
longword Integer (signed)
access:
r•d only
mechanism: by reference
Bit position, relative to baae, of the bit which UBSBBCCI tests and dean.
The position argument is the address of a signed longword integer containing
the bit position. A position of zero denotes the low-order bit of the byte bue.
The bit position is equal to the offset of the bit chosen &om the base position.
This offset may span the entire range of a signed longwmd integer; negative
offsets access bits in lower-addressed bytes.

type:

base
VMS Usage: addr- .
type:
unspecified
access:
read only
mechanism: by reference
Byte containing bit zero of the field that UBSBBCCI
The base
argument is the address of the bue position. The bit that LIBSBBCCI tests
and dean is position bits offset from the low bit of bale.

referenm.

DESCRIPTION The single bit spedfied by position and baR is tested, the previous state of

the bit remembered, and the bit cleared The reading of the state of the bit
and its clearing are interlocked against similar operations by other processors
or devices in the system. The remembered previous state of the bit is then
returned as the function value of UB$BBCCI.
For more information, see the VAX-11 Architectllre Reference Maniull.

Rn-1

SDML
TEMPLATES
• ENSURE FORMAT CONSISTENCY AMONG
DOCUMENTS IN THE SAME FAMILY
• ENSURE THAT ALL REQUIRED/RELEVANT
INFORMATION IS PRESENT
• SPECIFIC PIECES OF INFORMATION ARE IN
KNO.WN PLACES AND CAN BE EASILY EXTRACTED
(E.G. HELP FILES, COMMAND SUMMARIES, QUICK
REFERENCE GUIDES)

TEXMAC
•
•

READS SDML-CODED FILE
LOOKS TAGS UP IN A. "DEFINITION FILE";
REPLACES EACH TAG WITH FORMATTING
COMMANDS. FOR EXAMPLE:
<DEFIIE>(P:
\paragraph)

•

USING DIFFERENT DEFINITION FILES ENABLES
US TO PRODUCE OUTPUT FOR DIFFERENT TEXT
PROCESSING PROGRAMS. FOR EXAMPLE, A
DSRPLUS DEFINITION FILE MIGHT CONTAIN:
. <DEFINE> (P:

.b;)

Te<
•

FORMATS INPUT TEXT INTO LINES, PARAGRAPHS,
AND PAGES
.
• MACRO PACKAGE DEVELOPED FOR SOFTWARE
DOCUMENTATION NEEDS
• FORMAT VARIES DEPENDING ON BOOK DESIGN
(DOCTYPE). OUTPUT DEVICE
• PRODUCES OUTPUT FOR THESE DEVICES:
- AUTOLOGIC MICROS TYPESETTER
- LNO 1 LASER PRINTER
- LINE PRINTER
- VT 100, VT200 TERMINALS
- . LN03 LASER PRINTER

CMS/DOC
ULIBRARIAN" SYSTEM
• SUBSET OF DEC/CMS
• WRITER PUTS SOURCE FILES INTO LIBRARY
• RESTRICTS ACCESS TO SOURCE FILES
• PREVENTS PARALLEL DEVELOPMENT OF SOURCE
FILES
• TRACKS HISTORY OF DEVELOPMENT OF SOURCE·
FILES

DOCUMENT:
THE SOLUTION TO OUR PROBLEMS
FEATURES OF THE SYSTEM ·
• HIGH-QUALITY OUTPUT
• FORMATTED DRAFT COPY AVAILABLE EARLY IN
PRODUCTION CYCLE
• DISTRIBUTED MAINTENANCE OF FILES
• WRITERS SHIELDED FROM DETAILS OF
FORMATTING
• FORMAT CONSISTENCY WITHIN AND ACROSS
BOOKS
• ABILITY TO ADD NEW, SOPHISTICATED FORMATS

DOCUMENT
FEATURES OF THE SYSTEM
• SOFTWARE FOR TRACKING SOURCE FILES
• ENGLISH-LIKE, STRUCTURALLY ORIENTED TAGS
• SOURCE FILES ARE DEVICE INDEPENDENT
·• SOURCE FILES ARE FORMAT INDEPENDENT
• ABILITY TO PROCESS COMPLEX TABLES AND
EXAMPLES

<doctype>(manual)
<def ine>(exam chap\l)
<define>(list-chap\2}
<define>(typog chap\3}
<define>(fig cnap\4)
<def ine>(noti chap\5)
<def ine>(numx-chap\6)
<define>(specials chap\7)
<define>(pqdeflist chap\8)
<define>(table chap\9)
<def ine>(msg_apx\A)
<define>(ADMIN GUIDE\Administrator's Guide)
<define>(SDML PRIM\Getting Started with SDML)
<define>(SI»IL:UG\SDML User's Guide)
<chapter>(<note chap>\Notes and Footnotes)
<comment>********************************************************
Testing forms of the NOTE tag •.
*********************************************************<endcomment>
This chapter illustrates the <tag>(NO'!'E), <tag>(NOTES),
and <tag>(FOOTNOTE) tags.
<include>(text.dat)
<Headl>(Vanilla Notes)
The first note includes a list.
<note>The CROSS directive has these attributes:
<NLIST><LE>CROSS without a symbol list will not reenable the cross-reference
listing of a symbol specified in .NOCROSS with a symbol list.
<LE>If the cross-reference listing of all symbols is disabled, .CROSS
with a symbol list will have no effect until the cross-reference listing
is reenabled by .CROSS without a symbol list.
<ELS>
<ENDNOTE>
<include>(text.dat)
A long note, with a table in it:
<note>
-This is a branch instruction. The groups:
<nlist>
<le>Overf low and carry group
<twocollist>(5)
<twocols>(BVS\V EQL 1)
<twocols>(BVC\V EQL 0)
<twocols>(VCS\C EQL l)
<ENDtwocollist>
<le>Unsigned group:
<twocollist>(7)
<twocols>(BLSSU\C EQL 1)
<twocols>(BLEQU\{C OR Z} EQL 1)
<endtwocollist>
<ELS>
Here is an additional paragraph inside this note with more text.
<endnote>

Notes and Footnotes

This chapter illustrates the < NOTE> I < NOTES> I and
< FOOTNOTE> tags.

Flashy designs are inappropriate for software manuals or for
any serious or formal boob because they do not reflect the
intention of the writer. The purpose of any book design is
to clarify what the author is conveying, to translate the text
attractively as print on a page, to communicate the message
visually in harmony with the ideas.

5. 1

Vanilla Notes
The first note includes a list.

Note: The CROSS directive hu these attributes:
1 CROSS without a symbol list will not reenable the croureference listing of a symbol specified in .NOCROSS
with a symbol lilt.
2 If the crou-reference listing of all 1ymbols ii disabledr
.CROSS with a symbol list will have no effect until the
crose-reference listing is reenabled by .CROSS without a
symbol list.
Flashy designs are inappropriate for software manuals or for
any serious or formal boob because they do not reflect the
intention of the writer. The purpose of any book design is
to clarify what the author is conveying, to translate the text
attractively as print on a page, to communicate the message
visually in harmony with the ideas.
A long note, with a table in it

Note: Thia ii a branch instmction. The groups:

5-1

Chapter 5
Notes and Footnotes
This chapter illustrates the < NOTE> , < NOTES> , and < POOTNOTI!> tags.

Flashy designs are inappropriate for software manuals or for any serious

or formal books because they do not reflect the intention of the writer.
The purpose of any book design is to darlfy what the author is conveying,
to translate the text attractively as print on a page, to communicate the
message visually in harmony with the ideas.

5. 1 Vanilla Notes
The first note includes a list.
Note
The CROSS ditective has these attributes:
1. CROSS without a symbol list will not reenable
the cros&-reference listing of a symbol specified in
.NOCROSS with a symbol list.
2. If the aoss--reference listing of all symbols is disabled,
.CROSS with a symbol list will have no effect until the
cross-reference listing is reenabled by .CROSS without
a symbol list.

Notes and Footnotes 5-l

Chapter 5

Notes and Footnotes
This chapter illustrates the < NOTE> , <NOTES> , and < POOTNOTE> tags.

Flashy designs are inappropriate for software manuals. or for any serious
or formal books because they do not reflect the intention of the writer.
The purpose of any book design is to clarify what the author is conveying,
to translate the text attractively as print on a page, to communicate the
message visually in harmony with the ideas.

5.1

v••• Iotas
The first note includes a list.

NOTE
The CROSS directive has these attributes:
1. CROSS without a symbol list will not reenable the aossreference listing of a symbol specified in .NOCROSS with a
symbol list.
2. If the aoss-reference listing of all symbols is disabled,
.CR.OSS with a symbol list will have no effect until the
cross-reference listing is teenabled by .CROSS without a
symbol list.
' .
Flashy designs are inappropriate for software manuals or for any serious
or formal books because they do not reflect the intention of the writer.
The purpose of any book design is to clarify what the author is conveying,
to translate the text attractively as print on a page, to communicate the
message visually in harmony with the ideas.

DOCUMENT
AUTOMATED FEATURES OF THE SYSTEM
• PAGINATION
.
• SOPHISTICATED HYPHENATION
• KERNING, LIGATURES, MATH SYMBOLS
• INDEX AND TOC GENERATION
• RUNNING HEADS AND FOLIOS
• HEADING AND SECTION NUMBERING
• OUTLINE GENERATION

DOCUMENT
PRESENT DEVELOPMENT PLANS
• INTEGRATION OF TEXT AND GRAPHICS
• LSE INTERFACE
• PREVIEW TERMINAL
• ON-LINE DOCUMENTATION