Tutorial and
Application Guide

Previous Contents Index

12.8 Buttons

DECdocument creates links that are used as buttons which appear at the bottom of the screen/window when a browser displays an HTML file. For example:

         +------+  +----------+  +----------+  +-------+  +-------+ 
         | Next |  | Previous |  | Contents |  | Index |  | Begin | 
         +------+  +----------+  +----------+  +-------+  +-------+ 

There are buttons for:
NEXT next page
PREVIOUS previous page
CONTENTS table of contents
INDEX the index
BEGIN begin first page from the table of contents

DECdocument comes with the following button GIF files:
NEXT.GIF Next button
PREV.GIF Previous button
TOC.GIF Contents button
INDEX.GIF Index button
BEGIN.GIF Begin button

The above GIF files are located in the DOC$ROOT:[TOOLS] directory.

If you define the logical DOC$HTML_BUTTONS to be a location where GIF images can be found, DECdocument will create the appropriate HTML code to use these GIF files for the links instead of creating a plain text link. The format is:

        $ DEFINE DOC$HTML_BUTTONS "the_path" 

where the_path is the path to where the GIF files will be stored.

In DECdocument V3.2, the plain text links were changed to a table of colored buttons.

Now, you can use the new colored buttons (the default), or use GIF files for the buttons.

You can create any GIF files you want, but they must be given the names listed above (i.e. NEXT.GIF, PREV.GIF, etc.) and the DOC$HTML_BUTTONS logical must be defined.

12.9 New HTML Options

The following sections describe several new HTML options that were added in V3.2 of DECdocument.

12.9.1 REVISION Option

A DECdocument HTML option has been created for processing revision text. The REVISION option has two values which are:

If the REVISION option is not used, the output HTML revision text is printed in red and there are no vertical bars.

The REVISION option can be set up as follows:


12.9.2 IMAGES Option

A DECdocument HTML option has been created for identifying the GIF images directory path relative to the location of the HTML document.

The IMAGES option can be set up as follows:

        <HTML_OPTIONS>(IMAGES the_path) 

where the_path is the path to where the GIF image files will be stored.

For example:


12.9.3 Graphics Files - Sizing

A DECdocument HTML option has been added for controlling the resolution (size and density) of *.GIF files created by the Ghostscript PostScript to GIF conversion (PS and EPS files converted to .GIF files for HTML output). This option sets the resolution for the PostScript to GIF conversion command file (*_FIGURES.COM) created by the DECdocument HTML converter.

The GIF_RESOLUTION option has several values which are:

The GIF_RESOLUTION option can be set up as follows:


The lower the resolution, the smaller and less dense the image created. You can specify any number value. However, less than 50 or more than 300 is counter productive.

12.9.4 Color Values

A DECdocument HTML option has been added for controlling colors in the output HTML files.

With V3.2, COLOR ON is the default which causes default colors to be set up for output HTML files. The COLOR option can be turned on and off by specifying:

        <HTML_OPTIONS>(COLOR ON)     this is the default 

NOTE: If COLOR OFF, the HTML output will have no special coloring and will appear as it did prior to V3.2. This means that the HTML output goes back to the previous non-color behavior.

You can change the default colors for the different document parts. The color value can be a color (i.e. white) or the HEX value of a color (i.e. #FF0000). For example:


The document parts and default color values are:

Part Description
BODY default is white --- sets the document background color to the color value
default is lightseagreen --- sets the color for table heading background; can abbreviate to TH
default is blanchedalmond --- sets the color for table data background; can abbreviate to TD
HEADING default maroon --- sets the font color for <H1> headings
NOTE_BACKGROUND default lightskyblue --- sets the background color used for notes
NOTE_FOREGROUND default black --- sets the font color used for notes
SAMPLE_BACKGROUND default blanchedalmond --- sets the background color for sample tables
SAMPLE_FOREGROUND default mediumblue --- sets the font color used for sample text
CONTENTS_BUTTON default cyan --- sets the background color for the contents button
INDEX_BUTTON default lightskyblue --- sets the background color for the index button
BEGIN_BUTTON default lightpink --- sets the background color for the begin button
PREV_BUTTON default lightgoldenrodyellow --- sets the background color for the previous button
NEXT_BUTTON default aquamarine --- sets the background color for the next button

Chapter 13
Creating UNIX MANPAGES with DECdocument

This chapter provides information on UNIX MANPAGE files and how to create them.

13.1 MANPAGE Files

DECdocument processes a SDML file and produces a MANPAGE output file.

The DECdocument MANPAGE device converter was designed to create MANPAGE reference files for use on Digital UNIX systems. MANPAGES are normally used to create UNIX system on-line help documents.

The output MANPAGE reference files created by DECdocument contain Reference Semantic Markup Language (RSML) tags.

13.2 MANPAGE File Names

The output MANPAGE reference file created by DECdocument is given the same name as the source SDML file. The default file extension created by DECdocument for MANPAGE files is .1.

Output MANPAGE reference files can be given different names by using the /OUTPUT= qualifier with the document command.

13.3 Doctypes to Use

Producing MANPAGE reference files with DECdocument requires using the HELP doctype, SOFTWARE.REFERENCE doctype, or a doctype based on SOFTWARE.REFERENCE such as the GENERAL doctype.

MANPAGE files require a RSML .TH line. The .TH line indicates the beginning of the reference page and provides the title for the MANPAGE. The DECdocument MANPAGE converter uses the contents of the <TITLE> tag to generate the .TH line. The <TITLE> tag is placed in the front matter section of the SDML file --- this is the text between the <FRONT_MATTER> and <ENDFRONT_MATTER> tags.

HELP Doctype

Since MANPAGE files most closely resemble a help file, the HELP doctype would seem to be the most logical choice. However, when the HELP doctype is used, DECdocument ignores the front matter text section and the MANPAGE device converter does not have the <TITLE> tag text to create the .TH line. If the HELP doctype is used, the resultant MANPAGE reference file must be edited to insert the .TH line.


The SOFTWARE.REFERENCE based doctypes do use the front matter section and the DECdocument MANPAGE device converter does create the required .TH line in the output MANPAGE reference file.

13.4 Creating MANPAGE Files

Creating a MANPAGE reference file is as easy as creating PostScript (PS) or HTML output files. The document command is identical except that the destination is MANPAGE instead of PS or HTML. Here are DECdocument command examples:


When any of the above commands is given, DECdocument processes the DOGS.SDML file and creates:

        DOGS.1                  <-- document body 

The output MANPAGE file, DOGS.1, can then be transferred to a UNIX system and displayed using the command: MAN DOGS

13.5 Error Log File

If you attempt to build MANPAGE files and the SDML file(s) contain tags that cannot be implemented (i.e. translated into RSML commands), DECdocument creates an error log file. The error log file lists the problem tag(s), file and line location information, and the number of errors. Here is an example of an error log file:

        !--  Error log file for TESTDISK:[TESTER]TEST_PROFILE.1 
        Unimplemented Math command: lceil 
        characters \hbox{({\thinspace}\math{\lceil }{\thinspace})}. 
        TEX file :TESTDISK:[TESTER]TEST_FRONT.TEX  Line: 11805 
        Unimplemented Math command: lfloor 
        characters \hbox{({\thinspace}\math{\lfloor }{\thinspace})}. 
        TEX file :TESTDISK:[TESTER]TEST_FRONT.TEX  Line: 11811 
        Errors found:  2 

The name of the error log file is the SDML file name plus "_ERRORS.LOG". For example, if MANPAGE errors were found in DOGS.SDML, the error log file would be DOGS_ERRORS.LOG; for TEST_PROFILE.SDML, the name would be TEST_PROFILE_ERRORS.LOG.

13.6 Summary Comments

The <INDEX_FILE> and <CONTENTS_FILE> tags are ignored by the DECdocument MANPAGE device converter.

No special SDML tags are required for creating MANPAGE output.


DECdocument will produce MANPAGE output from any SDML file that can be processed by the HELP doctype, GENERAL doctype and SOFTWARE.REFERENCE design types. In most cases, DECdocument can produce MANPAGE output from other design types as well. However, the results might not be what is expected and errors could occur. This restriction will be lifted in future versions of DECdocument.

Most MATH tags have not been implemented because RSML does not have the concept of MATH at this time.

Appendix A
Locating and Correcting Tag Errors

When tags are written to the SDML file with an editor, it is possible to make typing errors which go unnoticed. When DECdocument attempts to process the tags in the SDML file, the errors show up and, depending on the severity of the errors, DECdocument can abort.

Some types of errors are more severe than others. The critical errors cause DECdocument to abort. When non-critical errors are encountered, DECdocument will simply ignore the tags and do nothing with the text. Whether the error is critical or not, DECdocument will report the error.

A.1 How Errors are Reported

There are several ways that DECdocument reports errors.

A.2 Creating a LIS File

When you give the DOCUMENT command, DECdocument displays information on the screen as it processes the SDML file. If errors are encountered, information about the errors is also displayed. Some errors are very recognizable and easily corrected. However, it could be that several errors are detected and some research is needed. To get a list of the processing steps and errors, you can create a LIS file.

Here is an example of a DOCUMENT command:

$ document myfile.sdml general ps

If you append /LIST to the DOCUMENT command, a LIS file will be created. The list file will be called MYFILE.LIS. The file name is the same as the SDML file. Here is the document command you would use to create the LIS file:

$ document myfile.sdml general ps/list

A list file looks like this:

Example A-1 Example of a LIS File

%DOC-I-IDENT, DECdocument V3.2 
[ T a g    T r a n s l a t i o n ]... 
%TAG-I-DEFSLOADD, End of Loading of Tag Definitions 
%TAG-I-ENDPASS_1, End of first pass over the input 
[ T e x t    F o r m a t t i n g ]... 
%TEX-I-PAGESOUT, 1 page written. 
[ D e v i c e    C o n v e r s i o n ]... 
%DVC-I-PAGESOUT, 1 page written to file: 
Date/Time:  2-JAN-1995 11:50:25.23 
CPU time: 4.1 secs. 

A.2.1 Errors in the LIS file

If there are tag errors in your SDML file, the errors will be listed in the "Tag Translation" section of the LIS file. For example, the following list file shows how errors are reported. In this case, the <EMPHASIS> tag was misspelled.

%DOC-I-IDENT, DECdocument V3.2 
[ T a g    T r a n s l a t i o n ]... 
%TAG-I-DEFSLOADD, End of Loading of Tag Definitions 
%TAG-W-TAGNOTDEF, tag <UNDEFINED_TAG>, line 4, file 
   Tag <EMPHASS> is undefined 
%TAG-I-ENDPASS_1, End of first pass over the input 
%TAG-I-UNDEFTAGS, There were 2 undefined tag invocations 
[ T e x t    F o r m a t t i n g ]... 
%TEX-I-PAGESOUT, 1 page written. 
[ D e v i c e    C o n v e r s i o n ]... 
%DVC-I-PAGESOUT, 1 page written to file: 
Date/Time:  2-JAN-1995 11:55:21.59 
CPU time: 3.93 secs. 

DECdocument attempts to provide you with as much information about your error as it can. Normally, it will provide:

The above tag error was a non-critical error and you can see that DECdocument completed processing and created the output file. However, if you print the PS output file, you will see the misspelled tag in the output because DECdocument ignored the tag and treated it as un-tagged text.

If a critical tag error occurs, DECdocument aborts after the errors are listed and no output file is created. Here is an example of the LIS file showing a critical error. In this case, there was no argument to the <UNDERLINE> tag.

%DOC-I-IDENT, DECdocument V3.2 
[ T a g    T r a n s l a t i o n ]... 
%TAG-I-DEFSLOADD, End of Loading of Tag Definitions 
%TAG-E-TAGNOTEND, end-of-file, line 7, file 
   Tag <UNDERLINE> from line 6 not terminated 
%TAG-E-TAG_FAILS, The tag translator has detected a fatal error 
-TAG-F-ABORTFORE, end-of-file, line 7, file 
   There have been more than 0 error messages of severity level E 
%DOC-E-ERROR_TAG, Errors found by the tag translator 
Date/Time:  2-JAN-1995 12:49:37.42 
CPU time: 1.7 secs. 

A.3 Other Types of Errors and Messages

There are five different types of errors that can occur when using DECdocument and five different types of error messages. These five are:

  1. Command line errors
    If you have an error in the DOCUMENT command line

    $ document myfile.sdml general ps
    an error message will be displayed and DECdocument will abort. For example, you will get an error if the doctype is not a valid doctype.
  2. Tag translation errors
    When DECdocument starts processing, the first step it performs is to translate the tags in the SDML file. If there are any tag errors, error messages are displayed. The preceding sections showed examples of tag error messages.
  3. Text formatting errors
    The next step DECdocument performs is to format the text in pages. If any formatting errors occur during this procedure, format error messages will be displayed. For example, if you set up a table that is too wide for the page margins, you will get an error message.
  4. Device conversion errors
    The last major step that DECdocument performs is to create an output file for the destination (i.e. PS) that you specified. DECdocument allows you to give the output file a specific name or file specification. That is, you can place the output file in a different location than the SDML file (see Section 11.4.2, /OUTPUT Qualifier). If DECdocument cannot find the specified directory location, you will get a device conversion error message.
  5. Index facility errors
    If you specify the index qualifier, DECdocument runs a procedure that creates an index file. If errors occur during the index processing, index error messages will be displayed. For example, you can create up to nine levels of sub-index entries. If you exceed the maximum number of levels, you will get an index error message.


The Producing Online and Printed Documentation manual contains several sections that describe, in detail, how DECdocument processes an SDML file.

The Command Summary and Processing Messages manual contains all the different types of informational and error messages that DECdocument displays.

Previous Next Contents Index