DECdocument
Producing Online and
Printed Documentation
Previous Contents Index

13.5.2 Processing the Online Booklet

To process the booklet to be displayed by Bookreader, enter the following command: 


 
    $ DOCUMENT exercise_profile MANUAL.ONLINE BOOKREADER /BATCH /CONTENTS /INDEX

The formatted output for the booklet includes the table of contents and the index in the correct locations in the output.

For information on how to view the booklet through Bookreader, see Section 11.5.

13.6 Copying the Processed Booklet

If you want to copy the output files of the already-processed booklet, use the following commands, then refer to Section 13.5 to print or view the booklet. 


 
    $ COPY DOC$ROOT:[EXAMPLES]EXERCISE_PROFILE.PS */LOG 
    $ COPY DOC$ROOT:[EXAMPLES]EXERCISE_PROFILE.DECW$BOOK */LOG 
    $ COPY DOC$ROOT:[EXAMPLES]EXERCISE_PROFILE.DECW$BOOKSHELF */LOG

Appendix A
Using LSE with DECdocument

This appendix provides an overview of the extensions of DECdocument for use with an optional productivity tool, the VAX Language-Sensitive Editor (LSE). This tool is not included with the DECdocument software; you must purchase it separately. Using LSE can increase your productivity as a DECdocument user. The LSE extensions of DECdocument support the tags and Data Item Descriptions in the MILSPEC.SECURITY and the MILSPEC.DRAFT docytpes. For information on how to purchase LSE, contact your DIGITAL sales representative.

In order to use LSE with DECdocument, you must have the following installed on your system¹:

Note

¹ See your system manager.

A.1 Using LSE with DECdocument

The VAX Language-Sensitive Editor (LSE) is a powerful and flexible text editor designed specifically for software development. LSE has important features that help you produce syntactically correct SDML markup in DECdocument.

To invoke LSE, issue the LSEDIT command followed by a file name with a SDML file type at the DCL prompt. For example: 


    $ LSEDIT USER.SDML

The following sections describe some of the key features of LSE. Section Section A.1.1 discusses how to enter source code using LSE and Section A.1.2 describes LSE's compiler interface features. Section A.1.3 gives examples of how to generate DECdocument source code with LSE.

For more details on advanced features of LSE, see the Guide to VAX Language-Sensitive Editor and VAX Source Code Analyzer.

A.1.1 Entering Source Code Using Tokens and Placeholders

LSE simplifies the tasks of developing and maintaining documents. LSE provides the functions of a traditional text editor, plus additional powerful features: language-specific placeholders and tokens, aliases, and compile and review features.

Placeholders are markers in the source code that indicate locations where you can provide text. Placeholders help you to supply the appropriate syntax in a given context. Generally, you do not need to type placeholders; they are inserted for you by LSE.

Placeholders are either optional or required. Required placeholders, which are delimited by braces ({}), represent places in the source code where you must provide text. Optional placeholders, which are delimited by brackets ([]), represent places in the source code where you can either provide additional constructs or delete the placeholder.

There are three types of LSE placeholders.
Type of Placeholder Description
Terminal Provides text that describes valid replacements for the placeholder
Nonterminal Expands into additional language constructs
Menu Provides a list of options corresponding to the placeholder

You can move forward or backward from placeholder to placeholder. In addition, you can delete or expand placeholders as needed. Section A.1.3 shows examples of expanding placeholders.

Tokens typically represent each tag in DECdocument. When expanded, tokens provide the complete syntax of a tag. You can type tokens directly into the buffer. Generally, you use tokens when you want to add a tag and there are no placeholders in an existing program. For example, typing COM and issuing the EXPAND command causes the tags for a comment to appear on your screen. You can also use tokens to bypass long menus in cases where expanding a placeholder, such as [element-or-template], would result in a lengthy menu.

You can use tokens to insert text when editing an existing file by typing the name for a function or keyword and issuing the EXPAND command.

LSE commands let you manipulate tokens and placeholders. These commands and their default key sequence are shown in Table A-1.

Table A-1 LSE Commands for Tokens and Placeholders
Command Key Sequence Function
EXPAND CTRL/E Expands a placeholder or token
UNEXPAND PF1-CTRL/E Reverses the effect of the most recent placeholder expansion
GOTO PLACEHOLDER/FORWARD CTRL/N Moves the cursor to the next placeholder
GOTO PLACEHOLDER/REVERSE CTRL/P Moves the cursor to the previous placeholder
ERASE PLACEHOLDER/FORWARD CTRL/K Erases a placeholder
UNERASE PLACEHOLDER PF1-CTRL/K Restores the most recently erased placeholder
None Down arrow Moves the indicator down through a menu
None Up arrow Moves the indicator up through a menu
None
  • ENTER
  • RETURN
Selects a menu option

You can display a list of all defined tokens and placeholders, or a particular token or placeholder, with the LSE commands SHOW TOKEN and SHOW PLACEHOLDER.

To copy the listed information into a separate file, first issue the appropriate SHOW command to put the list into the $SHOW buffer. Then issue the following commands: 


    LSE> GOTO BUFFER $SHOW 
    LSE> WRITE filename
To obtain a hard copy of the list, use the PRINT command at the DCL prompt to print the file you created.

A.1.2 Compiling Source Code

To compile your code and review compilation errors without leaving the editing session, you can use the LSE commands COMPILE and REVIEW. The COMPILE command issues a DCL command in a subprocess to invoke the DECdocument tag translator. The compiler then generates a file of compile-time diagnostic information that LSE can use to review compilation errors. The diagnostic information is generated with the /DIAGNOSTICS qualifier that LSE appends to the compilation command.

For example, to issue the COMPILE command while in the buffer USER.SDML, use the following command: 


    COMPILE $ doctype destination
The doctype and destination are any valid DECdocument keywords. When you issue the COMPILE command, the following DCL command executes: 


    $ DOCUMENT USER.SDML/DIAGNOSTICS=USER.DIA doctype destination
LSE supports all of DECdocument's command qualifiers.

The REVIEW command displays any diagnostic messages that result from a compilation. LSE displays the compilation errors in one window and the corresponding source code in a second window, so that you can review your errors while examining the associated source code. This capability eliminates tedious steps in the error correction process and helps ensure that all the errors are fixed before you recompile your program.

LSE provides several commands to help you review errors and examine your source code. These commands, and their default key sequence where applicable, are shown in Table A-2.

Table A-2 LSE Commands to Review Errors and Examine Source Code
Command Key Sequence Function
COMPILE None Compiles the contents of the source buffer. You can issue this command with the /REVIEW qualifier to put LSE in REVIEW mode immediately after the compilation.
REVIEW None Puts LSE into REVIEW mode and displays any errors resulting from the last compilation.
END REVIEW None Removes the buffer $REVIEW from the screen; returns the cursor to a single window containing the source buffer.
GOTO SOURCE CTRL/G Moves the cursor to the source buffer that contains the error.
NEXT STEP CTRL/F Moves the cursor to the next error in the buffer $REVIEW.
PREVIOUS STEP CTRL/B Moves the cursor to the previous error in the buffer $REVIEW.
  • Down arrow
  • Up arrow
Moves the cursor within a buffer.

A.1.3 Examples

The following sections show examples of using some common tokens and placeholders to write DECdocument code. The examples are expanded to show the formats and guidelines LSE provides; however, not all the examples are fully expanded.

The examples show expansions of the following DECdocument features:

Instructions and explanations precede each example. An arrow (<-) indicates the line in the code where an action has occurred.

See Table A-1 for the commands that manipulate tokens and placeholders.

Remember that braces ({}) enclose required placeholders; brackets ([]) enclose optional placeholders. When you erase an optional placeholder, LSE also deletes any associated text before and after that placeholder.

When you use LSE to create a new DECdocument file, the initial string, {element-or-template}, appears at the top of the screen. Expansion of the initial string produces the following: 


->  [profile] 
    [front_matter] 
    [chapter] 
    [part] 
    [appendix] 
    [glossary] 
    [tag-groups] 
    [article-tags] 
    [letter-tags] 
    [report-tags] 
    [overheads-tags] 
    [milspec-templates] 
    [software-documentation-templates]

A standard procedure in DECdocument is to place a single element, such as a chapter or appendix, or a single template, such as a milspec template or a software documentation template, into a single file.

A.1.3.1 Lists

Select the token LIST by typing LIS and expanding the token.

From the menu of possible list types, select the option Alphabetical-list. The following then appears on the screen in the editing buffer: 


 
    <LIST>(ALPHABETIC\[start-no]\[case]) 
    {list-element}... 
    <ENDLIST>

Erase the placeholder [start-no] and expand the placeholder [case]. Select UPPERCASE. 


 
    <LIST>(ALPHABETIC\UPPERCASE) 
    {list-element}... 
    <ENDLIST>

Move to the next placeholder and expand it to get an individual list element tag. 


 
    <LIST>(ALPHABETIC\UPPERCASE) 
    <LE>{text} 
    [list-element]... 
    <ENDLIST>

Type over the {text} placeholder to insert the text for the first list item.

A.1.3.2 Tables

Enter all or part of the token TABLE and expand it. 


 
    <TABLE>({caption}\[symbol]) 
    [<TABLE_ATTRIBUTES>] 
    <TABLE_SETUP>({number}[\col-width]...) 
    <TABLE_HEADS>({heading}[\heading]...) 
    {rows}... 
    <ENDTABLE>

The <TABLE> tag accepts two arguments: the caption to the table and a symbol to use for cross-references. With the cursor positioned on {caption}, enter the caption text. With the cursor positioned on [symbol], enter the symbol text. 


 
->  <TABLE>(Caption for the Table\newsymbol_tab) 
    [<TABLE_ATTRIBUTES>] 
    <TABLE_SETUP>({number}[\col-width]...) 
    <TABLE_HEADS>({heading}[\heading]...) 
    {rows}... 
    <ENDTABLE>

Expand the placeholder [<TABLE_ATTRIBUTES>] and choose a set of attributes from the menu. 


 
    <TABLE>(Caption for the Table\newsymbol_tab) 
->  <TABLE_ATTRIBUTES>(WIDE\MULTIPAGE) 
    <TABLE_SETUP>({number}[\col-width]...) 
    <TABLE_HEADS>({heading}[\heading]...) 
    {rows}... 
    <ENDTABLE>

Set up the table for the number and width of columns you want. Enter a number indicating the number of columns (2 through 9). Then expand the [\col-width] placeholder to enter a number indicating the width of the first table column. 


 
    <TABLE>(Caption for the Table\newsymbol_tab) 
    <TABLE_ATTRIBUTES>(WIDE\MULTIPAGE) 
->  <TABLE_SETUP>(3\{number}[\col-width]...) 
    <TABLE_HEADS>({heading}[\heading]...) 
    {rows}... 
    <ENDTABLE>

Notice that the expansion of the [\col-width] placeholder gives you the backslash needed to separate arguments and the {number} placeholder. If you enter a number into the [\col-width] placeholder without expanding it first, you do not get the backslash. Enter column widths for each column in the table except the last column. Delete the last [\col-width] placeholder. 


 
    <TABLE>(Caption for the Table\newsymbol_tab) 
    <TABLE_ATTRIBUTES>(WIDE\MULTIPAGE) 
->  <TABLE_SETUP>(3\15\15 ) 
    <TABLE_HEADS>({heading}[\heading]...) 
    {rows}...

The {heading} placeholders work like the [\col-width] placeholder. 


 
    <TABLE>(Caption for the Table\newsymbol_tab) 
    <TABLE_ATTRIBUTES>(WIDE\MULTIPAGE) 
    <TABLE_SETUP>(3\15\15 ) 
->  <TABLE_HEADS>(First heading\Second Heading\{heading}[\heading]...) 
    {rows}... 
    <ENDTABLE>

Enter a heading for each column and delete the last [\heading] placeholder.

Expand the {rows} placeholder to get tags for the body of the table. 


 
    <TABLE>(Caption for the Table\newsymbol_tab) 
    <TABLE_ATTRIBUTES>(WIDE\MULTIPAGE) 
    <TABLE_SETUP>(3\15\15 ) 
    <TABLE_HEADS>(First heading\Second Heading\{heading}[\heading]...) 
->  <TABLE_ROW>({item}[\item]...) 
    [rows]...

Enter an item for each column and keep expanding the [rows] placeholder until the table body is complete. Delete the last [rows] placeholder. The table is now ready for processing.

A.1.3.3 Profile

To place the tags for a document's profile into the editing buffer, type PRO and expand the token. 


 
    <PROFILE> 
    
           {element}... 
 
    <ENDPROFILE>

Expand the placeholder {element} to get the <ELEMENT> tag and the optional <INCLUDES_FILE> tag. 


 
    <PROFILE> 
 
    ->     <ELEMENT>({element-name}) 
 
              [<INCLUDES_FILE>] 
 
           [element]... 
 
    <ENDPROFILE>

Expand or delete the placeholder <INCLUDES_FILE> and expand the placeholder [element] as many times as you need.

A.1.3.4 Sample Template

There are two methods of accessing the Data Item Description (DID) templates for DOD-STD-2167-related military specifications:

Select one of the DIDs from the list. 


 
->  DI-MCCR-80012:  Software Top Level Design Document 
    DI-MCCR-80025:  Software Requirements Specification 
    DI-MCCR-80026:  Interface Requirements Specification 
    DI-MCCR-80027:  Interface Design Document 
    DI-MCCR-80028:  Data Base Design Document 
    DI-MCCR-80031:  Software Detailed Design Document

Select one of the DIDs, for example, DI-MCCR-80012. The menu that appears is a list of templates that make up the individual files in the Software Top Level Design Document.

For example, select DI-MCCR-80012__cover_page: 


 
    DI-MCCR-80012__profile 
    DI-MCCR-80012__symbols 
->  DI-MCCR-80012__cover_page 
    DI-MCCR-80012__Scope 
    DI-MCCR-80012__Referenced_Documents 
    DI-MCCR-80012__Requirements 
    DI-MCCR-80012__Qualification_Requirements 
    DI-MCCR-80012__Preparation_for_Delivery 
    DI-MCCR-80012__Notes 
    DI-MCCR-80012__Appendix

Each of the menu items displayed for DI-MCCR-80012 contains a template for a section of the Software Top Level Design Document. Place this template in a separate file. 


 
    <comment>(begin front matter component) 
    <front_matter> 
    <title_page> 
    <specification_info>(<reference>(control_number)\\<DATE>\) 
    <spec_title>(<reference>(DID80012_title)\For the\{text}\
    Contract No. <reference>(contract_number)\
    CDRL Sequence No. <reference>(CDRL_number)\<DATE>) 
 
    <subtitle>(Prepared for:\{text}\ \
    Prepared by:\{text}\{text}) 
 
    <endtitle_page> 
 
    <contents_file> 
 
    <endfront_matter> 
    <comment>(end front matter component)

The tags in the cover page template mark standard title page text. Fill in the variable information by typing over the {text} placeholders.

A.1.4 DECdocument Tokens and Placeholders

To see all the defined tokens provided by DECdocument, enter the following command: 


    LSE> SHOW TOKEN
To see all the defined placeholders provided by DECdocument, enter the following command: 


    LSE> SHOW PLACEHOLDER
To print a copy of either of these lists, you must first enter the appropriate SHOW command. This enters the list into the $SHOW buffer. Then enter the following commands: 


    LSE> GOTO BUFFER $SHOW 
    LSE> WRITE filename
At the DCL prompt, enter the PRINT command to obtain a hard copy of the list.

You can also specify a token name or placeholder name after the SHOW TOKEN or SHOW PLACEHOLDER command to get information about a particular token or placeholder.

Previous Next Contents Index