Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 % ======================================================================
3 % lscapeenhanced.dtx
4 % Copyright © 2008–2024 Markus Kohm
5 %
6 % This work is a KOMA-Script spin-off. For the original sources of
7 % KOMA-Script's `float.hak' see file `scrhack.dtx' in the KOMA-Script
8 % sources at <https://sourceforge.net/p/koma-script/code/>.
9 %
10 % Development is taking place as part of `scrhack' at
11 % <https://github.com/komascript/third-party-enhancements>. New issues
12 % should be reported there as well as known issues can be found.
13 %
14 % This work may be distributed and/or modified under the conditions of
15 % the LaTeX Project Public License, version 1.3c of the license.
16 % The latest version of this license is in
17 % http://www.latex-project.org/lppl.txt
18 % and version 1.<3c or later is part of all distributions of LaTeX
19 % version 2005/12/01 or later and of this work.
20 %
21 % This work has the LPPL maintenance status "author-maintained".
22 %
23 % The Current Maintainer and author of this work is Markus Kohm.
24 %
25 % This work consists of the file `lscapeenhanced.dtx' and `README.md'.
26 %
27 % The recommended way to install `lscapeenhanced' is to use
28 % the package manager of your TeX distribution.
29 % ======================================================================
30 %
31 %<*dtx>
32 \ifx\ProvidesFile\undefined\def\ProvidesFile#1[#2]{}\fi
33 \ProvidesFile{lscapeenhanced.dtx}
34 %</dtx>
35 %<*dtx|package>
36 %<package>\ProvidesPackage{lscapeenhanced}
37 [2024-04-16 v1.0
38 %<dtx> sources and unpack driver of
39 improved lscape package]
40 %</dtx|package>
41 %<*dtx>
42 \ifx\documentclass\undefined
43 \input docstrip.tex
44 \generate{%
45 \file{lscapeenhanced.sty}{%
46 \from{lscapeenhanced.dtx}{package}%
47 }%
48 }%
49 \else
50 \let\endbatchfile\relax
51 \fi
52 \endbatchfile
53 \documentclass[ngerman,USenglish]{koma-script-source-doc}
54 \usepackage{babel}
55 \usepackage{csquotes}
56 \usepackage[style=alphabetic]{biblatex}
57 \begin{filecontents}[force]{\jobname.bib}
58 @article{latexnews35,
59 author={{The {\LaTeX} Project Team}},
60 shortauthor={TLT},
61 year={2022},
62 month={6},
63 title={Issue 35},
64 journal={{\LaTeX} News},
65 url={http://mirrors.ctan.org/macros/latex/base/ltnews35.pdf},
66 urldate={2023-07-14},
67 }
68 @online{pkg:lscape,
69 author = {David Carlisle and {The \LaTeX{} Project Team}},
70 version = {3.02},
71 date = {2020-05-28},
72 title = {\pkg*{lscape} – Place selected parts of a document in landscape},
73 url = {https://ctan.org/pkg/lscape},
74 urldate = {2023-07-19},
75 note = {Modifies the margins and rotates the page contents but not the
76 page number. Useful, for example, with large multipage tables, as
77 it is compatible with \pkg{longtable} and \pkg{supertabular}.},
78 }
79 @manual{pkg:lscape:manual,
80 author = {David Carlisle},
81 version = {3.02},
82 date = {2020-05-08},
83 title = {The \pkg*{lscape} package},
84 url = {http://mirrors.ctan.org/macros/latex/required/graphics/lscape.pdf},
85 urldate = {2023-07-19},
86 abstract = {All text, within the \env{landscape} environment is rotate
87 through 90 degrees. The environment may span several pages. It
88 works well with, and was originally created for, use with
89 \pkg{longtable} to produce long wide tables.},
90 }
91 @online{pkg:pdflscape,
92 author = {Heiko Oberdiek},
93 version = {0.13},
94 date = {2022-10-28},
95 title = {\pkg*{pdflscape} – Make landscape pages display as landscape},
96 url = {https://ctan.org/pkg/pdflscape},
97 urldate = {2023-07-19},
98 note = {The package adds PDF support to the \env{landscape} environment
99 of package \pkg{lscape}, by setting the PDF \texttt{/Rotate} page
100 attribute. Pages with this attribute will be displayed in
101 landscape orientation by conforming PDF viewers.},
102 }
103 @manual{pkg:pdflscape:manual,
104 author = {Heiko Oberdiek},
105 version = {0.13},
106 date = {2022-10-28},
107 title = {The \pkg*{pdflscape} package},
108 url = {http://mirrors.ctan.org/macros/latex/contrib/pdflscape/pdflscape.pdf},
109 urldate = {2023-07-19},
110 abstract = {Package \pkg*{pdflscape} adds PDF support to the environment
111 \env{landscape} of package \pkg{lscape} by setting the PDF
112 page attribute \texttt{/Rotate}.},
113 }
114 @online{pkg:xpatch,
115 author = {Enrico Gregorio},
116 version = {0.3},
117 date = {2020-03-25},
118 title = {\pkg*{xpatch} – Extending \pkg{etoolbox} patching commands},
119 url = {https://ctan.org/pkg/xpatch},
120 urldate = {2023-07-19},
121 note = {The package generalises the macro patching commands provided
122 by Philipp Lehmann's \pkg{etoolbox}.},
123 }
124 @manual{pkg:xpatch:manual,
125 author = {Enrico Gregorio},
126 version = {0.3},
127 date = {2020-03-25},
128 title = {The \pkg*{xpatch} package
129 extending \pkg{etoolbox} patching commands},
130 url = {http://mirrors.ctan.org/macros/latex/contrib/xpatch/xpatch.pdf},
131 urldate = {2023-07-19},
132 abstract = {},
133 }
134 @online{pkg:scrlfile,
135 author = {Markus Kohm},
136 version = {3.41},
137 date = {2023-07-07},
138 title = {\pkg*{scrlfile} – Installation control (not only) for
139 \KOMAScript{} packages},
140 url = {https://ctan.org/pkg/scrlfile},
141 urldate = {2023-07-19},
142 note = {The package provides hooks for the execution of commands before
143 or after loading files, classes or packages independent from the
144 \LaTeX{} kernel version.},
145 }
146 @online{pkg:koma-script,
147 author={Markus Kohm},
148 version={3.41},
149 date={2023-07-07},
150 title={{\KOMAScript} --- A bundle of versatile classes and packages},
151 url={https://ctan.org/pkg/koma-script},
152 urldate={2023-07-14},
153 note={The \KOMAScript{} bundle provides replacements for the \pkg*{article},
154 \pkg*{report}, and \pkg*{book} classes with emphasis on typography and
155 versatility. There is also a letter class.},
156 }
157 @manual{pkg:koma-script:manual:de,
158 author={Markus Kohm},
159 date={2023-06-16},
160 title={{\KOMAScript}},
161 subtitle={Die Anleitung},
162 url={http://mirrors.ctan.org/macros/latex/contrib/koma-script/scrguide-de.pdf},
163 urldate={2023-07-04},
164 }
165 @manual{pkg:koma-script:manual:en,
166 author={Markus Kohm},
167 date={2023-06-16},
168 title={{\KOMAScript}},
169 subtitle={The Guide},
170 url={http://mirrors.ctan.org/macros/latex/contrib/koma-script/scrguide-en.pdf},
171 urldate={2023-07-14},
172 }
173 \end{filecontents}
174 \addbibresource{\jobname.bib}
175 \setcounter{StandardModuleDepth}{2}
176 \begin{document}
177 \nocite{pkg:lscape,pkg:pdflscape,pkg:koma-script}
178 \DocInput{lscapeenhanced.dtx}
179 \end{document}
180 %</dtx>
181 %\fi
182 %
183 % \changes{v0.1}{2023/06/01}{start of \KOMAScript{} spin-off}
184 % \changes{v1.0}{2024/04/16}{first release as standalone package}
185 %
186 % \GetFileInfo{lscapeenhanced.dtx}
187 % \title{Improving ``\pkg{lscape}'' and ``\pkg{pdflscape}''}
188 % \author{\href{mailto:[email protected]}{Markus Kohm}^^A
189 % \thanks{Repository and bug reports:
190 % \url{https://github.com/komascript/third-party-enhancements}^^A
191 % }%
192 % }
193 % \date{Version \filedate{} \fileversion}
194 % \maketitle
195 % \begin{abstract}
196 % Package \pkg*{lscapeenhanced} has started as hack module of the
197 % \KOMAScript{} package \pkg*{scrhack} years ago to fix an issue when using
198 % package \pkg{lscape} with \KOMAScript{} packages \pkg{scrlayer} or
199 % \pkg{scrlayer-scrpage}. This became necessary because package
200 % \pkg{lscape} has a somehow strange handling of \len{textheight}
201 % resp. \len{textwidth} at landscape pages. This is not only an issue with
202 % \KOMAScript{} but also other packages, e.g., \pkg{showframe}. Package
203 % \pkg*{lscapeenhanced} solved this issue. This is a really small change and
204 % best would be, if the \pkg*{lscape} author would at least include this
205 % change optionally.
206 % \end{abstract}
207 %
208 % \tableofcontents
209 %
210 %\iffalse
211 %<*doc>
212 %\fi
213 \section{What is the Potential Issue With
214 \texorpdfstring{\pkg{lscape}}{lscape}?}
215 \label{sec:why}
216
217 The \pkg{lscape} package defines a \env{landscape} environment to set the page
218 contents, but not the header or footer in landscape mode. Inside this
219 environment, \len{textheight} is set to the value of \len{textwidth}, but
220 \len{textwidth} is not set to the former value of \len{textheight}. This is
221 inconsistent. As far as I know, \len{textwidth} is left unchanged because
222 setting it to \len{textheight} could interfere with other packages or user
223 commands. But changing \len{textheight} also has this potential, and indeed it
224 breaks, for example, \pkg{showframe} and \pkg{scrlayer} and in consequence
225 also \pkg{scrlayer-scrpage}. Thus it would be best if \len{textheight} too
226 remained unchanged. \pkg*{lscapeenhanced} uses the \pkg{xpatch} package (see
227 \autocite{pkg:xpatch}) to modify the \env{landscape} environment's start macro
228 \cs{landscape} appropriately.
229
230 Incidentally, the \pkg{pdflscape} package also uses \pkg{lscape}, so
231 \pkg*{lscapeenhanced} affects the functioning of this package too.
232
233 \section{How to use \texorpdfstring{\pkg*{lscapeenhanced}}{lscapeenhanced}}
234 \label{sec:howtouse}
235
236 In the document preamble of your document you just can replace
237 \begin{verbatim}
238 \usepackage{lscape}
239 \end{verbatim}
240 by
241 \begin{verbatim}
242 \usepackage{lscapeenhanced}
243 \end{verbatim}
244 to load package \pkg*{lscapeenhanced}. This does still also load package
245 \pkg{lscape} but additionally patches one command of \pkg{lscape} to avoid
246 the issues shown in \autoref{sec:why}.
247
248 If you want you can alternatively also load both packages explicitly, either
249 \pkg{lscape} before \pkg*{lscapeenhanced} or---if you
250 want---\pkg*{lscapeenhanced} before \pkg{lscape}. This is also useful, if you
251 use a package, that uses \pkg{lscape} itself, i.e., \pkg{pdflscape}.
252
253 \DescribeOption{pdflscape}%
254 In case of \pkg{pdflscape} you can alternatively replace
255 \begin{verbatim}
256 \usepackage{pdflscape}
257 \end{verbatim}
258 by
259 \begin{verbatim}
260 \usepackage[pdflscape]{lscapeenhanced}
261 \end{verbatim}
262 in which case \pkg*{lscapeenhanced} would load \pkg{pdflscape}.
263
264 When using a class that uses \pkg{lscape}, the correct operation can be
265 ensured with
266 \begin{verbatim}
267 \AddToHook{package/lscape/after}{\RequirePackage{lscapeenhanced}}
268 \end{verbatim}
269 even before \cs{documentclass}. This requires at least \LaTeX{}
270 2020/10/01. For older versions of \LaTeX{} you can use
271 \begin{verbatim}
272 \RequirePackage{scrlfile}
273 \AfterPackage{lscape}{\RequirePackage{lscapeenhanced}}
274 \end{verbatim}
275 also before \cs{documentclass}. This would require the \KOMAScript{} package
276 \pkg{scrlfile}\nocite{pkg:scrlfile}.
277
278 The user interface of \pkg*{lscapeenhanced} is the same as of \pkg{lscape}
279 resp. \pkg{pdflscape}, see \autocite{pkg:lscape:manual}. The only difference
280 is, that the issue explained in \autoref{sec:why} has been fixed.
281
282 \DescribeOption{lscape}
283 To deactivate the changes of \pkg*{lscapeenhanced} you can use option
284 \opt{lscape=false}. This option can also be changed using
285 \begin{verbatim}
286 \SetKeys[lscapeenhanced]{lscape=false}
287 \end{verbatim}
288 or
289 \begin{verbatim}
290 \SetKeys[lscapeenhanced]{lscape=true}
291 \end{verbatim}
292 after loading the package.
293 %
294 % \iffalse
295 %</doc>
296 % \fi
297 %
298 % \MaybeStop{\printbibliography[heading=bibintoc]\PrintIndex}
299 %
300 % \iffalse
301 %<*package>
302 % \fi
303 % \section{Implementation}
304 %
305 % \pkg*{lscapeenhanced} uses the new \LaTeX{} kernel feature of
306 % key-value-options introduced in \autocite{latexnews35}. So we need at least
307 % \LaTeX{} 2022-06-01:
308 % \begin{macrocode}
309 \ifnum 0=\ifcsname IfFormatAtLeastTF\endcsname
310 \IfFormatAtLeastTF{2022-06-01}{1}{0}%
311 \else
312 0%
313 \fi\relax
314 \PackageError{lscapeenhanced}{LaTeX kernel too old}{%
315 The package needs at least LaTeX 2022-06-01.\MessageBreak
316 This error is fatal. Loading will be aborted.%
317 }%
318 \endinput
319 \fi
320 \ExplSyntaxOn
321 % \end{macrocode}
322 %
323 % \begin{option}{pdflscape}
324 % \begin{macro}{\@lscapeenhanced@req@packages}
325 % If the option is used (without value!) it just changes the macro
326 % indicating the package that should also be loaded. Package authors
327 % could also define the internal macro \cs{@lscapeenhanced@req@packages}.
328 % \begin{macrocode}
329 \providecommand*{\@lscapeenhanced@req@packages}{lscape}
330 \DeclareKeys{%
331 pdflscape .code = {
332 \renewcommand*{\@lscapeenhanced@req@packages}{lscape,pdflscape}
333 },
334 pdflscape .usage = load,
335 pdflscape .value_forbidden:n = true
336 }
337 % \end{macrocode}
338 % \end{macro}
339 % \end{option}
340 %
341 % \begin{option}{lscape}
342 % \begin{macro}{\if@lscapeenhanced@lscape}
343 % A switch to allow to activate and deactivate usage of the change.
344 % \begin{macrocode}
345 \newif\if@lscapeenhanced@lscape \@lscapeenhanced@lscapetrue
346 \DeclareKeys{%
347 lscape .if = @lscapeenhanced@lscape,
348 lscape.usage = general,
349 }
350 % \end{macrocode}
351 % \end{macro}
352 % \end{option}
353 %
354 % Processing the options:
355 % \begin{macrocode}
356 \ExplSyntaxOff
357 \ProcessKeyOptions\relax
358 % \end{macrocode}
359 %
360 % Now we can request the base package(s):
361 % \begin{macrocode}
362 \expandafter\RequirePackage\expandafter{\@lscapeenhanced@req@packages}
363 % \end{macrocode}
364 %
365 % As often as possible, we do not redefine macros of \pkg{lscape}, but patch
366 % them using \pkg{xpatch}:
367 % \begin{macrocode}
368 \RequirePackage{xpatch}
369 % \end{macrocode}
370 %
371 % \begin{command}{\landscape}
372 % This command is the beginning of environment \env{landscape}. This has to be
373 % patched using \pkg{xpatch}.
374 % \begin{macrocode}
375 \xpatchcmd{\landscape}{\textheight=\vsize}{%
376 \if@lscapeenhanced@lscape
377 % \end{macrocode}
378 % \begin{macro}{\@outputpage,\@lscapeenhanced@outputpage}
379 % \begin{ilength}{\@lscapeenhanced@textheight}
380 % Here the changed value of \len{textheight} is needed for initialization of
381 % \cs{@colht}. So we patch it to use the new internal
382 % \len{@lscapeenhanced@textheight} instead of \len{textheight}.
383 % \begin{macrocode}
384 \@lscapeenhanced@textheight=\vsize
385 \let\@lscapeenhanced@outputpage\@outputpage
386 \def\@outputpage{%
387 \@lscapeenhanced@outputpage\global\@colht\@lscapeenhanced@textheight
388 }%
389 \else
390 \textheight=\vsize
391 \fi
392 }{%
393 \PackageInfo{lscapeenhanced}{\string\landscape\space patched to make
394 \string\textheight\space change optional}%
395 }{%
396 \PackageWarning{lscapeenhanced}{Cannot patch \string\landscape!\MessageBreak
397 Maybe you are using a unsupported lscape version}%
398 \@lscapeenhanced@lscapefalse
399 }
400 \newlength{\@lscapeenhanced@textheight}
401 % \end{macrocode}
402 % \end{ilength}
403 % \end{macro}
404 % \end{command}
405 %
406 % \iffalse
407 %</package>
408 % \fi
409 %
410 % \Finale
411 % \PrintChanges
412 %
413 % \endinput
414 % Local Variables:
415 % mode: doctex
416 % ispell-local-dictionary: "en_US"
417 % eval: (flyspell-mode 1)
418 % TeX-master: t
419 % eval: (setcar (or (cl-member "Index" (setq-local TeX-command-list (copy-alist TeX-command-list)) :key #'car :test #'string-equal) (setq-local TeX-command-list (cons nil TeX-command-list))) '("Index" "mkindex %s" TeX-run-index nil t :help "makeindex for dtx"))
420 % End: