| 1 Overview of DOCUMENT Graphics Support
DOCUMENT has an open-ended strategy to support the
creation of compound documents.
Generally, if you have a graphics file that can be
printed on a device supported by DOCUMENT, you can
include that file into a document processed for that
device.
DOCUMENT supports compound documents while maintaining
the device independence of its source files. Graphics
files are identified in SDML tags that also name the
device for which the files are intended. When you
process your SDML file for another device, those tags
are ignored. When you process your SDML file for the
target device, the text processor leaves blank space
for the graphic and the device translator includes the
graphic into the printable file. A graphics file is
not actually included into a document until the final
printable file is made up by the device translator.
The DOCUMENT-supported devices that handle graphics
files are the following:
o LN03 (which prints sixel files)
o LN03R (or ScriptPrinter, which prints PostScript
files)
o LPS40 (or PrintServer 40, which prints PostScript
files)
DOCUMENT also supports the APS Micro-5 typesetter
internally to DIGITAL.
DOCUMENT Version 1.0 does NOT provide a means for
creating graphics.
Because of DOCUMENT's open-ended graphics support,
where graphics files are produced by applications
external to DOCUMENT itself, it is difficult to
give precise guidance to DOCUMENT users on including
graphics into their documents. Characteristics of the
output files vary from application to application, and
so does the user's ability to control the content of
the graphics file.
DOCUMENT accepts graphics files from the following
applications:
o DECslide, a graphics editor for the VT200 series of
terminal, a DEC product
o DECgraph, a tool for creating charts and graphs, a
DEC product
o Baseview, a tool for viewing CAD drawings, a DEC
product
o Capture, an internal tool for screen capture
o Vplot, a tool for converting VALID drawings to
sixel format
o SIGHT, a workstation-based graphics editor (only
full-page figures can be created), an internal tool
o GRED, a workstation-based graphics editor, an
internal tool developed with DOCUMENT in mind
Graphics produced in Regis format can be read by
DECslide, which then can produce a sixel file usable
by DOCUMENT.
Andrew Gent has written a program that will convert
sixel files to PostScript images and that converter
produces PostScript that can be used with DOCUMENT. A
pointer to that program is given in the last section
below.
2 DOCUMENT Graphics Tags
There are two ways to include a graphic into a
DOCUMENT file: as a figure and as an icon. Each must
be explicitly labeled in the SDML source file.
2.1 The <FIGURE_FILE> Tag
The <FIGURE_FILE> tag labels a graphics file to be
included in a document. It must be used in the context
of the <FIGURE> and <ENDFIGURE> tags. For a discussion
of the tags related to figures, see the VAX DOCUMENT
User's Guide, Part I.
Use one <FIGURE_FILE> for each device-specific
graphics file you will want to include. For example,
if you have both a sixel file and a PostScript file
that describe the same picture, use two <FIGURE_
FILE> tags, one for each file, between the <FIGURE>
and <ENDFIGURE> tags. Only the file labeled for the
device on which the document will be printed will be
included.
The information needed for the <FIGURE_FILE> tag is:
<FIGURE_FILE>(target-device\file-spec\vertical-size[\position[\position]])
The target device is a keyword specifying the device
on which the graphic will be printed. The two
keywords of interest are LN03 and POSTSCRIPT. (You
can also specify LINE_PRINTER to get blank space
in your lineprinter output, or APS, if you have an
Autologic typesetter.) The keyword LN03 is used when
the graphics file is in sixel format. The keyword
POSTSCRIPT is used for PostScript format.
The file specification gives the name of the graphics
file. A good convention to use is to name the LN03
files with a file type of SIX and the PostScript files
with a file type of PS. If you specify LINE_PRINTER
as your target device, use the keyword SPACE in place
of a file specification. (Line printers cannot print
graphics files.) You can also specify SPACE to obtain
blank space on an LN03 or PostScript printer if you
have no graphic for that device. When you do use
SPACE, any text in the fourth argument (such as an
art control number) will be printed in the midst of
the blank area left for the figure.
The vertical size tells the text formatter how much
blank space to leave. The vertical size must be a
number. The units are in picas (1 pica = 1/6 inch).
The numbers may be decimals. In versions prior to the
field test update, a number with with a decimal point
will be rounded down.
There are two valid keywords for the optional argument
for position:
o WIDE
o INDENT
Specify WIDE if your graphic is quite wide and your
document design has a wide left gutter. WIDE positions
the graphic at the leftmost point in the image area.
If you do not specify WIDE, the graphic will be
positioned at the left text margin.
Specify INDENT in the fourth argument if you want your
graphic to be set at a specific block indent on your
page. If you specifiy INDENT in the fourth argument,
you must specify the block indent level you want in
the fifth argument.
The following is an example of how you might code a
figure to obtain blank space in the output to a line
printer, and the graphic itself printed on an LN03 and
a PostScript device. The graphic is assumed to be 10
picas high.
<FIGURE>(Picture of Hand Done with GRED)
<FIGURE_FILE>(line_printer\SPACE\6)
<FIGURE_FILE>(ln03\hand.six\6)
<FIGURE_FILE>(postscript\hand.ps\6)
<ENDFIGURE>
2.2 The <ICON_FILE> Tag
The <ICON_FILE> tag labels a small graphics file that
will be positioned directly to the left or to the
right of some text in your document. It must be used
in the context of <ICON> and <ENDICON> tags. For a
discussion of the icon tags, see the VAX DOCUMENT
User's Guide, Part I.
Use one <ICON_FILE> for each device-specific graphics
file you will want to include. For example, if you
have both a sixel file and a PostScript file that
describe the same picture, use two <ICON_FILE> tags,
one for each file, between the <ICON> and <ENDICON>
tags. Only the file labeled for the device on which
the document will be printed will be included.
The information needed by the <ICON_FILE> tag is:
<ICON_FILE>(target-device\file-spec\vertical-size\horizontal-size\[RIGHT])
The target device is a keyword specifying the device
on which the graphic will be printed. The two
keywords of interest are LN03 and POSTSCRIPT. (You
can also specify LINE_PRINTER to get blank space
in your lineprinter output, or APS, if you have an
Autologic typesetter.) The keyword LN03 is used when
the graphics file is in sixel format. The keyword
POSTSCRIPT is used for PostScript format.
The file specification gives the name of the graphics
file. A good convention to use is to name the LN03
files with a file type of SIX and the PostScript files
with a file type of PS. If you specify LINE_PRINTER
as your target device, use the keyword SPACE in place
of a file specification. (Line printers cannot print
graphics files.) You can also specify SPACE to obtain
blank space on an LN03 or PostScript printer if you
have no graphic for that device. When you do use
SPACE, any text in the fourth argument (such as an
art control number) will be printed in the midst of
the blank area left for the figure.
The vertical size tells the text formatter how much
blank space to leave. The vertical size must be a
number. The units are in picas (1 pica = 1/6 inch).
The numbers may be decimals. In versions prior to the
field test update, a number with with a decimal point
will be rounded down.
The horizontal size tells the text formatter how
much to change the text margins to make room for the
graphic. The horizontal size must be a number. The
units are in picas (1 pica = 1/6 inch). The numbers
may be decimals. In versions prior to the field test
update, a number with with a decimal point will be
rounded down.
The optional argument RIGHT indicates that the icon
will be placed at the right hand side of the text. The
default is to place the icon to the left of the text.
The following is an example of how you might code
an icon. It shows the coding for both a right- and a
left-positioned graphic.
<ICON>
<ICON_FILE>(line_printer\SPACE\3\5)
<ICON_FILE>(postscript\hand.ps\3\5)
<ICON_FILE>(ln03\hand.six\3\5)
<ICON_TEXT>(<P> Here is a paragraph that the writer did not want the
reader to miss. Therefore, the writer called this text element an ICON and
labeled it in SDML. An ICON is a graphic placed either to the left or to the
right of some text, as shown here.)
<ENDICON>
<ICON>
<ICON_FILE>(line_printer\SPACE\3\5\RIGHT)
<ICON_FILE>(ln03\hand_pointing_left.six\3\5\RIGHT)
<ICON_FILE>(postscript\hand_pointing_left.ps\3\5\RIGHT)
<ICON_TEXT>(<P>Here is a paragraph that the writer did not want the
reader to miss. Therefore, the writer called this text element an ICON and
labeled it in SDML. An ICON is a graphic placed either to the left or to the
right of some text, as shown here.)
<ENDICON>
A known bug in the PostScript driver in the field
test of DOCUMENT V1.0 prevents the proper placement of
icons. That bug is fixed in the field test update.
3 The Procedure to Follow for Including Graphics Files
The procedure to follow for including graphics
files is an iterative one: it will most often take
several tries before you are fully satisfied with the
placement of your figure.
1. Create the graphic with your application.
2. Print the graphic on the appropriate target device.
3. Measure the graphic (in the vertical dimension
for a figure, in both vertical and horizontal
dimensions for an icon).
4. Enter the information concerning the graphic in
your SDML source file.
5. Process the source file through DOCUMENT and
examine the output.
6. Adjust the sizing information in your source file
as necessary.
7. Adjust the graphic itself using your application,
if possible and if needed.
8. Process the source file through DOCUMENT and
examine the output.
9. If you are not satisfied, adjust the sizing
information and process again (that is, return
to step 6).
Note that there is an interaction between two types of
changes you can make:
o You can change the placement of the figure using
SDML tags and sizing information.
o You can change the graphic itself (assuming you
have an application that allows you to modify the
graphic readily).
If you change the graphic, you may need to change the
SDML placement information. If you are dissatisfied
with the printed result, changing either the graphic
or the placement information may be sufficient to give
you good results.
4 Some Application-specific Hints
You may find it difficult to measure the precise size
of your graphic, especially if it does not include a
border. If you are using an application that allows
you to edit your graphic, place short lines at the top
and bottom, and along the rightmost and leftmost edges
of the picture. Use these to measure the vertical and
horizontal size, then delete them for the version of
the graphic you will use in your document.
You may want to obtain more spacing above or below
your graphic. You can do so using the <FIGURE_SPACE>
tag, passing as an argument to it the number of picas
of vertical spacing you want. The following example
shows how to obtain a half pica more of vertical space
between the graphic and the caption for the figure:
<FIGURE>(Graph Produced from DECgraph)
<FIGURE_SPACE>(.5)
<FIGURE_FILE>(line_printer\SPACE\10)
<FIGURE_FILE>(ln03\graph.six\10)
<ENDFIGURE>
4.1 Sixel Files
Sixel files are editable files. You can call them in
to your favorite text editor and change them. They do,
however, look forbidding. They were not meant to be
edited. In fact, it is a goal of CUP Engineering that
no human being should ever have to edit a sixel file.
Graphics applications should give you the ability to
create precisely the sixel file you want.
However, if you have a sixel file that you must print
and you do not have access to an application that will
allow you to easily modify the graphic, then edit you
must.
A hyphen character (-) creates a blank line six pixels
high in a sixel file. If you have a sixel with too
much white space, you can sometimes correct for that
by deleting hyphens. If you have a sixel with too
little white space, you can add hyphens to achieve the
effect you want.
4.2 RENDER (Hardcopy UIS)
Graphics produced by both GRED and SIGHT can be
processed through HCUIS (Hardcopy UIS) to produce
sixels and PostScript files by using the DCL command
RENDER on a workstation.
The optimum sixel file from RENDER is obtained with
the device specified as LN03PLUS and the qualifier
/NODRAFT (be sure your printer [0;4mis[m an LN03PLUS and
not just an LN03, or you may get a "band too complex"
error when you print your graphic -- blank bands will
appear in your picture if you get this error):
$ RENDER/DEVICE=LN03PLUS/OUT=.SIX/NODRAFT filename.typ
Files produced using GRED's cropping feature (to
produce graphics less than a whole page) should be
processed with the /FRAME qualifier. This qualifier
disables the automatic scaling and rotating features
of HCUIS that create a standalone 8 1/2 X 11 graphic.
/FRAME causes the sixel produced to print close to
the way the graphic is presented on the workstation
screen. Version 3.2 of Hardcopy UIS supports the
/FRAME qualifier. Files to modify earlier versions
of RENDER can be obtained by sending MAIL to
VAXUUM::PARSONS for a pointer.
For RENDER version V3.0, the qualifier analogous to
/FRAME for PostScript files is /PAPER=WINDOW. This
qualifier will produce a graphic that will not print
alone, but must be incorporated into a document to
print. Because PostScript files are editable, you
may process your file with /PAPER=WINDOW and and add
the PostScript command SHOWPAGE to the last line of
the file, using your favorite editor. The SHOWPAGE
command will cause the graphic to print standalone.
The SHOWPAGE command will not affect your ability to
incorporate the graphic into your document and will
allow you to measure your graphic in isolation.
The following example shows how to produce a
PostScript file using RENDER:
$ RENDER/DEVICE=LASER/OUT=.PS/PAPER=WINDOW filename.type
In V3.2 of RENDER, the /FRAME qualifier may be used
instead of /PAPER=WINDOW for PostScript output.
4.3 SIXTOPS
A program that converts sixel files to PostScript
images has been written by Andy Gent. It allows
scaling, vertical and horizontal positioning, and the
inclusion of art numbers.
A brief set of instructions and description of
the command line qualifiers is available from
BOOKIE::SYS$32T:[GENT.PUBLIC]SIXTOPS.DOC.
To install the program on a node, you set default to
the directory where you want the program installed,
copy BOOKIE::SYS$32T: [GENT.PUBLIC]COPY_SIXTOPS.COM
to that directory, and then execute it. This copies
the .EXE file, the command definition file, and the
instructions.
Andy will receive bug reports and suggestions at
BOOKIE::GENT, but the tool is supported only as time
permits.
|