summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/rotpages/Documentation/rotpages-doc.tex
blob: 89d43f97b03b20532aeac4c93e6125c27dcdc394 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
\documentclass[12pt,twocolumn]{article}
\usepackage[a4paper]{geometry}
\title{\texttt{rotpages.sty} --- Multiple page rotation in \LaTeX}
\author{Sergio Callegari}
\date{January 25th, 2002}

\begin{document}
\maketitle
\thispagestyle{empty}

\begin{abstract}
  This \LaTeX\ package permits to format documents where small sets of
  pages are rotated by 180 degrees and rearranged, so that they can be
  read by turning the printed copy upside-down. It was primarly meant
  for collecting exercises and solutions: the package permits to print
  the exercise text normally and the solution text upside-down in
  order to make it a bit harder for the students to unintentionally
  read the solutions before solving the exercises autonomously. Other
  uses are obviously possible.
\end{abstract}


\section{Introduction}
%%
The package \emph{rotpages.sty} is meant to be used when parts of a
document should be made purposely difficult to read or obfuscated.  An
obvious way to make something difficult to read is to print it
upside-down. This is well known by all those keen on puzzles and
cross-words as in puzzle magazines the solutions are often printed
``the wrong way'' to prevent the readers from spoiling the
pleasure of the quiz by unintentionally reading the solutions.
  
A similar situation emerges in collecting exercises and solutions as
an aid for students training. The solutions must be there, so that the
students can check their results and avoid getting stuck when they
cannot answer some questions. At the same time the solutions should
not be easily readable, otherwise the temptation to read them before
attempting to solve a problem can be too strong. A typical format for
exercise collections consists in putting all the exercises at the
beginning and all the answers at the end.  However, this makes people
flap pages back and forth all the time.  Having the solutions close to
the relevant exercises and obfuscating them by page rotation can
be an alternative practice.

In \LaTeX, it is very easy to rotate small amounts of text. The package
\texttt{graphics} is a valid aid in this sense. However, it is not easy
to deal with large amounts of text. If the rotated material has to
span many pages, it cannot be put in a \verb|\rotatebox| command.
Furthermore, if many pages need to be rotated, it is not sufficient to
flip them individually: they must also be rearranged so that they
appear in the proper order when the printed copy of the document is
read ``upside-down''.

The package \texttt{rotpages.sty} permits to rotate a few pages,
rearranging them consistently and preserving the normal \LaTeX\
algorithm for breaking the material into pages. 


\section{Usage}
%%
The package defines two basic commands: \verb|\rotboxpages| and
\verb|\endrotboxpages|, which take no arguments.

The command \verb|\rotboxpages| closes the current page and delimits
the beginning of the text which should be typeset upside-down. The
command \verb|\endrotboxpages| marks the end of the region which is
typeset upside-down and makes sure that the rotated pages are flushed
onto the \texttt{dvi} file. Then it opens a fresh page.  The rotated
material is by default printed surrounded by a frame (but this can be
changed).  Page headers and footers continue display the proper way.

When used in two-column mode, the package correctly rotates the
columns independently, rearranging them if necessary. The rotated
columns get individually framed. Note that the package might not
operate correctly with other packages that also alter the paging
algorithms.

The files in the \texttt{Examples} directory provide some usage
examples.

\subsection{Personalization}
%%
The behaviour of \texttt{rotpages.sty} can be largely
personalized. Rotpages can frame the rotated pages, scale them,
enhance them with notes (e.g. ``rotate the book to read this page
properly'') and so on. All this is done by means of two ``hooks''.

The first hook is set by renewing the command
\verb|\rotboxAtRotationHook|. Whenever \LaTeX\ has finished preparing
a page or a column and rotation is activated, \texttt{rotpages.sty}
assures that the material is not directly shipped to the dvi file. On
the contrary, the material is put into a box and this box is saved
onto a stack. When the rotation mode is terminated, all the boxes
saved onto the stack are shipped to the dvi file in inverse order. The
stack mechanism is obviously necessary because the pages need to be
rearranged while flipped upside down. The \verb|\rotboxAtRotationHook|
is invoked on the pages/columns just before saving them onto the stack
(i.e.\@ right after rotation). Hence the \verb|\rotboxAtRotationHook|
takes a box as its argument and should return a box. In the simplest
case the \verb|\rotboxAtRotationHook| command can just return its
argument. In more complex scenarios it can put a frame around it and
so on.

The second hook is set by renewing the command
\verb|\rotboxAtShippingHook|. The idea is the same as for the
\verb|\rotboxAtRotationHook|, however this hook is invoked when taking
the pages off the stack rather than while putting them onto the stack.

In most cases the two hooks can be used indifferently. However there
is a very subtle difference among the two. When putting the pages onto
the stack one can easily keep trace of the relative number of the page
among the lot that is being rotated, but cannot know the actual page
number as this will be determined only at shipping time. On the
contrary, when taking the pages out of the stack one can know the
actual page number, because the shipping is effectively taking place.
This differenc can be used to add numbering labels and
rotated/non-rotated text to the pages being rotated as one of the
files in the \texttt{Examples} directory shows.

In any case, consider that \texttt{rotpages.sty} has no problems in
dealing with labels and page-references and does so in the expected
way, i.e.\@ using the ``actual'' page numbers.

The default for the two hooks \verb|\rotboxAtShippingHook| and
\verb|\rotboxAtRotationHook| is the following: the
\verb|\rotboxAtRotationHook| frames the page, and the
\verb|\rotboxAtShippingHook| does nothing.

The package \texttt{rotpages.sty} also defines a couple of lengths:
\verb|\rotboxheight| and \verb|\rotboxwidth|. These are related to the
size of the rotated pages/columns. It is the user responsibility to
assure that the rotated pages are exactly as large as the normal ones.
However, if a page is framed, one must take into account that the
frame occupies space. If this fact were not considered, the rotated
pages would come out with smaller characters than the normal ones. In
fact, the text \emph{plus the frame} should occupy as much space as a
normal page. The solution to overcome this problem is to put slightly
less text on the pages which get rotated, i.e.\@ to format the text
for a \emph{virtual} page which is smaller than the normal ones,
accounting for the frame. The lengths \verb|\rotboxheight| and
\verb|\rotboxwidth| have exactly this purpose, setting the size of the
virtual pages on which the text to be rotated gets formatted.

The default for \verb|\rotboxheight| and \verb|\rotboxwidth| is the
size of a normal page, less the space occupied by the default frame.

To conclude, the \texttt{rotpages.sty} package defines a boolean
variable which can be used to test whether the current text is being
rotated or not. This is the variable \verb|\boolean{rotboxactive}|
which can be tested using the \verb|\ifthenelse| command.


\section{Known bugs and quirks}
%%
The package is unable to deal with float material. Avoid float
material in the rotated pages. Equations, quotations, displayed math
and other non-float material can safely be used.

Apart from this, the package is relatively young and no bugs are known
so far.  It should be observed that the \texttt{.dvi} files produced
with \texttt{rotpages.sty} cannot be viewed properly with
\texttt{xdvi}, \texttt{kdvi} and most dvi previewers. However, this is
not a problem of \texttt{rotpages.sty}, rather of \texttt{xdvi} which
does not understand correctly some of the \verb|\special|s produced by
the \texttt{graphics} package which is internally invoked by
\texttt{rotpages} for the page rotation. The postscript files produced
by \texttt{dvips} display and print correctly. The package is also
compatible with pdf\LaTeX.

In order to re-arrange the pages which are rotated, the shipping of
the formatted material to the \texttt{dvi} file needs to be deferred
until all the rotated pages are processed. This puts a limit on the
number of pages which can be rotated at once, since the deferring
mechanisms uses a stack which eats up the \LaTeX\ memory. 

\section{Internal operation}
%%
The package works by redefining the \verb|\@makecol| macro, which is
normally used by \LaTeX\ to format and ship a page to the dvi file.
Particularly, at the \verb|\rotboxpages| command, the \verb|\@opcol|
and the \verb|\@startcolumn| macros are temporarily disabled, so that
no page gets shipped to the \texttt{dvi} file and no page number can
be updated. Also the current page size is altered, following the
\verb|\rotboxheight| and \verb|\rotboxwidth| lengths. Furthermore, the
\verb|\@makecol| macro is temporarily modified, so that the formatted
pages get processed by the \verb|\rotboxAtRotationHook| command,
rotated and accumulated into a stack.

At the \verb|\endrotboxpages| command, the behaviour of \LaTeX\ gets
reset to the standard. After that, the pages that had been accumulated
onto the \texttt{rotpages} stack are processed by the
\verb|\rotboxAtShippingHook| command, scaled to a normal page size and
flushed to the \texttt{dvi} file. The stack mechanism assures that the
pages get to the \texttt{dvi} file in the correct (rearranged) order.

For the page rotation, \texttt{rotpages.sty} relies on the standard
\texttt{graphics} package and so does for scaling. 

\section{To-do}
%%
\begin{itemize}
\item Allow the package to pass options to the underlying graphics
  package, particularly concerning the drivers (dvips, xdvi, etc.) to
  use.
\item Make the package deal correctly with float material (maybe hard
  to do).
\item Check the compatibility of the package with other packages.
\end{itemize}
\end{document}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: