Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %<=*COPYRIGHT>
3 %% Copyright (c) 2011-2022 by Martin Scharrer <[email protected]>
4 %% -------------------------------------------------------------------
5 %% This work may be distributed and/or modified under the
6 %% conditions of the LaTeX Project Public License, either version 1.3
7 %% of this license or (at your option) any later version.
8 %% The latest version of this license is in
9 %% http://www.latex-project.org/lppl.txt
10 %% and version 1.3 or later is part of all distributions of LaTeX
11 %% version 2005/12/01 or later.
12 %%
13 %% This work has the LPPL maintenance status `maintained'.
14 %%
15 %% The Current Maintainer of this work is Martin Scharrer.
16 %%
17 %% This work consists of the files ifoddpage.dtx and ifoddpage.ins
18 %% and the derived filebase ifoddpage.sty.
19 %%
20 %<=/COPYRIGHT>
21 % \fi
22 %
23 % \iffalse
24 %<*driver>
25 \ProvidesFile{ifoddpage.dtx}[%
26 %<=*DATE>
27 2022/10/18
28 %<=/DATE>
29 %<=*VERSION>
30 v1.2
31 %<=/VERSION>
32 DTX file for ifoddpage package]
33 \documentclass{ydoc}
34 \GetFileInfo{ifoddpage.dtx}
35 \usepackage{ifoddpage}[\filedate]
36 \EnableCrossrefs
37 \CodelineIndex
38 \RecordChanges
39 \begin{document}
40 \DocInput{ifoddpage.dtx}
41 \PrintChanges
42 \PrintIndex
43 \end{document}
44 %</driver>
45 % \fi
46 %
47 % \CheckSum{90}
48 %
49 % \CharacterTable
50 % {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
51 % 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
52 % Digits \0\1\2\3\4\5\6\7\8\9
53 % Exclamation \! Double quote \" Hash (number) \#
54 % Dollar \$ Percent \% Ampersand \&
55 % Acute accent \' Left paren \( Right paren \)
56 % Asterisk \* Plus \+ Comma \,
57 % Minus \- Point \. Solidus \/
58 % Colon \: Semicolon \; Less than \<
59 % Equals \= Greater than \> Question mark \?
60 % Commercial at \@ Left bracket \[ Backslash \\
61 % Right bracket \] Circumflex \^ Underscore \_
62 % Grave accent \` Left brace \{ Vertical bar \|
63 % Right brace \} Tilde \~}
64 %
65 %
66 % \changes{v1.0}{2011/09/13}{First version.}
67 % \changes{v1.1}{2016/04/23}{Fixed misspelled macro name.}
68 % \changes{v1.2}{2022/10/18}{Updated documentation.}
69 %
70 %
71 % \DoNotIndex{\newcommand,\newenvironment}
72 %
73 % \GetFileInfo{ifoddpage.dtx}
74 % \author{Martin Scharrer}
75 % \email{[email protected]}
76 % \repository{https://github.com/MartinScharrer/ifoddpage}
77 % \maketitle
78 %
79 % \section{Introduction}
80 % Sometimes it is required to know if a macro is placed on an odd or even page.
81 % Simply testing the value of the \texttt{page} counter is not reliable, because \TeX\ reads and processes often more material than fits on the currently processed
82 % page in order to decide where to place the page break. Also moving material like floats can be placed on completely different pages than where the surrounding material
83 % is placed. The only reliable way to determine the correct page number is to write it to the auxiliary file using a label and read it back in the next compiler run.
84 % Labels use a so called \emph{whatsit}s (see \emph{The TeXBook}) to write the given code to the auxiliary file \emph{just when the material is shipped out}, i.e.\ a full page has
85 % been filled and is written to the output file. This way ensures that the determined page number is always correct, but adds an overhead.
86 %
87 % This package implements the described technique. A macro must be used to generate and read-back the label before the conditional can be used.
88 % A counter is used internally to provide unique names to the labels.
89 %
90 %
91 % \section{Usage}
92 % The following macros are provided for \LaTeX\ document authors:
93 %
94 % \DescribeMacro{\checkoddpage}
95 % This macro checks if the current page is odd or even by placing a label to the auxiliary file and reading it back in.
96 % This requires a second compiler run to work perfectly, but the code falls back to use the \texttt{page} counter value
97 % if the label is not yet defined, i.e.\ the label was just added or no auxiliary file existed.
98 % This fallback code might return wrong values for material just around page breaks, but
99 % is better than using a constant.
100 %
101 % Note that this macro inserts an invisible element (a so called \emph{whatsit}) which is placed on the page.
102 % It is possible that this happens to be at the very end of the last line of the page and any other code following it would then be placed
103 % on the next page. Some code like |\checkoddpage \ifoddpage odd\else even\fi| might then place the first macro on the current, say even, page but
104 % print `|even|' at the top of the next page which is odd. In order to avoid this both the check macro and the output text can be placed in the same
105 % box (e.g.\ |\mbox|). If the full content can't be placed in a box, e.g.\ because line breaking is required a |\mbox| can also be substituded by
106 % |\leavevmode| (to start a paragraph if required) and |\hbox| where the |{}| are replaced by |\bgroup| and |\egroup| so two alternative box ends can be specified:
107 %
108 % \begin{lstlisting}[gobble=2,numbers=none,basicstyle=\ttfamily]
109 % \leavevmode\hbox\bgroup
110 % \checkoddpage
111 % \ifoddpage
112 % odd\egroup\ more text
113 % \else
114 % even\egroup\ other text
115 % \fi
116 % \end{lstlisting}
117 %
118 % \noindent
119 % This boxes the \Macro\checkoddpage with the first word of both clauses. Note that in this case it the settings are local to the box scope and \Macro\ifoddpage should
120 % be used outside of it again (without another \Macro\checkoddpage).
121 %
122 % \DescribeMacro{ifoddpage}
123 % This \TeX\ conditional is set (locally) by \Macro\checkoddpage.
124 % It is true if the current page is odd, or false if it is even. This is independent from whether the \texttt{oneside} or \texttt{twoside} mode is used.
125 %
126 % \DescribeMacro{ifoddpageoroneside}
127 % This \TeX\ conditional is set (locally) by \Macro\checkoddpage.
128 % Like the previous conditional it is true if the current page is odd, or false if it is even.
129 % However, if the \texttt{oneside} mode is active it is always true.
130 % This is useful for code which needs to check if the odd or even page layout is used, because in \texttt{oneside} mode the odd page layout is used for all pages.
131 %
132 % \par\medskip\par\noindent
133 % The following macros are intended for package authors:
134 %
135 % \DescribeMacro{\@ifoddpage}{<true>}{<false>}
136 % This \LaTeX\ macro uses \Macro{ifoddpage} and executes its first argument if that conditional is true but the second argument if it is false.
137 % The \Macro\checkoddpage must be used closely beforehand to get correct results.
138 %
139 % \DescribeMacro{\@ifoddpageoroneside}{<true>}{<false>}
140 % This \LaTeX\ macro uses \Macro{ifoddpageoroneside} and executes its first argument if that conditional is true but the second argument if it is false.
141 % The \Macro\checkoddpage must be used closely beforehand to get correct results.
142 %
143 % \DescribeMacro{\oddpage@page}
144 % This macro expands (using multiple steps) to a text representation of the page number for the last \Macro\checkoddpage.
145 % It is used in this macro together with \Macro\ifodd to set the provided conditionals.
146 %
147 %
148 % \section{Similar packages}
149 % The \pkg{changepage} package and the \pkg{memoir} class also provide the core functionality of this package, i.e.\ they define \Macro\checkoddpage and \Macro\ifoddpage but no other of the mentioned macros.
150 % That package uses this conditional internally in order to allow the user to change the page layout for odd or even pages, which is its main function.
151 % The \pkg{ifoddpage} should work together with that package and class, but should be loaded last to ensure the correct functionality of \Macro{ifoddpageoroneside}.
152 % It also uses labels if it is loaded using the \texttt{strict} option.
153 % The \pkg{ifoddpage} has the following benefits over \pkg{changepage} (if the page layout doesn't have to be changed):
154 %
155 % \begin{itemize}
156 % \item Smaller code base, because no additional functionality is provided.
157 % \item The \Macro{ifoddpageoroneside} conditional is also provided which simplifies code which has to handle odd/even margins.
158 % \item The label code uses the same internal \LaTeX-core code as the normal \Macro\label and generates identical error, warning and info messages.
159 % \item The fallback page number is not constant (0) but the current \texttt{page} counter value is used, which is a good approximation.
160 % \end{itemize}
161 %
162 % \StopEventually{}
163 %
164 % \clearpage
165 % \section{Implementation}
166 %
167 % \iffalse
168 %<*ifoddpage.sty>
169 % \fi
170 % \begin{macrocode}
171 %<!COPYRIGHT>
172 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
173 \ProvidesPackage{ifoddpage}[%
174 %<!DATE>
175 %<!VERSION>
176 %<*DRIVER>
177 2099/01/01 develop
178 %</DRIVER>
179 Conditionals for odd/even page detection]
180 % \end{macrocode}
181 %
182 % \begin{macro}{\c@checkoddpage}
183 % Counter |checkoddpage| is needed to give each use of \Macro\checkoddpage an unique ID for
184 % \begin{macrocode}
185 \newcount\c@checkoddpage
186 % \end{macrocode}
187 % \end{macro}
188 %
189 % \begin{macro}{\thecheckoddpage}
190 % Expands to the value of |checkoddpage|, i.e. ID of last used \Macro\checkoddpage.
191 % \begin{macrocode}
192 \def\thecheckoddpage{\number\c@checkoddpage}
193 % \end{macrocode}
194 % \end{macro}
195 %
196 % \begin{macro}{\ifoddpage}
197 % Conditional: true if used on odd page after \Macro\checkoddpage.
198 % \begin{macrocode}
199 \newif\ifoddpage
200 % \end{macrocode}
201 % \end{macro}
202 %
203 % \begin{macro}{\ifoddpageoroneside}
204 % Conditional: true if used on odd page after \Macro\checkoddpage.
205 % Always true if used in a |oneside| document.
206 % \begin{macrocode}
207 \newif\ifoddpageoroneside
208 % \end{macrocode}
209 % \end{macro}
210 %
211 % \begin{macrocode}
212 \let\oddpage@checkpage\relax
213 % \end{macrocode}
214 %
215 % \begin{macro}{\oddpage@page}
216 % \begin{macrocode}
217 \def\oddpage@page{1}
218 % \end{macrocode}
219 % \end{macro}
220 %
221 %
222 % \begin{macro}{\oddpage@label}
223 % Produces a LaTeX label using the |checkoddpage| counter.
224 % An internal LaTeX macro is used for this.
225 % \begin{macrocode}
226 \def\oddpage@label{%
227 \@newl@bel{checkoddpage}%
228 }%
229 \write\@auxout{\noexpand\providecommand\noexpand\oddpage@label[2]{}}%
230 % \end{macrocode}
231 % \end{macro}
232 %
233 %
234 % \begin{macro}{\oddpage@checkpage}
235 % Writes the oddpage label with the current page number to the AUX file,
236 % so it can be read back during the following \LaTeX{} runs.
237 % \begin{macrocode}
238 \def\oddpage@checkpage#1{%
239 \@bsphack
240 \write\@auxout{\string\oddpage@label{#1}{\the\c@page}}%
241 \@esphack
242 }%
243 % \end{macrocode}
244 % \end{macro}
245 %
246 %
247 % \begin{macro}{\oddpage@page}
248 % Returns the page number of the last \Macro\checkoddpage macro.
249 % If there is no label for it defined in the AUX file, e.g.\ first compile run,
250 % then the current page number is used instead as a fallback.
251 % \begin{macrocode}
252 \def\oddpage@page{%
253 \expandafter\ifx\csname checkoddpage@\thecheckoddpage\endcsname\relax
254 \the\c@page
255 \else
256 \csname checkoddpage@\thecheckoddpage\endcsname
257 \fi
258 }%
259 % \end{macrocode}
260 % \end{macro}
261 %
262 %
263 % \begin{macro}{\checkoddpage}
264 % User macro to check if the current page has an odd page number.
265 % Increases |checkoddpage| counter to produce an unique ID for this macro usage.
266 % Calls \Macro\oddpage@checkpage to produce a reference entry in the AUX file.
267 % Then checks if the \Macro\oddpage@page is odd and sets
268 % \Macro{ifoddpage} and \Macro{ifoddpageoroneside} accordantly.
269 % Finally checks if the |twoside| setting is active and set \Macro{ifoddpageoroneside}
270 % to |true| if so.
271 % \begin{macrocode}
272 \DeclareRobustCommand\checkoddpage{%
273 \stepcounter{checkoddpage}%
274 \expandafter\oddpage@checkpage\expandafter{\number\c@checkoddpage}%
275 \ifodd\oddpage@page\relax
276 \oddpagetrue
277 \oddpageoronesidetrue
278 \else
279 \oddpagefalse
280 \oddpageoronesidefalse
281 \fi
282 \if@twoside\else
283 \oddpageoronesidetrue
284 \fi
285 }%
286 % \end{macrocode}
287 % \end{macro}
288 %
289 %
290 % \begin{macro}{\@ifoddpage}
291 % Wrapper around \Macro{ifoddpage}. Will expand to the next token if odd, to the second token if not.
292 % \begin{macrocode}
293 \def\@ifoddpage{%
294 \ifoddpage
295 \expandafter\@firstoftwo
296 \else
297 \expandafter\@secondoftwo
298 \fi
299 }
300 % \end{macrocode}
301 % \end{macro}
302 %
303 %
304 % \begin{macro}{\@ifoddpageoroneside}
305 % Wrapper around \Macro{ifoddpageoroneside}. Will expand to the next token if odd, to the second token if not.
306 % \begin{macrocode}
307 \def\@ifoddpageoroneside{%
308 \iftwosideoddside
309 \expandafter\@firstoftwo
310 \else
311 \expandafter\@secondoftwo
312 \fi
313 }
314 % \end{macrocode}
315 % \end{macro}
316 %
317 % \iffalse
318 %</ifoddpage.sty>
319 % \fi
320 %
321 % \Finale
322 % \endinput