Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 % ======================================================================
3 % floatbytocbasic.dtx
4 % Copyright © 2008–2023 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 % The Current Maintainer and author of this work is Markus Kohm.
22 %
23 % This work consists of the file `floatbytocbasic.dtx' and `README.md'.
24 %
25 % The recommended way to install `floatbytocbasic' is to use
26 % the package manager of your TeX distribution.
27 % ======================================================================
28 %
29 %<*dtx>
30 \ifx\ProvidesFile\undefined\def\ProvidesFile#1[#2]{}\fi
31 \ProvidesFile{floatbytocbasic.dtx}
32 %</dtx>
33 %<*dtx|package>
34 %<package>\ProvidesPackage{floatbytocbasic}
35 [2023-08-16 v1.0
36 %<dtx> sources and unpack driver of
37 improved float package using tocbasic]
38 %</dtx|package>
39 %<*dtx>
40 \ifx\documentclass\undefined
41 \input docstrip.tex
42 \generate{%
43 \file{floatbytocbasic.sty}{%
44 \from{floatbytocbasic.dtx}{package}%
45 }%
46 }%
47 \else
48 \let\endbatchfile\relax
49 \fi
50 \endbatchfile
51 \documentclass[ngerman,USenglish]{koma-script-source-doc}
52 \usepackage{babel}
53 \usepackage{csquotes}
54 \usepackage[style=alphabetic]{biblatex}
55 \begin{filecontents}[force]{\jobname.bib}
56 @online{pkg:float,
57 author={Anselm Lingnau},
58 title={\pkg*{float} --- Improved interface for floating objects},
59 version={1.3d},
60 date={2001-11-08},
61 url={https://ctan.org/pkg/float},
62 urldate={2023-07-14},
63 note={Improves the interface for defining floating objects such as figures
64 and tables. Introduces the boxed float, the ruled float and the
65 plaintop float. You can define your own floats and improve the
66 behaviour of the old ones.},
67 }
68 @manual{pkg:float:manual,
69 author={Anselm Lingnau},
70 date={2001-11-08},
71 title={An Improved Environment for Floats},
72 url={http://mirrors.ctan.org/macros/latex/contrib/float/float.pdf},
73 urldate={2023-07-14},
74 abstract={This style option improves the interface for defining floating
75 objects such as figures and tables in \LaTeX. It adds the notion
76 of a ‘float style’ that governs appearance of floats. New kinds of
77 floats may be defined using \cs{newfloat} command analogous to
78 \cs{newtheorem}. This style option also incorporates the
79 functionality of David Carlisle’s style option \pkg{here}, giving
80 floating environments a \texttt{[H]} option which means ‘PUT IT
81 HERE’ (as opposed to the standard \texttt{[h]} option which means
82 ‘You may put it here if you like’).},
83 }
84 @online{pkg:xpatch,
85 author = {Enrico Gregorio},
86 version = {0.3},
87 date = {2020-03-25},
88 title = {\pkg*{xpatch} – Extending \pkg{etoolbox} patching commands},
89 url = {https://ctan.org/pkg/xpatch},
90 urldate = {2023-07-19},
91 note = {The package generalises the macro patching commands provided
92 by Philipp Lehmann's \pkg{etoolbox}.},
93 }
94 @manual{pkg:xpatch:manual,
95 author = {Enrico Gregorio},
96 version = {0.3},
97 date = {2020-03-25},
98 title = {The \pkg*{xpatch} package
99 extending \pkg{etoolbox} patching commands},
100 url = {http://mirrors.ctan.org/macros/latex/contrib/xpatch/xpatch.pdf},
101 urldate = {2023-07-19},
102 abstract = {},
103 }
104 @online{pkg:scrlfile,
105 author = {Markus Kohm},
106 version = {3.41},
107 date = {2023-07-07},
108 title = {\pkg*{scrlfile} – Installation control (not only) for
109 \KOMAScript{} packages},
110 url = {https://ctan.org/pkg/scrlfile},
111 urldate = {2023-07-19},
112 note = {The package provides hooks for the execution of commands before
113 or after loading files, classes or packages independent from the
114 \LaTeX{} kernel version.},
115 }
116 @online{pkg:koma-script,
117 author={Markus Kohm},
118 version={3.41},
119 date={2023-07-07},
120 title={{\KOMAScript} --- A bundle of versatile classes and packages},
121 url={https://ctan.org/pkg/koma-script},
122 urldate={2023-07-14},
123 note={The \KOMAScript{} bundle provides replacements for the \pkg*{article},
124 \pkg*{report}, and \pkg*{book} classes with emphasis on typography and
125 versatility. There is also a letter class.},
126 }
127 @online{pkg:tocbasic,
128 author={Markus Kohm},
129 version={3.41},
130 date={2023-07-07},
131 title={\pkg*{tocbasic} --- Management of tables/lists of contents (and the
132 like)},
133 url={https://ctan.org/pkg/tocbasic},
134 urldate={2023-07-14},
135 note={The package provides means to create specialised ``table of
136 contents''-like lists of features of a document.},
137 }
138 @manual{pkg:koma-script:manual:de,
139 author={Markus Kohm},
140 date={2023-06-16},
141 title={{\KOMAScript}},
142 subtitle={Die Anleitung},
143 url={http://mirrors.ctan.org/macros/latex/contrib/koma-script/scrguide-de.pdf},
144 urldate={2023-07-04},
145 }
146 @manual{pkg:koma-script:manual:en,
147 author={Markus Kohm},
148 date={2023-06-16},
149 title={{\KOMAScript}},
150 subtitle={The Guide},
151 url={http://mirrors.ctan.org/macros/latex/contrib/koma-script/scrguide-en.pdf},
152 urldate={2023-07-14},
153 }
154 \end{filecontents}
155 \addbibresource{\jobname.bib}
156 \setcounter{StandardModuleDepth}{2}
157 \begin{document}
158 \nocite{pkg:float,pkg:koma-script,pkg:tocbasic}
159 \DocInput{floatbytocbasic.dtx}
160 \end{document}
161 %</dtx>
162 %\fi
163 %
164 % \changes{v0.1}{2023/06/01}{start of \KOMAScript{} spin-off}
165 % \changes{v1.0}{2023/08/19}{first package release}
166 %
167 % \GetFileInfo{floatbytocbasic.dtx}
168 % \title{Improving Package \pkg{float} Using
169 % \href{https://komascript.de/}{\KOMAScript} Package \pkg{tocbasic}}
170 % \author{\href{mailto:[email protected]}{Markus Kohm}}
171 % \date{Version \filedate{} \fileversion}
172 % \maketitle
173 % \begin{abstract}
174 % Package \pkg*{floatbytocbasic} has started as hack module of the
175 % \KOMAScript{} package \pkg*{scrhack} years ago to fix an issue when using
176 % package \pkg{float} with \KOMAScript~3. This became necessary because
177 % package \pkg{float} still depends on an interface once proposed by the
178 % \KOMAScript{} author, but which has long since failed to meet
179 % requirements. Unfortunately, this problem could not be solved in dialog
180 % with the author of \pkg{float}. Although \pkg*{floatbytocbasic} still
181 % loads the \pkg{float} package, it then changes some internal commands to
182 % use and optimally support the \KOMAScript{} package \pkg{tocbasic}. On the
183 % one hand, the user interface of \pkg{float} remains usable unchanged, but
184 % at the same time the package benefits from many possibilities of
185 % \pkg{tocbasic}.
186 % \end{abstract}
187 %
188 % \tableofcontents
189 %
190 %\iffalse
191 %<*doc>
192 %\fi
193 \section{Why should I use this package instead of
194 \texorpdfstring{\pkg{float}}{float} only if I use a \KOMAScript{} class or
195 \KOMAScript{} package \texorpdfstring{\pkg{tocbasic}}{tocbasic}?}
196 \label{sec:whywithkomascript}
197
198 The main symptom of using a deprecated interface to \KOMAScript{} by package
199 \pkg{float}, namely the use of \cs{float@listhead} and
200 \cs{float@addtolists}, are corresponding warnings when using one of the
201 \KOMAScript{} classes at the same time, for example:
202 \begin{verbatim}
203 Class scrbook Warning: \float@addtolists detected!
204 (scrbook) Implementation of \float@addtolist became
205 (scrbook) deprecated in KOMA-Script v3.01 2008/11/14 and
206 (scrbook) has been replaced by several more flexible
207 (scrbook) features of package `tocbasic`.
208 (scrbook) Since Version 3.12 support for deprecated
209 (scrbook) \float@addtolist interface has been
210 (scrbook) restricted to only some of the KOMA-Script
211 (scrbook) features and been removed from others.
212 (scrbook) Loading of package `scrhack' may help to
213 (scrbook) avoid this warning, if you are using a
214 (scrbook) a package that still implements the
215 (scrbook) deprecated \float@addtolist interface.
216 \end{verbatim}
217 or
218 \begin{verbatim}
219 Class scrbook Warning: \float@listhead detected!
220 (scrbook) Implementation of \float@listhead became
221 (scrbook) deprecated in KOMA-Script v3.01 2008/11/14 and
222 (scrbook) has been replaced by several more flexible
223 (scrbook) features of package `tocbasic`.
224 (scrbook) Maybe implementation of \float@listhead will
225 (scrbook) removed from KOMA-Script soon.
226 (scrbook) Loading of package `scrhack' may help to
227 (scrbook) avoid this warning, if you are using a
228 (scrbook) a package that still implements the
229 (scrbook) deprecated \float@listhead interface.
230 \end{verbatim}
231
232 If you know, that the issue is because of loading package \pkg{float} you can
233 avoid it using \pkg{floatbytocbasic} as explained in \autoref{sec:howtouse}.
234
235 \section{Why should I use this package instead of
236 \texorpdfstring{\pkg{float}}{float} only if I don't use a \KOMAScript{}
237 class or package?}
238 \label{sec:whywithoutkomascript}
239
240 Package \pkg{float} does not check if a file extension or environment already
241 has been defined when using \cs{newfloat}. So several definitions of float
242 environments either with the same name or the same file extension could happen
243 by accident. Package \pkg*{floatbytocbasic} adds test to avoid such
244 issues. Alternatively you can force the definition or do the definition only
245 if needed. See description of \cs{deffloat}, \cs{renewfloat} and
246 \cs{providefloat} in \autoref{sec:howtouse} for more information.
247
248 Package \pkg{tocbasic} provides several additional features, e.g.:
249 \begin{itemize}
250 \item automatic handling of language switching using \pkg{babel},
251 \item optional numbered heading for a list/table of contents,
252 \item optional adding an entry to the table of contents for a list/table of
253 contents even if the heading is not numbered,
254 \item easy configuration of entries to a list/table of contents.
255 \end{itemize}
256 Several more features can be added by the class or other packages. See section
257 about \pkg*{tocbasic} in the \KOMAScript{} manual, either
258 \autocite{pkg:koma-script:manual:en} or \autocite{pkg:koma-script:manual:de}.
259
260 \section{How to use \texorpdfstring{\pkg*{floatbytocbasic}}{floatbytocbasic}}
261 \label{sec:howtouse}
262
263 In the document preamble of your document you just can replace
264 \begin{verbatim}
265 \usepackage{float}
266 \end{verbatim}
267 by
268 \begin{verbatim}
269 \usepackage{floatbytocbasic}
270 \end{verbatim}
271 to load package \pkg*{floatbytocbasic}. This does still also load package
272 \pkg{float} but additionally patches several commands of \pkg{float} to avoid
273 the issues shown in \autoref{sec:whywithkomascript}.
274
275 If you want you can alternatively also load both packages explicitly, either
276 \pkg{float} before \pkg{floatbytocbasic} or---if you
277 want---\pkg{floatbytocbasic} before \pkg{float}. This is also useful, if you
278 use a package, that uses \pkg*{float} itself. In this case, you always should
279 load \pkg{floatbytocbasic} \emph{before} the package, that uses
280 \pkg{float}. Otherwise it is very likely that for some new float environments
281 the enhancements of \pkg*{floatbytocbasic} will not be used. Only if
282 \pkg*{floatbytocbasic} is loaded before the first use of \cs{newfloat} can it
283 be ensured that the definition of the new sliding environments is really done
284 with the help of \pkg{tocbasic} and thus its extended user interface is used.
285
286 When using a class that uses \pkg{float}, the correct operation can be ensured
287 with
288 \begin{verbatim}
289 \AddToHook{package/float/after}{\RequirePackage{floatbytocbasic}}
290 \end{verbatim}
291 even before \cs{documentclass}. This requires at least \LaTeX{}
292 2020/10/01. For older versions of \LaTeX{} you can use
293 \begin{verbatim}
294 \RequirePackage{scrlfile}
295 \AfterPackage{float}{\RequirePackage{floatbytocbasic}}
296 \end{verbatim}
297 also before \cs{documentclass}. This would require the \KOMAScript{} package
298 \pkg{scrlfile}\nocite{pkg:scrlfile}.
299
300 \begin{description}
301 \item[Note:] You \emph{should not} load \pkg*{float} after loading package
302 \pkg*{floatrow}. However, if you do, \pkg{floatrowbytocbasic} will be
303 loaded automatically.
304 \end{description}
305
306 The user interface of \pkg*{floatbytocbasic} is the same as of \pkg{float},
307 see \autocite{pkg:float:manual}. Following we document only the differences.
308
309 \DescribeCommand{\newfloat}
310 \DescribeCommand{\providefloat}
311 \DescribeCommand{\renewfloat}
312 \DescribeCommand{\deffloat}
313 See \autocite[section~2]{pkg:float:manual} for the basic usage of \cs{newfloat}.
314 The command takes three mandatory arguments and an optional one; it is of
315 the form:
316 \begin{quote}
317 \cs{newfloat}\marg{type}\marg{placement}\marg{ext}\oarg{within}
318 \end{quote}
319 \pkg{floatbytocbasic} adds the registration of the file extension \meta{ext},
320 which is the third argument. The main problem here is to decide what to do, if
321 \meta{ext} already has been registered. Package \pkg{float} simply does not
322 care for this case. It does neither report an error nor a warning, but just
323 redefine the float \meta{type} and reuses the auxiliary file extension
324 \meta{ext}. Because of the ``\texttt{new}'' in the name of the command, we
325 have decided to do it a little bit different. If the owner of the \meta{ext}
326 is \texttt{float}, it is assumed, that using the same auxiliary file is
327 intended and only an info is written to the \file{log}-file. Otherwise an
328 error is reported. But we also decided to define three new commands:
329 \begin{quote}\raggedright
330 \cs{deffloat}\marg{type}\marg{placement}\marg{ext}\oarg{within}\\
331 \cs{providefloat}\marg{type}\marg{placement}\marg{ext}\oarg{within}\\
332 \cs{renewfloat}\marg{type}\marg{placement}\marg{ext}\oarg{within}
333 \end{quote}
334 \cs{deffloat} also does not care for already existing \meta{type} environment
335 or already registered \meta{ext}. \cs{providefloat} does not overwrite
336 existing \meta{type} environment or already registered \meta{ext} for other
337 owners but \texttt{float}. \cs{renewfloat} does overwrite only already
338 existing \meta{type} environment with registered \meta{ext}. There are also
339 cases like defined \cs{\meta{type}} but not \cs{end\meta{type}} or not defined
340 environment \meta{type} but registered \meta{ext}. But there are no special
341 commands to handle these. If users need to take care for these cases, they can
342 test for definition using the \LaTeX{} kernel macro \cs{@ifundefined} and the
343 \pkg{tocbasic} command \cs{Ifattoclist}, described in the \KOMAScript{} user
344 manuals \autocite{pkg:koma-script:manual:en}
345 resp. \autocite{pkg:koma-script:manual:de}.
346 %
347 % \iffalse
348 %</doc>
349 % \fi
350 %
351 % \MaybeStop{\printbibliography[heading=bibintoc]\PrintIndex}
352 %
353 % \iffalse
354 %<*package>
355 % \fi
356 % \section{Implementation}
357 %
358 % \pkg{floatbytocbasic} depend on \KOMAScript{} package \pkg{tocbasic}. So we
359 % load it already before everything else. We use this package also to require
360 % at least \KOMAScript{} 3.41, which is one version before the intended
361 % spin-off.
362 % \begin{macrocode}
363 \@ifpackageloaded{floatrow}{%
364 \PackageWarning{floatbytocbasic}{%
365 package incompatible with package floatrow.\MessageBreak
366 Automatically using floatrowbytocbasic%
367 }%
368 \RequirePackage{floatrowbytocbasic}%
369 \endinput
370 }{}
371 \RequirePackage{tocbasic}[2023/07/07]
372 % \end{macrocode}
373 %
374 % We also load package \pkg{float}, because we reuse most of the code:
375 % \begin{macrocode}
376 \RequirePackage{float}
377 % \end{macrocode}
378 %
379 % As often as possible, we do not redefine macors of \pkg{float}, but patch
380 % them using \pkg{xpatch}\nocite{pkg:xpatch}:
381 % \begin{macrocode}
382 \RequirePackage{xpatch}
383 % \end{macrocode}
384 %
385 % We also use the new document command interface. So if the \LaTeX{} kernel is
386 % too old, we require \pkg{xparse}:
387 % \begin{macrocode}
388 \@ifundefined{NewDocumentCommand}{%
389 \RequirePackage{xparse}%
390 }{}
391 % \end{macrocode}
392 %
393 % \begin{command}{\deffloat}
394 % Basicly \cs{deffloat} is \cs{newfloat} of \pkg{float}:
395 % \begin{macrocode}
396 \@ifundefined{NewCommandCopy}{\let\deffloat\newfloat}{%
397 \NewCommandCopy\deffloat\newfloat
398 }
399 % \end{macrocode}
400 % But we also have to take care, that a not yet registered \meta{ext} has to
401 % be registered.
402 % \begin{description}
403 % \item[Note:] We do not need to setup feature \texttt{chapteratlist}, because
404 % classes like the \KOMAScript{} classes should use
405 %\begin{verbatim}
406 % \AtAddToTocList[float]{\setuptoc{\@currext}{chapteratlist}}
407 %\end{verbatim}
408 % to implement such features.
409 % \end{description}
410 % \begin{macrocode}
411 \xpretocmd\deffloat{%
412 \Ifattoclist{#3}{%
413 \let\reserved@a\relax
414 \owneroftoc[\def\reserved@a]{#3}\relax
415 \@ifundefined{reserved@a}{}{%
416 \Ifstr{\reserved@a}{float}{%
417 \PackageInfo{floatbytocbasic}{%
418 reusing file extension `#3' for\MessageBreak
419 float type `#1'%
420 }%
421 }{%
422 \PackageWarning{floatbytocbasic}{%
423 reusing file extension `#3' of owner\MessageBreak
424 `\reserved@a' for float `#1'\MessageBreak
425 not recommended%
426 }%
427 }%
428 }%
429 }{\addtotoclist[float]{#3}}%
430 }{}{%
431 \PackageError{floatbytocbasic}{incompatible definition of
432 \string\newfloat}{%
433 Package `floatbytocbasic' depends on the original definition of package
434 `float'.\MessageBreak
435 Some changes to that definition are tolerated.\MessageBreak
436 \@ifundefined{deffloat}%
437 {But it seems the definition is completely missing!}%
438 {But the current definition is incompatible!}%
439 \MessageBreak
440 Make sure, you have installed the original package `float' as referred
441 by\Messagebreak
442 section ``References'' of the manual.%
443 }%
444 }
445 % \end{macrocode}
446 % \end{command}
447 %
448 % \begin{command}{\newfloat,\providefloat,\renewfloat}
449 % \cs{newfloat} and \cs{renewfloat} similar to \cs{newcommand} and
450 % \cs{renewcommand} do some tests and maybe report an error, before
451 % (nevertheless) defining the float.
452 % \begin{macrocode}
453 \RenewDocumentCommand{\newfloat}{mmmo}{%
454 \@tempswatrue
455 \Ifattoclist{#3}{%
456 \let\reserved@a\relax
457 \owneroftoc[\def\reserved@a]{#3}\relax
458 \@ifundefined{reserved@a}{}{%
459 \Ifstr{\reserved@a}{float}{}{%
460 \PackageError{floatbytocbasic}{%
461 reusing `#3' of owner `\reserved@a' not allowed%
462 }{%
463 Each file extension should be used only once.\MessageBreak
464 Reusing is only allowed with the same owner/category.\MessageBreak
465 You, the class, or another package already uses `#3'.\MessageBreak
466 \@eha
467 }%
468 \@tempswafalse
469 }%
470 }%
471 }{}%
472 \if@tempswa
473 \expandafter\@ifdefinable\csname #1\endcsname{%
474 \IfValueTF{#4}{%
475 \deffloat{#1}{#2}{#3}[#4]%
476 }{%
477 \deffloat{#1}{#2}{#3}%
478 }%
479 }%
480 \fi
481 }
482 \NewDocumentCommand{\providefloat}{mmmo}{%
483 \@ifundefined{#1}{%
484 \newfloat{#1}{#2}{#3}[#4]%
485 }{}%
486 }
487 \NewDocumentCommand{\renewfloat}{mmmo}{%
488 \@ifundefined{#1}{%
489 \@latex@error{Environment #1 undefined}\@ehc
490 \removefromtoclist{#3}%
491 }{%
492 \Ifattoclist{#3}{%
493 \removefromtoclist{#3}%
494 }{%
495 \PackageError{floatbytocbasic}{extension `#3' not yet registered}{%
496 I can only renew floats with already registered
497 extensions.\MessageBreak
498 \@ehc
499 }%
500 }%
501 }%
502 \expandafter\let\csname #1\endcsname\relax
503 \expandafter\let\csname end#1\endcsname\relax
504 \newfloat{#1}{#2}{#3}[#4]%
505 }
506 % \end{macrocode}
507 % \end{command}
508 %
509 % \begin{command}{\listof}
510 % This command is redefined using a complete new definition using
511 % \pkg{tocbasic}'s \cs{listoftoc}.
512 % \begin{macrocode}
513 \renewcommand*\listof[2]{%
514 \@ifundefined{ext@#1}{%
515 \PackageError{floatbytocbasic}{unknown float type `#1'}\@eha
516 }{%
517 \@ifundefined{l@#1}{\expandafter\let\csname l@#1\endcsname\l@figure
518 \@ifundefined{l@#1}{%
519 \DeclareTOCStyleEntry[level=1,numwidth=2.3em,indent=1.5em]
520 {default}{#1}%
521 }{}%
522 }{}%
523 \listoftoc[{#2}]{\csname ext@#1\endcsname}%
524 }%
525 }%
526 % \end{macrocode}
527 % \end{command}
528 %
529 % \iffalse
530 %</package>
531 % \fi
532 %
533 % \Finale
534 % \PrintChanges
535 %
536 % \endinput
537 % Local Variables:
538 % mode: doctex
539 % ispell-local-dictionary: "en_US"
540 % eval: (flyspell-mode 1)
541 % TeX-master: t
542 % End: