summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tcolorbox/tcolorbox.doc.fitting.tex
blob: 20feddda9a64e0a45670c179022c4113f9c02746 (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
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
% !TeX root = tcolorbox.tex
% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
\clearpage
\section{Library \mylib{fitting}}\label{sec:fitting}%
\tcbset{external/prefix=external/fitting_}%
The library is loaded by a package option or inside the preamble by:
\begin{dispListing}
\tcbuselibrary{fitting}
\end{dispListing}

\subsection{Macros of the Library}

\begin{docCommand}{tcboxfit}{\oarg{options}\marg{box content}}
  Creates a colored box where the given \meta{box content} is fitted to
  the width and height of the box. A |tcboxfit| has to have a fixed height.
  If no fixed height is given, a square box is constructed.
  In principle, most \meta{options} for a \refEnv{tcolorbox}
  can be used for |\tcboxfit| with some restrictions. A |\tcboxfit| cannot have
  a lower part and cannot be broken.

\enlargethispage*{1cm}
\begin{dispExample}
% \usepackage{lipsum} \tcbuselibrary{raster}
\tcbset{colframe=blue!50!black,colback=red!10!white,
    boxsep=0pt,top=1mm,bottom=1mm,left=1mm,right=1mm,
    fit algorithm=hybrid*,raster equal skip=1mm}
\begin{tcbraster}[raster columns=3,raster valign=bottom]
  \tcboxfit[height=8cm]{\lipsum[1]}
  \tcboxfit[height=4cm]{\lipsum[1]}
  \tcboxfit[height=2cm]{\lipsum[1]}
\end{tcbraster}
\begin{tcbraster}[colback=green!10!white,boxsep=1mm]
  \tcboxfit[height=4cm]{\lipsum[2]}
  \tcboxfit[height=4cm,title=With a title]{\lipsum[2]}
\end{tcbraster}
\end{dispExample}
\end{docCommand}

\clearpage
\begin{marker}
See \Vref{subsec:xparse_tcboxfit} for more
elaborate methods to create new commands.
\end{marker}

\enlargethispage*{2cm}

\begin{docCommand}{newtcboxfit}{\oarg{init options}\brackets{\texttt{\textbackslash}\rmfamily\meta{name}}\oarg{number}\oarg{default}\marg{options}}
  Creates a new macro \texttt{\textbackslash}\meta{name} based on \refCom{tcboxfit}.
  Basically, |\newtcboxfit| operates like |\newcommand|.
  The new macro \texttt{\textbackslash}\meta{name} optionally takes \meta{number}$+1$ arguments, where
  \meta{default} is the default value for the optional first argument.
  The \meta{options} are given to the underlying |tcboxfit|.
  The \meta{init options} allow setting up automatic numbering,
  see Section \ref{sec:initkeys} from page \pageref{sec:initkeys}.
\begin{dispExample*}{sbs,lefthand ratio=0.6}
\newtcboxfit{\mybox}{colback=red!5!white,
  colframe=red!75!black,width=4cm,
  height=1.5cm,halign=center}

\mybox{This is my own box.}\par
\mybox{This is my own box with more text
       to be written.}
\end{dispExample*}

\begin{dispExample*}{sbs,lefthand ratio=0.6}
% \usepackage{lipsum}
\newtcboxfit{\mybox}[2]{colback=red!5!white,
  colframe=red!75!black,fonttitle=\bfseries,
  boxsep=1mm,left=0mm,right=0mm,top=0mm,
  bottom=0mm,halign=center,valign=center,
  nobeforeafter,width=#1,height=#2}

\mybox{2.5cm}{1cm}{First box}%
\mybox{2.5cm}{1cm}{Second box with more text}\\
\mybox{5cm}{2cm}{Third box with text}\\
\mybox{5cm}{3cm}{\lipsum[1]}
\end{dispExample*}

\begin{dispExample*}{sbs,lefthand ratio=0.6}
% \usepackage{lipsum}
\newtcboxfit{\mybox}[2][]{colback=red!5!white,
  colframe=red!75!black,
  width=#2,height=#2/3*2,#1}

\mybox[colback=yellow]{5cm}%
  {\lipsum[2]}
\end{dispExample*}
\end{docCommand}


\begin{docCommand}{renewtcboxfit}{\oarg{init options}\brackets{\texttt{\textbackslash}\rmfamily\meta{name}}\oarg{number}\oarg{default}\marg{options}}
  Operates like \refCom{newtcboxfit}, but based on |\renewcommand| instead of |\newcommand|.
  An existing macro is redefined.
\end{docCommand}


\clearpage

\begin{docCommands}[
    doc name        = tcbfitdim,
    doc description = {read-only \LaTeX\ length},
    doc updated     = 2020-04-24,
  ]{}
  This is a \LaTeX\ length adapted automatically by most variants of
  \refKey{/tcb/fit algorithm}. Therefore, it never is to be
  changed by the user, but may be applied read-only.
  The \refCom{tcbfitdim} corresponds to the font size and may also
  be used to calculate box margins or other distances in dependency.
  The initial and maximum value for \refCom{tcbfitdim} is set by
  \refKey{/tcb/fit basedim}.
\end{docCommands}


\begin{docCommand}{tcbfontsize}{\marg{factor}}
  Selects a font size inside a tcolorbox which is scaled with the given
  \meta{factor} relative to \refCom{tcbfitdim}.
  Also see \refKey{/tcb/fit fontsize macros}

\begin{dispExample*}{sbs,lefthand ratio=0.6}
\tcbset{colback=red!5!white,size=small,
  colframe=red!75!black}
\begin{tcolorbox}[fit basedim=10pt]
  {\tcbfontsize{0.25} Very tiny,}\\
  {\tcbfontsize{0.5} Small,}\\
  {\tcbfontsize{1} Normal,}\\
  {\tcbfontsize{2} Large,}\\
  {\tcbfontsize{4} Huge.}
\end{tcolorbox}
\end{dispExample*}
\begin{dispExample*}{sbs,lefthand ratio=0.6}
\tcbset{colback=red!5!white,size=small,
  colframe=red!75!black}
\begin{tcolorbox}[fit basedim=10pt,
    fit to height=2cm]
  {\tcbfontsize{0.25} Very tiny,}\\
  {\tcbfontsize{0.5} Small,}\\
  {\tcbfontsize{1} Normal,}\\
  {\tcbfontsize{2} Large,}\\
  {\tcbfontsize{4} Huge.}
\end{tcolorbox}
\end{dispExample*}
\end{docCommand}


\clearpage
\subsection{Option Keys of the Library}\label{subsec:fit}

The font size for the content of a box with fixed width and fixed height
can be adjusted automatically. This is called the \emph{fitbox capture mode}.
Note that the fit control algorithm
constructs a series of versions for the box and selects the 'best'.
Therefore, the compilation time is quite longer than for a normal box.
The algorithm will fail, if a different selected font size does not change the
overall size of the box content.
The \refCom{tcboxfit} macro uses this algorithm by default.


\medskip
\begin{marker}
  The fit control keys are only applicable to unbreakable boxes without
  a lower part.
  The box content should not change counters.
\end{marker}
\medskip

\enlargethispage*{5mm}
\begin{docTcbKey}{fit}{}{style, initially unset}
  Sets the \refKey{/tcb/capture} mode to |fitbox|, i.\,e.\ enables the
  font size adjustment algorithm. Thereby, a \refEnv{tcolorbox} acts
  like \refCom{tcboxfit} where the given \meta{box content} is fitted to
  the width and height of the box. Therefore, the box has to have a fixed height.
  If no fixed height is given, a square box is constructed.
  The font dimension \refCom{tcbfitdim} can also be used to adjust
  the margins of the box since a box with a tiny font may not need large
  margins. The number of constructed boxes is saved to the macro \docAuxCommand{tcbfitsteps}
  for analysis.

\begin{dispExample}
% \usepackage{lipsum}
% \tcbuselibrary{skins}
\newtcolorbox{fitting}[2][]{fit,height=#2,boxsep=1pt,valign=center,opacityupper=0.5,
  top=0.4\tcbfitdim,bottom=0.4\tcbfitdim,left=0.75\tcbfitdim,right=0.75\tcbfitdim,
  enhanced,watermark text={\tcbfitsteps},colframe=blue!75!black,colback=white,#1}

\begin{fitting}{4cm}
\lipsum[1]
\end{fitting}

\begin{fitting}{2cm}
\lipsum[2]
\end{fitting}

\begin{fitting}{1cm}
\lipsum[3]
\end{fitting}
\end{dispExample}
\end{docTcbKey}


\clearpage
\begin{docTcbKey}{fit to}{=\meta{width} and \meta{height}}{style, initially unset}
  Shortcut for using \refKey{/tcb/fit} and setting the \meta{width} and \meta{height} values
  separately.
\begin{dispExample*}{sbs,lefthand ratio=0.6}
\tcbset{colback=red!5!white,colframe=red!75!black}

\begin{tcolorbox}[fit to=3cm and 2cm]
  This box content is fitted to the given
  dimensions.
\end{tcolorbox}
\end{dispExample*}
\end{docTcbKey}


\begin{docTcbKey}{fit to height}{=\meta{height}}{style, initially unset}
  Shortcut for using \refKey{/tcb/fit} and setting the \meta{height} value separately.
\begin{dispExample*}{sbs,lefthand ratio=0.6}
\tcbset{colback=red!5!white,colframe=red!75!black}

\begin{tcolorbox}[fit to height=2cm]
  This box content is fitted to the given
  height.
\end{tcolorbox}
\end{dispExample*}
\end{docTcbKey}

\begin{docTcbKey}{fit basedim}{=\meta{length}}{no default, initially |10pt|}
  Sets the starting font dimension for the font size adjustment algorithm
  to \meta{length}. The algorithm never enlarges this dimension.
  Therefore, the final \refCom{tcbfitdim} is identical to or small than
  \meta{length}.

\begin{dispExample*}{sbs,lefthand ratio=0.6}
\tcbset{colback=red!5!white,colframe=red!75!black}

\begin{tcolorbox}[fit to=4cm and 2cm]
  Too few words for the box.
\end{tcolorbox}

\begin{tcolorbox}[fit to=4cm and 2cm,
  fit basedim=50pt]
  Enough words for the box.
\end{tcolorbox}
\end{dispExample*}
\end{docTcbKey}


\begin{docTcbKey}{fit skip}{=\meta{real value}}{no default, initially |1.2|}
  Sets the skip value of the selected font to \meta{real value} times \refCom{tcbfitdim}.

\begin{dispExample*}{sbs,lefthand ratio=0.6}
% \usepackage{lipsum}
\tcbset{colback=red!5!white,
  colframe=red!75!black,left=1mm,
  right=1mm,boxsep=0mm}

\begin{tcolorbox}[fit to=5cm and 4cm,
  fit skip=1.0  ]
  \lipsum[1]
\end{tcolorbox}
\end{dispExample*}
\end{docTcbKey}



\clearpage
\begin{docTcbKey}{fit fontsize macros}{}{style, initially unset}
  Redefines the standard \LaTeX\ font size macros
  |\tiny|, |\scriptsize|, |\footnotesize|, |\small|, |\normalsize|,
  |\large|, |\Large|, |\LARGE|, |\huge|, and |\Huge|,
  to set font sizes relative to
  the current \refCom{tcbfitdim}. Note that the display skip values for
  mathematical formulas are respected by the redefined macros.
  Also see \refCom{tcbfontsize}.

\begin{dispExample*}{sbs,lefthand ratio=0.6}
% \usepackage{lipsum}
\tcbset{colback=red!5!white,
  colframe=red!75!black,left=1mm,
  right=1mm,boxsep=0mm}

\begin{tcolorbox}[fit to height=4cm]
  {\Large\bfseries This text is
             not adapted:\par}
  \lipsum[2]
\end{tcolorbox}

\begin{tcolorbox}[fit to height=4cm,
  fit fontsize macros ]
  {\Large\bfseries This text is adapted:\par}
  \lipsum[2]
\end{tcolorbox}
\end{dispExample*}

\begin{dispExample*}{sbs,lefthand ratio=0.6}
\tcbset{colback=red!5!white,
  colframe=red!75!black,left=1mm,
  right=1mm,boxsep=0mm}

\let\realHuge=\Huge

\begin{tcolorbox}[fit basedim=7pt,
  fontupper=\normalsize,
  fit fontsize macros]
The relative relative font size macros
are also usable without the
\textit{fit} algorithm.\par
{\Huge Adapted Huge} ---
{\realHuge Original Huge}
\end{tcolorbox}

\end{dispExample*}


\begin{dispExample*}{sbs,lefthand ratio=0.6}
\tcbset{size=fbox,colback=red!5!white,
  colframe=red!75!black}

\tcboxfit[height=5cm,
  fit fontsize macros,
  fonttitle=\normalsize\bfseries,
  title=Adapted title]
{\lipsum[2]}

\end{dispExample*}
\end{docTcbKey}


\clearpage
\begin{docTcbKey}{fit height plus}{=\meta{dimension}}{no default, initially |0pt|}
  The box is allowed to enlarge the fixed height up to the given \meta{dimension},
  before a font size fit is applied. An optional \refKey{/tcb/fit width plus}
  is tried after the height adaption.
\begin{dispExample}
% \usepackage{lipsum}
\tcbset{colback=red!5!white,colframe=red!75!black,left=1mm,top=1mm,bottom=1mm,
  right=1mm,boxsep=0mm,width=3cm,height=3cm,nobeforeafter}

\begin{tcolorbox}[fit]
This is a tcolorbox.
\end{tcolorbox}
\begin{tcolorbox}[fit,fit height plus=1cm]
This is a tcolorbox.
\end{tcolorbox}
\begin{tcolorbox}[fit]
\lipsum[2]
\end{tcolorbox}
\begin{tcolorbox}[fit,fit height plus=1cm]
\lipsum[2]
\end{tcolorbox}
\end{dispExample}
\end{docTcbKey}


\begin{docTcbKey}{fit width plus}{=\meta{dimension}}{no default, initially |0pt|}
  The box is allowed to enlarge the fixed width up to the given \meta{dimension},
  before a font size fit is applied. An optional \refKey{/tcb/fit height plus}
  is tried before the width adaption.
  \enlargethispage*{1cm}
\begin{dispExample}
% \usepackage{lipsum}
\tcbset{colback=red!5!white,colframe=red!75!black,left=1mm,top=1mm,bottom=1mm,
  right=1mm,boxsep=0mm,width=3cm,height=3cm,nobeforeafter}

\begin{tcolorbox}[fit]
This is a tcolorbox.
\end{tcolorbox}
\begin{tcolorbox}[fit,fit width plus=1cm]
This is a tcolorbox.
\end{tcolorbox}
\begin{tcolorbox}[fit]
\lipsum[2]
\end{tcolorbox}
\begin{tcolorbox}[fit,fit width plus=1cm]
\lipsum[2]
\end{tcolorbox}
\end{dispExample}
\end{docTcbKey}


\begin{marker}
Typically but not necessarily, the optional title of a |tcolorbox| is not part of the fit operation.
If a \refKey{/tcb/fit width plus} is applied, the title is also adapted to
the new width. If counters are increased inside the title text, they may be
increased more than one time.
To avoid this, you are encouraged to use \refKey{/tcb/phantom} or \refKey{/tcb/step and label}
to set counters or use automatic numbering, see Subsection \ref{sec:numberedboxes}
from page \pageref{sec:numberedboxes}.
\end{marker}


\begin{docTcbKey}{fit width from}{=\meta{min} \texttt{to} \meta{max}}{style, no default}
  Sets the box width to \meta{min} and allows the width to grow up to \meta{max}.
\begin{dispExample}
% \usepackage{lipsum}
\tcbset{colback=red!5!white,colframe=red!75!black,left=1mm,top=1mm,bottom=1mm,
  right=1mm,boxsep=0mm,height=4cm}

\begin{tcolorbox}[fit,width=\linewidth/2]
\lipsum[2]
\end{tcolorbox}\par
\begin{tcolorbox}[fit width from=\linewidth/2 to \linewidth]
\lipsum[2]
\end{tcolorbox}\par
\end{dispExample}
\end{docTcbKey}

\clearpage
\begin{docTcbKey}{fit height from}{=\meta{min} \texttt{to} \meta{max}}{style, no default}
  Sets the box height to \meta{min} and allows the height to grow up to \meta{max}.
\begin{dispExample}
% \usepackage{lipsum}
\newtcolorbox{mybox}{colback=red!5!white,colframe=red!75!black,left=1mm,top=1mm,
  bottom=1mm,right=1mm,boxsep=0mm,width=4cm,nobeforeafter,
  fit height from=1cm to 8cm}

\begin{mybox}
This is a tcolorbox.
\end{mybox}
\begin{mybox}
This is a tcolorbox. This is a tcolorbox. This is a tcolorbox.
\end{mybox}
\begin{mybox}
\lipsum[2]
\end{mybox}
\end{dispExample}
\end{docTcbKey}

\clearpage
\begin{docTcbKey}{fit algorithm}{=\meta{name}}{no default, initially |fontsize|}
Sets the algorithm for the fitting process \emph{after} optionally width and height
are adapted. In the following, adapting the font size means adapting
\refCom{tcbfitdim}.
  Feasible values for \meta{name} are:
  \begin{itemize}
  \item\docValue{fontsize} (initial):
    The algorithm is a bisection method that adapts the font size until
    certain stop conditions are fulfilled. This is the most time-consuming
    method but it is robust and gives pleasant results.
    \begin{marker}
    The used font has to be freely scalable for this method!
    Other content than text is not scaled down.
    The aspect ratio is fully garanteed.
    \end{marker}
  \item\docValue{fontsize*}:\tcbdocmarginnote{\tcbdocnew{2014-10-29}}
    First, the \docValue{fontsize} algorithm is applied. If the font was scaled down
    and the resulting height is too small, the box is squeezed to fit the area.
    \begin{marker}
    The used font has to be freely scalable for this method!
    Other content than text may be slightly rescaled.
    The aspect ratio cannot be fully garanteed.
    \end{marker}
  \item\docValue{areasize}:
    The algorithm calculates the area size for the text without scaling the font.
    The text box is shaped for the needed aspect ratio in one or two
    steps. Finally, it is scaled down with a standard |\resizebox| macro.
    \begin{marker}
    The used font has not to be scalable. Every box content is scaled down.
    The aspect ratio cannot be fully garanteed.
    \end{marker}
  \item\docValue{areasize*}:\tcbdocmarginnote{\tcbdocnew{2014-10-29}}
    The \docValue{areasize} algorithm is applied, but if the content was scaled
    down and the resulting height is too small, the box is squeezed to fit the area.
    \begin{marker}
    The used font has not to be scalable. Every box content is scaled down.
    The aspect ratio cannot be fully garanteed.
    \end{marker}
  \item\docValue{hybrid}:
    First, this algorithm estimates the needed font size in one or two steps.
    Then an \docValue{areasize} fitting as above is a applied.
    \begin{marker}
    The used font has to be freely scalable for this method!
    Other content than text may be slightly rescaled.
    The aspect ratio cannot be fully garanteed.
    \end{marker}
  \item\docValue{hybrid*}:\tcbdocmarginnote{\tcbdocnew{2014-10-29}}
    First, this algorithm estimates the needed font size in one or two steps.
    Then an \docValue{areasize*} fitting as above is a applied.
    \begin{marker}
    The used font has to be freely scalable for this method!
    Other content than text may be slightly rescaled.
    The aspect ratio cannot be fully garanteed.
    \end{marker}
  \item\docValue{squeeze}:
    The text box is brutally scaled down to fit.
    \begin{marker}
    The aspect ratio is very likely to be horrible.
    You should not use this method for final documents.
    \end{marker}
\end{itemize}


\end{docTcbKey}
\begin{dispExample}
% \usepackage{lipsum}
\newtcboxfit{mybox}[1]{colback=red!5!white,colframe=red!75!black,left=1mm,top=1mm,
  bottom=1mm,right=1mm,boxsep=0mm,width=3.5cm,height=7cm,nobeforeafter,
  before upper=\textcolor{blue}{\rule{5mm}{5mm}}\ ,
  enhanced,watermark text={\tcbfitsteps},
  fonttitle=\bfseries,adjusted title=#1,fit algorithm=#1}

\mybox{fontsize}{\lipsum[2]}\hfill
\mybox{hybrid}{\lipsum[2]}\hfill
\mybox{areasize}{\lipsum[2]}\hfill
\mybox{squeeze}{\lipsum[2]}

Quality \dotfill versus \dotfill Speed
\end{dispExample}


\begin{dispExample}
% \usepackage{lipsum}
\newtcboxfit{mybox}[2]{colback=red!5!white,colframe=red!75!black,left=1mm,top=1mm,
  size=tight,width=7.2cm,height=5cm,nobeforeafter,
  before upper=\textcolor{blue}{\rule{5mm}{5mm}}\ ,
  enhanced,fonttitle=\bfseries,adjusted title=#2,fit algorithm=#1}

\mybox{hybrid}{hybrid (possible gap at end)}{\lipsum[1]}\hfill
\mybox{hybrid*}{hybrid* (no gap but possibly squeezed)}{\lipsum[1]}
\end{dispExample}


\clearpage
\begin{marker}
The following options set control parameters for the fit algorithm.
Mainly, they apply to the |fontsize| variant, see \refKey{/tcb/fit algorithm}.
The options should be seen as experimental and are likely to change in future versions,
if necessary.
\end{marker}

\begin{docTcbKey}{fit maxstep}{=\meta{number}}{no default, initially |20|}
  Sets the maximal step size for the font size adjustment algorithm.
  In normal situations, the algorithm stops before reaching the intial value of 20 steps.
  If the box content does not shrink, this value prevents an endless loop.
\end{docTcbKey}


\begin{docTcbKey}{fit maxfontdiff}{=\meta{dimension}}{no default, initially |0.1pt|}
  The algorithm stops, if the font size is determined within a deviation of
  \meta{dimension}.
\end{docTcbKey}


\begin{docTcbKey}{fit maxfontdiffgap}{=\meta{dimension}}{no default, initially |1pt|}
  The algorithm stops, if the number of lines is determined and the font size is
  determined within a deviation of \meta{dimension}.
\end{docTcbKey}


\begin{docTcbKey}{fit maxwidthdiff}{=\meta{dimension}}{no default, initially |1pt|}
  The algorithm stops, if the (optionally) flexible box width
  is determined within a deviation of \meta{dimension}.
\end{docTcbKey}


\begin{docTcbKey}{fit maxwidthdiffgap}{=\meta{dimension}}{no default, initially |10pt|}
  The algorithm stops, if the number of lines is determined and the (optionally) flexible box width
  is determined within a deviation of \meta{dimension}.
\end{docTcbKey}


\begin{docTcbKey}{fit warning}{=\meta{value}}{no default, initially |off|}
  Typically, the fit control algorithm constructs several auxiliary boxes
  to determine the optimal one. If not switched off, the construction of
  the auxiliary boxes may produce many |hbox| warnings. This option key
  changes the |\hbadness| value.
  \begin{itemize}
  \item\docValue{off}: Most of |'Underfull \hbox'| and |'Overfull \hbox'| warnings are
    switched off (including the ones for the finally used box).
  \item\docValue{on}: All warnings for all auxiliary boxes are displayed.
  \item\docValue{final}: Only warnings for the finally used box are displayed.
    Note that an additional box has to be contructed for theses messages.
  \end{itemize}
\end{docTcbKey}