summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/lualatex/linebreaker/linebreaker-doc.tex
blob: 729c9e9eaa81aab9ac352caf972a5ddd945a0a1b (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
\documentclass{l3doc}


% \usepackage[latin,english]{babel}=15pt
\usepackage{lipsum}
\usepackage{linebreaker}
\usepackage{lua-widow-control}
\linebreakersetup{debug}
\usepackage{hyperref}
\newcommand\authormail[1]{\footnote{\textless\url{#1}\textgreater}}
\ifdefined\HCode
\renewcommand\authormail[1]{\space\textless\Link[#1]{}{}#1\EndLink\textgreater}
\fi

\ifdefined\gitdate\else\def\gitdate{Undefined}\fi
\ifdefined\version\else\def\version{Undefined}\fi

\usepackage{listings}
\usepackage{fontspec}
\setmainfont{TeX Gyre Schola}
% \setmonofont[Scale=MatchLowercase]{Inconsolatazi4}
\IfFontExistsTF{Noto Sans Mono Regular}{%
    \setmonofont[Scale=MatchLowercase]{Noto Sans Mono Regular}
}{\setmonofont{NotoMono-Regular.ttf}}
\usepackage{upquote}

\usepackage{microtype}

\newcommand\testbox[1]{%
  \parbox{150pt}{%
    \parindent=15pt%
    \tolerance=1%
    \pretolerance=1%
    #1
  }%
}

\newcommand\printtest[1]{%
  \linebreakerdisable%
  \noindent\testbox{%
    #1
    \par\medskip\noindent\hfill\textbf{Without Linebreaker}\hfill\null
  }%
  \linebreakerenable%
  \hfill%
  \testbox{%
    #1
    \par\medskip\noindent\hfill\textbf{With Linebreaker}\hfill\null
  }%
}

\title{The \texttt{Linebreaker} package}
\author{Michal Hoftich\authormail{michal.h21@gmail.com}}
\date{Version \version\\\gitdate}
\begin{document}
\maketitle
\tableofcontents

\section{Introduction}

This package tries to prevent overflow lines in paragraphs or boxes.
It changes the Lua\TeX's \verb|linebreak| callback, and it re-typesets the paragraph 
with increased values of \cmd{\tolerance} and \cmd{\emergencystretch}
until the overflow doesn't happen. If that doesn't help, it chooses the solution
with the lowest badness.


The advantage of this approach is that paragraphs that have not overflowed are
typeset with default parameters. These are changed only for problematic
paragraphs.

The code is experimental, and you may find bugs or clashes with
other packages. You can send bug reports to the package's repository on 
Github\footnote{\url{https://github.com/michal-h21/linebreaker}}.



% \noindent\begin{minipage}{220pt}
 \def\testtext{%
The example document given below creates two pages by using Lua code alone. You
will learn how to access TeX's boxes and counters from the Lua side, shipout a
page into the PDF file, create horizontal and vertical boxes (hbox and vbox),
create new nodes and manipulate the nodes links structure. The example covers
the following node types: rule, whatsit, vlist, hlist and action.
 }



\begin{figure}
\printtest\testtext%
\caption{Example of Linebreaker's effect}
\end{figure}

% \end{minipage}
\newpage
\section{Usage}

There is only \LaTeX\ package at the moment. Con\TeX t and Plain \TeX\ are not supported.
You can enable the overflow paragraph handling by loading of the Linebreaker package:

% \begin{lstlisting}{latex}
% \usepackage[options]{linebreaker}
\begin{center}
\cmd{\usepackage}\verb|{linebreaker}|
\end{center}
% \end{lstlisting}

\subsection{Enable and disable Linebreaker}

The package owerflow handling is enabled by default. You can disable it and then re-enable using the following commands:

\begin{function}{\linebreakerdisable}
Disable line-breaking processing. \LaTeX\ will typeset the following paragraphs with the default values for line-breaking.
\end{function}

\begin{function}{\linebreakerenable}
Re-enable line-breaking processing after it was disabled by \cmd{\linebreakerdisable}.
\end{function}

\subsection{Change of Linebreaker parameters}

\begin{function}{\linebreakersetup}
  Change settings of the line-breaking algorithm.
  Usage: \cmd{\linebreakersetup}\Arg{options}


\end{function}

\subsubsection{Available options for the \cmd{\linebreakersetup} command}

\begin{function}{maxcycles}
Number of attempts to re-typeset the paragraph.
\end{function}

\begin{function}{maxemergencystretch}
Maximal allowed value of \verb|\emergencystretch|.
\end{function}

\begin{function}{maxtolerance}
Maximal allowed value of \verb|tolerance|.
\end{function}

\begin{function}{debug}
Print debugging info to the terminal output.
\end{function}

\subsubsection{Example of \cmd{\linebreakersetup} use}

\begin{lstlisting}{latex}
\linebreakersetup{
  maxtolerance=90,
  maxemergencystretch=1em,
  maxcycles=4
}
\end{lstlisting}



\section{Historical background}

The motivation to create this package was a 
question\footnote{\url{http://tex.stackexchange.com/q/200989/2891}} by Frank Mittelbach on
TeX.SE. His idea was to rewrite TeX’s paragraph-building algorithm in Lua to
allow detection of rivers and similar tasks unsupported by the standard TeX
line-breaking algorithm.

As a complete rewrite of the line-breaking algorithm seemed too complicated, 
I tried a different approach. Lua\TeX\ provides  callbacks for working with node lists. 
It calls these callbacks when actions on the node lists happen, such as 
ligaturing, kerning, before line-breaking, after line-breaking, and 
callback that  handles the line-breaking process. 

There is a \verb|tex.linebreak| function, which takes
node list and table with \TeX\ parameters (like \verb|lineskip|, \verb|baselineskip|, \verb|tolerance|,
etc.). It returns a new node list, with lines broken into horizontal boxes.

My idea is to process this returned node list, detect problems and call
`tex.linebreak` with different parameters if lines overflow. At the
moment, overflow box detection works in most cases, but river detection is unusable, and it needs further corrections.

\section{License}

Permission is granted to copy, distribute and/or modify this software
under the terms of the LaTeX Project Public License, version 1.3.

\section{Changes}

\begin{description}
  \item[v0.1, 2022-02-19]
    \begin{itemize}
      \item Initial version
    \end{itemize}
\end{description}

\end{document}