summaryrefslogtreecommitdiff
path: root/macros/generic/2up/doc/2up-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/generic/2up/doc/2up-doc.tex')
-rw-r--r--macros/generic/2up/doc/2up-doc.tex499
1 files changed, 499 insertions, 0 deletions
diff --git a/macros/generic/2up/doc/2up-doc.tex b/macros/generic/2up/doc/2up-doc.tex
new file mode 100644
index 0000000000..00409552a6
--- /dev/null
+++ b/macros/generic/2up/doc/2up-doc.tex
@@ -0,0 +1,499 @@
+%%
+%% $Id: 2up-doc.tex 1180 2020-05-09 10:02:00Z herbert $
+\documentclass[12pt]{article}
+%\usepackage[T1]{fontenc}
+\usepackage{libertinus}
+\usepackage{url}
+
+\usepackage{2up}
+\special{landscape}
+
+\let\TUfv\fileversion
+
+%% INSTRUCTIONS FOR TWO-UP PRINTING.
+%% 3. Uncomment one of the booklet options, if desired.
+%%
+%\targetlayout{twosided}
+\TwoupWrites
+
+% \targetlayout{Booklet} %% Booklet printing with 2-sided printer/copier.
+% \targetlayout{booklet} %% Booklet printing with 1-sided printer/copier.
+
+\twouplegaltarget
+\target{\magstepminus1}{29.6cm}{21cm}
+\source{\magstep0}{21cm}{29.6cm}
+
+\makeatletter
+%% PAGE NUMBERING:
+%% Adjust page numbering if using booklet layout option.
+\def\next{\if@leftpage\else\stepcounter{page}\fi}
+\@ifundefined{target@stop}{}{\next}
+
+%% Special list:
+\newcommand\namelistlabel[1]{\mbox{\bf #1}\hfil}
+\newenvironment{namelist}[1]%
+ {\begin{list}{}%
+ {\let\makelabel\namelistlabel
+ \settowidth{\labelwidth}{#1}
+ \setlength{\leftmargin}{1.1\labelwidth}}}%
+ {\end{list}}
+
+%% VERBATIM:
+%%
+\begingroup
+ \catcode`\{=12 \catcode`\}=12
+ \catcode`\(=1 \catcode`\)=2
+ \catcode`\+=0 \catcode`\\=12
+ +gdef+|(\) % \| = character \
+ +gdef+{({) % \{ = character {
+ +gdef+}(}) % \} = character }
++endgroup
+\def\Backslash{\protect\|}
+%%
+%% Define some functional font commands:
+%%
+\def\MainFont{\tt} % For macro definitions.
+\def\UsageFont{\tt} % For in-line macro names.
+\def\InlineFont{\tt} % For other in-line snipets of code.
+\def\MetaFont{\rm\it} % For meta arguments.
+%%
+%% Short-cuts for font commands:
+%%
+\def\s#1{\string#1}
+\def\t#1{{\InlineFont\string#1}} % For other in-line code.
+\def\m#1{{\MetaFont #1\/}} % For just putting things in italics
+\def\M#1{{\InlineFont\{\m{#1}\}}} % Arg is in italic, enclosed in tt braces.
+\let\N\t % For in-line macro names.
+\catcode`\<=13 \def<#1>{\m{#1}} % <meta>
+\catcode`\"=13\def"{\verb"} % Short verb
+%%
+%% This is for listing macro definitions in a quote-like environment.
+%%
+\begingroup
+ \catcode`\[=1 \catcode`\]=2
+ \catcode`\{=13 \catcode`\}=12
+ \gdef\@MD[%
+ \catcode`\{=13 \catcode`\}=12
+ \def{##1}[\{[\MetaFont ##1]\}]]
+\endgroup
+\def\MD{%
+ \quote
+ \begingroup
+ \@MD
+ \def\end{\endgroup\end}%
+ \def\\{\@centercr\s}%
+ \MainFont
+ \s}
+\def\endMD{\endquote}
+%%
+%% End preamble.
+\catcode`\@=12
+
+\begin{document}
+
+\title{Documentation for 2up.tex:\\
+ Two-up printing for Generic TeX}
+\author{Timothy Van Zandt\thanks{Version 1.3a prepared by Herbert Voß. The documentation was put into
+ \LaTeX\ format by David Todd and Herbert Voß}\\ \url{tvz@Princeton.EDU}}
+\date{Version \TUfv\\[3pt] \today}
+
+\maketitle
+\thispagestyle{empty}
+
+\begin{abstract}
+ "2up.tex"/"2up.sty" allows one to print a document two-up, with
+considerable flexibility as to paper size and layout. It produces a standard
+dvi file, and does not involve an additional dvi or PostScript filter. It
+should work with most \TeX\ macro packages.
+
+\end{abstract}
+
+\clearpage
+\tableofcontents
+\clearpage
+
+\section{Usage}
+Load 2up as a \LaTeX\ package with \texttt{\textbackslash usepackage}.
+There is a good chance you will get the desired layout. See the rest of
+this documentation for detailed information on controlling 2up.
+
+\section{Comparison with other methods}
+
+There are other tools for two-up printing:
+\begin{description}
+\item[PostScript filters]
+These work well as long as you only use PostScript fonts (as opposed to the
+usual Metafont fonts). Otherwise, the PostScript filter scales bitmapped
+fonts, and the quality is lower than with "2up.tex".
+
+\item[Rokicki's dvidvi]
+"dvidvi" is a versatil tool that does much more than
+2up printing. However, if only rearranges the pages, and does not adjust the
+magnification to ensure that the pages fit properly in a two-up format. It
+also adds one more step to the \TeX-dvi-printer cycle. "2up.tex", on the other
+hand, combines the changes to \TeX's magnification and page layout with the
+rearranging of the pages, all with an easy-to-use interface and from within
+your \TeX\ document. (See Section \ref{dvidvi} on using both "2up.tex" and
+"dvidvi" together.)
+\end{description}
+
+\section{A warning about fonts}
+
+Two-up printing generally involves reducing a document, and thus using fonts
+sizes that are not typically found on your system. If you are using bitmapped
+fonts (standard for \TeX\ users), and you do not have and cannot generate the
+extra fonts bitmaps, you will find 2up.sty (and any other method of two-up
+printing) to give very poor quality output.
+
+If you are using a program like Rokicki's "dvips" that can generate extra font
+bitmaps as needed, you will find that it takes a long time to print your 2up
+document the first few times, as "dvips" is busy making the extra fonts. This
+problem will go away. Be thankful you have such an easy way to get extra font
+bitmaps.
+
+\section{Source and target dimensions}
+
+Set the target and source layout:
+\begin{MD}
+ \source{mag}{width}{height}\\
+ \target{mag}{width}{height}
+\end{MD}
+
+\begin{itemize}
+\item The ``source'' layout is the layout of your document
+the way it is usually printed. The ``target'' layout is the layout when it
+is printed two-up.
+
+\item <width> and <height> are the true width and height of the paper,
+when looking at the output right-side-up.
+
+\item <mag> refers to the source and target magnification. It should be an
+integer, equal to 1000 times the magnification factor. There are also some
+magic magnification numbers:
+\begin{description}
+\item[$\setminus$magstep<n>] for a magnification of 1.2$^n$ (n=0,...,5), or
+
+\item[$\setminus$magstepminus<n>] for a magnification of 1.2$^{-n}$
+(n=0,...,5).
+\end{description}
+Using these magnification values will make best use of the available fonts on
+your system.
+\end{itemize}
+
+"2up.tex" takes each source page, and centers in half a target page. To get
+the pages to fit, the magnification of the document typically has to be
+reduced. If you find that the pages are too crowded, try reducing the target
+magnification. If they are too lonely, try increasing the target
+magnification.
+
+If you want to adjust the positioning of the scaled pages, try changing the
+values of "\hoffset" or "\voffset" with "\advance" or \LaTeX's "\addtolength".
+
+Don't change the magnification of your document after using the "\target"
+command, as you will override the settings made by 2up.tex.
+
+You can also specify some options:
+\begin{MD}
+ \targetlayout{options}
+\end{MD}
+where <options> is a comma separated list with no spaces. Valid
+options are:
+\begin{namelist}{topbottomxxx}
+
+\item [topbottom] The two source pages are printed one on top of the other.
+\item [twosided] Odd pages are always printed on the right or the bottom.
+\item [booklet] Pages are printed like a booklet. See Section \ref{booklet}.
+\item [Booklet] Like "booklet", but for two-sided printers/copiers.
+\item [dvidvi] For arranging in two-up layout with "dvidvi". See Section
+\ref{dvidvi}.
+
+\end{namelist}
+
+The only other changes you might want to make to your document are the
+following:
+\begin{itemize}
+\item You have to see to it that the target output is printed with the
+correct orientation (landscape or portrait). See the documentation for your
+dvi driver for details.
+
+\item "2up.tex" will inserts a line between pages if you change the following
+dimensions:
+\begin{namelist}{pagesepwidthxxx}
+\item [$\setminus$pagesepwidth] Thickness of line. (Default 0pt)
+\item [$\setminus$pageseplength] Length of line. (Default 6.5in)
+\item [$\setminus$pagesepoffset] Distance from bottom of page to bottom of
+line, or (with "topbottom" layout) from side of page to beginning of line.
+(Default 1in)
+\end{namelist}
+
+\item You can, but do not need to, use the following commands:
+\begin{namelist}{twoupemptypagexxx}
+
+\item [$\setminus$twoupemptypage] inserts a completely blank half page
+in the target.
+
+\item [$\setminus$twoupclearpage] \LaTeX\ users: ejects a complete target
+page.
+
+\item [$\setminus$twoupeject] Plain \TeX users: ejects a complete target
+page.
+
+\end{namelist}
+\end{itemize}
+
+\section{Defaults}
+
+ The following commands set the parameters for some common sources and
+targets. The definitions of these commands are also useful examples.
+
+ For A4 paper, just replace "8.5in" and "11in" in the definitions below by
+the width and height of A4 paper.
+
+\begin{description}
+
+\item [$\setminus$twouparticle]
+
+This is the default for \LaTeX.
+\begin{namelist}{Sourcexx}
+
+\item [Source:] A portrait document on 8.5x11 inch paper with wide margins as
+used in \LaTeX's article style, and without marginal notes.
+
+\item [Target:] A landscape document on the same size paper, with the source
+pages printed side by side.
+
+\item [Definition:]\hspace{1pt}
+\begin{verbatim}
+\target{\magstepminus1}{11in}{8.5in}
+\source{\magstep0}{8.5in}{11in}}
+\end{verbatim}
+\end{namelist}
+
+If you use narrower side margins, or if you use marginal notes, then you
+will need to use "\twoupplain" or \\ "\twouplegaltarget", defined below.
+
+\item [$\setminus$twoupplain]
+
+This is the default for non-\LaTeX.
+
+It is the same as "\twouparticle", but for source documents with narrower
+margins.
+\begin{namelist}{Sourcexxx}
+
+\item [Definition:]\hspace{1pt}
+\begin{verbatim}
+\target{\magstepminus2}{11in}{8.5in}
+\source{\magstep0}{8.5in}{11in}
+\end{verbatim}
+\end{namelist}
+
+\item [$\setminus$twouplegaltarget]
+
+\begin{namelist}{Sourcexxx}
+\item [Source:] A portrait document on 8.5x11 inch paper with just about any
+margins and perhaps with marginal notes.
+
+\item [Target:] A landscape document on legal size paper (8.5x14 inches),
+with the source pages printed side by side.
+
+\item [Definition:]\hspace{1pt}
+\begin{verbatim}
+\target{\magstepminus1}{14in}{8.5in}
+\source{\magstep0}{8.5in}{11in}
+\end{verbatim}
+\end{namelist}
+
+\item [$\setminus$twouplandscape]\hspace{1pt}
+\begin{namelist}{Sourcexxx}
+
+\item [Source:] A landscape document on 8.5x11 inch paper with just about any
+margins.
+
+\item [Target:] A portrait document on the same size paper, with the
+source pages stacked vertically.
+
+\item [Definition:]\hspace{1pt}
+\begin{verbatim}
+\target{\magstepminus2}{8.5in}{11in}
+\source{\magstep0}{11in}{8.5in}
+\targetlayout{topbottom}
+\end{verbatim}
+\end{namelist}
+
+\end{description}
+
+
+\section{True Dimensions}
+
+\TeX\ lets you use `true' dimensions, as in
+\begin{verbatim}
+ \topmargin 1truein
+ \setlength{\topmargin}{1truein}
+\end{verbatim}
+This sets the length to 1 inch
+as it appears on the page, no matter what the magnification.
+
+Once you use `true' dimensions, it is impossible to change the
+magnification of your document, and hence it is almost impossible
+to use 2up.tex. You will get an error like:
+\begin{verbatim}
+ ! Incompatible magnification (833);
+ the previous value will be retained (2000).
+\end{verbatim}%
+
+The use of `true' dimensions might be hiding in macros or style files
+you are using. For example, Plain \TeX's "\magnification" command uses
+true dimensions; use "\mag" instead, and then set "\hsize" and
+"\vsize" appropriately scaled. If you can't find the culprit `true'
+dimension in your document or input files, try putting this on the
+(very) first line of your document:
+\begin{verbatim}
+ \mag 143 \voffset 1truein \mag 1000
+\end{verbatim}
+
+You will get the error listed above wherever true dimensions are used
+(and in some other places as well).
+
+
+\section{Page Cross-References}
+
+ Page cross-references (e.g., in an index or table of contents) will not be
+accurate with "2up.tex", because finished pages are not immediately shipped
+out. This can also cause problems with some special \LaTeX\ styles that have
+multiple ".aux" files (e.g., for each chapter).
+
+ To get better, but not perfect, page cross-references, try putting the
+command
+\begin{verbatim}
+ \TwoupWrites
+\end{verbatim}
+at the beginning of your document, after inputting "2up.tex". This is good for
+drafts, and may fix problems with \LaTeX\ styles that have multiple ".aux"
+files. "\TwoupWrites" makes "\write" and "\read" "\immediate", if you know
+what that means. It might cause problems of its own, but try it and see.
+
+ To get accurate page cross-references:
+\begin{enumerate}
+\item Run the job without "2up.tex", until all cross-references
+are properly resolved. Run any index utility at this point.
+
+\item Run the job ONE MORE TIME with "2up.tex"; it will use the
+correct cross-references from the previous runs. (In \LaTeX\ documents,
+it is useful at this point to include the "\nofiles" command, so that
+the correct cross-references are preserved.)
+\end{enumerate}
+
+\section{Booklets\label{booklet}}
+
+Here are some special considerations for making booklets:
+
+\begin{itemize}
+
+\item Use the "booklet" target layout if your printer or copier cannot print
+two
+sides directly. "2up.tex" prints out the ``tops'' of the pages, and then the
+``bottoms'', so that you can copy or print on both sides by doing one side,
+flipping the output over, and doing the other side.
+
+\item Use "Booklet" if your printer or copier can print directly on two sides.
+
+\item You must have enough memory and box registers to hold all the pages in
+the document. A Big\TeX\ should be able to handle at least a 32-page booklet.
+
+\item Sometimes booklet printing is part of the design of a document, rather
+than an afterthought. In this case, you should set up the margins for the
+target half-page rather than using "2up.tex" to scale the document. For
+example, if using \LaTeX, 8.5x11 inch paper, \LaTeX's twoside style option,
+and headings, try the following page parameter changes:
+\begin{verbatim}
+ \setlength{\oddsidemargin}{-0.2in}
+ \setlength{\evensidemargin}{-0.5in}
+ \setlength{\textwidth}{4.2in}
+ \setlength{\textheight}{6.5in}
+ \setlength{\topmargin}{-.4in}
+\end{verbatim}
+If you do this, "2up.tex" isn't adjusting margins or scaling the
+document. You coould therefore get by without "2up.tex" by using "dvidvi".
+\end{itemize}
+
+\section{Using dvidvi\label{dvidvi}}
+
+ With the "dvidvi" layout option, "2up.tex" takes care of adjusting the
+margins, and you then use "dvidvi" to arrange the pages in a two-up
+format. The advantage is that cross referencing comes out right.
+The disadvantage is that it involves one more step.
+
+Start by \TeX ing your document with "2up.tex" and the "dvidvi" layout option.
+Then run the dvi file through "dvidvi". Specify the offsets for "dvidvi" at
+the middle of the page. E.g., for
+a side-by-side layout on 8.5x11in paper, use
+\begin{verbatim}
+ dvidvi '2:0,1(5.5in,0in)' foo bar
+\end{verbatim}
+For other paper sizes, replace "5.5in" by half the target paper width. For the
+"topbottom" layout, reverse the dimensions, e.g.,
+(0in,5.5in). For booklet printing, see the
+the documentation for "dvidvi".
+
+
+\section{Compatibility\label{compatibility}}
+
+ These macros should work with most \TeX\ macro packages, except for
+the following possible but unlikely compatibility problems:
+
+\begin{itemize}
+
+\item If you use a macro package other than \LaTeX\ that does unusual things
+to end a document and/or that modifies the definition of "\end", you may
+find that the last page is nor printed or that an extra page with headings
+is inserted at the end of the document. This is fixable on a case-by-case
+basis. See the redefinition of "\end" in "2up.tex".
+
+\item "2up.tex" might not work if you meddle with \TeX's "\shipout" primitive
+after loading "2up.tex".
+
+\item If the first page of the source document is not on the first two-up
+target
+page (possible, for example, with two-sided printing and the "booklet"
+option, but generally unlikely), "\special"'s that come at the beginning
+of the document also do not get onto the first page of output. This can mess
+up "\special"'s for landscape printing or
+including a PostScript header file. In this case, you have to specify
+these things as command line options when using your dvi driver.
+
+\end{itemize}
+
+
+\section{Changes}
+\begin{namelist}{V0.9xxx}
+\raggedright
+
+\item [V0.9a] Everything redone. Too many differences to point out.
+
+\item [V0.9b] Interface redone again. "booklet" option added.
+
+\item [V0.9c] Pages ship out a little earlier. A few bugs fixed.
+
+ Parameters "\pageseplength" and "\pagesepthickness" added.
+
+\item [V0.9d] Fixed bug with "\twoupclearpage" and "\twoupeject".
+
+\item [V0.9e] Made pages be counted (from dvi driver's viewpoint) by the
+physical page number.
+
+\item [V0.9f] Parameter "\pagesepoffset" added, and "\pagesepthickness"
+changed to "\pagesepwidth".
+
+\item [V1.0] None. Just seemed seemed like it was time to call it 1.0
+
+\item [V1.1] Added "Booklet" and "dvidvi" target layouts.
+
+ "\hoffset" and "\voffset" in source document now have expected effect.
+
+\item[V1.2] Fixed incompatibility problem with AmS-\TeX/AmS-\LaTeX.
+ Added "\TwoupWrites" command.
+\item[V1.3] LPPL license and updated documentation (hv).
+
+\end{namelist}
+\end{document}
+%% END 2up-doc