% This file is part of the CTAN package named plain-widow.
% 
%   plain-widow-doc.tex: instructions for the package
%   Version 1.0, 13.05.2025
%
%   Copyright (C) 2025  Udo Wermuth (author)
%
%   This program is free software: you can redistribute it and/or modify
%   it under the terms of the GNU General Public License as published by
%   the Free Software Foundation, either version 3 of the License, or
%   (at your option) any later version.
%
%   This program is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%   GNU General Public License for more details.
%
%   You should have received a copy of the GNU General Public License
%   along with this program.  If not, see <http://www.gnu.org/licenses/>.
%

\outer\def\beginsection#1\par{\vskip 0pt plus 3\baselineskip\penalty-250
  \vskip 0pt plus -3\baselineskip\bigskip\vskip\parskip
  \message{#1}\leftline{\bf#1}\nobreak\smallskip\noindent}
% %%%
% %%% verbatim macros (from manmac.tex)
% %%%
\newskip\ttglue {\tt\global\ttglue=0.5em plus 0.25em minus 0.15em }
\def\ttverbatim{\begingroup \frenchspacing
  \catcode`\\=12 \catcode`\{=12 \catcode`\}=12 \catcode`\$=12 \catcode`\&=12
  \catcode`\#=12 \catcode`\%=12 \catcode`\~=12 \catcode`\_=12 \catcode`\^=12
  \obeyspaces \obeylines \tt}
\def\verbatimspace{\ifvmode\indent\fi\space}
{\obeyspaces \gdef\makespaceverbspace{\def {\verbatimspace}}}
\outer\def\verbatim{$$\ifdim\parskip>0pt
    \abovedisplayskip=\parskip \abovedisplayshortskip=\parskip
    \belowdisplayskip=\parskip \belowdisplayshortskip=\parskip
  \else
    \abovedisplayskip=3pt \abovedisplayshortskip=3pt
    \belowdisplayskip=3pt \belowdisplayshortskip=3pt
  \fi
  \let\par=\endgraf \ttverbatim \makespaceverbspace \parskip=0pt
  \catcode`\§=0 \advance\leftskip by 10pt \ttfinish}
{\catcode`\§=0 §catcode`§\=12 % § is temporary escape character
  §obeylines % end of line is active
  §gdef§ttfinish#1^^M#2\endverbatim{§vbox{#2}§endgroup$$}}
\catcode`\|=\active
{\obeylines \gdef|{\ttverbatim \spaceskip\ttglue \let^^M=\  \let|=\endgroup}}

\def\noitem{\item{\phantom{0.}}}

% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\font\titlefont=cmssdc10 at 36pt
\font\subtitlefont=cmssdc10 at 17pt
%
\centerline{\titlefont plain-widow}
\bigskip
\centerline{\subtitlefont Version 1.0, 13.05.2025}
\bigskip
\centerline{Macros for plain \TeX\ by Udo Wermuth}
\medskip
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

This package contains three output routines that one can use to
replace |\plainoutput|. The first adds a reporting of widow, club, and
broken lines at a page break to |\plainoutput|. The second avoids
widow lines by changing the size of the page by $\pm1$ line. The third
tries to avoid widow lines for spreads.

\medskip

To use one of the three output routines instead of\/ |\plainoutput|
load the corresponding file via |\input|; see below. A fourth file
allows a user to change the size of the page by $\pm1$ line manually.

\smallskip
\item{1.}All files must be loaded before \TeX\ starts the typesetting.
\item{2.}All files change the penalties |\postdisplaypenalty|,
         |\displaywidowpenalty|, |\widowpenalty|, and |\brokenpenalty|
         compared to {\tt plain.tex}. See section~1 if you want to
         change them or |\clubpenalty| or |\interlinepenalty|.
\item{3.}All files except the one of section~1 must be loaded
         after |\vsize| is set.
\item{4.}All files except the one of section~1 replaces a fixed dimension
         in |\makefootline| by the macro |\footlinedist|. The distance
         is increased by 6pt from 24pt to 30pt.
\item{5.}Load only one file and load it only once. One can switch
         between output routines; see below.
\smallskip

\noindent
For more details see my article in TUGboat {\bf46}:1 (2025), 136--144.



\beginsection 1. File {\tt pxwreport.tex}

The file sets up a reporting of pages with club lines, widow lines,
and broken lines, i.e., pages whose last word is hyphenated. The report
is given at the end of the run.

To identify the different situations it changes several vertical
penalties by a small amount. Compared to |plain.tex| the file sets the
following values.

\smallskip
\item{1.}|\brokenpenalty| is increased by 1 and becomes 101;
\item{2.}|\displaywidowpenalty| is increased by 1 and becomes 51;
\item{3.}|\widowpenalty| is increased by 1 and becomes 151;
\item{4.}|\postdisplaypenalty| is increased by 2 and becomes 2.
\smallskip

These settings make all combinations unique and the reporting can
determine the situation at a page break. Read the comments in {\tt
report.tex} if you want to change them or another vertical penalty.

A report contains three lines; for example:

\indent\indent{\tt Widow lines on the following pages: 5, 17, (23), (25)?, 30.}

\indent\indent{\tt Club lines on the following pages: 11, 30, 33.}

\indent\indent{\tt Hyphen at page break on the following pages: none found.}

\noindent
They list the pages with the problematic lines. In the first line a
page number in parentheses stands for a display widow line; a `?'\
after the closing parenthesis signals a possible widow line after a
display.

There is one configuration parameter: |\PXprint|. It contains the
value 1. If you change this definition, for example, |\def\PXprint{0
}| the report is not shown.

Even if you loaded {\tt pxwreport.tex} the original behavior of
|\plainoutput| is established if\/ |\startwithPlain| is called before
the typesetting starts.



\beginsection 2. File {\tt pxwsingle.tex}

This file implements an output routine that changes the |\vsize| by
$\pm1$~line so that no page contains a club or a widow line. The
macros write a line like {\tt SINGLE: |\vsize| + 1 line} into the log
file if they change |\vsize| for a page.

This file loads {\tt pxwreport.tex} of section~1. It introduces the macro
|\footlinedist| that contains the value~30pt to replace a fix valued
of~24pt in plain's |\makefootline|.

If you change the |\vsize| in the document you must call
|\PXstorevsize|. Otherwise the routine will return to the former value
of\/ |\vsize|.

The file contains the macro |\startwithReport| that switches back to
{\tt pxwreport.tex} if it is called before the first page is
output. Otherwise, you can switch between the two output routines with
|\fromSingletoReport| and |\fromReporttoSingle|.

In order to see the actions of the output routine the flag
|\ifPXshowoutputroutine| can be set true. Then the log file contains
the information {\tt OUTPUT: single} in front of the shipped out page
number.



\beginsection 3. File {\tt pxwspread.tex}

This file implements an output routine that uses a point system to
avoid widow lines, club lines, and broken lines on a spread. It cannot
guarantee to eliminate them all, so right hand pages are more
important than left hand pages. Moreover, it accepts club lines or
broken lines if widow lines can be avoided.

The first page is output using the output routine of section~2.

This file loads {\tt pxwsingle.tex} of section~2 and, thus, it also loads
{\tt pxwreport.tex} of section~1. The flag |\ifPXshowoutputroutine| works
here too. (You can uncomment a line in the code if you want to see the
computed points.) The log file contains message pairs {\tt OUTPUT:
(left)} and {\tt (right) spread} in front of the page numbers; a
change of the |\vsize| is now reported as, for example, {\tt SPREAD:
|\vsize| - 1 line}.


To switch between output routines you can call |\startwithSingle|,
|\fromSpreadtoReport|, |\fromReporttoSpread|, |\fromSingletoSpread|,
and |\fromSpreadtoSingle|. Of course, you can also use the switch
commands of section~2 if you work with the output routine of
section~2, i.e., after you called, for example, |\fromSpreadtoSingle|.



\beginsection 4. File {\tt pxwmanual.tex}

This file loads {\tt pxwreport.tex} and provides its output routine; see
section~1. It also contains some code from {\tt pxwsingle.tex} of
section~2 and adds new macros to change |\vsize| manually.

For example, after
|\def\PXpostoutput{\PXminus(10) \PXplus(14) \PXstop(15)}| pages 10--13
are one line shorter and page~14 is one line longer. You can use
|\PXplus|, |\PXminus|, and |\PXstop| several times in the definition
or use several definitions in sequence. But only the latest
|\PXpostoutput| is active and only pages that are not yet built obey
the |\PXplus|, |\PXminus|, and |\PXstop| commands.

The log file states changes of |\vsize| in this way: {\tt MANUAL:
|\vsize| + 1 line}, {\tt MANUAL: |\vsize| - 1 line}, and {\tt MANUAL:
|\vsize|} (for |\PXstop|).


\bye