path: root/macros/latex/contrib/nowidow/nowidow.dtx

% \iffalse meta-comment
%
% Copyright (C) 2011 by Raphaël Pinson <raphink@gmail.com>
% ---------------------------------------------------------------------------
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Raphaël Pinson.
%
% This work consists of the files nowidow.dtx and nowidow.ins
% and the derived filebase nowidow.sty.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{nowidow.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{nowidow}
%<*package>
    [2011/09/20 1.0 Easily prevent widows and orphans]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{nowidow}[2011/09/14]
\usepackage{epigraph}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{nowidow.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{55}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{1.0}{2011/09/20}{Improve documentation}
% \changes{0.4}{2011/09/14}{Add orphan management}
% \changes{0.3}{2011/09/13}{Add setnowidow command and package options}
% \changes{0.2}{2011/09/11}{Fix nowidow@X}
% \changes{0.1}{2011/09/11}{Initial version}
%
% \DoNotIndex{\newcommand,\newenvironment}
%
% \providecommand*{\url}{\texttt}
% \GetFileInfo{nowidow.dtx}
% \title{The \textsf{nowidow} package}
% \author{Rapha\"el Pinson \\ \url{raphink@gmail.com}}
% \date{\fileversion~from \filedate}
%
% \maketitle
%
% \section{Introduction}
%
% \setlength{\epigraphwidth}{15em}
% \renewcommand{\epigraphsize}{\footnotesize}
% \epigraph{%
% Religion that is pure and undefiled \\
%   \hspace{2em} before God, the Father, is this: \\
%   \hspace{2em} to visit orphans and widows \\
%      \hspace{5em} in their affliction, \\
%      \hspace{5em} and to keep oneself \\
%      \hspace{5em} unstained from the world.
% }{James~1:27 --- ESV}
%
% This package was based on the answer to a
% question\footnote{\url{http://tex.stackexchange.com/questions/26272/expansion-issue-with-begingroup-and-foreach/26275\#26275}}
% about expansion with |\begingroup| and |\foreach| asked on \url{http://tex.stackexchange.com}.
% Thanks to Martin Scharrer\footnote{\url{http://tex.stackexchange.com/users/2975/martin-scharrer}} for his solution.
%
% Widows (single lines at the top of a page) and orphans
% (single lines at the bottom of a page) happen frequently
% and should be avoided.
%
% The |\widowpenalties| and |\clubpenalties| commands allow to prevent them,
% but their syntax is a bit complex to use.
%
% The \textsf{nowidow} package provides |\nowidow| and |\noclub| commands
% which are simpler to use in order to prevent widows and orphans.
%
% \section{Usage}
%
% To load the package, use:
%
% \begin{verbatim}
%    \usepackage[<options>]{nowidow}
% \end{verbatim}
%
% When no options are specified, the package will only provide macros
% and not load any settings automatically.
% The following sections describe the possible options for this package.
%
% \subsection{Options}
%
% \DescribeMacro{defaultlines=<value>}
%
% The \texttt{defaultlines} option 
% sets the default minimal number of lines
% to be kept after or before the page break.
%
% \DescribeMacro{all}
%
% The \texttt{all} option sets the widow and orphan penalties
% for the whole document upon loading the package, for example:
%
% \begin{verbatim}
%    \usepackage[defaultlines=4,all]{nowidow}
% \end{verbatim}
%
% \subsection{Commands}
%
% \DescribeMacro{\nowidow}
%
% To prevent widows in a paragraph, call |\nowidow|
% immediatly at the end of the paragraph (without an empty line),
% optionally followed by the minimal number of lines you
% want after the page break:
%
% \begin{verbatim}
% This paragraph overflows to the next page,
% but I really don't want any widows in it.
% \nowidow[3]
% \end{verbatim}
%
% The minimal number of lines to be kept after
% the page break defaults to 2 if not specified
% or overridden by the \texttt{defaultlines} option.
%
% \DescribeMacro{\setnowidow}
%
% This macro is similar to |\nowidow| but sets
% the widow penalty for the whole document
% instead of the current paragraph only.
%
% This macro is used when the package is loaded
% with the \texttt{all} option.
%
% \DescribeMacro{\noclub}
%
% This is similar to the |\nowidow| command
% but prevents orphans at the end of a page:
%
% \begin{verbatim}
% This paragraph overflows to the next page,
% but I really don't want any orphans in it.
% \noclub[3]
% \end{verbatim}
%
% The minimal number of lines to be kept before
% the page break defaults to 2 if not specified
% or overridden by the \texttt{defaultlines} option.
%
% \DescribeMacro{\setnoclub}
%
% This macro is similar to |\noclub| but sets
% the orphan penalty for the whole document
% instead of the current paragraph only.
%
% This macro is used when the package is loaded
% with the \texttt{all} option.
%
% \StopEventually{}
%
% \section{Implementation}
%
% \iffalse
%<*package>
% \fi
%
%    \begin{macrocode}
\ProvidesPackage{nowidow}
%    \end{macrocode}
%
% \begin{macro}{Options}
%    \begin{macrocode}
\RequirePackage{kvoptions}
\SetupKeyvalOptions{
   family=nowidow,
   prefix=nowidow@,
}
\DeclareStringOption[2]{defaultlines}
\DeclareBoolOption{all}
\ProcessKeyvalOptions*
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\nowidow@X}
%    \begin{macrocode}
\def\nowidow@X#1{%
    \ifnum#1<\nowidowmax
        10000
        \expandafter\nowidow@X\expandafter{%
           \the\numexpr(#1)+1\expandafter\relax\expandafter}%
    \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\setnowidow}
%    \begin{macrocode}
\newcommand{\setnowidow}[1][\nowidow@defaultlines]{%
    \mathchardef\nowidowmax#1\relax
    \widowpenalties #1 \nowidow@X{1} 0\par
}
\ifnowidow@all
   \setnowidow
\fi
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\nowidow}
%    \begin{macrocode}
\newcommand{\nowidow}[1][\nowidow@defaultlines]{%
    \begingroup
    \setnowidow[#1]
    \endgroup
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\setnoclub}
%    \begin{macrocode}
\newcommand{\setnoclub}[1][\nowidow@defaultlines]{%
    \mathchardef\nowidowmax#1\relax
    \clubpenalties #1 \nowidow@X{1} 0\par
}
\ifnowidow@all
   \setnoclub
\fi
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\noclub}
%    \begin{macrocode}
\newcommand{\noclub}[1][\nowidow@defaultlines]{%
    \begingroup
    \setnoclub[#1]
    \endgroup
}
%    \end{macrocode}
% \end{macro}
%
% \iffalse
%</package>
% \fi
%
% \Finale
\endinput