Where can I find documentation for the \nolinebreak command?

Question

Where can I find documentation on how to use the \nolinebreak command?

The Guide to LaTeX2e for Authors at latex-project.org never makes mention of \nolinebreak

The source code guide states that \nolinebreak is implemented by multiplying its input parameter penalty by (-1) and passing the result into \nopagebreak.

I haven't found documentation on how to use the command.

Answer 1

The LaTeX2e source fails to emphasize that \linebreak and \nolinebreak deals with horizontal list output, while \pagebreak and \nopagebreak deals with vertical list output. It's just mentioned to be analogous.

Here is the code for \linebreak, from latex.ltx:

\def\linebreak{\@testopt{\@no@lnbk-}4}
\def\nolinebreak{\@testopt\@no@lnbk4}
\def\@no@lnbk #1[#2]{%
  \ifvmode
    \@nolnerr
  \else
    \@tempskipa\lastskip
    \unskip
    \penalty #1\@getpen{#2}%
    \ifdim\@tempskipa>\z@
      \hskip\@tempskipa
      \ignorespaces
    \fi
  \fi}

From this we see that both \linebreak and \nolinebreak calls \@no@lnbk internally. Calling \linebreak results in the first argument of \@no@lnbk to be a negative -, while \nolinebreak doesn't supply a first argument (or leaves it empty). In fact, \nolinebreak is equivalent to \linebreak[4].

Within \@no@lnbk, a test is made to ensure you're not in vertical mode (\ifvmode). If you are in vertical mode, \linebreak and \nolinebreak will result in an error (\@nolnerr or "There's no line here to end."). The following example replicates this failure:

\documentclass{article}

\begin{document}

Lorem ipsum

\linebreak

\end{document}

If you are not in vertical mode, the last skip is stored, undone (\unskip) and a \penalty is inserted. Penalties can increase or decrease the "badness" of what is being set on the page. Inserting a negative penalty (when you're using \linebreak) reduces the badness and therefore encourages a breaking point, while a positive penalty (when using \nolinebreak) increases the badness and therefore discourages a breaking point.

Once the penalty has been inserted, the original skip is replaced (and subsequent spaces inserted in the code is ignored (\ignorespaces). The penalty has to be inserted before the skip to avoid visually-odd breaking points.

---

\linebreak is equivalent to \linebreak[4], while

• \linebreak[0] inserts \penalty -0 (not necessary);
• \linebreak[1] inserts \penalty -\@lowpenalty (\penalty -51);
• \linebreak[2] inserts \penalty -\@medpenalty (\penalty -151);
• \linebreak[3] inserts \penalty -\@highpenalty (\penalty -301); and
• \linebreak[4] inserts \penalty -\@M (\penalty -10000)
• \nolinebreak inserts \penalty \@M (\penalty 10000)

Answer 2

See Sec. 9.8, texdoc latex2e. There is an online version on latexref.xyz. If you are interested in topic penalty, you can read TeX related books like The TeXbook and TeX by Topic.

Answer 3

You can find the command description in the LaTeX manual or in the LaTeX companion.

From the LaTeX manual (page 95):

Although unwanted line breaks are usually prevented with the ~ and \mbox commands described in Section 2.1.1, LaTeX also provides a \nolinebreak command that forbids TeX from breaking a line at that point. Like the \linebreak command, \nolinebreak takes a digit from 0 to 4 as an optional argument to convert the prohibition into a suggestion that this isn't a good place for a line break—the higher the number, the stronger the suggestion. A \nolinebreak[0] command is equivalent to \linebreak[0], and \nolinebreak[4] is equivalent to \nolinebreak.

On page 213:

\linebreak[num]
\nolinebreak[num]
The \linebreak command encourages and \nolinebreak discourages a line break, by an amount depending upon num, which is a digit from 0 to 4. […]