| Previous | Contents | Index |
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:
<HTML_OPTIONS>(REVISION BAR)
or
<HTML_OPTIONS>(REVISION COLOR BLUE)
|
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:
<HTML_OPTIONS>(IMAGES GIF_DIR)
|
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:
<HTML_OPTIONS>(GIF_RESOLUTION LOW)
<HTML_OPTIONS>(GIF_RESOLUTION MEDIUM)
<HTML_OPTIONS>(GIF_RESOLUTION HIGH)
<HTML_OPTIONS>(GIF_RESOLUTION ULTRA)
<HTML_OPTIONS>(GIF_RESOLUTION nn)
|
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
<HTML_OPTIONS>(COLOR OFF)
|
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:
<HTML_OPTIONS>(COLOR HEADING BLUE)
<HTML_OPTIONS>(COLOR HEADING #FF0000)
<HTML_OPTIONS>(COLOR BODY YELLOW, COLOR TABLE_HEAD BLUE)
|
The document parts and default color values are:
| Part | Description |
|---|---|
| BODY | default is white --- sets the document background color to the color value |
|
TABLE_HEAD
TH |
default is lightseagreen --- sets the color for table heading background; can abbreviate to TH |
|
TABLE_DATA
TD |
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 |
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.
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:
DOCUMENT DOGS.SDML HELP MANPAGE
DOCUMENT DOGS.SDML GENERAL MANPAGE\OUTPUT=TEST_DOGS
DOCUMENT DOGS.SDML SOFTWARE.REF MANPAGE\CONDITION=TEXT
|
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.
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
| 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. -TEX-I-OUTFILENAME, 'USER:[DOC]MYFILE.DVI_PS' [ D e v i c e C o n v e r s i o n ]... %DVC-I-PAGESOUT, 1 page written to file: USER:[DOC]MYFILE.PS DOCUMENT /LIST MYFILE.SDML GENERAL PS 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 USER:[DOC]MYFILE.SDML;2 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. -TEX-I-OUTFILENAME, 'USER:[DOC]MYFILE.DVI_PS' [ D e v i c e C o n v e r s i o n ]... %DVC-I-PAGESOUT, 1 page written to file: USER:[DOC]MYFILE.PS DOCUMENT /LIST MYFILE.SDML GENERAL PS 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 USER:[DOC]MYFILE.SDML;5 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 USER:[DOC]MYFILE.SDML;5 There have been more than 0 error messages of severity level E %DOC-E-ERROR_TAG, Errors found by the tag translator DOCUMENT /LIST MYFILE.SDML GENERAL PS Date/Time: 2-JAN-1995 12:49:37.42 CPU time: 1.7 secs. |
There are five different types of errors that can occur when using DECdocument and five different types of error messages. These five are:
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 |