Debian Codegraph @

texmf-dist/doc/lualatex/linebreaker/linebreaker-doc.tex

raw
1 \documentclass{l3doc}
2
3
4 % \usepackage[latin,english]{babel}=15pt
5 \usepackage{lipsum}
6 \usepackage{linebreaker}
7 \usepackage{lua-widow-control}
8 \linebreakersetup{debug}
9 \usepackage{hyperref}
10 \newcommand\authormail[1]{\footnote{\textless\url{#1}\textgreater}}
11 \ifdefined\HCode
12 \renewcommand\authormail[1]{\space\textless\Link[#1]{}{}#1\EndLink\textgreater}
13 \fi
14
15 \ifdefined\gitdate\else\def\gitdate{Undefined}\fi
16 \ifdefined\version\else\def\version{Undefined}\fi
17
18 \usepackage{listings}
19 \usepackage{fontspec}
20 \setmainfont{TeX Gyre Schola}
21 % \setmonofont[Scale=MatchLowercase]{Inconsolatazi4}
22 \IfFontExistsTF{Noto Sans Mono Regular}{%
23 \setmonofont[Scale=MatchLowercase]{Noto Sans Mono Regular}
24 }{\setmonofont{NotoMono-Regular.ttf}}
25 \usepackage{upquote}
26
27 \usepackage{microtype}
28
29 \newcommand\testbox[1]{%
30 \parbox{150pt}{%
31 \parindent=15pt%
32 \tolerance=1%
33 \pretolerance=1%
34 #1
35 }%
36 }
37
38 \newcommand\printtest[1]{%
39 \linebreakerdisable%
40 \noindent\testbox{%
41 #1
42 \par\medskip\noindent\hfill\textbf{Without Linebreaker}\hfill\null
43 }%
44 \linebreakerenable%
45 \hfill%
46 \testbox{%
47 #1
48 \par\medskip\noindent\hfill\textbf{With Linebreaker}\hfill\null
49 }%
50 }
51
52 \title{The \texttt{Linebreaker} package}
53 \author{Michal Hoftich\authormail{[email protected]}}
54 \date{Version \version\\\gitdate}
55 \begin{document}
56 \maketitle
57 \tableofcontents
58
59 \section{Introduction}
60
61 This package tries to prevent overflow lines in paragraphs or boxes.
62 It changes the Lua\TeX's \verb|linebreak| callback, and it re-typesets the paragraph
63 with increased values of \cmd{\tolerance} and \cmd{\emergencystretch}
64 until the overflow doesn't happen. If that doesn't help, it chooses the solution
65 with the lowest badness.
66
67
68 The advantage of this approach is that paragraphs that have not overflowed are
69 typeset with default parameters. These are changed only for problematic
70 paragraphs.
71
72 The code is experimental, and you may find bugs or clashes with
73 other packages. You can send bug reports to the package's repository on
74 Github\footnote{\url{https://github.com/michal-h21/linebreaker}}.
75
76
77
78 % \noindent\begin{minipage}{220pt}
79 \def\testtext{%
80 The example document given below creates two pages by using Lua code alone. You
81 will learn how to access TeX's boxes and counters from the Lua side, shipout a
82 page into the PDF file, create horizontal and vertical boxes (hbox and vbox),
83 create new nodes and manipulate the nodes links structure. The example covers
84 the following node types: rule, whatsit, vlist, hlist and action.
85 }
86
87
88
89 \begin{figure}
90 \printtest\testtext%
91 \caption{Example of Linebreaker's effect}
92 \end{figure}
93
94 % \end{minipage}
95 \newpage
96 \section{Usage}
97
98 There is only \LaTeX\ package at the moment. Con\TeX t and Plain \TeX\ are not supported.
99 You can enable the overflow paragraph handling by loading of the Linebreaker package:
100
101 % \begin{lstlisting}{latex}
102 % \usepackage[options]{linebreaker}
103 \begin{center}
104 \cmd{\usepackage}\verb|{linebreaker}|
105 \end{center}
106 % \end{lstlisting}
107
108 \subsection{Enable and disable Linebreaker}
109
110 The package owerflow handling is enabled by default. You can disable it and then re-enable using the following commands:
111
112 \begin{function}{\linebreakerdisable}
113 Disable line-breaking processing. \LaTeX\ will typeset the following paragraphs with the default values for line-breaking.
114 \end{function}
115
116 \begin{function}{\linebreakerenable}
117 Re-enable line-breaking processing after it was disabled by \cmd{\linebreakerdisable}.
118 \end{function}
119
120 \subsection{Change of Linebreaker parameters}
121
122 \begin{function}{\linebreakersetup}
123 Change settings of the line-breaking algorithm.
124 Usage: \cmd{\linebreakersetup}\Arg{options}
125
126
127 \end{function}
128
129 \subsubsection{Available options for the \cmd{\linebreakersetup} command}
130
131 \begin{function}{maxcycles}
132 Number of attempts to re-typeset the paragraph.
133 \end{function}
134
135 \begin{function}{maxemergencystretch}
136 Maximal allowed value of \verb|\emergencystretch|.
137 \end{function}
138
139 \begin{function}{maxtolerance}
140 Maximal allowed value of \verb|tolerance|.
141 \end{function}
142
143 \begin{function}{cubic}
144 Use cubic method for the \verb|tolerance| calculation. By default, \verb|tolerance| is calculated
145 using a linear method, with constant steps. With the cubic method, each step is larger than the previous.
146 \end{function}
147
148 \begin{function}{debug}
149 Print debugging info to the terminal output.
150 \end{function}
151
152 \subsubsection{Example of \cmd{\linebreakersetup} use}
153
154 \begin{lstlisting}{latex}
155 \linebreakersetup{
156 maxtolerance=90,
157 maxemergencystretch=1em,
158 maxcycles=4
159 }
160 \end{lstlisting}
161
162
163
164 \section{Historical background}
165
166 The motivation to create this package was a
167 question\footnote{\url{http://tex.stackexchange.com/q/200989/2891}} by Frank Mittelbach on
168 TeX.SE. His idea was to rewrite TeX’s paragraph-building algorithm in Lua to
169 allow detection of rivers and similar tasks unsupported by the standard TeX
170 line-breaking algorithm.
171
172 As a complete rewrite of the line-breaking algorithm seemed too complicated,
173 I tried a different approach. Lua\TeX\ provides callbacks for working with node lists.
174 It calls these callbacks when actions on the node lists happen, such as
175 ligaturing, kerning, before line-breaking, after line-breaking, and
176 callback that handles the line-breaking process.
177
178 There is a \verb|tex.linebreak| function, which takes
179 node list and table with \TeX\ parameters (like \verb|lineskip|, \verb|baselineskip|, \verb|tolerance|,
180 etc.). It returns a new node list, with lines broken into horizontal boxes.
181
182 My idea is to process this returned node list, detect problems and call
183 `tex.linebreak` with different parameters if lines overflow. At the
184 moment, overflow box detection works in most cases, but river detection is unusable, and it needs further corrections.
185
186 \section{License}
187
188 Permission is granted to copy, distribute and/or modify this software
189 under the terms of the LaTeX Project Public License, version 1.3.
190
191 \section{Changes}
192
193 \begin{description}
194 \item[v0.1c, 2023-03-21]\hfill
195 \begin{itemize}
196 \item Pass default parameters to all calls of \verb|tex.linebreak|, in order to support Bidi text in all instances.
197 \end{itemize}
198 \item[v0.1b, 2023-03-08]\hfill
199 \begin{itemize}
200 \item Set maximal value of tolerance to 8189, bigger value doesn't have any effect.
201 \item Added \verb|cubic| method for calculating tolerance.
202 \item Explicitly set the \verb|tex.linebreak| parameters, to support paragraph direction and other paragraph variables.
203 \end{itemize}
204 \item[v0.1a, 2022-03-12]\hfill
205
206 \begin{itemize}
207 \item Fixed fatal error in the function that calculates width of last lines in paragraphs.
208 \end{itemize}
209
210 \item[v0.1, 2022-02-19]\hfill
211
212 \begin{itemize}
213 \item Initial version
214 \end{itemize}
215 \end{description}
216
217 \end{document}
218