summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/lscapeenhanced/lscapeenhanced.dtx
blob: 91192b5d080af421645291f1961a9cd36eb25288 (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
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
% \iffalse meta-comment
% ======================================================================
% lscapeenhanced.dtx
% Copyright © 2008–2024 Markus Kohm
%
% This work is a KOMA-Script spin-off.  For the original sources of
% KOMA-Script's `float.hak' see file `scrhack.dtx' in the KOMA-Script
% sources at <https://sourceforge.net/p/koma-script/code/>.
%
% Development is taking place as part of `scrhack' at
% <https://github.com/komascript/third-party-enhancements>.  New issues
% should be reported there as well as known issues can be found.
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, version 1.3c of the license.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.<3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later and of this work.
%
% This work has the LPPL maintenance status "author-maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
% This work consists of the file `lscapeenhanced.dtx' and `README.md'.
%
% The recommended way to install `lscapeenhanced' is to use
% the package manager of your TeX distribution.
% ======================================================================
%
%<*dtx>
\ifx\ProvidesFile\undefined\def\ProvidesFile#1[#2]{}\fi
\ProvidesFile{lscapeenhanced.dtx}
%</dtx>
%<*dtx|package>
%<package>\ProvidesPackage{lscapeenhanced}
             [2024-04-16 v1.0
%<dtx>              sources and unpack driver of
              improved lscape package]
%</dtx|package>
%<*dtx>
\ifx\documentclass\undefined
  \input docstrip.tex
  \generate{%
    \file{lscapeenhanced.sty}{%
      \from{lscapeenhanced.dtx}{package}%
    }%
  }%
\else
  \let\endbatchfile\relax
\fi
\endbatchfile
\documentclass[ngerman,USenglish]{koma-script-source-doc}
\usepackage{babel}
\usepackage{csquotes}
\usepackage[style=alphabetic]{biblatex}
\begin{filecontents}[force]{\jobname.bib}
@article{latexnews35,
  author={{The {\LaTeX} Project Team}},
  shortauthor={TLT},
  year={2022},
  month={6},
  title={Issue 35},
  journal={{\LaTeX} News},
  url={http://mirrors.ctan.org/macros/latex/base/ltnews35.pdf},
  urldate={2023-07-14},
}
@online{pkg:lscape,
  author  = {David Carlisle and {The \LaTeX{} Project Team}},
  version = {3.02},
  date    = {2020-05-28},
  title   = {\pkg*{lscape} – Place selected parts of a document in landscape},
  url     = {https://ctan.org/pkg/lscape},
  urldate = {2023-07-19},
  note    = {Modifies the margins and rotates the page contents but not the
             page number. Useful, for example, with large multipage tables, as
             it is compatible with \pkg{longtable} and \pkg{supertabular}.},
}
@manual{pkg:lscape:manual,
  author   = {David Carlisle},
  version  = {3.02},
  date     = {2020-05-08},
  title    = {The \pkg*{lscape} package},
  url      = {http://mirrors.ctan.org/macros/latex/required/graphics/lscape.pdf},
  urldate  = {2023-07-19},
  abstract = {All text, within the \env{landscape} environment is rotate
              through 90 degrees. The environment may span several pages. It
              works well with, and was originally created for, use with
              \pkg{longtable} to produce long wide tables.},
}
@online{pkg:pdflscape,
  author  = {Heiko Oberdiek},
  version = {0.13},
  date    = {2022-10-28},
  title   = {\pkg*{pdflscape} – Make landscape pages display as landscape},
  url     = {https://ctan.org/pkg/pdflscape},
  urldate = {2023-07-19},
  note    = {The package adds PDF support to the \env{landscape} environment
             of package \pkg{lscape}, by setting the PDF \texttt{/Rotate} page
             attribute. Pages with this attribute will be displayed in
             landscape orientation by conforming PDF viewers.},
}
@manual{pkg:pdflscape:manual,
  author   = {Heiko Oberdiek},
  version  = {0.13},
  date     = {2022-10-28},
  title    = {The \pkg*{pdflscape} package},
  url      = {http://mirrors.ctan.org/macros/latex/contrib/pdflscape/pdflscape.pdf},
  urldate  = {2023-07-19},
  abstract = {Package \pkg*{pdflscape} adds PDF support to the environment
              \env{landscape} of package \pkg{lscape} by setting the PDF
              page attribute \texttt{/Rotate}.},
}
@online{pkg:xpatch,
  author   = {Enrico Gregorio},
  version  = {0.3},
  date     = {2020-03-25},
  title    = {\pkg*{xpatch} – Extending \pkg{etoolbox} patching commands},
  url      = {https://ctan.org/pkg/xpatch},
  urldate  = {2023-07-19},
  note     = {The package generalises the macro patching commands provided
              by Philipp Lehmann's \pkg{etoolbox}.},
}
@manual{pkg:xpatch:manual,
  author   = {Enrico Gregorio},
  version  = {0.3},
  date     = {2020-03-25},
  title    = {The \pkg*{xpatch} package
              extending \pkg{etoolbox} patching commands},
  url      = {http://mirrors.ctan.org/macros/latex/contrib/xpatch/xpatch.pdf},
  urldate  = {2023-07-19},
  abstract = {},
}
@online{pkg:scrlfile,
  author   = {Markus Kohm},
  version  = {3.41},
  date     = {2023-07-07},
  title    = {\pkg*{scrlfile} – Installation control (not only) for
              \KOMAScript{} packages},
  url      = {https://ctan.org/pkg/scrlfile},
  urldate  = {2023-07-19},
  note     = {The package provides hooks for the execution of commands before
              or after loading files, classes or packages independent from the
              \LaTeX{} kernel version.},
}
@online{pkg:koma-script,
  author={Markus Kohm},
  version={3.41},
  date={2023-07-07},
  title={{\KOMAScript} --- A bundle of versatile classes and packages},
  url={https://ctan.org/pkg/koma-script},
  urldate={2023-07-14},
  note={The \KOMAScript{} bundle provides replacements for the \pkg*{article},
        \pkg*{report}, and \pkg*{book} classes with emphasis on typography and
        versatility. There is also a letter class.},
}
@manual{pkg:koma-script:manual:de,
  author={Markus Kohm},
  date={2023-06-16},
  title={{\KOMAScript}},
  subtitle={Die Anleitung},
  url={http://mirrors.ctan.org/macros/latex/contrib/koma-script/scrguide-de.pdf},
  urldate={2023-07-04},
}
@manual{pkg:koma-script:manual:en,
  author={Markus Kohm},
  date={2023-06-16},
  title={{\KOMAScript}},
  subtitle={The Guide},
  url={http://mirrors.ctan.org/macros/latex/contrib/koma-script/scrguide-en.pdf},
  urldate={2023-07-14},
}
\end{filecontents}
\addbibresource{\jobname.bib}
\setcounter{StandardModuleDepth}{2}
\begin{document}
  \nocite{pkg:lscape,pkg:pdflscape,pkg:koma-script}
  \DocInput{lscapeenhanced.dtx}
\end{document}
%</dtx>
%\fi
%
% \changes{v0.1}{2023/06/01}{start of \KOMAScript{} spin-off}
% \changes{v1.0}{2024/04/16}{first release as standalone package}
%
% \GetFileInfo{lscapeenhanced.dtx}
% \title{Improving ``\pkg{lscape}'' and ``\pkg{pdflscape}''}
% \author{\href{mailto:komascript@gmx.info}{Markus Kohm}^^A
%   \thanks{Repository and bug reports:
%     \url{https://github.com/komascript/third-party-enhancements}^^A
%   }%
% }
% \date{Version \filedate{} \fileversion}
% \maketitle
% \begin{abstract}
%   Package \pkg*{lscapeenhanced} has started as hack module of the
%   \KOMAScript{} package \pkg*{scrhack} years ago to fix an issue when using
%   package \pkg{lscape} with \KOMAScript{} packages \pkg{scrlayer} or
%   \pkg{scrlayer-scrpage}.  This became necessary because package
%   \pkg{lscape} has a somehow strange handling of \len{textheight}
%   resp. \len{textwidth} at landscape pages. This is not only an issue with
%   \KOMAScript{} but also other packages, e.g., \pkg{showframe}. Package
%   \pkg*{lscapeenhanced} solved this issue. This is a really small change and
%   best would be, if the \pkg*{lscape} author would at least include this
%   change optionally.
% \end{abstract}
%
% \tableofcontents
%
%\iffalse
%<*doc>
%\fi
\section{What is the Potential Issue With
  \texorpdfstring{\pkg{lscape}}{lscape}?}
\label{sec:why}

The \pkg{lscape} package defines a \env{landscape} environment to set the page
contents, but not the header or footer in landscape mode. Inside this
environment, \len{textheight} is set to the value of \len{textwidth}, but
\len{textwidth} is not set to the former value of \len{textheight}. This is
inconsistent. As far as I know, \len{textwidth} is left unchanged because
setting it to \len{textheight} could interfere with other packages or user
commands. But changing \len{textheight} also has this potential, and indeed it
breaks, for example, \pkg{showframe} and \pkg{scrlayer} and in consequence
also \pkg{scrlayer-scrpage}. Thus it would be best if \len{textheight} too
remained unchanged. \pkg*{lscapeenhanced} uses the \pkg{xpatch} package (see
\autocite{pkg:xpatch}) to modify the \env{landscape} environment's start macro
\cs{landscape} appropriately.

Incidentally, the \pkg{pdflscape} package also uses \pkg{lscape}, so
\pkg*{lscapeenhanced} affects the functioning of this package too.

\section{How to use \texorpdfstring{\pkg*{lscapeenhanced}}{lscapeenhanced}}
\label{sec:howtouse}

In the document preamble of your document you just can replace
\begin{verbatim}
  \usepackage{lscape}
\end{verbatim}
by
\begin{verbatim}
  \usepackage{lscapeenhanced}
\end{verbatim}
to load package \pkg*{lscapeenhanced}. This does still also load package
\pkg{lscape} but additionally patches one command of \pkg{lscape} to avoid
the issues shown in \autoref{sec:why}.

If you want you can alternatively also load both packages explicitly, either
\pkg{lscape} before \pkg*{lscapeenhanced} or---if you
want---\pkg*{lscapeenhanced} before \pkg{lscape}. This is also useful, if you
use a package, that uses \pkg{lscape} itself, i.e., \pkg{pdflscape}.

\DescribeOption{pdflscape}%
In case of \pkg{pdflscape} you can alternatively replace
\begin{verbatim}
  \usepackage{pdflscape}
\end{verbatim}
by
\begin{verbatim}
  \usepackage[pdflscape]{lscapeenhanced}
\end{verbatim}
in which case \pkg*{lscapeenhanced} would load \pkg{pdflscape}.

When using a class that uses \pkg{lscape}, the correct operation can be
ensured with
\begin{verbatim}
  \AddToHook{package/lscape/after}{\RequirePackage{lscapeenhanced}}
\end{verbatim}
even before \cs{documentclass}. This requires at least \LaTeX{}
2020/10/01. For older versions of \LaTeX{} you can use
\begin{verbatim}
  \RequirePackage{scrlfile}
  \AfterPackage{lscape}{\RequirePackage{lscapeenhanced}}
\end{verbatim}
also before \cs{documentclass}. This would require the \KOMAScript{} package
\pkg{scrlfile}\nocite{pkg:scrlfile}.

The user interface of \pkg*{lscapeenhanced} is the same as of \pkg{lscape}
resp. \pkg{pdflscape}, see \autocite{pkg:lscape:manual}. The only difference
is, that the issue explained in \autoref{sec:why} has been fixed.

\DescribeOption{lscape}
To deactivate the changes of \pkg*{lscapeenhanced} you can use option
\opt{lscape=false}. This option can also be changed using
\begin{verbatim}
  \SetKeys[lscapeenhanced]{lscape=false}
\end{verbatim}
or
\begin{verbatim}
  \SetKeys[lscapeenhanced]{lscape=true}
\end{verbatim}
after loading the package.
%
% \iffalse
%</doc>
% \fi
%
% \MaybeStop{\printbibliography[heading=bibintoc]\PrintIndex}
%
% \iffalse
%<*package>
% \fi
% \section{Implementation}
%
% \pkg*{lscapeenhanced} uses the new \LaTeX{} kernel feature of
% key-value-options introduced in \autocite{latexnews35}. So we need at least
% \LaTeX{} 2022-06-01:
%    \begin{macrocode}
\ifnum 0=\ifcsname IfFormatAtLeastTF\endcsname
    \IfFormatAtLeastTF{2022-06-01}{1}{0}%
  \else
    0%
  \fi\relax
  \PackageError{lscapeenhanced}{LaTeX kernel too old}{%
    The package needs at least LaTeX 2022-06-01.\MessageBreak
    This error is fatal. Loading will be aborted.%
  }%
  \endinput
\fi
\ExplSyntaxOn
%    \end{macrocode}
%
% \begin{option}{pdflscape}
% \begin{macro}{\@lscapeenhanced@req@packages}
% If the option is used (without value!) it just changes the macro
% indicating the package that should also be loaded. Package authors
% could also define the internal macro \cs{@lscapeenhanced@req@packages}.
%    \begin{macrocode}
\providecommand*{\@lscapeenhanced@req@packages}{lscape}
\DeclareKeys{%
  pdflscape .code              = {
    \renewcommand*{\@lscapeenhanced@req@packages}{lscape,pdflscape}
                                 },
  pdflscape .usage             = load,
  pdflscape .value_forbidden:n = true
}
%    \end{macrocode}
% \end{macro}
% \end{option}
%
% \begin{option}{lscape}
% \begin{macro}{\if@lscapeenhanced@lscape}
% A switch to allow to activate and deactivate usage of the change.
%    \begin{macrocode}
\newif\if@lscapeenhanced@lscape \@lscapeenhanced@lscapetrue
\DeclareKeys{%
  lscape .if    = @lscapeenhanced@lscape,
  lscape.usage  = general,
}
%    \end{macrocode}
% \end{macro}
% \end{option}
%
% Processing the options:
%    \begin{macrocode}
\ExplSyntaxOff
\ProcessKeyOptions\relax
%    \end{macrocode}
%
% Now we can request the base package(s):
%    \begin{macrocode}
\expandafter\RequirePackage\expandafter{\@lscapeenhanced@req@packages}
%    \end{macrocode}
%
% As often as possible, we do not redefine macros of \pkg{lscape}, but patch
% them using \pkg{xpatch}:
%    \begin{macrocode}
\RequirePackage{xpatch}
%    \end{macrocode}
%
% \begin{command}{\landscape}
% This command is the beginning of environment \env{landscape}. This has to be
% patched using \pkg{xpatch}.
%    \begin{macrocode}
\xpatchcmd{\landscape}{\textheight=\vsize}{%
  \if@lscapeenhanced@lscape
%    \end{macrocode}
% \begin{macro}{\@outputpage,\@lscapeenhanced@outputpage}
% \begin{ilength}{\@lscapeenhanced@textheight}
% Here the changed value of \len{textheight} is needed for initialization of
% \cs{@colht}. So we patch it to use the new internal
% \len{@lscapeenhanced@textheight} instead of \len{textheight}.
%    \begin{macrocode}
    \@lscapeenhanced@textheight=\vsize
    \let\@lscapeenhanced@outputpage\@outputpage
    \def\@outputpage{%
      \@lscapeenhanced@outputpage\global\@colht\@lscapeenhanced@textheight
    }% 
  \else
    \textheight=\vsize
  \fi
}{%
  \PackageInfo{lscapeenhanced}{\string\landscape\space patched to make
    \string\textheight\space change optional}%
}{%
  \PackageWarning{lscapeenhanced}{Cannot patch \string\landscape!\MessageBreak
    Maybe you are using a unsupported lscape version}%
  \@lscapeenhanced@lscapefalse
}
\newlength{\@lscapeenhanced@textheight}
%    \end{macrocode}
% \end{ilength}
% \end{macro}
% \end{command}
%
% \iffalse
%</package>
% \fi
%
% \Finale
% \PrintChanges
%  
% \endinput
% Local Variables:
% mode: doctex
% ispell-local-dictionary: "en_US"
% eval: (flyspell-mode 1)
% TeX-master: t
% 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"))
% End: