4.4BSD/usr/src/contrib/dipress/doc/guide.me

Compare this file to the similar file:
Show the results in this format: 

.bp
.sh 1 "Invoking the Programs"
.lp
All of the programs provided with this toolkit have associated manual
pages for easy reference.  Since a set of programs is more than the
sum of its options, some suggested uses are given below.
.sh 2 "\*(IP File Editor: ipfe"
.lp
This program executes page level operations on an \*(IP files.  For example,
it will read an \*(IP master and output a new master that has all
the pages offset for binding.  It can extract and combine pages from
different \*(IP files.  In addition, it can insert files that are requested
via the \*(IP
.i sequenceInsertFile
command.
.lp.
Ipfe is used on this document to move the table of contents to the front.
\*(TR, like make document compilers, only makes one pass of the source files.
This means that table of contents (TOC) entries are gathered as each section
is encountered and then output at the end.  Typically, the TOC is moved
by hand from the back of the document to the front.  This step can be
automated.  In this document, the cover page and TOC both occur at the
end.  On what is to be last page of the finished document the following
\*(TR commands appear:
.(l
	.nr x \\n%+1
	.sy echo ipfe -o body.ip doc-.ip \\\\"[1-\\n%]\\\\" > Split-pages.sh
	.sy echo ipfe -o cover.ip doc-.ip \\\\"[\\nx-]\\\\" >> Split-pages.sh
.)l
The first line takes the current page number and adds one to it and
stores the result in the variable ``x''.  The next two lines call the
shell to create a file called \%``Split-page'' which has two lines.
The first line of that file says create a new \*(IP file which
is the body of the document and the second a file that has the remainder.
The makefile that creates this document, executes the shell script to
split up the file.  It then pastes the two files together in opposite order
(and processes inserts) with:
.(l
\f(TR	ipfe -o doc.ip -s cover.ip body.ip
.)l
.lp
Image frames in Viewpoint are one way to create the sequenceInsertFile command.
The technique used by Viewpoint is described in the Print Service
Integration Standard \(sc6.6:
.i "Interpress image, form and logo interface" "."
Note that two sequenceInsertFile commands are created for each image frame:
one for the file named by the user and other for library routine called
"LIB>ILF".  Some printers support the library routine (Xerox 8700 & 9700)
and for others you will have to supply your own (Xerox 8044).
.sh 2 "ipmetrics"
.lp
The \*(IP standard specifies that fonts metrics (like widths of characters)
are distributed as \*(IP files which when executed leave
on the stack property lists which contain
metric information about the fonts.  The program ``ipmetrics''
will execute an \*(IP master and produce metrics for \*(TR, TeX or a
``generic'' composition system.
.sh 2 "iptroff and dipress"
.lp
The shell script ``iptroff\|'' is simply a front-end for TI-\*(TR and dipress.
Only under special circumstances will one need to invoke dipress directly.
In general, one invokes iptroff just as regular \*(TR would be used.
For example:
.(l
\f(TRiptroff -me foo.me
.)l
.lp
Remember, that many pre-processors such as eqn and pic
need to know which output device you intend to use.  When using iptroff,
specifiy the ``\-Tip'' switch.
.sh 3 "Fonts"
.lp
In order to be compatible with the C/A/T phototypsetter, there are the
standard four fonts: R, B, I and S.  The fonts provided with
this distribution have all the characters that the C/A/T had as well as
many new special characters.  These are documented in Appendix \f(RN3\fR.
Because \*(TR has a restriction of only 221 special character names,
it was not possible to give all the special characters unique names.
The overflow characters were placed in three (3) pseudo-fonts as follows:\(dg
.(f
.ti -\n(fiu
\(dgThey are pseudo-fonts in the sense that although \*(TR thinks
they are separate fonts, they are actually mapped to the same Interpress font.
.)f
.RS
.ip "RN"
This is the roman numeral font.  It has the digits one through nine
mapped to the matching roman numeral.  The digit zero is mapped to roman
numeral 10.
.ip "CN"
This is the circled (arabic) numeral font.  The digits are mapped
in the same way.
.ip "XX"
The remaining miscellaneous characters which are mapped to normal
ASCII characters.
.RE
.sh 3 "Inserting \*(IP files into \*(TR Documents"
.lp
This section discusses how to merge existing \*(IP files into a \*(TR
document.  Before proceeding in detail, it is important to note two things
about \*(IP files: they are laid out on a cartesian plane and they don't
have any information indicating the image size (bounding box).
.lp
The request to insert an \*(IP file is done using \*(TR transparent
throughput mode (see \(sc10.6. of the \*(TR manual).  The format
of such a command is:
.br
	\\!x Xerox IP File.Name
.br
The effect is to create a
.i SequenceInsertFile
request at the current position with the requested file name.  Thus the file
is not actually inserted in the \*(IP master, only it's name.  The actual
insertion of the file is done in a seperate step.  The current position
is where the insert's origin will be placed.  As mentioned before, \*(IP
files are laid out on a cartesian plane.  Typically, the point (0, 0) is
in the lower left hand corner of the page and the X-axis increases along
the bottom to the right and the Y-axis increases along the left edge going
up.  (first quadrant rules)
.lp
There is one problem with the above transparent command: it may not
do the right thing because \*(TR is buffered.  Something like the following
sequence is recommended:
.(l I
	.fl
	\\!V\\n(nl
	.nr x \\n(.o+\\n(.i
	\\!H\\nx
	\\!x Xerox IP File.Name
.)l
.lp
Inserts are easiest to handle if they sit in the first quadrant and abut
the origin. The program plot2ip has the ability to position
files this way.  In Viewpoint, a graphics frame can be placed at the bottom
left corner by setting the following property sheets:
.(l I
\fIpage\fP properties:
\(em\(emPage Margins LEFT: 0
\(em\(emPage Margins BOTTOM: 0

\fIgraphics frame\fP properties:
\(em\(emMargins Left: 0
\(em\(emMargins Bottom: 0
\(em\(emAlighnment (horizontally): FLUSH LEFT
\(em\(emAlighnment (vertically): FLUSH BOTTOM
\(em\(emSpan: Page
.)l
Now paginate the document and the graphics frame should appear correctly.
An alternative is to use ipfe to change the X and Y position of the page.
.lp
As mentioned above, iptroff will only produce an insertion request
for a file.  Not all \(IP printers support this feature.  In particular,
the Xerox 8044 does not.  To cause the insertion to happen before
the \*(IP master is sent to the printer, the program ipfe can be used.
For example,
.(l I
\f(TRipfe -s -o output.ip master.ip
.)l
will cause the file master.ip to be copied to output.ip while fulfilling
insertion requests.  If, in the \*(TR document, we asked for the insertion
of head.ip but we wanted that mapped to /usr/local/lib/ip/letterhead.ip
we would type:
.(l I
\f(TRipfe -s -a head.ip:/usr/local/lib/ip/letterhead.ip
	-o output.ip master.ip
.)l
For more details, check ipfe the manual page.
.sh 3 "Inserting RES files into \*(TR documents"
.lp
This section discusses how to merge files in the Raster Encoding Standard
(RES) with \*(TR documents.  RES files are encoding similarly to \*(IP
but they don't image.  Instead they leave data on the stack that can
be used to image them.  This property of RES files means that decisions
about how a raster image will look on a page can be deffered until
the \*(IP master is executed.
.lp
A sample of the RES insert command in \*(TR is:
.(l
	\\!x Xerox RES bl 300spi File.Name
.)l
In this example, the ``bl'' means that the current position should
anchor the bottom-left of the image.  The possible values for this
field are:
.sp
.TS
box center;
l l.
code	position
_
bl	bottom left
tl	top left
br	bottom right
tr	top right
c	center
.TE
.sp
In this example, the 300 means that the raster should be imaged at 300 spots
(dots) per inch.  A resolution of zero (0) indicates that the natural
resolution specified in the RES file should be used.
.lp
The following is a sample RES file that was originally drawn on an
Apple MacIntosh using MacPaint.
.br
.ne 3i
.sv 3i
.fl
\!V\n(nl
.nr x \n(.o+\n(.i
\!H\nx
\!x Xerox RES bl 144spi happy-family.res
.sh 3 "Hints and Warnings"
.lp
This section discusses unexpected behavior that users of iptroff might
encounter and how to deal with it.
.lp
On page three (3) of
.i "Typesetting Mathematics - User's Guide"
it is implied that typing a ``{'' to eqn will produce a roman ``{'' in the
output.  Unfortuately, eqn doesn't produce any code to guarantee this behavior.
Instead it relies on the fact that the C/A/T would always print ``{'' as
a roman character.  Since the \*(IP fonts include bold and italic curly
brackets, eqn output will produce italic curly brackets by default.
.lp
The \-me macros have a bug where some footnotes are broken across pages when
they shouldn't be.  This may be because our higher device resolution
alters the fudge factor that is used
to compute the amount of space to reserve for a footnote.
.lp
The 4.2 BSD macros have been modified to produce cut-marks for roll paper
devices such as Versatec plotters.  These cut marks will cause appearance
errors to appear on the banner page produced by the 8044 printer.  
In \-me they can be removed by placing the following
two lines at the front of your file:
.(l
\f(TR	.rm @m
.)l
In \-ms they can be removed by using the following lines:
.(l
\f(TR	.rm CM
.)l
.lp
The default physical offset for \*(TR is often too small.  When
using paper that is 8\(12 inches wide most users
will preface their files with a
.(l
\f(TR	.po 1i
.)l
.lp
to produce the correct page centering.