% $Id: paras.tex,v 1.4 2020/01/01 19:16:14 karl Exp $
% This is part of the book TeX for the Impatient.
% Copyright (C) 2003-2020 Paul W. Abrahams, Kathryn A. Hargreaves, Karl Berry.
% See file fdl.tex for copying conditions.

\input macros
\chapter {Commands \linebreak for composing \linebreak paragraphs}

\chapterdef{paras}

This section covers commands that 
deal with characters, words, lines, and entire paragraphs.
For an explanation of the conventions used in this section,
see \headcit{Descriptions of the commands}{cmddesc}.

\begindescriptions

\section {Characters and accents}

%==========================================================================
\subsection {Letters and ligatures for European alphabets}

\begindesc
\xrdef{fornlets}
\bix^^{ligatures}
^^{special symbols}
^^{European alphabets}
%
\ctsx AA {Scandinavian letter \AA}
\ctsx aa {Scandinavian letter \aa}
\ctsx AE {\AE\ ligature}
\ctsx ae {\ae\ ligature}
\ctsx L {Polish letter \L}
\ctsx l {Polish letter \l}
\ctsx O {Danish/Norwegian letter \O}
\ctsx o {Danish/Norwegian letter \o}
\ctsx OE {\OE\ ligature}
\ctsx oe {\oe\ ligature}
\ctsx ss {German letter \ss}
\explain
These commands produce various letters and ligatures from European
alphabets.
They are useful for occasional words and phrases in these
languages---but if you need to typeset a large amount of text in a European
language, you should probably be using a version of \TeX\ adapted
to that language.\footnote{The \TeX\ Users Group (\xref{resources}) can
provide you with information about European language versions of \TeX.}

You'll need a space after these commands when you use them within a word,
so that
\TeX\ will treat the following letters as part of the word
rather than as part of the command.
You needn't be in \minref{math mode} to use these commands.
\example
{\it les \oe vres de Moli\`ere}
|
\produces
{\it les \oe vres de Moli\`ere}
\endexample
\eix^^{ligatures}
\enddesc

%==========================================================================
\subsection {Special symbols}

\begindesc
^^{special characters}
%
\easy\ctspecialx # \ctsxrdef{@pound} {pound sign \#}
\ctspecialx $ \ctsxrdef{@bucks} {dollar sign \$}
\ctspecialx % \ctsxrdef{@percent} {percent sign \%}
\ctspecialx & \ctsxrdef{@and} {ampersand \&}
\ctspecialx _ \ctsxrdef{@underscore} {underscore \_}
\ctsx lq {left quote \lq}
\ctsx rq {right quote \rq}
\aux\ctsx lbrack left bracket [
\aux\ctsx rbrack right bracket ]
\ctsx dag {dagger symbol \dag}
\ctsx ddag {double dagger symbol \ddag}
\ctsx copyright {copyright symbol \copyright}
\ctsx P {paragraph symbol \P}
\ctsx S {section symbol \S}
\explain
These commands produce various special characters and marks.  The first
five commands are necessary because \TeX\ by default
attaches special meanings to
the characters (|#|, |$|, |%|, |&|, |_|).
You needn't be in \minref{math mode} to use these commands.

You can use the dollar sign in the Computer Modern
italic fonts to get the ^{pound
sterling} symbol, as shown in the example below.

\example
\dag It'll only cost you \$9.98 over here, but in England
it's {\it \$}24.98.
|
\produces
\dag It'll only cost you \$9.98 over here, but in England
it's {\it \$}24.98.
\endexample
\enddesc

\begindesc
\cts TeX {}
\explain
This command produces the \TeX\ logo. Remember to follow it by
|\!vs| or to enclose it in a \minref{group} when you want a space
after it.

\example
A book about \TeX\ is in your hands.
|
\produces
A book about \TeX\ is in your hands.
\endexample
\enddesc

\begindesc
\cts dots {}
\explain
^^{dots}
This command produces an ^{ellipsis}, i.e., three dots, in ordinary text.
It's intended for use in mathematical writing; for an ellipsis 
between ordinary words, you should use |$\ldots$| \ctsref{\ldots} instead.
Since |\dots| includes its own space, you shouldn't follow it by 
|\!vs|.
\example
The sequence $x_1$, $x_2$, \dots, $x_\infty$
does not terminate.
|
\produces
The sequence $x_1$, $x_2$, \dots, $x_\infty$
does not terminate.
\endexample
\enddesc

\see ``Miscellaneous ordinary math symbols'' (\xref{specsyms}).
%==========================================================================
\subsection {Arbitrary characters}

\begindesc
\bix^^{characters}
\cts char {\<charcode>}
\explain
This command produces the character located at position \<charcode>
of the current font.
\example
{\char65} {\char `A} {\char `\A}
|
\produces
{\char65} {\char `A} {\char `\A}
\endexample
\enddesc

\begindesc
\cts mathchar {\<mathcode>}
\explain
This command produces the math character whose class, family, and 
font position are given by \<mathcode>.
It is only legal in math mode.
\example
\def\digger{\mathchar "027F} % Like \spadesuit in plain TeX.
% Class 0, family 2, font position "7F.
$\digger$
|
\produces
\def\digger{\mathchar "027F}
% class 0, family 2, font position "7F
$\digger$
\endexample
\enddesc

\see |\delimiter| (\xref\delimiter).
\eix^^{characters}

%==========================================================================
\subsection {Accents}

\begindesc
^^{accents}
\xrdef{accents}
%
\ctspecialx ' \ctsxrdef{@prime} {^{acute accent} as in \'e}
\ctspecialx . \ctsxrdef{@dot} {^{dot accent} as in \.n}
\ctspecialx = \ctsxrdef{@equal} {^{macron accent} as in \=r}
\ctspecialx ^ \ctsxrdef{@hat} {^{circumflex accent} as in \^o}
\ctspecialx ` \ctsxrdef{@lquote} {^{grave accent} as in \`e}
\ctspecialx " \ctsxrdef{@quote} {^{umlaut accent} as in \"o}
\ctspecialx ~ \ctsxrdef{@not} {^{tilde accent} as in \~a}
\ctsx c {^{cedilla accent} as in \c c}
\ctsx d {^{underdot accent} as in \d r}
\ctsx H {^{Hungarian umlaut accent} as in \H o}
\ctsx t {^{tie-after accent} as in \t uu}
\ctsx u {^{breve accent} as in \u r}
\ctsx v {^{check accent} as in \v o}
\explain
These commands produce accent marks in ordinary text.  You'll usually
need to leave a space after the ones denoted by a single letter
(see ``Spaces'', \xref{spaces}).

\example
Add a soup\c con of \'elan to my pin\~a colada.
|
\produces
Add a soup\c con of \'elan to my pin\~a colada.
\endexample

\margin{`see also' moved to end of group, replacing the one there.}
\enddesc

\begindesc
\cts i {}
\cts j {}
\explain
These commands produce dotless versions of the letters `i' and `j'.
You should use them instead of the ordinary `i' and `j' when you are putting
an accent above those letters in ordinary text.
^^{dotless letters}
Use the ^|\imath| and ^|\jmath| commands (\xref\imath)
for dotless `i's and `j's in math formulas.
\example
long `i' as in l\=\i fe  \quad \v\j
|
\produces
long `i' as in l\=\i fe  \quad \v\j
\endexample
\enddesc

\begindesc
\cts accent {\<charcode>}
\explain
^^{accents}
This command puts an accent over the character following this command.
The accent is the character at position \<charcode> in the current font.
\TeX\ assumes that the accent has been designed to fit over a character
$1$\thinspace ex high in the same font as the accent.  If the 
character to be accented
is taller or shorter, \TeX\ adjusts the position accordingly.  You can
change \minref{font}s between the accent and the next character, thus
drawing the accent character and the character to be accented
from different fonts.  If
the accent character isn't really intended to be
an accent, \TeX\ won't complain; it
will just typeset something ridiculous.
\example
l'H\accent94 otel des Invalides
% Position 94 of font cmr10 has a circumflex accent.
|
\produces
l'H\accent94 otel des Invalides
% Position 94 of font cmr10 has a circumflex accent.
\endexample
\see Math accents (\xref{mathaccent}).
\enddesc
%==========================================================================
\subsection {Defeating boundary ligatures}

\begindesc
\bix^^{ligatures}
\cts noboundary {}
\explain
You can defeat a ligature
or kern that \TeX\ applies to the
first or last character of a word by putting |\noboundary| just before
or just after the word.  
Certain fonts intended for languages other than English
contain a special boundary
character that \TeX\ puts at the beginning
and end of each word.
The boundary character occupies no space and is invisible when printed.
It enables \TeX\ to provide different typographical
treatment to characters at the beginning or end of a word,
since
the boundary character can be part of a sequence of
characters to be kerned or replaced by a ligature.
(None of the standard \TeX\ fonts contain this boundary character.)
The effect of |\noboundary| is to delete the
boundary character if it's there, thus preventing \TeX\
from recognizing the ligature or kern.
\eix^^{ligatures}
\enddesc

%==========================================================================
\section {Selecting fonts}

\xrdef{selfont}

%==========================================================================
\subsection {Particular fonts}

\begindesc
^^{fonts}
%
\ctsx fivebf {use $5$-point bold font}
\ctsx fivei {use $5$-point math italic font}
\ctsx fiverm {use $5$-point roman font}
\ctsx fivesy {use $5$-point math symbol font}
\ctsx sevenbf {use $7$-point bold font}
\ctsx seveni {use $7$-point math italic font}
\ctsx sevenrm {use $7$-point roman font}
\ctsx sevensy {use $7$-point math symbol font}
\ctsx tenbf {use $10$-point bold text font}
\ctsx tenex {use $10$-point math extension font}
\ctsx teni {use $10$-point math italic font}
\ctsx tenrm {use $10$-point roman text font}
\ctsx tensl {use $10$-point slanted roman font}
\ctsx tensy {use $10$-point math symbol font}
\ctsx tenit {use $10$-point italic font}
\ctsx tentt {use $10$-point typewriter font}
\explain
These commands cause \TeX\ to typeset the following text in the
specified font.  Normally you would enclose 
one of these font-selecting commands in a
group, together with the text to be set in the selected font.
Outside of a group a font-selecting command is
effective until the end of the document
(unless you override it with another such command). 
\example
See how I've reduced my weight---from
120 lbs.\ to {\sevenrm 140 lbs}.
|
\produces
See how I've reduced my weight---from
120 lbs.\ to {\sevenrm 140 lbs}.
\endexample
\enddesc

\begindesc
\cts nullfont {}
\explain
This command selects a font, built into \TeX,
that has no characters in it.  \TeX\ uses it
as a replacement for an undefined font in a family of math fonts.
\enddesc

%==========================================================================
\subsection {Type styles}

\xrdef{seltype}
\begindesc
^^{type styles}
\easy\ctsx bf {use boldface type}
\ctsx it {use italic type}
\ctsx rm {use roman type}
\ctsx sl {use slanted type}
\ctsx tt {use typewriter type}
\explain
These commands select a type style without changing the typeface or
the point size.\footnote{
\TeX\ does not provide predefined commands for changing just the point
size, e.g., |\eightpoint|.
Supporting such commands would require a great number of fonts,
most of which would never be used.
Such commands were, however, used in typesetting \texbook.}
Normally you would enclose 
one of these type style commands in a
group, together with the text to be set in the selected font.
Outside of a group a type style command is
effective until the end of the document
(unless you override it with another such command). 
\example
The Dormouse was {\it not} amused.
|
\produces
The Dormouse was {\it not} amused.
\endexample
\enddesc

\see ``Fonts in math formulas'' (\xref{mathfonts}).
%==========================================================================
\section {Uppercase and lowercase}

\begindesc
\bix^^{case conversion}
\bix^^{uppercase//conversion to}
\bix^^{lowercase//conversion to}
\cts lccode {\<charcode> \tblentry{number}}
\cts uccode {\<charcode> \tblentry{number}}
\explain
The |\lccode| and |\uccode| values for the $256$ possible input
characters specify the correspondence between the lowercase and
uppercase forms of letters.  These values are used by the |\lowercase|
and |\uppercase| commands respectively and by \TeX's hyphenation
algorithm.

\TeX\ initializes the values of |\lccode| and |\uccode| as follows:

\ulist\compact
\li The |\lccode| of a lowercase letter is the {\ascii} code for that letter.
\li The |\lccode| of an uppercase letter is the {\ascii} code for the
corresponding lowercase letter.
\li The |\uccode| of an uppercase letter is the {\ascii} code for that letter.
\li The |\uccode| of a lowercase letter is the {\ascii} code for the
corresponding uppercase letter.
\li The |\lccode| and |\uccode| of a nonletter are both zero.
\endulist

Most of the time there's no reason to change these values,
but you might want to change them if you're using a  language
that has more letters than English.
\example
\char\uccode`s \char\lccode`a \char\lccode`M
|
\produces
\char\uccode`s \char\lccode`a \char\lccode`M
\endexample
\enddesc

\begindesc
\cts lowercase {\rqbraces{\<token list>}}
\cts uppercase {\rqbraces{\<token list>}}
\explain ^^{case conversion}
These commands convert the letters in \<token list>,
i.e., those tokens with category code $11$, to their lowercase
and uppercase forms.
The conversion of a letter is defined by its |\lccode| (for lowercase)
or |\uccode| (for uppercase) table value.
Tokens in the list that are not letters are not affected---even if the
tokens are \minref{macro} calls or other commands that expand into letters.
\example
\def\x{Cd} \lowercase{Ab\x} \uppercase{Ab\x}
|
\produces
\def\x{Cd} \lowercase{Ab\x} \uppercase{Ab\x}

\eix^^{case conversion}
\eix^^{uppercase//conversion to}
\eix^^{lowercase//conversion to}
\endexample
\enddesc

%==========================================================================
\section {Interword spacing}

\begindesc
\bix^^{spaces//interword}
\easy\ctsbasic {\\\vs}{}
\blankidxref\ctsxrdef{@space}
\explain
This command explicitly produces an interword
space called a ``^{control space}''.
A control space is useful when a
letter occurs immediately after a control sequence, or in any other
circumstance where you don't want two tokens to be run together in the
output.
The amount of space produced by |\!vs|
is independent of preceding punctuation, i.e., its space factor
(\xref\spacefactor) is $1000$.

Incidentally, if you want to print the `\vs' ^^{visible space}
character that we've used here to denote a space, you can get it by typing
|{\tt \char `\ }|.

\example
The Dormouse was a \TeX\ expert, but he never let on.
|
\produces
The Dormouse was a \TeX\ expert, but he never let on.
\endexample
\enddesc

\begindesc
\cts space {}
\explain
This command is equivalent to an input space character.
It differs from ^|\ | in that its
width \emph{can} be affected by preceding punctuation.
\example
Yes.\space No.\space Maybe.\par
Yes.\!vs!.No.\!vs!.Maybe.

|
\produces
Yes.\space No.\space Maybe.\par
Yes.\ No.\ Maybe.
\endexample
\enddesc

\begindesc
\ctsact  ^^M \xrdef{@newline}
\explain
This construct produces the ^{end of line} character.
It normally has two effects when \TeX\ encounters it in 
your input:
\olist
\li It acts as a command, producing either an input space
(if it comes at the end of a nonblank line)
or a |\par| token (if it comes at the end of a blank line).
^^|\par//from empty line|
\li It ends the input line, causing \TeX\ to ignore the remaining
characters on the line.
\endolist
\noindent
However, |^^M| does \emph{not} end the line when it appears in the
context |`\^^M|, denoting the ASCII code for control-M (the number $13$).
You can change the meaning of |^^M|
by giving it a different \minref{category code}.
See \xrefpg{twocarets} for a more general explanation of the |^^| notation.
\example
Hello.^^MGoodbye.
Goodbye again.\par
The \char `\^^M\ character.\par
% The fl ligature is at position 13 of font cmr10
\number `\^^M\ is the end of line code.\par
Again, \number `^^M is the end of line code,
isn't it? % 32 is the ASCII code for a space
|
\produces
{\catcode `\^ = 7 % disable indexing use within this display
Hello.^^MGoodbye
Goodbye again.\par
The \char `\^^M\ character.\par
\number `\^^M\ is the end of line code.\par
Again, \number `^^M is the end of line code,
isn't it?}
\endexample
\enddesc

\begindesc
\easy\ctsact ~ \xrdef{@not}
\explain
The \minref{active character} `|~|', called a ``^{tie}'', 
produces a normal interword space
between two words and links those words so that
a line break will not occur between them.
You should use a tie in any context where a line break would be confusing,
e.g., before a middle initial, after an abbreviation such as ``Dr.'',
or after ``Fig.'' in ``Fig.~8''.

\example
P.D.Q.~Bach (1807--1742), the youngest and most
imitative son of Johann~S. Bach, composed the
{\sl Concerto for Horn and Hardart}.
|
\produces
\margin{The inversion of dates is deliberate---cf. Peter Schickele.}
P.D.Q.~Bach (1807--1742), the youngest and most
imitative son of Johann~S. Bach, composed the
{\sl Concerto for Horn and Hardart}.
\endexample\enddesc

\begindesc
\easy\ctspecial / \ctsxrdef{@slash}
\explain
Every character in a \TeX\ \minref{font}
has an ``^{italic correction}'' associated with it, although
the italic correction
is normally zero for a character in an unslanted (upright) font.
The italic correction specifies the extra space that's needed
when you're switching from a slanted font (not necessarily
an italic font) to an unslanted font.  
The extra
space is needed because a slanted character projects into the
space that follows it, making the space look too small when the
next character is unslanted.
The metrics file for a font includes the italic correction of each 
character in the font.
^^{metrics file//italic correction in}

The |\/| command
produces an ^{italic correction} for the preceding character.
You should insert an italic correction when you're switching from
a slanted font to an unslanted font,
except when the next character is a period or comma.
\example
However, {\it somebody} ate {\it something}: that's clear.

However, {\it somebody\/} ate {\it something\/}:
that's clear.
|
\produces
However, {\it somebody} ate {\it something}: that's clear.

However, {\it somebody\/} ate {\it something\/}:
that's clear.
\endexample
\enddesc

\begindesc
\cts frenchspacing {}
\cts nonfrenchspacing {}
\explain
^^{interword spacing}
\TeX\ normally adjusts the spacing between words to account for
punctuation marks.  For example, it inserts extra space at the end of a
sentence and adds some stretch to the \minref{glue} following any
punctuation mark there.  The |\frenchspacing| command tells \TeX\ to make
the interword spacing independent of punctuation, while the
|\nonfrenchspacing| command tells \TeX\ to use its normal spacing rules.  
If you don't specify
|\frenchspacing|, you'll get \TeX's normal spacing.

See \xrefpg{periodspacing} for advice on how to control \TeX's treatment
of punctuation at the end of sentences.

\example
{\frenchspacing  An example: two sentences. Right? No.\par}
{An example: two sentences. Right? No. \par}%
|
\produces
{\frenchspacing  An example: two sentences. Right? No.\par}
{An example: two sentences. Right? No. \par}%
\endexample

\enddesc

\begindesc
\cts obeyspaces {}
\explain
\TeX\ normally condenses a sequence of several spaces to a single space.
|\obeyspaces| instructs \TeX\ to produce a space in the output
for each space in the input.
|\obeyspaces| does not cause spaces at the beginning of a line
to show up, however; for that we recommend the |\obey!-white!-space|
command defined in |eplain.tex| 
(\xref{ewhitesp}).
^^|\obeywhitespace|
|\obeyspaces| is often useful when you're typesetting something,
computer input for example,
in a monospaced font (one in which each character takes up the
same amount of space)
and you want to show exactly what each line of input looks like.

You can use the |\obeylines| command (\xref{\obeylines}) to get \TeX\
to follow the line boundaries of your input.  |\obeylines| is often
used in combination with |\obeyspaces|.
\example 
These     spaces    are    closed   up
{\obeyspaces but   these  are     not   }.
|
\produces
These     spaces    are    closed   up
{\obeyspaces but   these  are     not   }.
\endexample
\enddesc

\begindesc
\cts spacefactor {\param{number}}
\cts spaceskip {\param{glue}}
\cts xspaceskip {\param{glue}}
\cts sfcode {\<charcode> \tblentry{number}}
\explain
These primitive \minref{parameter}s affect how much space \TeX\
puts between two adjacent words, i.e., the ^{interword spacing}.
The normal interword spacing is supplied by the current font.
As \TeX\ is processing a \minref{horizontal list}, it keeps track of the
^{space factor} $f$ in |\spacefactor|.
As it processes each input character $c$, it updates $f$ according to the
value of $f_c$, the space factor code of $c$ (see below).
For most characters, $f_c$ is $1000$ and \TeX\ sets $f$ to $1000$.
(The initial value of $f$ is also $1000$.)
When \TeX\ sees an interword space, it adjusts the size of that space 
by multiplying the stretch and shrink of that space by 
$f/1000$ and $1000/f$ respectively.
Thus:
\olist\compact
\li If $f=1000$, the interword space keeps its normal value.
\li If $f<1000$, the interword space gets less \minref{stretch}
and more \minref{shrink}.
\li If $f>1000$, the interword space gets more \minref{stretch}
and less \minref{shrink}.
\endolist
% > changed to \ge on the next line after second edition was typeset. 
% Correction made by A-W production.
In addition, if $f\ge2000$ the interword space is further increased by the
``extra space'' parameter associated with the current font.

Each 
input character $c$ has an entry in the |\sfcode| (space factor code)
table.
The |\sfcode| table entry is independent of the font.
Usually \TeX\ just sets $f$ to $f_c$ after it processes $c$.
However:
\ulist
\li If $f_c$ is zero, \TeX\ leaves $f$ unchanged.
Thus a character such as `|)|' in \plainTeX,
for which $f_c$ is zero, is essentially transparent to
the interword space calculation.
\li If $f<1000<f_c$, \TeX\ sets $f$ to $1000$ rather than to $f_c$,
i.e., it refuses to raise $f$ very rapidly.
\endulist
The |\sfcode| value for a period is normally $3000$, 
which is why \TeX\ usually puts extra space after a period
% > to \ge here, too, as above.
(see the rule above for the case $f\ge2000$).
Noncharacter items in a horizontal list, e.g., vertical rules,
generally act like characters with a space factor of $1000$.

You can change the space factor explicitly by assigning
a different numerical value to |\spacefactor|.
You can also override the normal
interword spacing by assigning a different numerical
value to |\xspaceskip| or to |\spaceskip|:
\ulist
\li |\xspaceskip| specifies the glue to be used when $f\ge2000$;
in the case where
|\xspaceskip| is zero, the normal rules apply.
\li |\spaceskip| specifies the glue to be used when $f<2000$ or when
\hbox{|\xspaceskip|} is zero; if |\spaceskip| is zero, the normal rules apply.
The stretch and shrink of
the |\spaceskip| glue, like that of the ordinary interword glue, 
is modified according to the value of $f$.
\endulist

See \knuth{page~76} for the precise rules that \TeX\ uses in calculating
interword \minref{glue}, and \knuth{pages~285--287} for the adjustments
made to |\spacefactor| after various items in a horizontal list.
\eix^^{spaces//interword}
\enddesc

%==========================================================================
\section {Centering and justifying lines}

\begindesc
\bix^^{centering}
\bix^^{flush left}
\bix^^{flush right}
\bix^^{justification}
\easy\cts centerline {\<argument>}
\cts leftline {\<argument>}
\cts rightline {\<argument>}
\explain
The |\centerline| command produces an \minref{hbox} exactly as wide
as the current line and places \<argument> at the center of the box.
The |\leftline| and |\rightline| commands are analogous; they
place \<argument> at the left end or at the right end of the box.
If you want to apply one of these commands to
several consecutive lines, you must apply
it to each one individually.
See \xrefpg{eplaincenter} for an alternate approach.

Don't use these commands within a paragraph---if you do, 
\TeX\ probably won't be able to break the paragraph into lines and
will complain about an overfull hbox.
\example
\centerline{Grand Central Station}
\leftline{left of Karl Marx}
\rightline{right of Genghis Khan}
|
\produces
\centerline{Grand Central Station}
\leftline{left of Karl Marx}
\rightline{right of Genghis Khan}

\eix^^{centering}
\eix^^{flush left}
\eix^^{flush right}
\eix^^{justification}

\endexample
\enddesc

\begindesc
\easy\cts line {\<argument>}
\explain
This command produces an \minref{hbox} containing \<argument>.
The hbox is exactly as wide as the current line, i.e., it
extends from the right margin to the left margin.
\example
\line{ugly \hfil suburban \hfil sprawl}
% Without \hfil you'd get an `underfull box' from this.
|
\produces
\line{ugly \hfil suburban \hfil sprawl}%
\endexample

\enddesc

\begindesc
^^{overlapping text}
\cts llap {\<argument>}
\cts rlap {\<argument>}
\explain
These commands enable you to produce text that overlaps
whatever happens to be to the left or to the right of the current
position.  |\llap| backspaces by the width of \<argument> and then
typesets \<argument>.  |\rlap| is similar, except that it typesets 
\<argument> first and then backspaces.  |\llap| and |\rlap| are useful for
placing text outside of the current margins.
Both |\llap| and |\rlap| do their work by creating
a \minref{box} of zero~width.

You can also use |\llap| or |\rlap| to construct special characters by
^{overprinting}, but don't try it unless you're sure that the characters
you're using have the same width (which is the case for a monospaced
font such as ^|cmtt10|, the Computer Modern $10$-point ^{typewriter font}).
^^{Computer Modern fonts}
\example
\noindent\llap{off left }\line{\vrule $\Leftarrow$
left margin of examples\hfil right margin of examples
$\Rightarrow$\vrule}\rlap{ off right}
|
\produces
\noindent\llap{off left }\line{\vrule $\Leftarrow$
left margin of examples\hfil right margin of examples
$\Rightarrow$\vrule}\rlap{ off right}
\endexample

%\example
%{\tt O\llap{!|}}
%|
%\produces
%{\cm \tt O\llap{\char `|}}
%\endexample

\nobreak % don't lose the \see
\enddesc

\see |\hsize| (\xref{\hsize}).

%==========================================================================
\section {Shaping paragraphs}

\subsection {Starting, ending, and indenting paragraphs}

\begindesc
\bix^^{paragraphs//shaping}
\ctspecial par \ctsxrdef{@par}
\explain
This command ends a paragraph and puts \TeX\ into \minref{vertical mode},
ready to add more items to the page.  Since \TeX\ converts a blank line in
your input file into a |\par| \minref{token}, you don't ordinarily need to
type an explicit |\par| in order to end a paragraph.

An important point is that |\par| doesn't tell
\TeX\ to start a paragraph; it only tells \TeX\ to end a paragraph.
\TeX\ starts a paragraph when it is in ordinary vertical mode (which it
is after a |\par|) and encounters an inherently horizontal item such as
a letter.  As part of its ceremony for starting a paragraph, \TeX\
^^{paragraphs//starting}
inserts an amount of vertical space given by the parameter |\parskip|
(\xref{\parskip}) and indents the paragraph by a horizontal space given
by |\parindent| (\xref{\parindent}).

You can usually cancel any interparagraph space produced by a |\par| by giving
the command |\vskip -\lastskip|.  It can often
be helpful to do this when you're writing a \minref{macro} that is
supposed to work the same way whether or not it is preceded by a blank
line.

You can get \TeX\ to take some special action at the start of each paragraph
by placing the instructions in ^|\everypar| (\xref\everypar).

See \knuth{pages~283 and 286} for the precise effect of |\par|.

\example
\parindent = 2em
``Can you row?'' the Sheep asked, handing Alice a pair of
knitting-needles as she was speaking.\par ``Yes, a little%
---but not on land---and not with needles---'' Alice was
starting to say, when suddenly the needles turned into oars.
|
\produces
\parindent = 2em
``Can you row?'' the Sheep asked, handing Alice a pair of
knitting-needles as she was speaking.\par ``Yes, a little%
---but not on land---and not with needles---'' Alice was
starting to say, when suddenly the needles turned into oars.
\endexample
\enddesc

\begindesc
\cts endgraf {}
\explain
This command is a synonym for the ^|\par| primitive command.
It is useful when you've redefined ^|\par| but still want access to the
original definition of |\par|.
\enddesc

\begindesc
\cts parfillskip {\param{glue}}
\explain
^^{paragraphs//glue at end of}
This parameter specifies the horizontal glue that
\TeX\ inserts at the end of a paragraph.
The default value of |\parfillskip| is |0pt plus 1fil|,
which causes the last line of a paragraph to be
filled out with blank space.  A value of |0pt| forces
\TeX\ to end the last line of a paragraph at the right margin.
\enddesc

\bix^^{indentation}
\begindesc
\easy\cts indent {}
\explain
If \TeX\ is in vertical mode, as it is after ending a paragraph,
this command inserts the ^|\parskip| interparagraph glue,
puts \TeX\ into horizontal mode, starts a paragraph, and
indents that paragraph by |\parindent|.
If \TeX\ is already in horizontal mode, this command merely produces
a blank space of width |\parindent|.
Two |\indent|s in a row 
produce two indentations.
^^{indentation}

As the example below shows, an |\indent| at a point where \TeX\
would start a paragraph anyway is redundant.
When \TeX\ is in vertical mode and sees a letter or some other
inherently horizontal command, it starts a paragraph by
switching to horizontal mode,
doing an |\indent|, and processing the horizontal command.

\example
\parindent = 2em  This is the first in a series of three 
paragraphs that show how you can control indentation. Note
that it has the same indentation as the next paragraph.\par
\indent This is the second in a series of three paragraphs.
It has \indent an embedded indentation.\par
\indent\indent This doubly indented paragraph
is the third in the series.
|
\produces
\parindent = 2em  This is the first in a series of three 
paragraphs that show how you can control indentation. Note
that it has the same indentation as the next paragraph.\par
\indent This is the second in a series of three paragraphs.
It has \indent an embedded indentation.\par
\indent\indent This doubly indented paragraph
is the third in the series.
\endexample
\enddesc


\begindesc
\easy\cts noindent {}
\explain
If \TeX\ is in vertical mode, as it is after ending a paragraph,
this command inserts the ^|\parskip| interparagraph glue,
puts \TeX\ into horizontal mode, and starts an unindented paragraph.
It has no effect in horizontal mode, i.e., within a paragraph.
Starting a paragraph with |\noindent| thus cancels
the indentation by |\parindent|
that would normally occur there.
^^{indentation}

A common use of |\noindent| is to cancel the indentation of 
the first line of a
paragraph when the paragraph follows some displayed material.

\example
\parindent = 1em
Tied round the neck of the bottle was a label with the
words \smallskip \centerline{EAT ME}\smallskip
\noindent beautifully printed on it in large letters.
|
\produces
\parindent = 1em
Tied round the neck of the bottle was a label with the
words \smallskip \centerline{EAT ME}\smallskip
\noindent beautifully printed on it in large letters.
\endexample
\enddesc

\margin{{\tt\\textindent} moved here from later in the section.}
\begindesc
\cts textindent {\<argument>}
\explain
^^{indentation}
This command tells \TeX\ to start a paragraph and indent it by
|\par!-indent|,
as usual.
\TeX\ then right-justifies \<argument> within the indentation
and
follows it with an en space (half an em).
\PlainTeX\ uses this command to typeset footnotes (\xref\footnote)
^^{footnotes//using \b\tt\\textindent\e\ with}
and items in lists (see |\item|, \xref\item).

\example
\parindent = 20pt \textindent{\raise 1pt\hbox{$\bullet$}}%
You are allowed to use bullets in \TeX\ even if
you don't join the militia, and many peace-loving
typographers do so.
|
\produces
\parindent = 20pt \textindent{\raise 1pt\hbox{$\bullet$}}%
You are allowed to use bullets in \TeX\ even if
you don't join the militia, and many peace-loving
typographers do so.
\endexample\enddesc

\begindesc
\cts parindent {\param{dimen}}
\explain
This \minref{parameter} specifies the amount by which
the first line of each paragraph is to be indented. ^^{indentation}
As the example below shows, it's a bad idea to set both |\parindent|
and ^|\parskip| to zero since then the paragraph breaks are 
no longer apparent.
\example
\parindent = 2em This paragraph is indented by 2 ems.
\par \parindent=0pt This paragraph is not indented at all.
\par Since we haven't reset the paragraph indentation,
this paragraph isn't indented either.
|
\produces
\parindent = 2em This paragraph is indented by 2 ems.
\par \parindent=0pt This paragraph is not indented at all.
\par Since we haven't reset the paragraph indentation,
this paragraph isn't indented either.
\endexample\enddesc

\begindesc
\cts everypar {\param{token list}}
\explain
\TeX\ performs the commands in \<token list> whenever it
enters horizontal mode, e.g., when it starts a paragraph.
By default |\everypar| is empty, but you can 
take extra actions at the start of every paragraph by putting
the commands for those actions into a token list
and assigning that token list to |\everypar|.

\example
\everypar = {$\Longrightarrow$\enspace}
Now pay attention!!\par
I said, ``Pay attention!!''.\par
I'll say it again!! Pay attention!!
|
\produces
\everypar = {$\Longrightarrow$\enspace}
Now pay attention!\par
I said, ``Pay attention!''.\par
I'll say it again! Pay attention!
\endexample
\enddesc
\secondprinting{\vfill\eject}

%==========================================================================
\subsection {Shaping entire paragraphs}

\begindesc
\margin{This command was also described in the `Pages' chapter. The
description here now combines the two earlier descriptions.}
\bix^^{line breaks//and paragraph shape}
\easy\cts hsize {\param{dimen}}
\explain
This \minref{parameter} specifies the current ^{line length},
i.e., the usual width of lines in a paragraph
starting at the left margin.
A great many \TeX\ commands, e.g., |\centerline| (\xref{\centerline})
and |\hrule| (\xref{\hrule}), implicitly use the value of
|\hsize|.  By changing |\hsize| within a group
you can change the width of the constructs produced by such commands.

If you 
set |\hsize| within a \minref{vbox} that contains text, the vbox will
have whatever width you've given to |\hsize|.
^^{vboxes//width determined by \b\tt\\hsize\e}

\PlainTeX\ sets |\hsize| to |6.5in|.

\example
{\hsize = 3.5in % Set this paragraph 3.5 inches wide.
The hedgehog was engaged in a fight with another hedgehog,
which seemed to Alice an excellent opportunity for
croqueting one of them with the other.\par}%
|
\produces
{\hsize = 3.5in 
The hedgehog was engaged in a fight with another hedgehog,
which seemed to Alice an excellent opportunity for croqueting
one of them with the other.\par}%

\doruler{\8\8\8\tick\1\tick\2\tick\1\tick\3}{3.5}{in}
\nextexample
\leftline{\raggedright\vtop{\hsize = 1.5in
Here is some text that we put into a paragraph that is
an inch and a half wide.}\qquad
\vtop{\hsize = 1.5in Here is some more text that
we put into another paragraph that is an inch and a
half wide.}}
|
\produces
\leftline{\raggedright\vtop{\hsize = 1.5in
Here is some text that we put into a paragraph that is
an inch and a half wide.}\qquad
\vtop{\hsize = 1.5in Here is some more text that
we put into another paragraph that is an inch and a
half wide.}}
\endexample
\enddesc

\begindesc
\easy\cts narrower {}
\explain
^^{paragraphs//narrow}
This command makes paragraphs narrower, increasing the left and right
margins by |\parindent|, the
current paragraph ^{indentation}.
It achieves this by increasing
both |\leftskip| and |\rightskip| by |\parindent|.
Normally you place |\narrower| at the
beginning of a \minref{group} containing the paragraphs that you want to
make narrower.  If you forget to enclose |\narrower| within a group,
you'll find that all the rest of your document will have narrow
paragraphs.

|\narrower| affects just those paragraphs that end after you invoke it.
If you end a |\narrower| group before you've ended
a paragraph, \TeX\ won't make that paragraph narrower.

\example
{\parindent = 12pt \narrower\narrower\narrower
This is a short paragraph. Its margins are indented
three times as much as they would be
had we used just one ``narrower'' command.\par}
|
\produces
{\parindent = 12pt \narrower\narrower\narrower
This is a short paragraph. Its margins are indented
three times as much as they would be
had we used just one ``narrower'' command.\par}
\endexample\enddesc

\begindesc
\cts leftskip {\param{glue}}
\cts rightskip {\param{glue}}
\explain
These parameters tell \TeX\ how much glue to place
at the left and at the right end of each line of the current
paragraph.  We'll just explain how |\leftskip| works since |\rightskip| 
is analogous.

^^{indentation} You can increase the left margin by setting |\leftskip|
to a fixed nonzero \minref{dimension}.  If you give |\leftskip| some
stretch, you can produce ^{ragged left} text, i.e.,
text that has an uneven left margin.

Ordinarily, you should enclose any \minref{assignment} to |\leftskip|
in a \minref{group} together with the affected text
in order to keep its effect from continuing to
the end of your document.  However, it's pointless to change
|\leftskip|'s value inside a group that is in turn
contained within a paragraph---the value of |\leftskip| at the
\emph{end} of a paragraph
is what determines how \TeX\ breaks the paragraph into lines.  \minrefs{line
break}

\example
{\leftskip = 1in The White Rabbit trotted slowly back
again, looking anxiously about as it went, as if it had
lost something.  {\leftskip = 10in % has no effect
It muttered to itself, ``The Duchess!! The Duchess!! She'll
get me executed as sure as ferrets are ferrets!!''}\par}%
|
\produces
{\leftskip = 1in The White Rabbit trotted slowly back
again, looking anxiously about as it went, as if it had
lost something.  {\leftskip = 10in % has no effect
It muttered to itself, ``The Duchess! The Duchess!
She'll get me executed as sure as ferrets are ferrets!''}\par}%
\nextexample
\pretolerance = 10000 % Don't hyphenate.
\rightskip = .5in plus 2em
The White Rabbit trotted slowly back again, looking
anxiously about as it went, as if it had lost something.
It muttered to itself, ``The Duchess!! The Duchess!! She'll
get me executed as sure as ferrets are ferrets!!''
|
\produces
\pretolerance = 10000 % Don't hyphenate.
\rightskip = .5in plus 2em
The White Rabbit trotted slowly back again, looking
anxiously about as it went, as if it had lost something.
It muttered to itself, ``The Duchess! The Duchess! She'll
get me executed as sure as ferrets are ferrets!''
\endexample
\enddesc

\begindesc
\easy\cts raggedright {}
\cts ttraggedright {}
\explain
These commands cause \TeX\ to typeset your document 
``^{ragged right}''.  Interword spaces all 
have their natural size, i.e., they all have the same width and
don't stretch or shrink.
Consequently the right margin is generally not even.
The alternative, which is \TeX's default, is to typeset your document
justified,
^^{justification}
i.e., with uniform left and right margins.
In justified text, interword spaces are stretched in order to 
make the right margin even.
Some typographers prefer ragged right because 
it avoids distracting ``rivers'' of white space on the printed page.
\minrefs{justified text}

You should use the |\ttraggedright| command when typesetting text in a
monospaced font and the |\raggedright| command when typesetting text in any
other font.  

Most of the time you'll want to apply these commands to an entire document,
but you can limit their effects by enclosing them
in a \minref{group}.
\example
\raggedright ``You couldn't have it if you {\it did\/}
want it,'' the Queen said. ``The rule is, jam tomorrow
and jam yesterday---but never jam {\it today\/}.''
``It {\it must\/} come sometimes to `jam today,%
thinspace'' Alice objected. ``No, it can't'', said the
Queen. ``It's jam every {\it other\/} day: today isn't
any {\it other\/} day.''
|
\produces
\raggedright ``You couldn't have it if you {\it did\/}
want it,'' the Queen said. ``The rule is, jam tomorrow
and jam yesterday---but never jam {\it today\/}.''
``It {\it must\/} come sometimes to `jam today,%
'\thinspace'' Alice objected. ``No, it can't'', said the
Queen. ``It's jam every {\it other\/} day: today isn't
any {\it other\/} day.''
\endexample
\enddesc

\begindesc
\cts hang {}
\explain
This command indents the second and subsequent lines of a paragraph
by |\parindent|, the paragraph ^{indentation}
(\xref{\parindent}).
Since the first line is already indented by |\parindent|
(unless you've cancelled the indentation with |\noindent|), the
entire paragraph appears to be indented by |\parindent|.

\example
\parindent=24pt \hang  ``I said you {\it looked} like an
egg, Sir,'' Alice gently explained to Humpty Dumpty. ``And
some eggs are very pretty, you know,'' she added.
|
\produces
\parindent=24pt \hang  ``I said you {\it looked} like an
egg, Sir,'' Alice gently explained to Humpty Dumpty. ``And
some eggs are very pretty, you know,'' she added.
\endexample
\enddesc

\begindesc
\cts hangafter {\param{number}}
\cts hangindent {\param{dimen}}

\explain
These two \minref{parameter}s jointly
specify  ``^{hanging indentation}'' for a paragraph.
The hanging indentation indicates to \TeX\ that certain lines
of the paragraph should
be indented and the remaining lines should have their normal width.
^^{indentation}
|\hangafter| determines which lines
are indented, while |\hangindent| determines the amount of indentation
and whether it occurs on the left or on the right: 

\ulist
\li Let $n$ be the value of |\hangafter|.  If $n < 0$, 
the first $-n$ lines of the paragraph will be indented.
If $n\ge0$, all but the first $n$ lines of the paragraph will be
indented.

\li Let $x$ be the value of |\hangindent|.
If $x\ge0$, the lines will be indented
by $x$ on the left. If $x<0$ the lines will be indented by $-x$ on
the right.  
\endulist

When you specify hanging indentation, it applies 
only to the next paragraph (if you're in vertical mode) or to
the current paragraph (if you're in horizontal mode).
\TeX\ uses the values of |\hangafter| and |\hangindent| at the end of a
paragraph, when it breaks that paragraph into lines.\minrefs{line
break}
 
Unlike most of the other paragraph-shaping parameters,
|\hangafter| and |\hangindent| are reset to their default values
at the start of each paragraph, namely,
$1$ for |\hangafter| and $0$ for |\hangindent|.
If you want to typeset a sequence of paragraphs with hanging
indentation, use |\everypar| (\xref{\everypar}).
^^|\everypar//for hanging indentation|
If you specify |\hangafter| and |\hangindent| as well as ^|\parshape|,
\TeX\ ignores the |\hangafter| and |\hangindent|.

\example
\hangindent=6pc \hangafter=-2
This is an example of a paragraph with hanging indentation. 
In this case, the first two lines are indented on the left,
but after that we return to unindented text.
|
\produces
\hangindent=6pc \hangafter=-2
This is an example of a paragraph with hanging indentation. 
In this case, the first two lines are indented on the left,
but after that we return to unindented text.
\nextexample
\hangindent=-6pc \hangafter=1
This is another example of a paragraph with hanging
indentation.  Here, all lines after the first have been
indented on the right. The first line, on the other
hand, has been left unindented.
|
\produces
\hangindent=-6pc \hangafter=1
This is another example of a paragraph with hanging
indentation.  Here, all lines after the first have been
indented on the right. The first line, on the other
hand, has been left unindented.
\endexample
\enddesc

\margin{{\tt\\textindent} has been moved to earlier in this section.}

\begindesc
\cts parshape {$n\; i_1 l_1\; i_2 l_2\; \ldots \;i_n l_n$}
\explain
This command specifies the shape of the first $n$ lines of a paragraph---
the next paragraph if you're in vertical mode and the current paragraph
if you're in horizontal mode.
The $i$'s and $l$'s are all
dimensions.  The first line is indented by $i_1$ and has length $l_1$,
the second line is indented by $i_2$ and has length $l_2$, and so forth.
If the paragraph has more than $n$ lines, the last indentation\slash
length pair is used for the extra lines.
To achieve special effects such as the one
shown here, you usually have to experiment a lot, insert kerns here and
there, and choose your words to fit the shape.

|\parshape|, like ^|\hangafter| and ^|\hangindent|, is effective only for one
paragraph.
If you specify |\hangafter| and |\hangindent| as well as |\par!-shape|,
\TeX\ ignores the ^|\hangafter| and ^|\hangindent|.

By the way, the following example saves and restores |\fontdimen| values
explicitly, using temporary registers, since |\fontdimen| changes are
always global (see \xref\fontdimen).

\ifodd\pageno\vfill\eject\fi % so the wineglass is on a single page.

\example
% A small font and close interline spacing make this work
\smallskip\font\sixrm=cmr6 \sixrm \baselineskip=7pt
\dimen0=\fontdimen3\font \dimen2=\fontdimen4\font
\fontdimen3\font=1.8pt \fontdimen4\font=.9pt
\noindent \hfuzz=.1pt
\parshape 30 0pt 120pt 1pt 118pt 2pt 116pt 4pt 112pt 6pt
108pt 9pt 102pt 12pt 96pt 15pt 90pt 19pt 84pt 23pt 77pt
27pt 68pt 30.5pt 60pt 35pt 52pt 39pt 45pt 43pt 36pt 48pt
27pt 51.5pt 21pt 53pt 16.75pt 53pt 16.75pt 53pt 16.75pt 53pt
16.75pt 53pt 16.75pt 53pt 16.75pt 53pt 16.75pt 53pt 16.75pt
53pt 14.6pt 48pt 24pt 45pt 30.67pt 36.5pt 51pt 23pt 76.3pt
The wines of France and California may be the best known,
but they are not the only fine wines. Spanish wines are
often underestimated, and quite old ones may be available at
reasonable prices. For Spanish wines the vintage is not so
critical, but  the climate of the Bordeaux region varies
greatly from year to year. Some vintages are not as good as
others, so these years ought to be s\kern -.1pt p\kern -.1pt
e\kern -.1pt c\hfil ially n\kern .1pt o\kern .1pt
t\kern .1pt e\kern .1pt d\hfil: 1962, 1964, 1966.  1958,
1959, 1960, 1961, 1964, 1966 are also good California
vintages. Good luck finding them!!
\fontdimen3\font=\dimen0 \fontdimen4\font=\dimen2
|
%\margin{Wineglass text replaced because of permissions problem.}
\produces
% A small font and close interline spacing make this work
\smallskip\font\sixrm=cmr6 \sixrm \baselineskip=7pt
\dimen0=\fontdimen3\font \dimen2=\fontdimen4\font
\fontdimen3\font=1.8pt \fontdimen4\font=0.9pt
\noindent \hfuzz=0.1pt % reordered to save a line
\parshape 30 0pt 120pt 1pt 118pt 2pt 116pt 4pt 112pt 6pt 108pt 9pt 102pt
12pt 96pt 15pt 90pt 19pt 84pt 23pt 77pt 27pt 68pt 30.5pt 60pt 35pt 52pt
39pt 45pt 43pt 36pt 48pt 27pt 51.5pt 21pt 53pt 16.75pt 53pt 16.75pt
53pt 16.75pt 53pt 16.75pt 53pt 16.75pt 53pt 16.75pt 53pt 16.75pt
53pt 16.75pt 53pt 14.6pt 48pt 24pt 45pt 30.67pt 36.5pt 51pt 23pt 76.3pt
The wines of France and California may be the best
known, but they are not the only fine wines. Spanish
wines are often underestimated, and quite old ones may
be available at reasonable prices. For Spanish wines
the vintage is not so critical, but  the climate of the
Bordeaux region varies greatly from year to year. Some
vintages are not as good as others,
so these years ought to be
s\kern -.1pt p\kern -.1pt e\kern -.1pt c\hfil ially
n\kern .1pt o\kern .1pt t\kern .1pt e\kern .1pt d\hfil:
1962, 1964, 1966.  1958, 1959, 1960, 1961, 1964,
1966 are also good California vintages.
Good luck finding them!
\fontdimen3\font=\dimen0 \fontdimen4\font=\dimen2
\endexample
\eix^^{indentation}
\enddesc

\begindesc
\cts prevgraf {\param{number}}
\explain
In horizontal mode, this parameter specifies the 
number of lines in the paragraph so far; in vertical mode,
it specifies the number of lines in the previous paragraph.
\TeX\ only sets |\prevgraf| after it has finished breaking some text into
lines, i.e., at a math display or at the end of a paragraph.
See \knuth{page~103} for more details about it.
\enddesc

\begindesc
\cts vadjust {\rqbraces{\<vertical mode material>}}
\explain
This command inserts the specified \<vertical mode material> just after the 
output line containing the position where the command occurs.
^^{vertical lists//inserting in paragraphs}
You can use it, for instance, to cause a page eject or to insert extra
space after a certain line.

\example
Some of these words are \vadjust{\kern8pt\hrule} to be
found above the line and others are to be found below it.
|
\produces
Some of these words are \vadjust{\kern8pt
\hbox to \hsize{\hfil\vbox{\advance\hsize by -\parindent
\hrule width \hsize}}}
to be found above the line and others are to be found below it.
\endexample
\enddesc

\see |\parindent| (\xref\parindent),
|\parskip| (\xref\parskip), |\everypar| (\xref\everypar).
\eix^^{line breaks//and paragraph shape}
\eix^^{paragraphs//shaping}

%==========================================================================
\section {Line breaks}

%==========================================================================
\subsection {Encouraging or discouraging line breaks}

\begindesc
\bix^^{line breaks}
\bix^^{line breaks//encouraging or discouraging}
\ctspecial break {} \xrdef{hbreak}
\explain
This command forces a line break.
Unless you do something to fill out the line, you're likely to
get an ``underfull hbox'' complaint.
|\break| can also be used in vertical mode.
\example
Fill out this line\hfil\break and start another one.\par
% Use \hfil here to fill out the line.
This line is underfull---we ended it\break prematurely.
% This line causes an `underfull hbox' complaint.
|
\produces
\hbadness = 10000 % avoid hbadness message
Fill out this line\hfil\break and start another one.\par
% Use \hfil here to fill out the line.
This line is underfull---we ended it\break prematurely.
% This line causes an `underfull hbox' complaint.
\endexample\enddesc

\begindesc
\ctspecial nobreak {} \xrdef{hnobreak}
\explain
This command prevents a line break where it
otherwise might occur.
|\nobreak| can also be used in vertical mode.
\example
Sometimes you'll encounter a situation where
a certain space\nobreak\qquad must not get lost.
|
\produces
Sometimes you'll encounter a situation where
a certain space\nobreak\qquad must not get lost.
\endexample
\enddesc

\begindesc
\ctspecial allowbreak {} \xrdef{hallowbreak}
\explain
This command tells \TeX\ to 
allow a line break where one could not ordinarily occur.
It's most often useful within a math formula, since \TeX\
is reluctant to break lines there.  ^^{line breaks//in math formulas}
|\allowbreak| can also be used in vertical mode.
\example
Under most circumstances we can state with some confidence
that $2+2\allowbreak=4$, but skeptics may disagree.
\par For such moronic automata, it is not difficult to
analyze the input/\allowbreak output behavior in the limit.
|
\produces
Under most circumstances we can state with some confidence
that $2+2\allowbreak=4$, but skeptics may disagree.
\par For such moronic automata, it is not difficult to
analyze the input/\allowbreak output behavior in the limit.
\endexample\enddesc

\begindesc
\ctspecial penalty {\<number>} \xrdef{hpenalty}
\explain
This command produces a \minref{penalty} item.
The penalty item makes \TeX\ more or less willing to break a line
at the point where that item occurs.
A negative penalty, i.e., a bonus, encourages a line break;
a positive penalty discourages a line break.  
A penalty of $10000$ or more prevents a break altogether,
while a penalty of $-10000$ or less forces a break.
|\penalty| can also be used in vertical mode.
\secondprinting{\vfill\eject}
\example
\def\break{\penalty -10000 } % as in plain TeX
\def\nobreak{\penalty 10000 } % as in plain TeX
\def\allowbreak{\penalty 0 } % as in plain TeX
|
\endexample
\enddesc

\secondprinting{\vglue-\baselineskip\vskip0pt}
\begindesc
\cts obeylines {}
\explain
\TeX\ normally treats an end of line as a space.
|\obeylines| instructs \TeX\ to treat each end of line as
an end of paragraph, thus forcing a line break.
|\obeylines| is often useful when you're typesetting verse or
computer programs.
^^{verse, typesetting}^^{poetry, typesetting}^^{computer programs, typesetting}
If any of your lines are longer than the effective line length
(|\hsize|\tminus|\parindent|),
however,
you may get an extra line break within those lines.

Because \TeX\ inserts the |\parskip| glue (\xref\parskip)
between lines controlled by |\obeylines| (since it thinks each line is a
paragraph), you should normally set |\parskip| to zero when you're using
|\obeylines|.

You can use the ^|\obeyspaces| command (\xref{\obeyspaces}) to get
\TeX\ to take spaces within a line literally.  |\obeylines| and |\obeyspaces|
are often used together.
\example 
\obeylines
``Beware the Jabberwock, my son!!
\quad The jaws that bite, the claws that catch!!
Beware the Jubjub bird, and shun
\quad The frumious Bandersnatch!!''
|
\produces
\obeylines
``Beware the Jabberwock, my son!
\quad The jaws that bite, the claws that catch!
Beware the Jubjub bird, and shun
\quad The frumious Bandersnatch!''
\endexample
\enddesc

\secondprinting{\vglue-\baselineskip\vskip0pt}

\begindesc
\easy\cts slash {}
\explain
This command produces a ^{solidus} (/) and also tells \TeX\ that it can
break the line after the solidus, if necessary.
\example
Her oldest cat, while apparently friendly to most people,
had a Jekyll\slash Hyde personality when it came to mice.
|
\produces
Her oldest cat, while apparently friendly to most people,
had a Jekyll\slash Hyde personality when it came to mice.
\endexample
\eix^^{line breaks//encouraging or discouraging}
\enddesc

\secondprinting{\vfill\eject}


%==========================================================================
\subsection {Line breaking parameters}

\begindesc
\bix^^{line breaks//parameters affecting}
%
\cts pretolerance {\param{number}}
\cts tolerance {\param{number}}
\explain
These parameters determine the \minref{badness} that \TeX\ will tolerate
on each line when it is choosing line breaks
for a paragraph.
The badness is a measure of how far the interword spacing deviates from
the ideal.
|\pretolerance| specifies the  tolerable badness for
line breaks without hyphenation;
|\tolerance| specifies the tolerable badness for line breaks with
hyphenation.
The tolerable badness can be exceeded in either of two ways:
a line is too tight (the interword spaces are too
small) or it is too loose (the interword spaces are too big).

\ulist
\li If \TeX\ must set a line too loosely, it
complains about an ``underfull hbox''.
\li If \TeX\ must set a line too rightly, 
it lets the line run past the right margin and
complains about an ``overfull \minref{hbox}''.
\endulist

\noindent \TeX\ chooses line breaks in the following steps:
\olist
\li It attempts to choose line breaks without hyphenating.
If none of the
resulting lines have a badness exceeding |\pretolerance|, the
line breaks are acceptable and the paragraph can now be set.
\li Otherwise, it tries another set of line breaks, this
time allowing hyphenation.  If none of the resulting lines have a badness
exceeding |\tolerance|, the new set of line breaks is
acceptable and the paragraph can now be set.
\li Otherwise, it adds ^|\emergencystretch| (see below) to the stretch
of each line and tries again.
\li If none of these attempts have produced an acceptable
set of line breaks,
it sets the paragraph with one or more overfull hboxes
and complains about them.
\endolist

\PlainTeX\ sets |\tolerance| to $200$ and |\pretolerance| to $100$.
If you set |\tolerance| to $10000$, \TeX\
becomes infinitely tolerant and accepts any spacing, no matter how bad
(unless it encounters a word that won't fit on a line, even with
hyphenation).  Thus by changing |\tolerance| you can avoid
overfull and underfull hboxes, but at the cost of making the spacing worse.
By making |\pretolerance| larger you can get \TeX\ to avoid hyphenation
(and also run faster),
again at the cost of possibly worse spacing.
If you set |\pretolerance| to $-1$,
\TeX\ will not even try to set the paragraph without hyphenation.

The  ^|\hbadness| parameter (\xref \hbadness) determines the level of badness
that \TeX\ will tolerate before it complains, but |\hbadness| does not affect
the way that \TeX\ typesets your document.
The ^|\hfuzz| parameter (\xref \hfuzz) determines the amount that
an hbox can exceed its specified width before \TeX\ considers it to be
erroneous.
\enddesc

\begindesc
\cts emergencystretch {\param{dimen}}
\explain
By setting this parameter to be greater than zero,
you can make it easier for \TeX\
to typeset your document without generating overfull hboxes.
^^{overfull boxes}
This is a better alternative than setting |\tolerance=10000|,
since that tends to produce really ugly lines.
If \TeX\ can't typeset a paragraph without exceeding ^|\tolerance|,
it will try again, adding |\emergencystretch| to the stretch of each
line.
The effect of the change is to scale down the badness of each
line, enabling \TeX\ to make spaces wider than they would otherwise be
and thus choose line breaks that are as
good as possible under the circumstances.
\enddesc

\begindesc
\cts looseness {\param{number}}
\explain
\minrefs{line break}
This parameter gives you a way 
to change the total number of lines in a paragraph from what they
optimally would be.
|\looseness| is so named because it's a
measure of how loose the paragraph is, i.e., how much extra space there is in
it. 

Normally, |\looseness| is $0$ and
\TeX\ chooses line breaks in its usual way.  But if
|\looseness| is, say, $3$, \TeX\ does the following:
\olist
\li It chooses line breaks normally, resulting in a paragraph of $n$ lines.
\li It discards these line breaks and
tries to find a new set of line breaks that gives the paragraph $n+3$ lines.
(Without the previous step, \TeX\ wouldn't know the value of $n$.)
\li If the previous attempt results in lines whose badness exceeds
|\tol!-er!-ance|,
^^|\tolerance|
it tries to get $n+2$ lines---and if that also fails,
$n+1$ lines, and finally $n$ lines again.
\endolist
\noindent
Similarly, if looseness is $-n$,
\TeX\ attempts to set the paragraph with $n$
fewer lines  than normal.
The easiest way for \TeX\ to make a paragraph one line longer is to put
a single word on the excess line.  You can prevent this by
putting a tie (\xref{@not}) between the last two words of the paragraph. 

Setting |\looseness| is the best way to force a paragraph
to occupy a given number of lines.
Setting it to a negative value is useful when you're trying to
increase the amount of text you can fit on a page.
Similarly, setting it to a positive
value is useful when you're trying to 
decrease the amount of text on a page.

\TeX\ sets |\looseness| to $0$ when it ends a paragraph, after breaking
the paragraph into lines.
If you want to change the looseness of several paragraphs, you must do it
individually for each one or put the change into |\everypar|
\ctsref\everypar.
^^|\everypar//for setting \b\tt\\looseness\e|
\enddesc

\begindesc
\cts linepenalty {\param{number}}
\explain
\minrefs{line break}
This parameter specifies the \minref{penalty} that \TeX\ assesses for each line
break when it is breaking a paragraph into lines.
The penalty is independent of where the line break occurs.
Increasing the value
of this parameter causes \TeX\ to try harder to set a paragraph with a 
minimum number of lines, even at the cost of other aesthetic considerations
such as avoiding overly tight interword spacing.
Demerits are in units of \minref{badness} squared, so
you need to assign a rather large value to this parameter (in the
thousands) for it to have any effect.
\PlainTeX\ sets |\linepenalty| to $10$.
\enddesc

\begindesc
\cts adjdemerits {\param{number}}
\explain
\minrefs{line break}
^^{hyphenation//penalties for}
{\tighten
This parameter specifies additional \minref{demerits} that \TeX\ attaches to a
breakpoint between two adjacent lines that are
``visually incompatible''.  
Such a pair of lines makes a paragraph appear uneven.
Incompatibility is evaluated in terms of the tightness or looseness
of lines:
}
\olist\compact
\li A line is tight if its \minref{glue} needs to shrink by at least $50\%$.
\li A line is decent if its badness is $12$ or less.
\li A line is loose if its glue needs to stretch by more than $50\%$.
\li A line is very loose if its glue needs to stretch so much
that its badness exceeds $100$.
\endolist
Two adjacent lines are visually incompatible
if their categories are not adjacent, e.g., a tight line is next to a loose one
or a decent line is next to a very loose one.

Demerits are in units of \minref{badness} squared, so 
you need to assign a rather large value to this parameter (in the 
thousands) for it to have any effect.
\PlainTeX\ sets |\adjdemerits| to~$10000$.
\enddesc

\begindesc
\bix^^{hyphenation//penalties for}
\cts exhyphenpenalty {\param{number}}
\explain
\minrefs{line break}
This parameter specifies the \minref{penalty} that \TeX\ attaches to a 
breakpoint at an explicit hyphen such as the one in
``helter-skelter''.  Increasing this parameter has the effect of discouraging
\TeX\ from ending a line at an explicit hyphen.
\PlainTeX\ sets |\exhyphenpenalty| to $50$.
\enddesc

\begindesc
\cts hyphenpenalty {\param{number}}
\explain
\minrefs{line break}
This parameter specifies the \minref{penalty} that \TeX\ attaches to a 
breakpoint at an implicit hyphen.
Implicit hyphens can come from \TeX's hyphenation dictionary or
from ^{discretionary hyphens} that you've inserted with |\-|~(\xref{\@minus}).
^^|-//leads to {\tt\\hyphenpenalty}|
Increasing this parameter has the effect of discouraging
\TeX\ from hyphenating words.
\PlainTeX\ sets |\hyphenpenalty| to $50$.
\enddesc

\begindesc
\cts doublehyphendemerits {\param{number}}
\explain
\minrefs{line break}
{\tighten
This parameter specifies additional \minref{demerits} that \TeX\
attaches to a breakpoint when that breakpoint leads to
two consecutive lines that end in a hyphen.
Increasing the value of this parameter has the effect of discouraging
\TeX\ from hyphenating two lines in a row.
Demerits are in units of \minref{badness} squared, so
you need to assign a rather large value to this parameter (in the
thousands) for it to have any effect.
\PlainTeX\ sets |\doublehyphendemerits| to $10000$.
}
\enddesc

\begindesc
\cts finalhyphendemerits {\param{number}}
\explain
\minrefs{line break}
{\tighten
This parameter specifies additional \minref{demerits} that \TeX\
attaches to a breakpoint that causes 
the next to last line of a paragraph to end with a hyphen.
Such a hyphen is generally considered to be unaesthetic
because of the possible blank space from a short last line beneath it.
Increasing the value of this parameter has the effect of discouraging
\TeX\ from ending the next to the last line with a hyphen.
Demerits are in units of \minref{badness} squared, so
you need to assign a rather large value to this parameter (in the
thousands) for it to have any effect.
\PlainTeX\ sets |\finalhyphendemerits| to $5000$.
}
\eix^^{hyphenation//penalties for}
\enddesc

\begindesc
\cts binoppenalty {\param{number}}
\explain
^^{operators}
This parameter specifies the penalty for breaking a math formula
after a binary operator when the formula appears in a paragraph.
\PlainTeX\ sets |\binoppenalty| to $700$.
\enddesc

\begindesc
\cts relpenalty {\param{number}}
\explain
^^{relations}
This parameter specifies the penalty for breaking a math formula
after a relation when the formula appears in a paragraph.
\PlainTeX\ sets |\rel!-penal!-ty| to~$500$.

\eix^^{line breaks//parameters affecting}
\enddesc

%==========================================================================
\subsection {Hyphenation}

\begindesc
\bix^^{hyphenation}
%
\easy\ctspecial - \ctsxrdef{@minus}
\explain
The |\-| command inserts a ``discretionary hyphen''
^^{discretionary hyphens}
into a word.
The discretionary hyphen allows \TeX\ to hyphenate the word at that
place.  \TeX\ isn't obliged to hyphenate there---it does so
only if it needs to.  This command is useful when a word 
that occurs in one or two places in your document
needs to be hyphenated,
but \TeX\ can't find an appropriate hyphenation point on its own.
\example
Alice was exceedingly reluctant to shake hands first
with either Twee\-dle\-dum or Twee\-dle\-dee, for
fear of hurting the other one's feelings.
|
\produces
Alice was exceedingly reluctant to shake hands first
with either Twee\-dle\-dum or Twee\-dle\-dee, for
fear of hurting the other one's feelings.
\endexample
\enddesc

\begindesc
\cts discretionary {\rqbraces{\<pre-break text>}
   \rqbraces{\<post-break text>}
   \rqbraces{\<no-break text>}}
\explain
\minrefs{line break}
^^{hyphenation}
This command specifies a ``discretionary break'', namely,
a place where \TeX\ can break a line.
It also tells \TeX\ what text to put on either side of the break.
\ulist
\li If \TeX\ does not break there, it uses the \<no-break text>.
\li If \TeX\ does break there, it puts the \<pre-break text> just before
the break and the \<post-break text> just after the break.
\endulist
\noindent
Just as with |\-|,
\TeX\ isn't obligated to break a line at a discretionary break.
In fact, |\-| is ordinarily equivalent to |\discretionary!allowbreak{-}{}{}|.

\TeX\ sometimes inserts discretionary breaks on its own.
For example, it inserts |\discretionary!allowbreak{}{}{}| after
an explicit hyphen or dash.

{\hyphenchar\tentt=-1 % needed to avoid weirdnesses
\example
% An ordinary discretionary hyphen (equivalent to \-):
\discretionary{-}{}{}
% A place where TeX can break a line, but should not
% insert a space if the line isn't broken there, e.g.,
% after a dash:
\discretionary{}{}{}
% Accounts for German usage: `flicken', but `flik-
% ken':
German ``fli\discretionary{k-}{k}{ck}en''
|
^^{hyphenation//German}
\endexample}

\enddesc

\begindesc
\cts hyphenation {\rqbraces{\<word>\thinspace\vs\ $\ldots$\ \vs
   \thinspace\<word>}}
\explain
\TeX\ keeps a dictionary of exceptions to its ^{hyphenation} rules.
Each dictionary entry indicates how a particular word should
be hyphenated.  
The |\hyphenation| command adds words to the dictionary.
Its argument is a sequence of words separated by blanks. 
Uppercase and lowercase letters are equivalent.
The hyphens in each word indicate the places
where \TeX\ can hyphenate that word.
A word with no hyphens in it will never be hyphenated.
However, you can still override the hyphenation dictionary by
using |\-| in a particular occurrence of a word.
You need to provide all the grammatical forms of a word
that you want \TeX\ to handle, e.g., both the singular and the plural.

\example
\hyphenation{Gry-phon my-co-phagy}
\hyphenation{man-u-script man-u-scripts piz-za}
|
\endexample
\enddesc

\begindesc
\cts uchyph {\param{number}}
\explain
A positive value of |\uchyph| (uppercase hyphenation)
permits hyphenation of words, such as proper names,
that start with a capital letter.
A zero or negative
value inhibits such hyphenation.  \PlainTeX\ sets |\uchyph| to $1$,
so \TeX\  normally tries to hyphenate words that start with a capital letter.
\enddesc

\begindesc
\cts showhyphens {\rqbraces{\<word>\thinspace\vs\ $\ldots$\ \vs
   \thinspace\<word>}}
\explain
This command isn't normally used in documents, but you can use it at
your terminal to see how \TeX\ would hyphenate some random set of words.
The words, with hyphenations indicated, appear both in the log and at
your terminal.  You'll get a complaint about an underfull hbox---just
ignore it.
\example
\showhyphens{threshold quizzical draughts argumentative}
|
\logproduces
Underfull \hbox (badness 10000) detected at line 0
[] \tenrm thresh-old quizzi-cal draughts ar-gu-men-ta-tive
|
\endexample
\enddesc

\begindesc
\cts language {\param{number}}
\explain
Different languages have different sets of hyphenation rules.
This parameter determines the set of ^{hyphenation rules} that \TeX\ uses.
By changing |\language| you can get \TeX\
to hyphenate portions of text or entire documents according to the 
hyphenation rules appropriate to a particular language.
^^{European languages}
Your ^{local information} about \TeX\ will tell you if any
additional sets of hyphenation rules are available (besides the
ones for English)
and what the appropriate values of |\language| are.
The default value of |\language| is $0$.

\TeX\ sets the current language to $0$ at the start of every paragraph,
and compares |\language| to the current language whenever it adds
a character to the current paragraph.
If they are not the same, \TeX\ adds a ^{whatsit} indicating the
language change.
This whatsit is the clue in later processing that the language rules
should change.
\enddesc

\begindesc
\cts setlanguage {\<number>}
\explain
This command sets the current language to \<number>
by inserting the same whatsit that you'd get by changing ^|\language|.
However, it does not change the value of |\language|.
\enddesc

\begindesc
\cts lefthyphenmin {\param{number}}
\cts righthyphenmin {\param{number}}
\explain
These parameters specify the smallest word fragments that \TeX\ allows
at the left and at the right end of a hyphenated word.
\PlainTeX\ defaults them to $2$ and $3$ respectively;
these are the recommended values for English.
\enddesc

\begindesc
\bix^^{fonts//hyphenation characters for}
\cts hyphenchar {\<font>\param{number}}
\explain
\TeX\ doesn't necessarily use the `-' character at hyphenation points.
Instead, it uses the |\hyphenchar| of the current font, which is usually
`-' but need not be.   If a font has a negative |\hyphenchar| value,
\TeX\ won't hyphenate words in that font.

Note that \<font> is a control sequence
that names a font, not a \<font\-name> that names font files.
Beware: 
an assignment to |\hyphenchar| is \emph{not} undone at the end
of a group.
If you want to change |\hyphenchar| locally, you'll need to
save and restore its original value explicitly.

\example
\hyphenchar\tenrm = `- 
   % Set hyphenation for tenrm font to `-'.
\hyphenchar\tentt = -1
   % Don't hyphenate words in font tentt.
|
\endexample
\enddesc

\begindesc
\cts defaulthyphenchar {\param{number}}
\explain
When \TeX\ reads the metrics file
^^{metrics file//default hyphen in}
for a font in response to a
^|\font| command, it sets the font's ^|\hyphenchar| to
|\default!-hyphen!-char|.
If the value of |\default!-hyphen!-char| is
not in the range $0$--$255$ when you load a font,
\TeX\ won't hyphenate any words in that font  unless you
override the decision by setting the font's |\hyphenchar| later on.
\PlainTeX\  sets |\default!-hyphen!-char| to $45$, the \ascii\ code
for `|-|'.
\example
\defaulthyphenchar = `-
   % Assume `-' is the hyphen, unless overridden.
\defaulthyphenchar = -1
   % Don't hyphenate, unless overridden.
|
\endexample

\eix^^{fonts//hyphenation characters for}
\enddesc

\see |\pretolerance| (\xref \pretolerance).
\eix^^{hyphenation}
\eix^^{line breaks}

%==========================================================================
\section {Section headings, lists, and theorems}

\begindesc
^^{section headings}
\easy\ctspecial beginsection {\<argument>\thinspace{\bt\\par}}
   \ctsxrdef{@beginsection}
\explain
You can use this command to begin a major subdivision of your document.
\<argument> is intended to serve as a section title.
|\beginsection| surrounds \<argument>
by extra vertical space and sets it in
boldface, left-justified.
You can produce the |\par| that ends \<argument> with a blank line.
\let\message = \gobble % Don't bother to tell us about Pig and Pepper.
\example
$\ldots$  till she had brought herself down to nine
inches high.

\beginsection Section 6. Pig and Pepper

For a minute or two she stood looking at the house $\ldots$
|
\produces
$\ldots$  till she had brought herself down to nine
inches high.

\beginsection Section 6. Pig and Pepper

For a minute or two she stood looking at the house $\ldots$
\endexample
\enddesc

\begindesc
\cts item {\<argument>}
\cts itemitem {\<argument>}
\explain
^^{itemized lists}
These commands are useful for creating ^{itemized lists}.  The entire paragraph
following \<argument> is indented by |\parindent|
^^|\parindent//indentation for itemized lists|
(for |\item|) or by |2\parindent| (for |\itemitem|).
(See \xrefpg{\parindent} for an explanation of |\parindent|.)
Then \<argument>,
followed by an en space, is placed just to
the left of the text of the
first line of the paragraph so that it falls within the paragraph indentation
as specified by |\parindent|.

If you want to include more than one
paragraph in an item, put |\item{}| in front of the additional paragraphs.
\example
{\parindent = 18pt
\noindent Here is what we require:
\item{1.}Three eggs in their shells,
but with the yolks removed.
\item{2.}Two separate glass cups containing:
\itemitem{(a)}One-half cup {\it used} motor oil.
\itemitem{(b)}One cup port wine, preferably French.
\item{3.}Juice and skin of one turnip.}
|
\produces
{\parindent = 18pt
\noindent Here is what we require:
\item{1.}Three eggs in their shells,
but with the yolks removed.
\item{2.}Two separate glass cups containing:
\itemitem{(a)}One-half cup {\it used} motor oil.
\itemitem{(b)}One cup port wine, preferably French.
\item{3.}Juice and skin of one turnip.}
\endexample
\enddesc

\begindesc
\easy\ctspecial proclaim {\<argument>{\tt.}\vs\thinspace
   \<general text>\thinspace{\bt\\par}}
   \ctsxrdef{@proclaim}
\explain
^^{theorems}
^^{lemmas}
^^{hypotheses}
This command ``proclaims'' a theorem, lemma, hypothesis, etc.
It sets \<argument> in boldface type and the following paragraph in
italics.  \<arg\-u\-ment> must be followed by a period and a space token,
which serve
to set off \<argument> from \<general text>.
\<general text> consists of the text up to the next paragraph
boundary.  You can include multiple paragraphs by using |\endgraf|
instead of a blank line or |\par|.
\example
\proclaim Theorem 1.
What I say is not to be believed.

\proclaim Corollary 1. Theorem 1 is false.\par
|
\produces
\proclaim Theorem 1.
What I say is not to be believed.

\proclaim Corollary 1. Theorem 1 is false.\par
\endexample
\enddesc

\enddescriptions
\endchapter
\byebye
