Debian Codegraph @

texmf-dist/source/latex/nowidow/nowidow.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2011 by Raphaël Pinson <[email protected]>
4 % ---------------------------------------------------------------------------
5 % This work may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either version 1.3
7 % of this license or (at your option) any later version.
8 % The latest version of this license is in
9 % http://www.latex-project.org/lppl.txt
10 % and version 1.3 or later is part of all distributions of LaTeX
11 % version 2005/12/01 or later.
12 %
13 % This work has the LPPL maintenance status `maintained'.
14 %
15 % The Current Maintainer of this work is Raphaël Pinson.
16 %
17 % This work consists of the files nowidow.dtx and nowidow.ins
18 % and the derived filebase nowidow.sty.
19 %
20 % \fi
21 %
22 % \iffalse
23 %<*driver>
24 \ProvidesFile{nowidow.dtx}
25 %</driver>
26 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
27 %<package>\ProvidesPackage{nowidow}
28 %<*package>
29 [2011/09/20 1.0 Easily prevent widows and orphans]
30 %</package>
31 %
32 %<*driver>
33 \documentclass{ltxdoc}
34 \usepackage{nowidow}[2011/09/14]
35 \usepackage{epigraph}
36 \EnableCrossrefs
37 \CodelineIndex
38 \RecordChanges
39 \begin{document}
40 \DocInput{nowidow.dtx}
41 \PrintChanges
42 \PrintIndex
43 \end{document}
44 %</driver>
45 % \fi
46 %
47 % \CheckSum{55}
48 %
49 % \CharacterTable
50 % {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
51 % 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
52 % Digits \0\1\2\3\4\5\6\7\8\9
53 % Exclamation \! Double quote \" Hash (number) \#
54 % Dollar \$ Percent \% Ampersand \&
55 % Acute accent \' Left paren \( Right paren \)
56 % Asterisk \* Plus \+ Comma \,
57 % Minus \- Point \. Solidus \/
58 % Colon \: Semicolon \; Less than \<
59 % Equals \= Greater than \> Question mark \?
60 % Commercial at \@ Left bracket \[ Backslash \\
61 % Right bracket \] Circumflex \^ Underscore \_
62 % Grave accent \` Left brace \{ Vertical bar \|
63 % Right brace \} Tilde \~}
64 %
65 %
66 % \changes{1.0}{2011/09/20}{Improve documentation}
67 % \changes{0.4}{2011/09/14}{Add orphan management}
68 % \changes{0.3}{2011/09/13}{Add setnowidow command and package options}
69 % \changes{0.2}{2011/09/11}{Fix nowidow@X}
70 % \changes{0.1}{2011/09/11}{Initial version}
71 %
72 % \DoNotIndex{\newcommand,\newenvironment}
73 %
74 % \providecommand*{\url}{\texttt}
75 % \GetFileInfo{nowidow.dtx}
76 % \title{The \textsf{nowidow} package}
77 % \author{Rapha\"el Pinson \\ \url{[email protected]}}
78 % \date{\fileversion~from \filedate}
79 %
80 % \maketitle
81 %
82 % \section{Introduction}
83 %
84 % \setlength{\epigraphwidth}{15em}
85 % \renewcommand{\epigraphsize}{\footnotesize}
86 % \epigraph{%
87 % Religion that is pure and undefiled \\
88 % \hspace{2em} before God, the Father, is this: \\
89 % \hspace{2em} to visit orphans and widows \\
90 % \hspace{5em} in their affliction, \\
91 % \hspace{5em} and to keep oneself \\
92 % \hspace{5em} unstained from the world.
93 % }{James~1:27 --- ESV}
94 %
95 % This package was based on the answer to a
96 % question\footnote{\url{http://tex.stackexchange.com/questions/26272/expansion-issue-with-begingroup-and-foreach/26275\#26275}}
97 % about expansion with |\begingroup| and |\foreach| asked on \url{http://tex.stackexchange.com}.
98 % Thanks to Martin Scharrer\footnote{\url{http://tex.stackexchange.com/users/2975/martin-scharrer}} for his solution.
99 %
100 % Widows (single lines at the top of a page) and orphans
101 % (single lines at the bottom of a page) happen frequently
102 % and should be avoided.
103 %
104 % The |\widowpenalties| and |\clubpenalties| commands allow to prevent them,
105 % but their syntax is a bit complex to use.
106 %
107 % The \textsf{nowidow} package provides |\nowidow| and |\noclub| commands
108 % which are simpler to use in order to prevent widows and orphans.
109 %
110 % \section{Usage}
111 %
112 % To load the package, use:
113 %
114 % \begin{verbatim}
115 % \usepackage[<options>]{nowidow}
116 % \end{verbatim}
117 %
118 % When no options are specified, the package will only provide macros
119 % and not load any settings automatically.
120 % The following sections describe the possible options for this package.
121 %
122 % \subsection{Options}
123 %
124 % \DescribeMacro{defaultlines=<value>}
125 %
126 % The \texttt{defaultlines} option
127 % sets the default minimal number of lines
128 % to be kept after or before the page break.
129 %
130 % \DescribeMacro{all}
131 %
132 % The \texttt{all} option sets the widow and orphan penalties
133 % for the whole document upon loading the package, for example:
134 %
135 % \begin{verbatim}
136 % \usepackage[defaultlines=4,all]{nowidow}
137 % \end{verbatim}
138 %
139 % \subsection{Commands}
140 %
141 % \DescribeMacro{\nowidow}
142 %
143 % To prevent widows in a paragraph, call |\nowidow|
144 % immediatly at the end of the paragraph (without an empty line),
145 % optionally followed by the minimal number of lines you
146 % want after the page break:
147 %
148 % \begin{verbatim}
149 % This paragraph overflows to the next page,
150 % but I really don't want any widows in it.
151 % \nowidow[3]
152 % \end{verbatim}
153 %
154 % The minimal number of lines to be kept after
155 % the page break defaults to 2 if not specified
156 % or overridden by the \texttt{defaultlines} option.
157 %
158 % \DescribeMacro{\setnowidow}
159 %
160 % This macro is similar to |\nowidow| but sets
161 % the widow penalty for the whole document
162 % instead of the current paragraph only.
163 %
164 % This macro is used when the package is loaded
165 % with the \texttt{all} option.
166 %
167 % \DescribeMacro{\noclub}
168 %
169 % This is similar to the |\nowidow| command
170 % but prevents orphans at the end of a page:
171 %
172 % \begin{verbatim}
173 % This paragraph overflows to the next page,
174 % but I really don't want any orphans in it.
175 % \noclub[3]
176 % \end{verbatim}
177 %
178 % The minimal number of lines to be kept before
179 % the page break defaults to 2 if not specified
180 % or overridden by the \texttt{defaultlines} option.
181 %
182 % \DescribeMacro{\setnoclub}
183 %
184 % This macro is similar to |\noclub| but sets
185 % the orphan penalty for the whole document
186 % instead of the current paragraph only.
187 %
188 % This macro is used when the package is loaded
189 % with the \texttt{all} option.
190 %
191 % \StopEventually{}
192 %
193 % \section{Implementation}
194 %
195 % \iffalse
196 %<*package>
197 % \fi
198 %
199 % \begin{macrocode}
200 \ProvidesPackage{nowidow}
201 % \end{macrocode}
202 %
203 % \begin{macro}{Options}
204 % \begin{macrocode}
205 \RequirePackage{kvoptions}
206 \SetupKeyvalOptions{
207 family=nowidow,
208 prefix=nowidow@,
209 }
210 \DeclareStringOption[2]{defaultlines}
211 \DeclareBoolOption{all}
212 \ProcessKeyvalOptions*
213 % \end{macrocode}
214 % \end{macro}
215 %
216 % \begin{macro}{\nowidow@X}
217 % \begin{macrocode}
218 \def\nowidow@X#1{%
219 \ifnum#1<\nowidowmax
220 10000
221 \expandafter\nowidow@X\expandafter{%
222 \the\numexpr(#1)+1\expandafter\relax\expandafter}%
223 \fi
224 }
225 % \end{macrocode}
226 % \end{macro}
227 %
228 % \begin{macro}{\setnowidow}
229 % \begin{macrocode}
230 \newcommand{\setnowidow}[1][\nowidow@defaultlines]{%
231 \mathchardef\nowidowmax#1\relax
232 \widowpenalties #1 \nowidow@X{1} 0\par
233 }
234 \ifnowidow@all
235 \setnowidow
236 \fi
237 % \end{macrocode}
238 % \end{macro}
239 %
240 % \begin{macro}{\nowidow}
241 % \begin{macrocode}
242 \newcommand{\nowidow}[1][\nowidow@defaultlines]{%
243 \begingroup
244 \setnowidow[#1]
245 \endgroup
246 }
247 % \end{macrocode}
248 % \end{macro}
249 %
250 % \begin{macro}{\setnoclub}
251 % \begin{macrocode}
252 \newcommand{\setnoclub}[1][\nowidow@defaultlines]{%
253 \mathchardef\nowidowmax#1\relax
254 \clubpenalties #1 \nowidow@X{1} 0\par
255 }
256 \ifnowidow@all
257 \setnoclub
258 \fi
259 % \end{macrocode}
260 % \end{macro}
261 %
262 % \begin{macro}{\noclub}
263 % \begin{macrocode}
264 \newcommand{\noclub}[1][\nowidow@defaultlines]{%
265 \begingroup
266 \setnoclub[#1]
267 \endgroup
268 }
269 % \end{macrocode}
270 % \end{macro}
271 %
272 % \iffalse
273 %</package>
274 % \fi
275 %
276 % \Finale
277 \endinput