\input amigatexinfo
\input texinfo
@c %**start of header
@set VERSION 1.1
@setfilename DviDvi.guide
@settitle DviDvi @value{VERSION}    Documentation
@setchapternewpage off

@iftex
@parskip=0.75em
@end iftex
@c %**end of header


@titlepage
@title{DviDvi}
@subtitle{A dvi file converter}
@subtitle{}
@subtitle{Version @value{VERSION}}
@author{Thomas Rockicki}
@vskip 0pt plus 1filll
DviDvi converts a DVI-file into another DVI-file. This is version
@value{VERSION}, author Thomas Rockicki, Amiga-Port (better: PasTeX-Port)
Thomas Baetzler and Jochen Wiedmann. Copyright (C) 1988-91, Radical
Eye Software

Here's a little hack I threw together for those doing pagination
tricks. The dvidvi program converts a DVI file into another DVI file,
with perhaps certain changes.

Enjoy; this is an early release, so make suggestions, improvements,
and I'll get back to you with a better version later.
@end titlepage


@ifinfo
@node Top
@top DviDvi V@value{VERSION} Documentation
DviDvi converts a DVI-file into another DVI-file. This is version
@value{VERSION}, author Thomas Rockicki, Amiga-Port (better: PasTeX-Port)
Thomas Baetzler and Jochen Wiedmann. Copyright (C) 1988-91, Radical
Eye Software

Here's a little hack I threw together for those doing pagination
tricks. The dvidvi program converts a DVI file into another DVI file,
with perhaps certain changes.

Enjoy; this is an early release, so make suggestions, improvements,
and I'll get back to you with a better version later.

@menu
* Invocation::	    Parameters, options and arguments
* Examples::	    The @samp{-m} parameter
* DviPS::	    Installing and using DviDvi with DviPS
* PasTeX::	    Installing and using DviDvi with ShowDVI and DVIPrint
* Informations::    Contacting Thomas Rockicki
@end menu
@end ifinfo


@node Invocation
@chapter Parameters, options and arguments
Invocation is
@example
    @samp{dvidvi param infile outfile}
@end example

What are the parameters?  The 'easy' parameters are the following:

@table @strong
@item -f n
page n is first page selected
@item -l n
page n is last page selected
@item -n n
select at most n pages. Notice that n is the number of pages
selected, independently of the number of pages actually contained
in a sheet
@item -i @{ n1..n2 | n1 @}[,...]
include pages (ranges allowed). When this option is used, ONLY the
specified pages are selected. However, we can exclude from these
pages with the option -x.
@item -x @{ n1..n2 | n1 @}[,...]
exclude pages (ranges allowed)
@item -q
work in quiet mode, that is do not print in the screen messages of
how the work is being done.
@item -r
reverse the order of the pages.
@item -sm m
Scale the magnification. (Magnification is multiplied by magstep(m)).
@item -sh m
Scale the document-height. (Height is multiplied by magstep(m)).
@item -sw m
Scale the document-width. (Width is multiplied by magstep(m)).
@end table

The page numbers for the above options -f, -l, -i and -x can
be specified in different ways.

@enumerate
@item
If a number n is given, it is interpreted as the n'th page from the
begining of the .dvi file. Of course, this number is independent
of the page number assigned by TeX.
@item
TeX page numbers are those who are actually written in the page;
these page numbers can be modified, for example, by using the TeX
commands @samp{\pagenumbering}, @samp{\setcounter@{page@}@{n@}}, and
@samp{\addtocounter@{page@}@{n@}}. A TeX page number can be specified
by preceding the number n with the character @. Thus, if you
specify @samp{-f @@25 -l @@30} you select the pages between 25 and 30,
these numbers being those assigned by TeX.
@item
However, several pages can have the same TeX page number in a .dvi
file. For example, the introductory pages in a book are numbered
i, ii, and so on until the first chapter begins and then, the
pages are numbered 1, 2, etc.  In this case, the pages numbered i
and 1 in the .dvi file have the same TeX page number. If you want
to select for example the second occurrence of the page numbered
1, you can specify a page number as @samp{(@@2)1}. Thus @samp{@@1} is
equivalent to @samp{(@@1)1}. For example, if you specify
@samp{-f (@@2)1 -l(@@2)10} you select the pages between 1 and 10 of
the first chapter, not the introductory pages between i and x.
@end enumerate

There is another parameter that tells DviDvi how you want to change
page layout and specifications. But this parameter is somewhat
complicated and therefore explained in a special section.
@xref{Examples}.


@node Examples
@chapter the @samp{-m}-parameter

There is another parameter that tells dvidvi how you want to change
page layout and specifications. This is the @samp{-m} parameter.

The number preceding the colon is the modulo value. Everything will
be done in chunks of pages this big. If there is no colon, than the
default value is assumed to be one. The last chunk of pages is padded
with as many blank pages as necessary.

Following the colon is a comma-separated list of page numbers.
These page numbers are with respect to the current chunk of pages, and
must lie in the range zero to the modulo value less one. If a negative
sign precedes the number, then the page is taken from the mirror chunk;
if there are m chunks, then the mirror chunk of chunk n is the chunk
numbered m-n-1. Put simply, it is the chunk numbered the same, only
from the end. This can be used to reverse pages. If no number is
given, the page number defaults to 1.

Following each page number is an optional offset value in
parenthesis, which consists of a pair of comma-separated dimensions.
Each dimension is a decimal number with an optional unit of measure.
The default unit of measure is inches, or the last unit of measure
used. All units are in true dimensions.  Allowable units of measure
are the same that TeX allows: @code{min}, @code{mm}, @code{cm}, @code{pt},
@code{pc}, @code{dd} and @code{cc}.

Simple enough, eh?  Okay, let's do some simple things.

@table @samp
@item -m -
Reverses the order of the pages. This time, both the modulo and
the page number are defaulted.
@item -m 2:0
Selects the first, third, fifth, etc. pages from the file. Print
this one after printing the next, taking the paper out of the feed
tray and reinserting it into the paper feed.
@item -m 2:-1
Selects the second, fourth, etc. pages, and writes them in reverse
order.
@item -m 4:-1,2(4.25in,0in)
@itemx -m 4:-3,0(4.25in,0in)
Useful for printing a little booklet, four pages to a sheet,
double-sided, for stapling in the middle. Print the first one,
put the stack back into the printer upside down, and print the
second. The `in' specifications are superfluous.
@item -m ,(1pt,1)
Scare your system administrator! Actually, things are so blurry
with this option, you may want to send enemies letters printed
like this. *Long* letters.
@item -m 4:0(5.5in,4.25),3(0,4.25)
@itemx -m 4:1(0in,4.25),2(5.5,4.25)
Print a four-page card on one sheet. Print the first, rotate the
paper 180 degrees and feed it again. (PostScript people can do
funny tricks with PostScript so this isn't necessary.)
@end table


@node DviPS
@chapter Installing and using DviDvi with DviPS

Installation isn't very hard: Just copy the program to a place
contained in your search-path.

Note that you don't need the parameters @samp{-sm}, @samp{-sw} and
@samp{sh} with DviPS: The document-width and -height are simply
ignored by Dvips and the magnification can be changed with the -x
parameter.

A little example might help, which prints a DVI file with two pages
per sheet of paper:

@example
       @samp{dvidvi -m 2:0,1(7.3,0.0) infile.dvi outfile.dvi}

       @samp{dvips -x 694 outfile.dvi}
@end example

Note that the @samp{-x}-parameter divides the magnification by magstep(2),
because 694 equals to 1000 divided by 1.44 (magstep(2)).

@node PasTeX
@chapter Installing and using DviDvi with PasTeX

Things are a little bit more complicated using PasTeX. This is
because PasTeX (ShowDVI and DVIprint, to be a little more precise) uses
the informations about document-width and height contained in the DVI
file to determine the size of RAM that is needed. Further it isn't
possible to scale the magnification in a device-independent way. (For
example you need to divide the number 180 by magstep(2) when printing
on a Nec-P6 in draft-mode instead of the device-independent number 1000
from the example above.)

DviDvi satisfies our needs with the options @samp{-sm}, @samp{-sw} and
@samp{-sh} here. The example above would look here as follows:

@example
       @samp{dvidvi -m 2:0(0.0,-0.75),1(7.3,-0.75) -sm -2 -sw 4}
       @samp{	    infile.dvi outfile.dvi}

       @samp{dviprint landscape on outfile.dvi}
@end example

Installing looks nearly the same as installing DviDvi for DviPS
(Simply copy the program to whereever you want), except that the
automatical font-generation needs to get a little bit enhanced. (We
need to support magstep(-4) up to magstep(9) now instead of magstep(0)
up to magstep(9).) This is done by replacing the original file
@file{MakeTeXFont.rexx} with the file @file{PasTeX/MakeTeXFont.rexx}
from the DviDvi-distribution.


@node Informations
@chapter Contacting Thomas Rockicki

I (Jochen Wiedmann for now) am very sorry, that i don't know Thomas
Rockicki's address, especially because of his friendly invitation to
make suggestions about the program. All i found was an old
Internet-address in Georg Hessmann's dvips-distribution. I don't know
if it's still valid, but here it is:

@example
       @strong{rockicki@@neon.stanford.edu}
@end example

You can contact me as well, if you have problems concerning the
Amiga-port. I don't know if i can help (all i know about DVI files was
what i learned in the last three hours), but i'll try. Here's how you
reach me:

@example
     Jochen Wiedmann
     Am Eisteich 9
     72555 Metzingen
     Germany

     Phone: 07123 / 14881
     Internet: wiedmann@@mailserv.zdv.uni-tuebingen.de
@end example

Thomas Baetzler did much work in fixing bugs and revising the source. His
address is:

@example
    Thomas Baetzler
    Herrenstr. 62
    76133 Karlsruhe
    Germany

    Internet: thb@@mil.ka.sub.org
    Fido: 2:2476/454.2
    Z-Netz: thb@@norton.zer
@end example
@bye
