Debian Codegraph @

texmf-dist/source/latex/semioneside/semioneside.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2005 by Stephan Hennig <[email protected]>
4 % -------------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.2
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.2 or later is part of all distributions of LaTeX
14 % version 1999/12/01 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
20 %<package>\ProvidesPackage{semioneside}
21 %<package> [2005/09/19 v0.41 Put only special contents on left-hand pages (SH)]
22 %
23 %<*driver>
24 \documentclass{ltxdoc}
25 \usepackage{semioneside}[2005/09/18]\semionesideoff
26 \usepackage{graphicx}
27 \usepackage{ifpdf}
28 \ifpdf
29 \DeclareGraphicsRule{*}{mps}{*}{}
30 \fi
31 \EnableCrossrefs
32 \CodelineIndex
33 \RecordChanges
34 \begin{document}
35 \DocInput{semioneside.dtx}
36 \PrintChanges
37 \PrintIndex
38 \end{document}
39 %</driver>
40 % \fi
41 %
42 % \CheckSum{61}
43 %
44 % \CharacterTable
45 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
46 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
47 % Digits \0\1\2\3\4\5\6\7\8\9
48 % Exclamation \! Double quote \" Hash (number) \#
49 % Dollar \$ Percent \% Ampersand \&
50 % Acute accent \' Left paren \( Right paren \)
51 % Asterisk \* Plus \+ Comma \,
52 % Minus \- Point \. Solidus \/
53 % Colon \: Semicolon \; Less than \<
54 % Equals \= Greater than \> Question mark \?
55 % Commercial at \@ Left bracket \[ Backslash \\
56 % Right bracket \] Circumflex \^ Underscore \_
57 % Grave accent \` Left brace \{ Vertical bar \|
58 % Right brace \} Tilde \~}
59 %
60 %
61 % \changes{v0.4}{2005/07/30}{.dtx package version with revised
62 % documentation}
63 % \changes{v0.41}{2005/09/19}{included MetaPost source in .dtx file}
64 % \changes{v0.41}{2005/09/19}{released package on CTAN}
65 %
66 % \GetFileInfo{semioneside.sty}
67 %
68 % \DoNotIndex{\newcommand,\newenvironment,\ifx,\fi,\global,\let}
69 %
70 %
71 % \title{The \textsf{semioneside} package\thanks{This document
72 % corresponds to \textsf{semioneside}~\fileversion, dated
73 % \filedate.}}
74 % \author{Stephan Hennig\\ \texttt{[email protected]}}
75 %
76 % \maketitle
77 %
78 % \begin{abstract}
79 % This package supports the creation of semi one sided documents.
80 % That is, two sided documents, where all text is output on
81 % right-hand pages---like in one sided documents---and only special
82 % contents is output on left-hand pages on user request,
83 % \emph{e.\,g.}, floating elements.
84 % \end{abstract}
85 %
86 %
87 % \section{Introduction}
88 %
89 % Some institutions require a document layout where running text
90 % appears on right-hand pages only---as in one sided documents---,
91 % but figures and tables, and only those, are displayed on left-hand
92 % pages. This package supports the preparation of such semi one
93 % sided documents. That is, all running text is output on
94 % right-hand pages and only special content, \emph{e.\,g.},
95 % floating objects, are output on left-hand pages on user request.
96 % Otherwise left-hand pages stay empty.
97 %
98 % References to left-hand pages are possible by defining a proper
99 % label on a left-hand page. The page counter can be configured to:
100 % \begin{itemize}
101 % \item keep left-hand pages syncronized with the facing right-hand
102 % page,
103 % \item keep left-hand pages syncronized with the preceeding
104 % right-hand page, \emph{i.\,e.}, page numbers refer to single
105 % sheets, or
106 % \item count every left- and right-hand page as in normal two
107 % sided documents.
108 % \end{itemize}
109 %
110 % \emph{When using this package keep in mind that this is more a
111 % quick hack than a robust solution!} Several problems are listed
112 % in section \ref{sec:knownproblems}.\footnote{The best solution to
113 % avoid all sorts of problems is not to use this package. You have
114 % been warned!}
115 %
116 %
117 % \section{How It Works}
118 %
119 % Before describing the usage of the \textsf{semioneside} package
120 % lets have a look at how it works behind the scenes.
121 %
122 % The functionality of the \textsf{semioneside} package is based on
123 % the |\afterpage| macro from the |afterpage| package. What happens
124 % after a page break is essentially this:
125 % \begin{enumerate}
126 % \item Since the current page break happend to occur at the end of
127 % a right-hand page---remember that the first page of a document is
128 % a right-hand page---, a new left-hand page begins. Now the
129 % |afterpage| package calls the working macro
130 % |\semioneside@skipleftpage| which in turn calls these macros:
131 % \begin{verbatim}
132 %\leftpagecontrolstart
133 %\leftpagecontent
134 %\leftpagecontrolend
135 %\clearpage
136 %\rightpagecontrolstart
137 % \end{verbatim}
138 %
139 % \item The |\clearpage| command in the macro sequence above
140 % finishes the left-hand page and so macro |\rightpagecontrolstart|
141 % is called at the beginning of a new right-hand page.
142 %
143 % \item Now, everything is ready to continue running text from the
144 % last right-hand page. At the next page break again |afterpage|
145 % calls |\semioneside@skipleftpage| and steps~1 to~3 are repeated.
146 % \end{enumerate}
147 % The complete procedure is illustrated in
148 % Figure~\ref{fig:procedure}.
149 % \begin{figure}[t]
150 % \centering
151 % \includegraphics{figure.1}
152 % \caption{How the \textsf{semioneside} package intercepts page
153 % breaks.}
154 % \label{fig:procedure}
155 % \end{figure}
156 %
157 %
158 % \section{Usage}
159 %
160 % As can be seen, four macros are called during type setting left-
161 % and right-hand pages. Macro
162 % |\leftpagecontent|\DescribeMacro{\leftpagecontent}{} is the main
163 % user macro. It contains the stuff that shall be output on the
164 % next left-hand page and can be modified via |\renewcommand|. If
165 % you want to have a figure on a left-hand page you should pass the
166 % whole figure environment including caption and label to
167 % |\leftpagecontent| (see the example code in file |example.tex|).
168 %
169 % The remaining three macros
170 % |\leftpagecontrolstart|\DescribeMacro{\leftpagecontrolstart},
171 % |\leftpagecontrolend|\DescribeMacro{\leftpagecontrolend}{} and
172 % |\rightpagecontrolstart|\DescribeMacro{\rightpagecontrolstart}{}
173 % are hooks and can be used to adjust page numbering, the page
174 % style of left-hand pages \emph{etc}. By default
175 % |\leftpagecontrolstart| calls |\thispagestyle{empty}|, macro
176 % |\leftpagecontrolend| is empty and macro |\rightpagecontrolstart|
177 % decreases the page counter by one. That is, left-hand pages have
178 % no head and foot line and the page number equals that of the
179 % facing right-hand page. Note, the page counter is not adjusted on
180 % a left-hand page, but on the following right-hand page.
181 %
182 % Issuing the following macro sequence in the document preamble
183 % results in a layout where left-hand pages have the same page
184 % number as the preceeding right-hand page, \emph{i.\,e.}, page
185 % numbers refer to sheets. Additionally page numbers are shown on
186 % left-hand pages:
187 % \begin{verbatim}
188 %\renewcommand*{\leftpagecontrolstart}{%
189 % \pagestyle{plain}%
190 % \addtocounter{page}{-1}%
191 %}
192 %\renewcommand*{\leftpagecontrolend}{}
193 %\renewcommand*{\rightpagecontrolstart}{}
194 % \end{verbatim}
195 %
196 % There are two more user macros,
197 % |\semionesideoff|\DescribeMacro{\semionesideoff}{} and
198 % |\semionesideon|\DescribeMacro{\semionesideon}{}, which can be used
199 % to turn semi one sided layout off and on manually in the document.
200 % You might have to insert an empty page manually before
201 % |\semionesideon| to keep left- and right-hand pages syncronized.
202 % By default, semi one sided layout is activated.
203 %
204 %
205 % \section{Known Problems}\label{sec:knownproblems}
206 %
207 % Since this package is everything but a robust solution, there are
208 % some issues you have to take care of:
209 % \begin{enumerate}
210 % \item Contents that shall be output on a left-hand page has to be
211 % declared \emph{on the preceeding} right-hand page. Since there is
212 % only a narrow window of approx. one page to declare left-hand
213 % page contents, it is recommended to finish running text first and
214 % only deal with left-hand page contents when page breaks of the
215 % document are stable.
216 %
217 % \item Paragraphs longer than one page can cause the whole
218 % mechanism to get out-of-sync. This seems to be due to \TeX's page
219 % breaking mechanism. When a paragraph breaks across several pages
220 % the |\afterpage| command is not executed at a page break (at
221 % least not reliably) and all gets mixed up. Beware of too long
222 % paragraphs!
223 %
224 % \item\label{enum:book} When using document class |book| a blank
225 % page seems to be inserted before the first |\chapter| or
226 % |\maketitle| command. A workaround is to call macro
227 % |\semionesideoff| directly after loading the package in the
228 % document preamble and call macro |\semionesideon| manually after
229 % |\maketitle| or the first |\chapter| command. See also the next
230 % issue.
231 %
232 % \item\label{enum:memoir} A similar problem was reported with the
233 % |memoir| class and |\part| command, which inserts two empty pages
234 % instead of only one. A workaround was to copy |memoir|'s
235 % definition of |\part| and remove a |\newpage| call there. In case
236 % you call this dirty hacking, you have been warned before.
237 %
238 % \item When switching semi one sided layout on and off manually in
239 % the document pages can get out-of-sync. To avoid this, try to add
240 % a |\clearpage| or |\cleardoublepage| command before
241 % |\semionesideon|. If pages are still out-of- sync try to add the
242 % following macro sequence:
243 % \begin{verbatim}
244 %\clear(double)page
245 %\leftpagecontrolstart\null\leftpagecontrolend
246 %\clearpage
247 %\rightpagecontrolstart
248 % \end{verbatim}
249 %
250 % \item At the end of the document one or two empty pages may be
251 % appended. To get rid of those just call |\semionesideoff| before
252 % |\end{document}|.
253 % \end{enumerate}
254 %
255 % I'm sure there are a lot more problems one can run into. In case
256 % you can't solve them by hand, try to set your document without
257 % the \textsf{semioneside} package and present this to your editor
258 % or boss for approval.\footnote{Don't tell them the rules are bad.
259 % Just asking if the document is ok, might be the better way.}
260 % Since figures on left-hand pages were originally meant as a help
261 % when preparing manuscripts on type writers, there is no real
262 % benefit in it in digital document preparation.
263 %
264 %
265 % \section{Tips \& Tricks}
266 %
267 % \paragraph{Symmetric and asymmetric type area}
268 % This package works with the
269 % standard classes |article|, |report| and |book|. The |article|
270 % class leads to a symmetric layout. You can get a symmetric
271 % layout with the |report| or |book| classes, too, by calling them
272 % with the |oneside| document class option (see
273 % issue~\ref{enum:book} in section~\ref{sec:knownproblems}).
274 % Omitting this option unfortunately leads to an alternating type
275 % area on right-hand pages. (I don't know why.) In case you need an
276 % asymmetric layout with the |book| class have a look at the
277 % |asymmetric| option of the |geometry| package.
278 %
279 %
280 % \section{Bugs and Development}
281 %
282 % As mentioned before, this package is no perfect solution to the
283 % problem it tries to solve, but rather a quick shot. Since I
284 % don't think I can improve on it much, I would appreciate if
285 % someone would take over development or rewrite this package from
286 % scratch to make the code more robust.
287 %
288 % Anyway, if you find bugs (and hopefully workarounds) feel free
289 % to contact me at \texttt{[email protected]}. I'll try to
290 % list them in the \emph{Known Problems} section at least.
291 %
292 % \iffalse
293 %<*figure>
294 verbatimtex
295 \documentclass{article}
296 \begin{document}
297 \footnotesize
298 etex
299 prologues := 1;
300 beginfig(1);
301 numeric pwd, pht, pdx;
302 pwd = 110bp;
303 pht = 110bp;
304 pdy = .1*pht;
305 spht = .6pht;
306
307 pickup pencircle scaled .8bp;
308 draw ( (0bp,0bp)--(2pwd,0bp)--(2pwd,spht)..{dir 190}(pwd,spht)..(0bp,spht)--cycle ) shifted (0bp,pht+pdy);
309 draw ( (pwd,0bp)--(pwd,spht) ) shifted (0bp,pht+pdy);
310 draw unitsquare xscaled 2pwd yscaled pht;
311 draw (pwd,0bp)--(pwd,pht);
312 draw ( (0bp,0bp)--(2pwd,0bp)--(2pwd,-spht)..{dir 190}(pwd,-spht)..(0bp,-spht)--cycle ) shifted (0bp,-pdy);
313 draw ( (pwd,0bp)--(pwd,-spht) ) shifted (0bp,-pdy);
314
315 label.top(btex left hand page etex, (.5pwd,spht) shifted (0bp,pht+2pdy));
316 label.top(btex right hand page etex, (1.5pwd,spht) shifted (0bp,pht+2pdy));
317 label.top(btex \parbox{100pt}{\itshape\dotfill\ running text \dotfill} etex, (1.5pwd,0bp) shifted (0bp,pht+pdy));
318 label.rt(btex \begin{tabular}{@{}l@{}}page\\break\end{tabular} etex, (2pwd,0bp) shifted (.5pdy,pht+pdy));
319 label.llft(btex \begin{tabular}[c]{@{}l@{}}called via\\\texttt{\textbackslash afterpage}\end{tabular} $\left\{\mathrm{\raisebox{-2\baselineskip}{\rule{0pt}{4\baselineskip}}}\right.$ etex, (0bp,pht) shifted (-.25pdy,0bp));
320 label.bot(btex \parbox{100pt}{\ttfamily\textbackslash leftpagecontrolstart\par\textbackslash leftpagecontent\par\textbackslash leftpagecontrolend\par\textbackslash clearpage} etex, (.5pwd,pht));
321 label.bot(btex \parbox{100pt}{\texttt{\textbackslash rightpagecontrolstart}\par\dotfill\ \textit{running text} \dotfill} etex, (1.5pwd,pht));
322 label.top(btex \parbox{100pt}{\itshape\dotfill\ running text \dotfill} etex, (1.5pwd,0bp));
323 label.rt(btex \begin{tabular}{@{}l@{}}page\\break\end{tabular} etex, (2pwd,0bp) shifted (.5pdy,0bp));
324 label.llft(btex \begin{tabular}[c]{@{}l@{}}called via\\\texttt{\textbackslash afterpage}\end{tabular} $\left\{\mathrm{\raisebox{-2\baselineskip}{\rule{0pt}{4\baselineskip}}}\right.$ etex, (0bp,-pdy) shifted (-.25pdy,0bp));
325 label.bot(btex \parbox{100pt}{\ttfamily\textbackslash leftpagecontrolstart\par\textbackslash leftpagecontent\par\textbackslash leftpagecontrolend\par\textbackslash clearpage} etex, (.5pwd,-pdy));
326 label.bot(btex \parbox{100pt}{\texttt{\textbackslash rightpagecontrolstart}\par\dotfill\ \textit{running text} \dotfill} etex, (1.5pwd,-pdy));
327
328 pickup pencircle scaled .4bp;
329 drawarrow (.25pwd,pht-45pt){dir -45}..(.8pwd,pht-30pt)..{right}(.99pwd,.95pht);
330 drawarrow ( (.25pwd,pht-45pt){dir -45}..(.8pwd,pht-30pt)..{right}(.99pwd,.95pht) ) shifted (0bp,-pht-pdy);
331 endfig;
332
333 end
334 %</figure>
335 % \fi
336 %
337 % \iffalse
338 %<*example>
339 \documentclass{article}
340 \usepackage{semioneside}
341 \usepackage[english]{babel}
342 \usepackage{blindtext}
343 \begin{document}
344 \section{Example}
345 \Blindtext[3]
346 \renewcommand{\leftpagecontent}{
347 \begin{figure}
348 \centering
349 \rule{4cm}{2cm}
350 \caption{A picture.}
351 \label{fig:picA}
352 \end{figure}
353 }
354 \Blindtext[3]
355 A reference to figure~\ref{fig:picB} on p.~\pageref{fig:picB}.
356 \renewcommand{\leftpagecontent}{
357 \begin{figure}
358 \centering
359 \rule{3cm}{2cm}
360 \caption{A second picture.}
361 \label{fig:picB}
362 \end{figure}
363 \begin{figure}
364 \centering
365 \rule{4cm}{5cm}
366 \caption{A third picture.}
367 \label{fig:picC}
368 \end{figure}
369 }
370 \Blindtext[6]
371 A reference to figure~\ref{fig:picA} on p.~\pageref{fig:picA}
372 \semionesideoff
373 \end{document}
374 %</example>
375 % \fi
376 %
377 %
378 % \StopEventually{\PrintChanges}
379 %
380 %
381 %<*package>
382 % \section{Implementation}
383 %
384 % Make sure the |afterpage| package is loaded.
385 % \begin{macrocode}
386 \RequirePackage{afterpage}
387 % \end{macrocode}
388 %
389 % \begin{macro}{\leftpagecontent}
390 % Define a macro that stores the contents that shall be output on
391 % a left-hand page.
392 % \begin{macrocode}
393 \newcommand*{\leftpagecontent}{}
394 % \end{macrocode}
395 % \end{macro}
396 %
397 % \begin{macro}{\leftpagecontrolstart}
398 % Define a macro that may contain control statements that are
399 % executed at the beginning of left-hand pages before
400 % |\leftpagecontent|. Default is to make the left-hand page
401 % style |empty| here.
402 % \begin{macrocode}
403 \newcommand*{\leftpagecontrolstart}{%
404 \thispagestyle{empty}%
405 }
406 % \end{macrocode}
407 % \end{macro}
408 %
409 % \begin{macro}{\leftpagecontrolend}
410 % Define a macro that may contain control statements that are
411 % executed at the end of left-hand pages after |\leftpagecontent|.
412 % By default, it is empty.
413 % \begin{macrocode}
414 \newcommand*{\leftpagecontrolend}{}
415 % \end{macrocode}
416 % \end{macro}
417 %
418 % \begin{macro}{\rightpagecontrolstart}
419 % Define a macro that may contain control statements that are
420 % executed at the beginning of right-hand pages before the running
421 % text continues. By default, the page counter is decreased by one
422 % here.
423 % \begin{macrocode}
424 \newcommand*{\rightpagecontrolstart}{%
425 \addtocounter{page}{-1}%
426 }
427 % \end{macrocode}
428 % \end{macro}
429 %
430 % \begin{macro}{\semioneside@longempty}
431 % Define a long \emph{empty} macro which is used in a test (see
432 % |\ifx| below).
433 % \begin{macrocode}
434 \newcommand*{\semioneside@longempty}{}
435 % \end{macrocode}
436 % \end{macro}
437 %
438 % \begin{macro}{\semioneside@skipleftpage}
439 % This is the working macro. It calls itself recursively via
440 % |\afterpage|. The recursion can be started by issuing the command
441 % |\semionesideon|. In fact, this is already done when the package
442 % is loaded.
443 % \begin{macrocode}
444 \newcommand*{\semioneside@skipleftpage}{}
445 % \end{macrocode}
446 % \end{macro}
447 %
448 % \begin{macro}{\semioneside@skipleftpagetemplate}
449 % Define a template for the working macro
450 % |\semioneside@skipleftpage|. This is used in |\semionesideon|.
451 % \begin{macrocode}
452 \newcommand*{\semioneside@skipleftpagetemplate}{%
453 \ifx\leftpagecontent\empty%
454 \let\leftpagecontent\null%
455 \fi%
456 \ifx\leftpagecontent\semioneside@longempty%
457 \let\leftpagecontent\null%
458 \fi%
459 \leftpagecontrolstart%
460 \leftpagecontent%
461 \leftpagecontrolend%
462 \clearpage%
463 \rightpagecontrolstart%
464 \afterpage{\semioneside@skipleftpage}%
465 \global\let\leftpagecontent\empty%
466 }
467 % \end{macrocode}
468 % \end{macro}
469 %
470 % \begin{macro}{\semionesideon}
471 % Define a macro to activate semi one sided layout.
472 % \begin{macrocode}
473 \newcommand*{\semionesideon}{%
474 \global\let\semioneside@skipleftpage\semioneside@skipleftpagetemplate%
475 \afterpage{\semioneside@skipleftpage}%
476 }
477 % \end{macrocode}
478 % \end{macro}
479 %
480 % \begin{macro}{\semionesideoff}
481 % Define a macro to deactivate semi one sided layout.
482 % \begin{macrocode}
483 \newcommand*{\semionesideoff}{%
484 \global\let\semioneside@skipleftpage\empty%
485 \global\let\leftpagecontent\empty%
486 }
487 % \end{macrocode}
488 % \end{macro}
489 %
490 % Switch on semi one sided layout.
491 % \begin{macrocode}
492 \semionesideon
493 % \end{macrocode}
494 %
495 %</package>
496 %
497 % \Finale