| 1 |
% \iffalse |
| 2 |
% +AMDG |
| 3 |
% |
| 4 |
% This document is copyright 2019 by Donald P. Goodman, and is |
| 5 |
% released publicly under the LaTeX Project Public License. The |
| 6 |
% distribution and modification of this work is constrained by the |
| 7 |
% conditions of that license. See |
| 8 |
% http://www.latex-project.org/lppl.txt |
| 9 |
% for the text of the license. This document is released |
| 10 |
% under version 1.3c of that license, and this work may be distributed |
| 11 |
% or modified under the terms of that license or, at your option, any |
| 12 |
% later version. |
| 13 |
% |
| 14 |
% This work has the LPPL maintenance status 'maintained'. |
| 15 |
% |
| 16 |
% The Current Maintainer of this work is Donald P. Goodman |
| 17 |
% ([email protected]). |
| 18 |
% |
| 19 |
% This work consists of poetry.dtx, poetry.ins, and |
| 20 |
% derived files poetry.sty and poetry.pdf. |
| 21 |
% \fi |
| 22 |
|
| 23 |
% \iffalse |
| 24 |
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01] |
| 25 |
%<package>\ProvidesPackage{poetry}[2019/05/02 v2.2 support for typesetting poetry] |
| 26 |
%<*driver> |
| 27 |
\documentclass{ltxdoc} |
| 28 |
|
| 29 |
\usepackage{doc} |
| 30 |
\usepackage{xellipsis} |
| 31 |
\usepackage{parcolumns} |
| 32 |
\usepackage{array} |
| 33 |
\usepackage{xcolor} |
| 34 |
\usepackage{lettrine} |
| 35 |
\setcounter{DefaultLines}{3} |
| 36 |
\setlength{\DefaultFindent}{2pt} |
| 37 |
\renewcommand{\LettrineFontHook}{\color{red}} |
| 38 |
\usepackage{url} |
| 39 |
\usepackage{poetry} |
| 40 |
\usepackage{spverbatim} |
| 41 |
\usepackage[typeone]{dozenal} |
| 42 |
\usepackage{makeidx} |
| 43 |
\usepackage[colorlinks]{hyperref} |
| 44 |
\EnableCrossrefs |
| 45 |
\PageIndex |
| 46 |
\CodelineNumbered |
| 47 |
\RecordChanges |
| 48 |
\makeindex |
| 49 |
\DoNotIndex{\?,\{,\},\|,\DeclareFontFamily,\DeclareFontShape, |
| 50 |
\if,\else,\fi,\def,\divide,\clubpenalty,\widowpenalty,\ifdim,\fi, |
| 51 |
\ifnum,\fi, \ifx, \fi, \Huge, \Large, \LARGE, \begin, \end, |
| 52 |
\bfseries, \baselineskip, \begingroup,\endgroup, |
| 53 |
\jobname, \l@poem,\leftskip, \linewidth, \index, |
| 54 |
\@dottedtocline, \@firstoftwo, \@ifnextchar, \@starttoc, |
| 55 |
\addcontentsline, \advance, \everypar, \expandafter, |
| 56 |
\hangafter, \hangindent, \hbox, \hfil, \hsize, \hskip, |
| 57 |
\multiply, \linewidth, \llap, \blap, \rlap, \tlap, |
| 58 |
\makeindex, \newcommand, \newcount, \newcounter, |
| 59 |
\newdimen, \newif, \newlength, \noindent, \par, |
| 60 |
\parindent, \penalty, \ProvidesPackage, \relax, |
| 61 |
\RequirePackage, \setcounter, \setlength, \settowidth, |
| 62 |
\stepcounter, \textwidth, \the, \today, \value, \vbox, |
| 63 |
\vskip, \vss, |
| 64 |
} |
| 65 |
|
| 66 |
\def\example#1#2{% |
| 67 |
\begin{parcolumns}{2} |
| 68 |
\colchunk[1]{#1}% |
| 69 |
\colchunk[2]{#1}% |
| 70 |
\end{parcolumns} |
| 71 |
}% |
| 72 |
|
| 73 |
\tracingmacros=3 |
| 74 |
\begin{document} |
| 75 |
\DocInput{poetry.dtx} |
| 76 |
\end{document} |
| 77 |
%</driver> |
| 78 |
% \fi |
| 79 |
% |
| 80 |
% \title{The |poetry| Package, v2.2} |
| 81 |
% \author{Donald P.\ Goodman III} |
| 82 |
% \date{\today} |
| 83 |
% |
| 84 |
% \maketitle |
| 85 |
% |
| 86 |
% \begin{abstract} |
| 87 |
% The |poetry| package provides some macros and general |
| 88 |
% doodads for typesetting poetry. There is, of course, |
| 89 |
% already the excellent |verse| package, and the |poetrytex| |
| 90 |
% package provides some extra functionality on top of it. |
| 91 |
% But |poetry| provides much of the same functionality in a |
| 92 |
% bit of a different way, and with a few additional |
| 93 |
% abilities, such as facilities for a list of poems, an |
| 94 |
% index of first lines, and some structural commands. |
| 95 |
% \end{abstract} |
| 96 |
% |
| 97 |
% \tableofcontents |
| 98 |
% |
| 99 |
% \section{Introduction} |
| 100 |
% |
| 101 |
% The |verse| package provides some truly excellent verse |
| 102 |
% typesetting abilities. Its documentation, particularly, |
| 103 |
% is a great demonstration of (1) how to write \LaTeX\ |
| 104 |
% documentation, and (2) how difficult typesetting poetry |
| 105 |
% with \LaTeX\ was before |verse| came along. And yet, |
| 106 |
% occasionally one comes to some things that it doesn't seem |
| 107 |
% able to do. At least, I personally did; when lines |
| 108 |
% wrapped, the line number was placed along the |
| 109 |
% \emph{bottom} of the line, rather than the top, and there |
| 110 |
% doesn't seem to be any way to fix this rather odd |
| 111 |
% behavior. |
| 112 |
% |
| 113 |
% So, the |poetry| package was born. It endeavors to |
| 114 |
% provide all the same functionality as |verse|, in a |
| 115 |
% (mostly) compatible way; but also to fill in this little |
| 116 |
% lacuna, plus any others I happened across while doing it. |
| 117 |
% It also endeavors to add similar functionality as I found |
| 118 |
% in the other major \LaTeX\ poetry package, |poetrytex|, |
| 119 |
% which includes some great ideas for document structure. |
| 120 |
% Finally, it adds some new functionality which is not, to |
| 121 |
% my knowledge, included elsewhere. |
| 122 |
% |
| 123 |
% This document is written in accordance with the \LaTeX\ |
| 124 |
% \textsc{docstrip} utility, which allows the automatic |
| 125 |
% extraction of package code and documentation. |
| 126 |
% |
| 127 |
% The numbering in this document is in \emph{dozenal}; that |
| 128 |
% is, numbering goes 1, 2, 3, 4, 5, 6, 7, 8, 9, \x, \e, 10, |
| 129 |
% 11\xelip It uses the |dozenal| \LaTeX\ package to make |
| 130 |
% this happen. For more information, visit |
| 131 |
% \url{http://www.dozenal.org}. |
| 132 |
% |
| 133 |
% \section{Typesetting Verse} |
| 134 |
% \label{sect:verse} |
| 135 |
% |
| 136 |
% \subsection{Basics} |
| 137 |
% \label{sub:basics} |
| 138 |
% |
| 139 |
% |poetry|'s basic environment is, as one would expect, the |
| 140 |
% |poem| environment. \DescribeEnv{poem}|\begin{poem}| |
| 141 |
% and |\end{poem}| will get your poem off and running, no |
| 142 |
% questions asked. The environment redefines certain |
| 143 |
% commands, particularly |\\|, so be aware that you can't |
| 144 |
% use |\\| just anywhere within your poem. Alternatively, |
| 145 |
% you can use \DescribeMacro{\poem}|\poem| to begin the |
| 146 |
% poem, and just use the normal |\\-| to end it (about which |
| 147 |
% more in a moment). |
| 148 |
% |
| 149 |
% Conceptually, each line of the poem is a paragraph, so in |
| 150 |
% order to ensure proper paragraph setting, the |poem| |
| 151 |
% environment also resets |\parindent|, |\hangindent|, and |
| 152 |
% |\hangafter| to appropriate values. We will see how to |
| 153 |
% customize those values in Section \ref{sub:custspace}. |
| 154 |
% |
| 155 |
% End each line of your poem with \DescribeMacro{\\}|\\|, |
| 156 |
% which will end the line and also number the next line. By |
| 157 |
% default, every line is numbered; if you want some other |
| 158 |
% behavior, you will find how to customize line numbering in |
| 159 |
% Section \ref{sub:custlineno}. |
| 160 |
% |
| 161 |
% If the poem has stanzas, end them with the command |
| 162 |
% \DescribeMacro{\\!}|\\!|; this will insert the appropriate |
| 163 |
% amount of vertical spacing, as well as reset the verse |
| 164 |
% line number counter. |
| 165 |
% |
| 166 |
% To end the entire poem, after the last line use |
| 167 |
% \DescribeMacro{\\-}|\\-| (double backslash followed by a |
| 168 |
% hyphen). This clearly differentiates normal line endings; |
| 169 |
% line endings which also end stanzas; and the final line of |
| 170 |
% the poem. |
| 171 |
% |
| 172 |
% If you wish to end the poem for a moment, then resume it |
| 173 |
% later, use \DescribeMacro{\\*}|\\*|. You can then insert |
| 174 |
% whatever you want (e.g., a subpart heading, or some |
| 175 |
% annotations). When you want to start the poetry again, |
| 176 |
% begin the line with \DescribeMacro{\*}|\*|. This allows |
| 177 |
% you insert mostly arbitrary material without leaving the |
| 178 |
% |\poem| environment. |
| 179 |
% |
| 180 |
% Finally, if you want to end the poem for a moment (that |
| 181 |
% is, insert some non-poetical material, like a subpart |
| 182 |
% heading or some annotations), but also want to end a |
| 183 |
% verse, you can use \DescribeMacro{\\?}|\\?|. This |
| 184 |
% combines |\\!| and |\\*|; it has the same visual effect as |
| 185 |
% the latter, but the semantic meaning of the former. Since |
| 186 |
% non-poetical material will follow, it does \emph{not} |
| 187 |
% insert the inter-stanza spacing. You must still use |\*| |
| 188 |
% when you restart poetical material. |
| 189 |
% |
| 190 |
% The idea behind these commands is not to make life |
| 191 |
% difficult for the typesetter, but to mark semantic |
| 192 |
% concepts; that is, to mark very clearly when a line ends; |
| 193 |
% when a line ending is also a stanza ending; when a line |
| 194 |
% ending is followed by non-poetry material; and when a line |
| 195 |
% ending is also the final line of the poem. This kind of |
| 196 |
% information makes it much easier for format converters to |
| 197 |
% work, as well as for semantic readers to figure out what's |
| 198 |
% going on. |
| 199 |
% |
| 200 |
% If you need to include some non-poetry material right at |
| 201 |
% the beginning of a poem, use the starred version to begin |
| 202 |
% it: \DescribeMacro{\poetry*}|\poetry*| or |
| 203 |
% \DescribeMacro{\begin\{poem\}*}|\begin{poem}*|. This will |
| 204 |
% suppress the first line number. When you're ready to |
| 205 |
% begin your first line, begin it with |\*| to insert the |
| 206 |
% first line number. |
| 207 |
% |
| 208 |
% If a line needs some extra indentation, indent it with |
| 209 |
% \DescribeMacro{\hin}|\hin|. This adds the space |
| 210 |
% |\poemhinwd| to the left margin of that particular line and |
| 211 |
% no other. All other paragraph settings are adjusted |
| 212 |
% accordingly. This command can be repeated as needed to |
| 213 |
% produce specific indentation. |
| 214 |
% |
| 215 |
% An example of this basic usage: |
| 216 |
% |
| 217 |
% \begin{verbatim} |
| 218 |
% \begin{poem} |
| 219 |
% Let me not to the marriage of true minds \\ |
| 220 |
% \hin Admit impediments. Love is not love \\ |
| 221 |
% Which alters when it alteration finds, \\ |
| 222 |
% \hin Or bends with the remover to remove: \\! |
| 223 |
% |
| 224 |
% O, no! it is an ever-fixed mark, \\ |
| 225 |
% \hin That looks on tempests and is never shaken; \\ |
| 226 |
% It is the star to every wandering bark, \\ |
| 227 |
% \hin Whose worth's unknown, although his height be taken. \\- |
| 228 |
% \end{poem} |
| 229 |
% \end{verbatim} |
| 230 |
% |
| 231 |
% Which produces (with drastically reduced line length, to |
| 232 |
% show how wrapping will work in these cases; though keep in |
| 233 |
% mind that all these lengths are customizable): |
| 234 |
% |
| 235 |
% \setlength{\poemindent}{1.5in} |
| 236 |
% \setlength{\poemmaxlinewd}{2in} |
| 237 |
% \begin{poem} |
| 238 |
% Let me not to the marriage of true minds \\ |
| 239 |
% \hin Admit impediments. Love is not love \\ |
| 240 |
% Which alters when it alteration finds, \\ |
| 241 |
% \hin Or bends with the remover to remove: \\! |
| 242 |
% |
| 243 |
% O, no! it is an ever-fixed mark, \\ |
| 244 |
% \hin That looks on tempests and is never shaken; \\ |
| 245 |
% It is the star to every wandering bark, \\ |
| 246 |
% \hin Whose worth's unknown, although his height be taken. \\- |
| 247 |
% \end{poem} |
| 248 |
% |
| 249 |
% \subsection{Customizing Spacing and Indentation} |
| 250 |
% \label{sub:custspace} |
| 251 |
% |
| 252 |
% |poetry| inserts some space above and below the typeset |
| 253 |
% poems (unless you tell it not to). |
| 254 |
% \DescribeMacro{\poemtopskip}|\poemtopskip| is inserted |
| 255 |
% above the poem, and |
| 256 |
% \DescribeMacro{\poembotskip}|\poembotskip| is inserted |
| 257 |
% below it. These are standard \LaTeX\ lengths, and can be |
| 258 |
% reset in the usual way. By default, both are set at |
| 259 |
% |1em|. |
| 260 |
% |
| 261 |
% \DescribeMacro{\poemindent}|\poemindent| is the length |
| 262 |
% that governs how far the poem will be indented from the |
| 263 |
% left margin. Reset it as usual with \LaTeX's |\setlength| |
| 264 |
% command; e.g., |\setlength{\poemindent}{1.5in}| to indent |
| 265 |
% the entire poem 1.5in from the left margin. By default, |
| 266 |
% |\poemindent| is |0pt|, meaning that verses are flush with |
| 267 |
% the left margin. This also means that line numbers, if |
| 268 |
% they are on the left, will hang into the left margin. |
| 269 |
% |
| 270 |
% It may be that you wish to control the overall widths of |
| 271 |
% lines; for example, you may want poetry lines to be |
| 272 |
% shorter than the actual text lines. For this, use |
| 273 |
% \DescribeMacro{\poemmaxlinewd}|\poemmaxlinewd|. By |
| 274 |
% default, this standard \LaTeX\ length is set to equal |
| 275 |
% |\linewidth|, so poetry lines can equal the length of the |
| 276 |
% text block. If you don't want this, then you can set it |
| 277 |
% as you please. E.g., if your text block is |5in| wide and |
| 278 |
% you want a half inch of space on either side of your |
| 279 |
% poetry lines, set |\poemmaxlinewd| to |4in| and |
| 280 |
% |\poemindent| to |0.5in|. |
| 281 |
% |
| 282 |
% When lines wrap, |poetry| applies a certain |\hangindent| |
| 283 |
% to make them look nice. To change the length of this |
| 284 |
% hanging indent, reset the value of the standard \LaTeX\ |
| 285 |
% length \DescribeMacro{\poemhangindent}|\poemhangindent|, |
| 286 |
% in any of the usual ways (e.g., |\setlength|). By |
| 287 |
% default, |\poemhangindent| is |1em|. |
| 288 |
% |
| 289 |
% Often, particularly when a poem (or lyrics) are simply a |
| 290 |
% small portion of a largely prosaic work, we want the lines |
| 291 |
% more-or-less centered within the text block. The |verse| |
| 292 |
% package does this by providing an optional argument to the |
| 293 |
% |verse| environment, giving the length of a line which |
| 294 |
% will serve as the basis for centering the entire poem. |
| 295 |
% |poetry| instead provides the |\centerpoem| commands. |
| 296 |
% \DescribeMacro{\centerpoemon}|\centerpoemon| sets the |
| 297 |
% centering mechanism on, and (obviously) |
| 298 |
% \DescribeMacro{\centerpoemoff}|\centerpoemoff| turns it |
| 299 |
% off. |\centerpoemon| takes a mandatory argument, the line |
| 300 |
% which you wish to serve as the basis for the centering: |
| 301 |
% |
| 302 |
% \begin{center} |
| 303 |
% \cmd{\centerpoemon} \marg{line-to-use-for-centering} |
| 304 |
% \end{center} |
| 305 |
% |
| 306 |
% What this command does is measures the length of the line, |
| 307 |
% compares it to the text block, and then centers that line; |
| 308 |
% all other lines in the poem will share a left and right |
| 309 |
% margin with that line. E.g.: |
| 310 |
% |
| 311 |
% \begin{verbatim} |
| 312 |
% \centerpoemon{The ship has weather'd every rack, the prize we sought is won} |
| 313 |
% \begin{poem} |
| 314 |
% O captain! my captain! The fearful trip is done; \\ |
| 315 |
% The ship has weather'd every rack, the prize we sought is won;\\- |
| 316 |
% \end{poem} |
| 317 |
% \end{verbatim} |
| 318 |
% |
| 319 |
% Which gives us: |
| 320 |
% |
| 321 |
% \setlength{\poemmaxlinewd}{\textwidth} |
| 322 |
% \centerpoemon{The ship has weather'd every rack, the |
| 323 |
% prize we sought is won} |
| 324 |
% \begin{poem} |
| 325 |
% O captain! my captain! The fearful trip is done; \\ |
| 326 |
% The ship has weather'd every rack, the prize we sought is won;\\- |
| 327 |
% \end{poem} |
| 328 |
% |
| 329 |
% Note that this \emph{does} set the maximum line width to |
| 330 |
% the width of that line, as well. You can reset this after |
| 331 |
% issuing |\centerpoemon| if that's not the behavior you |
| 332 |
% want; that is, if you want to center on that particular |
| 333 |
% line but still allow other lines to be longer. This |
| 334 |
% behavior makes it default that your poem will actually be |
| 335 |
% centered on the width of the line you've entered; however, |
| 336 |
% if you're really just looking for an approximate optical |
| 337 |
% centering, with lines extending longer if necessary, set |
| 338 |
% |\poemmaxlinewd| to what you want your longest line to be. |
| 339 |
% Just make sure that you set it \emph{after} you set |
| 340 |
% |\centerpoemon|. |
| 341 |
% |
| 342 |
% |\centerpoemoff| simply resets |\poemindent| to |0pt| and |
| 343 |
% |\poemmaxlinewd| to |\textwidth|. |
| 344 |
% |
| 345 |
% The indentation given by |\hin| is controlled by the |
| 346 |
% \LaTeX\ length \DescribeMacro{\poemhinwd}|\poemhinwd|, |
| 347 |
% which can be set however the user wishes. By default, it |
| 348 |
% is |1em|. E.g.: |
| 349 |
% |
| 350 |
% \begin{verbatim} |
| 351 |
% \centerpoemon{Alas, poor Yorick! I knew him. Horatio!} |
| 352 |
% \settowidth{\poemhinwd}{Alas, poor Yorick! I knew him. } |
| 353 |
% \begin{poem} |
| 354 |
% Alas, poor Yorick! I knew him.\\ |
| 355 |
% \hin Horatio! \\ |
| 356 |
% \setlength{\poemhinwd}{2em} |
| 357 |
% A fellow of infinite jest, of most excellent fancy. \\ |
| 358 |
% \hin He hath borne me on his back a thousand times, \\ |
| 359 |
% and now, how abhorred in my imagination it is! \\ |
| 360 |
% My gorge rises at it. Here hung those lips\xelip\\- |
| 361 |
% \end{poem} |
| 362 |
% \end{verbatim} |
| 363 |
% |
| 364 |
% This is a common requirement when the meter of one line is |
| 365 |
% continued onto the next, as in this famous line(s) from |
| 366 |
% \textit{Hamlet}: |
| 367 |
% |
| 368 |
% \centerpoemon{Alas, poor Yorick! I knew him. Horatio!} |
| 369 |
% \begin{poem} |
| 370 |
% \settowidth{\poemhinwd}{Alas, poor Yorick! I knew him. } |
| 371 |
% Alas, poor Yorick! I knew him.\\ |
| 372 |
% \hin Horatio! \\ |
| 373 |
% \setlength{\poemhinwd}{2em} |
| 374 |
% A fellow of infinite jest, of most excellent fancy. \\ |
| 375 |
% \hin He hath\label{ln:ex} borne me on his back a thousand times, \\ |
| 376 |
% and now, how abhorred in my imagination it is! \\ |
| 377 |
% My gorge rises at it. Here hung those lips\xelip\\- |
| 378 |
% \end{poem} |
| 379 |
% |
| 380 |
% This way we can advance the second line so that it's |
| 381 |
% clearly a continuation of the first. The second |\hin| |
| 382 |
% command here is just to show that the lengths can be |
| 383 |
% adjusted at will throughout the poem, and it doesn't |
| 384 |
% effect the line numbering in any way. |
| 385 |
% |
| 386 |
% Using |\hin| manually works fine, but sometimes it's a |
| 387 |
% hassle, particularly when the indentation pattern is |
| 388 |
% regular. E.g., when every second line is to be indented, |
| 389 |
% why should you manually have to insert |\hin| every second |
| 390 |
% line? That's the sort of thing computers are good at. |
| 391 |
% Fortunately, |poetry| agrees with you, and offers the |
| 392 |
% \DescribeMacro{poemindentevery}|poemindentevery| counter. |
| 393 |
% This is a standard \LaTeX\ counter. If its value is |0|, |
| 394 |
% it has no effect whatsoever; if its value is any other |
| 395 |
% integer, however, it will indent every multiple of that |
| 396 |
% line number. E.g.: |
| 397 |
% |
| 398 |
% \begin{verbatim} |
| 399 |
% \setcounter{poemindentevery}{3} |
| 400 |
% \setcounter{poemlinenumsevery}{2} |
| 401 |
% \begin{poem} |
| 402 |
% Once upon a midnight dreary, while I pondered, weak and weary,\\ |
| 403 |
% Over many a quaint and curious volume of forgotten lore---\\ |
| 404 |
% While I nodded, nearly napping, suddenly there came a tapping,\\ |
| 405 |
% As of someone gently rapping, rapping at my chamber door.\\ |
| 406 |
% ``'Tis some visitor,'' I muttered, ``tapping at my chamber door---\\ |
| 407 |
% Only this and nothing more.''\\- |
| 408 |
% \end{poem} |
| 409 |
% \end{verbatim} |
| 410 |
% |
| 411 |
% Which will give us this: |
| 412 |
% |
| 413 |
% \setcounter{poemindentevery}{3} |
| 414 |
% \setcounter{poemlinenumsevery}{2} |
| 415 |
% \begin{poem} |
| 416 |
% Once upon a midnight dreary, while I pondered, weak and weary,\\ |
| 417 |
% Over many a quaint and curious volume of forgotten lore---\\ |
| 418 |
% While I nodded, nearly napping, suddenly there came a tapping,\\ |
| 419 |
% As of someone gently rapping, rapping at my chamber door.\\ |
| 420 |
% ``'Tis some visitor,'' I muttered, ``tapping at my chamber door---\\ |
| 421 |
% Only this and nothing more.''\\- |
| 422 |
% \end{poem} |
| 423 |
% \setcounter{poemindentevery}{0} |
| 424 |
% \setcounter{poemlinenumsevery}{1} |
| 425 |
% |
| 426 |
% Notice that line numbers are also unaffected by this |
| 427 |
% setting; line numbers will be placed where needed, and |
| 428 |
% indents will be added as needed, without regard for one |
| 429 |
% another. (We will officially meet the counter |
| 430 |
% |poemlinenumsevery| in Section \ref{subsub:basiclineno}.) |
| 431 |
% |
| 432 |
% Sometimes, however, indenting every third line (or |
| 433 |
% whatever) isn't the right solution; sometimes each |
| 434 |
% \emph{verse} has a particular indentation pattern. For |
| 435 |
% that, |poetry| offers the command |
| 436 |
% \DescribeMacro{\poemvsindentlines}|\poemvsindentlines|. |
| 437 |
% Redefine this command to contain a list of the line |
| 438 |
% numbers (by verse) you wish to indent, and |poetry| will dutifully |
| 439 |
% indent them. E.g.: |
| 440 |
% |
| 441 |
% \begin{verbatim} |
| 442 |
% \def\poemvsindentlines{23}% |
| 443 |
% \begin{poem} |
| 444 |
% I saw you starting for another war,\\ |
| 445 |
% The emblem of adventure and of youth,\\ |
| 446 |
% So that men trembled, saying: He forsooth\\ |
| 447 |
% Has gone, has gone, and shall return no more.\\- |
| 448 |
% \end{poem} |
| 449 |
% \end{verbatim} |
| 450 |
% |
| 451 |
% \def\poemvsindentlines{23}% |
| 452 |
% \begin{poem} |
| 453 |
% I saw you starting for another war,\\ |
| 454 |
% The emblem of adventure and of youth,\\ |
| 455 |
% So that men trembled, saying: He forsooth\\ |
| 456 |
% Has gone, has gone, and shall return no more.\\- |
| 457 |
% \end{poem} |
| 458 |
% \def\poemvsindentlines{0}% |
| 459 |
% |
| 460 |
% If you give a line number larger than the number of lines |
| 461 |
% in a verse, it will be quietly ignored. |
| 462 |
% |
| 463 |
% Note that |\poemvsindentlines| and |poemindentevery| will |
| 464 |
% \emph{stack}; if a line qualifies for both, it will be |
| 465 |
% indented twice. |
| 466 |
% |
| 467 |
% |\poemvsindentlines| allows you to arrange the indentation |
| 468 |
% on each verse with very fine detail, assuming that all |
| 469 |
% your verses are indented the same way. |
| 470 |
% |
| 471 |
% Finally, you should meet |
| 472 |
% \DescribeMacro{\poemverseskip}|\poemverseskip|, which |
| 473 |
% controls the distance between verses (stanzas) of the |
| 474 |
% poem. By default, this is set equal to |\baselineskip|, |
| 475 |
% leaving about one full line between stanzas. This is a |
| 476 |
% standard \LaTeX\ length, and can be reset in the usual |
| 477 |
% way. |
| 478 |
% |
| 479 |
% \subsection{Customizing Line Numbering} |
| 480 |
% \label{sub:custlineno} |
| 481 |
% |
| 482 |
% \subsubsection{Basics of Line Numbering} |
| 483 |
% \label{subsub:basiclineno} |
| 484 |
% |
| 485 |
% Line numbers, unlike in |verse|, \emph{are} typeset by |
| 486 |
% default. To turn them off, just say |
| 487 |
% \DescribeMacro{\poemlinenumsfalse}|\poemlinenumsfalse|. |
| 488 |
% Of course, issuing |
| 489 |
% \DescribeMacro{\poemlinenumstrue}|\poemlinenumstrue| will |
| 490 |
% do the opposite. |
| 491 |
% |
| 492 |
% \centerpoemoff |
| 493 |
% \begin{verbatim} |
| 494 |
% \poemlinenumsfalse |
| 495 |
% \begin{poem} |
| 496 |
% O captain! my captain! The fearful trip is done; \\ |
| 497 |
% \poemlinenumstrue |
| 498 |
% The ship has weather'd every rack, the prize we sought is won;\\ |
| 499 |
% The port is near, the bells I hear, the people all exulting, \\ |
| 500 |
% While follow eyes the steady keel, the vessel grim and daring; \\- |
| 501 |
% \end{poem} |
| 502 |
% \end{verbatim} |
| 503 |
% |
| 504 |
% Which gives us: |
| 505 |
% |
| 506 |
% \poemindent=0pt |
| 507 |
% \poemlinenumsfalse |
| 508 |
% \begin{poem} |
| 509 |
% O captain! my captain! The fearful trip is done; \\ |
| 510 |
% \poemlinenumstrue |
| 511 |
% The ship has weather'd every rack, the prize we sought is won;\\ |
| 512 |
% The port is near, the bells I hear, the people all exulting, \\ |
| 513 |
% While follow eyes the steady keel, the vessel grim and daring; \\- |
| 514 |
% \end{poem} |
| 515 |
% |
| 516 |
% Notice that |poetry| actually sets the line number |
| 517 |
% \emph{before} the rest of the line; so when turning line |
| 518 |
% numbers on again, you need to put |\poemlinenumstrue| one |
| 519 |
% line earlier than you might expect. |
| 520 |
% |
| 521 |
% Line numbers aren't just on or off, however; you can have |
| 522 |
% them every certain number of lines, for example. The |
| 523 |
% command for this is |
| 524 |
% \DescribeMacro{\poemlinenumsevery}|\poemlinenumsevery|; note that |
| 525 |
% this is a \emph{counter}, so redefine it with |
| 526 |
% |\setcounter| and friends. By default, its value is |1|. |
| 527 |
% The value works as one would expect; |2| means a number |
| 528 |
% every two lines, |3| every three lines, and so on. For |
| 529 |
% example: |
| 530 |
% |
| 531 |
% \begin{verbatim} |
| 532 |
% \setcounter{poemlinenumsevery}{2} |
| 533 |
% \poemlinenumstrue |
| 534 |
% \begin{poem} |
| 535 |
% O captain! my captain! The fearful trip is done; \\ |
| 536 |
% The ship has weather'd every rack, the prize we sought is won;\\ |
| 537 |
% The port is near, the bells I hear, the people all exulting, \\ |
| 538 |
% While follow eyes the steady keel, the vessel grim and daring; \\- |
| 539 |
% \end{poem} |
| 540 |
% \end{verbatim} |
| 541 |
% |
| 542 |
% Gives us this: |
| 543 |
% |
| 544 |
% \setcounter{poemlinenumsevery}{2} |
| 545 |
% \poemlinenumstrue |
| 546 |
% \begin{poem} |
| 547 |
% O captain! my captain! The fearful trip is done; \\ |
| 548 |
% The ship has weather'd every rack, the prize we sought is won;\\ |
| 549 |
% The port is near, the bells I hear, the people all exulting, \\ |
| 550 |
% While follow eyes the steady keel, the vessel grim and daring; \\- |
| 551 |
% \end{poem} |
| 552 |
% \setcounter{poemlinenumsevery}{0} |
| 553 |
% |
| 554 |
% This can, of course, be set to any value, though typically |
| 555 |
% 1--4 are reasonable ones. A sufficiently high number will |
| 556 |
% essentially turn off line numbering; e.g., 84, as by the |
| 557 |
% time you've seen the 84th line you won't remember what the |
| 558 |
% last line number was. But I'm certainly not going to make |
| 559 |
% it impossible. |
| 560 |
% |
| 561 |
% Often, though, you won't want to print line numbers every |
| 562 |
% arbitrary number of lines throughout the poem, but on |
| 563 |
% certain lines by verse. E.g., perhaps you want to number |
| 564 |
% lines 2, 3, and 5 of a poem, but not 1, 4, and 6. To |
| 565 |
% accomplish this, use the \DescribeMacro{\poemnumlines}|\poemnumlines| |
| 566 |
% macro. If empty, it has no effect, and by default it is |
| 567 |
% empty. However, if you put in a list of numbers, |
| 568 |
% then the lines of each stanza corresponding to that list |
| 569 |
% of numbers will be numbered accordingly. So, for example, |
| 570 |
% to number 2, 3, and 5 only: |
| 571 |
% |
| 572 |
% \begin{verbatim} |
| 573 |
% \def\poemnumlines{235} |
| 574 |
% \begin{poem} |
| 575 |
% Once upon a midnight dreary, while I pondered, weak and weary,\\ |
| 576 |
% Over many a quaint and curious volume of forgotten lore---\\ |
| 577 |
% While I nodded, nearly napping, suddenly there came a tapping,\\ |
| 578 |
% As of someone gently rapping, rapping at my chamber door.\\ |
| 579 |
% ``'Tis some visitor,'' I muttered, ``tapping at my chamber door---\\ |
| 580 |
% Only this and nothing more.''\\- |
| 581 |
% \end{poem} |
| 582 |
% \def\poemnumlines{} |
| 583 |
% \end{verbatim} |
| 584 |
% |
| 585 |
% Yields the following: |
| 586 |
% \def\poemnumlines{235} |
| 587 |
% \begin{poem} |
| 588 |
% Once upon a midnight dreary, while I pondered, weak and weary,\\ |
| 589 |
% Over many a quaint and curious volume of forgotten lore---\\ |
| 590 |
% While I nodded, nearly napping, suddenly there came a tapping,\\ |
| 591 |
% As of someone gently rapping, rapping at my chamber door.\\ |
| 592 |
% ``'Tis some visitor,'' I muttered, ``tapping at my chamber door---\\ |
| 593 |
% Only this and nothing more.''\\- |
| 594 |
% \end{poem} |
| 595 |
% \def\poemnumlines{} |
| 596 |
% |
| 597 |
% This pattern will repeat for each verse until you set |
| 598 |
% |\poemnumline| to something else. |
| 599 |
% |
| 600 |
% Finally, line numbers can be placed on either the right or the |
| 601 |
% left. |poetry| v2.0 introduces significantly more |
| 602 |
% flexibility into this mechanic; however, to preserve |
| 603 |
% backward compatibility, the old commands are still |
| 604 |
% recognized. To place line numbers on the right, use |
| 605 |
% \DescribeMacro{\poemlinenumrighttrue}|\poemlinenumrighttrue|; |
| 606 |
% to put them back on the left, use the corresponding |
| 607 |
% command |
| 608 |
% \DescribeMacro{\poemlinenumrightfalse}|\poemlinenumrightfalse|. |
| 609 |
% Note that these commands merely set the right-hand line |
| 610 |
% number spot to equal the poem line counter; this will make |
| 611 |
% sense to you later. |
| 612 |
% |
| 613 |
% \begin{verbatim} |
| 614 |
% \poemlinenumrighttrue |
| 615 |
% \setcounter{poemlinenumsevery}{1} |
| 616 |
% \begin{poem} |
| 617 |
% O captain! my captain! The fearful trip is done; \\ |
| 618 |
% \poemlinenumrightfalse |
| 619 |
% The ship has weather'd every rack, the prize we sought is won;\\ |
| 620 |
% The port is near, the bells I hear, the people all exulting, \\ |
| 621 |
% While follow eyes the steady keel, the vessel grim and daring; \\- |
| 622 |
% \end{poem} |
| 623 |
% \end{verbatim} |
| 624 |
% |
| 625 |
% Which gives us this (notice that right-side line numbers |
| 626 |
% are placed after |\poemmaxlinewd|): |
| 627 |
% |
| 628 |
% \poemlinenumrighttrue |
| 629 |
% \setcounter{poemlinenumsevery}{1} |
| 630 |
% \begin{poem} |
| 631 |
% O captain! my captain! The fearful trip is done; \\ |
| 632 |
% \poemlinenumrightfalse |
| 633 |
% The ship has weather'd every rack, the prize we sought is won;\\ |
| 634 |
% The port is near, the bells I hear, the people all exulting, \\ |
| 635 |
% While follow eyes the steady keel, the vessel grim and daring; \\- |
| 636 |
% \end{poem} |
| 637 |
% |
| 638 |
% Notice again that the line's line number is printed |
| 639 |
% \emph{first}, before the line; so you need to put this |
| 640 |
% command one line earlier than you'd expect. |
| 641 |
% |
| 642 |
% Please notice also that \emph{the line numbers are |
| 643 |
% \emph{not} part of the line when calculating widths}. |
| 644 |
% They are boxes which overhang the end or beginning of the |
| 645 |
% line. Please keep that in mind when you're planning your |
| 646 |
% formats. |
| 647 |
% |
| 648 |
% As of v2.0, |poetry| allows numbering to appearing on both |
| 649 |
% the right \emph{and} left side of the poem. This is a |
| 650 |
% much more flexible mechanism than before, and should be |
| 651 |
% used in preference to the old |\poemlinenumsrighttrue| |
| 652 |
% mechanism in any new work. |
| 653 |
% |
| 654 |
% Any of the line numbering variables beginning with |\poem| |
| 655 |
% have corresponding versions beginning with |\poemrt|. You |
| 656 |
% can then set the variables arbitrarily for the left and |
| 657 |
% right sides, which will not effect one another. |
| 658 |
% E.g., perhaps you want to show total line numbers on the |
| 659 |
% left, and verse line numbers on the right, both on every |
| 660 |
% two lines: |
| 661 |
% |
| 662 |
% \begin{quote} |
| 663 |
% |\renewcommand{\thepoemline}{\arabic{poemline}}|\\ |
| 664 |
% |\setcounter{poemlinenumsevery}{2}|\\ |
| 665 |
% |\setcounter{poemrtlinenumsevery}{2}|\\ |
| 666 |
% |\renewcommand{\thepoemrtline}{\arabic{verseline}}|\\ |
| 667 |
% \end{quote} |
| 668 |
% |
| 669 |
% \renewcommand{\thepoemline}{\arabic{poemline}} |
| 670 |
% \setcounter{poemlinenumsevery}{2} |
| 671 |
% \setcounter{poemrtlinenumsevery}{2} |
| 672 |
% \renewcommand{\thepoemrtline}{\arabic{verseline}} |
| 673 |
% \centerpoemon{Whose woods these are I think I know.} |
| 674 |
% \begin{poem} |
| 675 |
% Whose woods these are I think I know. \\ |
| 676 |
% His house is in the village though; \\ |
| 677 |
% He will not see me stopping here \\ |
| 678 |
% To watch his woods fill up with snow. \\! |
| 679 |
% |
| 680 |
% My little horse must think it queer \\ |
| 681 |
% To stop without a farmhouse near \\ |
| 682 |
% Between the woods and frozen lake \\ |
| 683 |
% The darkest evening of the year. \\- |
| 684 |
% \end{poem} |
| 685 |
% \setcounter{poemlinenumsevery}{0} |
| 686 |
% \setcounter{poemrtlinenumsevery}{0} |
| 687 |
% |
| 688 |
% This is useful for those volumes that wish to list a |
| 689 |
% stanza number as well as a line numbers, one on each side. |
| 690 |
% |poetry| offers the stanza number as the counter |
| 691 |
% \DescribeMacro{stanzacount}|stanzacount|. For example, to |
| 692 |
% put the line count on the right, with a stanza count on the |
| 693 |
% first line of each stanza on the left: |
| 694 |
% |
| 695 |
% \begin{quote} |
| 696 |
% |\def\poemnumlines{1}|\\ |
| 697 |
% |\renewcommand{\thepoemline}{\arabic{stanzacount}}|\\ |
| 698 |
% |\setcounter{poemrtlinenumsevery}{1}|\\ |
| 699 |
% |\renewcommand{\thepoemrtline}{\arabic{poemline}}|\\ |
| 700 |
% \end{quote} |
| 701 |
% |
| 702 |
% \def\poemnumlines{1} |
| 703 |
% \renewcommand{\thepoemline}{\arabic{stanzacount}} |
| 704 |
% \setcounter{poemrtlinenumsevery}{1} |
| 705 |
% \renewcommand{\thepoemrtline}{\arabic{poemline}} |
| 706 |
% \centerpoemon{Whose woods these are I think I know.} |
| 707 |
% \begin{poem} |
| 708 |
% Whose woods these are I think I know. \\ |
| 709 |
% His house is in the village though; \\ |
| 710 |
% He will not see me stopping here \\ |
| 711 |
% To watch his woods fill up with snow. \\! |
| 712 |
% |
| 713 |
% My little horse must think it queer \\ |
| 714 |
% To stop without a farmhouse near \\ |
| 715 |
% Between the woods and frozen lake \\ |
| 716 |
% The darkest evening of the year. \\- |
| 717 |
% \end{poem} |
| 718 |
% |
| 719 |
% We can occasionally do some truly interesting things this |
| 720 |
% way. For example, to have odd-numbered lines marked on |
| 721 |
% the left and even on the right: |
| 722 |
% |
| 723 |
% \begin{quote} |
| 724 |
% |\renewcommand{\thepoemline}{\arabic{poemline}}|\\ |
| 725 |
% |\renewcommand{\thepoemrtline}{\arabic{poemline}}|\\ |
| 726 |
% |\def\poemnumlines{13}|\\ |
| 727 |
% |\def\poemrtnumlines{24}|\\ |
| 728 |
% \end{quote} |
| 729 |
% |
| 730 |
% \setcounter{poemlinenumsevery}{99} |
| 731 |
% \setcounter{poemrtlinenumsevery}{99} |
| 732 |
% \renewcommand{\thepoemline}{\arabic{poemline}} |
| 733 |
% \renewcommand{\thepoemrtline}{\arabic{poemline}} |
| 734 |
% \def\poemnumlines{13} |
| 735 |
% \def\poemrtnumlines{24} |
| 736 |
% \centerpoemon{Whose woods these are I think I know.} |
| 737 |
% \begin{poem} |
| 738 |
% Whose woods these are I think I know. \\ |
| 739 |
% His house is in the village though; \\ |
| 740 |
% He will not see me stopping here \\ |
| 741 |
% To watch his woods fill up with snow. \\! |
| 742 |
% |
| 743 |
% My little horse must think it queer \\ |
| 744 |
% To stop without a farmhouse near \\ |
| 745 |
% Between the woods and frozen lake \\ |
| 746 |
% The darkest evening of the year. \\! |
| 747 |
% |
| 748 |
% He gives his harness bells a shake \\ |
| 749 |
% To ask if there is some mistake. \\ |
| 750 |
% The only other sound's the sweep \\ |
| 751 |
% Of easy wind and downy flake. \\- |
| 752 |
% \end{poem} |
| 753 |
% |
| 754 |
% \subsubsection{Styling Line Numbers} |
| 755 |
% \label{subsub:stylelineno} |
| 756 |
% |
| 757 |
% As mentioned before, the line numbers are set in boxes |
| 758 |
% which overhang either the left or right margins of the |
| 759 |
% line, depending on the value of |\ifpoemlinenumright| |
| 760 |
% (that is, on whether you've isseud |\poemlinenumrighttrue| |
| 761 |
% or not). The size of that box, and how much it overhangs |
| 762 |
% the margin, are both within your control. |
| 763 |
% |
| 764 |
% By default, the box is |2em| wide, and it's separated from |
| 765 |
% the margin by |0pt|. To change the space between the box |
| 766 |
% and the line itself, use the standard \LaTeX\ length |
| 767 |
% \DescribeMacro{\poemlinenumboxgap}|\poemlinenumboxgap|; |
| 768 |
% below, see some lines from \textit{Henry V} to |
| 769 |
% demonstrate. The first two lines are set with default |
| 770 |
% line number spacing; the second two with |
| 771 |
% |\poemlinenumboxgap| set to |1em|: |
| 772 |
% |
| 773 |
% \centerpoemon{We few, we happy few; we band of brothers;} |
| 774 |
% |
| 775 |
% \poemlinenumrightfalse |
| 776 |
% \begin{poem} |
| 777 |
% We few, we happy few; we band of brothers; \\ |
| 778 |
% \setlength{\poemlinenumboxgap}{1em} |
| 779 |
% for he today who sheds his blood with me \\ |
| 780 |
% shall be my brother; be he ne'er so vile \\ |
| 781 |
% this day shall gentle his condition. \\- |
| 782 |
% \end{poem} |
| 783 |
% |
| 784 |
% The width of the line number box itself is controlled by |
| 785 |
% \DescribeMacro{\poemlinenumboxwd}|\poemlinenumboxwd|, |
| 786 |
% another standard \LaTeX\ length which can be reset, as |
| 787 |
% usual, with |\setlength|. Below, we have some more of |
| 788 |
% \textit{Henry V}, this time with varying line number box |
| 789 |
% widths; the first two lines have the default, the second |
| 790 |
% two have a width of |1em|: |
| 791 |
% |
| 792 |
% \centerpoemon{shall think themselves accurs'd they were not here,} |
| 793 |
% \poemlinenumrighttrue |
| 794 |
% \begin{poem} |
| 795 |
% And gentlemen in England now abed \\ |
| 796 |
% \setlength{\poemrtlinenumboxwd}{1em} |
| 797 |
% shall think themselves accurs'd they were not here, \\ |
| 798 |
% and hold their manhoods cheap whilst any speaks \\ |
| 799 |
% that fought with us, upon St.~Crispin's day. \\- |
| 800 |
% \end{poem} |
| 801 |
% |
| 802 |
% The line number itself is held in the \LaTeX\ macro |
| 803 |
% \DescribeMacro{\thepoemline}|\thepoemline|; so you can |
| 804 |
% style this as you wish. However, in the event you want |
| 805 |
% line numbers to look a certain way in the poem itself, |
| 806 |
% but a different way when you use them elsehwere, you can |
| 807 |
% use \DescribeMacro{\poemlinenumstyle}|\poemlinenumstyle| |
| 808 |
% to change their appearance. For example, the following |
| 809 |
% uses |\def\poemlinenumstyle{\footnotesize\color{green}}| |
| 810 |
% and |\def\poemrtlinenumstyle{\LARGE\color{red}}|: |
| 811 |
% |
| 812 |
% \centerpoemon{Thou see'st the world, Volumnius, how it goes; } |
| 813 |
% \renewcommand{\thepoemline}{\arabic{poemline}} |
| 814 |
% \renewcommand{\thepoemrtline}{\arabic{poemline}} |
| 815 |
% \def\poemnumlines{13} |
| 816 |
% \def\poemrtnumlines{24} |
| 817 |
% \def\poemlinenumstyle{\footnotesize\color{green}} |
| 818 |
% \def\poemrtlinenumstyle{\LARGE\color{red}} |
| 819 |
% \begin{poem} |
| 820 |
% Thou see'st the world, Volumnius, how it goes; \\ |
| 821 |
% our enemies have beat us to the pit. \\ |
| 822 |
% It would be better to jump in ourselves, \\ |
| 823 |
% than tarry till they push us. \\- |
| 824 |
% \end{poem} |
| 825 |
% |
| 826 |
% The right line style is an insane choice; but it does |
| 827 |
% demonstrate how things work. By default, both |
| 828 |
% |\poemlinenumstyle| and |\poemrtlinenumstyle| do nothing. |
| 829 |
% \def\poemlinenumstyle{} |
| 830 |
% \def\poemrtlinenumstyle{} |
| 831 |
% \def\poemrtnumlines{} |
| 832 |
% |
| 833 |
% Labels can be placed on any line of poetry, and refer back |
| 834 |
% to that line. Make references with the usual \LaTeX\ |
| 835 |
% |\ref| and |\label| commands; for example, ``line |
| 836 |
% \ref{ln:ex}'' refers to line 4 of the quotation from |
| 837 |
% \textit{Hamlet} we gave you earlier. If you've loaded |
| 838 |
% |hyperref|, these will correctly turn into hyperlinks, as |
| 839 |
% well. |
| 840 |
% |
| 841 |
% |
| 842 |
% \section{Document Structure} |
| 843 |
% \label{sect:structure} |
| 844 |
% |
| 845 |
% |poetry| actually provides some significant structural |
| 846 |
% commands, as well, which may make it easier to typeset |
| 847 |
% larger amounts of poetry. It was inspired here more by |
| 848 |
% |poetrytex| than by |verse|; indeed, this area is really |
| 849 |
% where |poetrytex| shines. However, |poetry| does add some |
| 850 |
% functionality to it. We'll explore first counters, |
| 851 |
% then sectioning. |
| 852 |
% |
| 853 |
% \subsection{Other Counters} |
| 854 |
% \label{sub:othcounters} |
| 855 |
% |
| 856 |
% |poetry| provides several other counters, which will |
| 857 |
% probably rarely be useful when typesetting poetry, but |
| 858 |
% which are provided just in case. |
| 859 |
% |
| 860 |
% Besides |\thepoemline|, we also have |
| 861 |
% \DescribeMacro{verseline}|verseline|, a counter which |
| 862 |
% keeps track of what line in a given verse is currently |
| 863 |
% being typeset. It's reset every time you call |\\!|, to |
| 864 |
% signify the end of a verse (or, more properly for poetry, |
| 865 |
% stanza). It's typeset with |\theverseline|, which can be |
| 866 |
% redefined in the normal \LaTeX\ ways. For example, to |
| 867 |
% number each verse with the poem line number, a colon, and |
| 868 |
% a verse line number, try: |
| 869 |
% |
| 870 |
% \begin{center} |
| 871 |
% |\renewcommand{\thepoemline}{\arabic{poemline}:\arabic{verseline}}| |
| 872 |
% \end{center} |
| 873 |
% |
| 874 |
% You'll get something like this: |
| 875 |
% |
| 876 |
% \renewcommand{\thepoemline}{\arabic{poemline}:\arabic{verseline}} |
| 877 |
% \centerpoemon{Whose woods these are I think I know.} |
| 878 |
% \begin{poem} |
| 879 |
% Whose woods these are I think I know. \\ |
| 880 |
% His house is in the village though; \\ |
| 881 |
% He will not see me stopping here \\ |
| 882 |
% To watch his woods fill up with snow. \\! |
| 883 |
% |
| 884 |
% My little horse must think it queer \\ |
| 885 |
% To stop without a farmhouse near \\ |
| 886 |
% Between the woods and frozen lake \\ |
| 887 |
% The darkest evening of the year. \\- |
| 888 |
% \end{poem} |
| 889 |
% |
| 890 |
% We also have a counter for the number of poems themselves; |
| 891 |
% two, actually. First is |
| 892 |
% \DescribeMacro{abspoemno}|abspoemno|, which keeps track of |
| 893 |
% the poem numbers throughout the entire document. |
| 894 |
% |abspoemno| is typeset, as always with \LaTeX\ counters, |
| 895 |
% with |\theabspoemno|. This number can be useful with sets |
| 896 |
% of poems, such as Shakespeare's sonnets; or with |
| 897 |
% anthologies which include untitled poems, which might |
| 898 |
% otherwise be difficult to list in a table of contents. |
| 899 |
% |
| 900 |
% Second, there is the \emph{poem group} counter, or |
| 901 |
% \DescribeMacro{poemno}|poemno|. |poemno| equals |
| 902 |
% |abspoemno| unless you're utilizing poem groups (for which |
| 903 |
% see Section \ref{sub:structures}). Starting a new poem |
| 904 |
% group resets |poemno| but not |abspoemno|. |
| 905 |
% |
| 906 |
% We will see some poetry-specific sectioning commands in |
| 907 |
% Section \ref{subsub:usemeta}. These commands increment |
| 908 |
% |poemno| and |abspoemno|; so if you're not using those |
| 909 |
% sectioning commands, these numbers won't be incremented. |
| 910 |
% If for some reason you don't use a visible title for your |
| 911 |
% poem, or wish to use your own sectioning commands, but |
| 912 |
% still want it counted for the purposes of these counters, |
| 913 |
% you need to tell |poetry| so. Issue |
| 914 |
% \DescribeMacro{\poemnew}|\poemnew| prior to starting your |
| 915 |
% |poem| environment; it will increment your counters |
| 916 |
% without putting anything in your text. |
| 917 |
% |
| 918 |
% These counters are formatted, as always, with the \LaTeX\ |
| 919 |
% |\the| commands: |\thepoemno|, |\theabspoemno|. |
| 920 |
% |
| 921 |
% \subsection{Other Variables} |
| 922 |
% \label{sub:othervars} |
| 923 |
% |
| 924 |
% |poetry| gives a few variables that we can use to fill in |
| 925 |
% gaps when we have them. |
| 926 |
% |
| 927 |
% \DescribeMacro{\poemblanktitle}|\poemblanktitle| is the |
| 928 |
% word that |poetry| will use when it's asked to typeset a |
| 929 |
% title but it doesn't have one; by default, this is set as |
| 930 |
% |Untitled|. Reset this with |\def| or |\renewcommand|; |
| 931 |
% e.g., |\renewcommand{\poemblanktitle}{Not Titled}|. Then, |
| 932 |
% when you are expected to input a title and you don't have |
| 933 |
% one (possible in, for example, the |\titlepoem| command, |
| 934 |
% for which see Section \ref{sub:metadata}), instead of |
| 935 |
% printing ``Untitled'', |poetry| will print ``Not Titled''. |
| 936 |
% |
| 937 |
% There is a corresponding |
| 938 |
% \DescribeMacro{\poemblankauthor}|\poemblankauthor|, which |
| 939 |
% does the same thing. Its default value is |Anonymous|. |
| 940 |
% |
| 941 |
% \subsection{Metadata} |
| 942 |
% \label{sub:metadata} |
| 943 |
% |
| 944 |
% All poems have authors, even if we don't know who; and |
| 945 |
% some also have titles. In other words, poems have |
| 946 |
% \emph{metadata}, data about themselves, and |poetry| |
| 947 |
% provides easy ways to deal with these things, whether we |
| 948 |
% have the information or not. Sometimes it will be |
| 949 |
% convenient to use the variables from Section |
| 950 |
% \ref{sub:othervars} in these commands. |
| 951 |
% |
| 952 |
% |poetry| keeps the issue of \emph{having} the metadata |
| 953 |
% separate from \emph{typesetting} it. You can set these |
| 954 |
% variables but never have them appear in the final |
| 955 |
% document. In theory, this information could instead by |
| 956 |
% embedded in the |pdf| for document readers to use, or |
| 957 |
% things of that nature. At present, pdf doesn't have any |
| 958 |
% means to embed metadata about individual parts of a |
| 959 |
% document; however, should such a capability be added, |
| 960 |
% |poetry| will be ready. |
| 961 |
% |
| 962 |
% \subsubsection{Setting Metadata Values} |
| 963 |
% \label{subsub:setmeta} |
| 964 |
% |
| 965 |
% \DescribeMacro{\thepoemtitle}|\thepoemtitle| holds the |
| 966 |
% currently defined poem title, if any. You might find this |
| 967 |
% handy for running headers, TOC entries, and the like. |
| 968 |
% |
| 969 |
% \DescribeMacro{\thepoemauthor}|\thepoemauthor| corresponds |
| 970 |
% to |\thepoemtitle|, and is useful for the same sorts of |
| 971 |
% things. |
| 972 |
% |
| 973 |
% Most written works these days have \emph{licenses}; |
| 974 |
% |poetry| makes it easy to specify that, as well. The |
| 975 |
% variable is |
| 976 |
% \DescribeMacro{\thepoemlicense}|\thepoemlicense|, and |
| 977 |
% defaults to the string |Public Domain|. To alter this, |
| 978 |
% simply redefine it with |\def| or |\renewcommand|; e.g., |
| 979 |
% |\renewcommand{\thepoemlicense}{CC-BY-SA}|. To change the |
| 980 |
% default, redefine |
| 981 |
% \DescribeMacro{\poemdefaultlicense}|\poemdefaultlicense|. |
| 982 |
% |
| 983 |
% Publication date can also be important, particularly when |
| 984 |
% combined with certain types of licensing. To specify |
| 985 |
% this, redefine |
| 986 |
% \DescribeMacro{\thepoempubdate}|\thepoempubdate|, which |
| 987 |
% defaults to the value of |\today|. |
| 988 |
% |
| 989 |
% \subsubsection{Using Metadata} |
| 990 |
% \label{subsub:usemeta} |
| 991 |
% |
| 992 |
% The most obvious way of using the metadata you've set for |
| 993 |
% a poem is to \emph{typeset} it. |poetry| offers a number |
| 994 |
% of ways to do this. |
| 995 |
% |
| 996 |
% If you're only interested in printing the poem's title, |
| 997 |
% you can use the \DescribeMacro{\titlepoem}|\titlepoem| |
| 998 |
% command: |
| 999 |
% |
| 1000 |
% \begin{center} |
| 1001 |
% \cmd{\titlepoem} \marg{title} |
| 1002 |
% \end{center} |
| 1003 |
% |
| 1004 |
% E.g., with the default settings: |
| 1005 |
% |
| 1006 |
% \bigskip\hrule\bigskip |
| 1007 |
% \begin{parcolumns}[rulebetween]{2}% |
| 1008 |
% \colchunk[1]{ |
| 1009 |
% |\titlepoem{\poemblanktitle}| |
| 1010 |
% }\colchunk[2]{% |
| 1011 |
% \titlepoem{\poemblanktitle} |
| 1012 |
% }\end{parcolumns}% |
| 1013 |
% \bigskip\hrule\bigskip |
| 1014 |
% |
| 1015 |
% If you have multiple untitled poems to typeset, it may be |
| 1016 |
% convenient to use |\thepoemno| or |\theabspoemno| to |
| 1017 |
% different them; e.g., |
| 1018 |
% |
| 1019 |
% \begin{center} |
| 1020 |
% |\titlepoem{Untitled No.\ \thepoemno}| |
| 1021 |
% \end{center} |
| 1022 |
% |
| 1023 |
% |\titlepoem| will reset the variable |\thepoemtitle| to |
| 1024 |
% whatever argument you give it. This will be available |
| 1025 |
% later for other uses. |
| 1026 |
% |
| 1027 |
% If you want to typeset both the title and the author, |
| 1028 |
% |poetry| provides you with |
| 1029 |
% \DescribeMacro{\titleauthorpoem}|\titleauthorpoem|: |
| 1030 |
% |
| 1031 |
% \begin{center} |
| 1032 |
% \cmd{\titlepoem} \marg{title} \marg{author} |
| 1033 |
% \end{center} |
| 1034 |
% |
| 1035 |
% \bigskip\hrule\bigskip |
| 1036 |
% \begin{parcolumns}[rulebetween]{2}% |
| 1037 |
% \colchunk[1]{ |
| 1038 |
% \noindent|\titleauthorpoem|\par |
| 1039 |
% \quad|{\poemblanktitle}|\par |
| 1040 |
% \quad|{\poemblankauthor}| |
| 1041 |
% }\colchunk[2]{% |
| 1042 |
% \titleauthorpoem{\poemblanktitle}{\poemblankauthor} |
| 1043 |
% }\end{parcolumns}% |
| 1044 |
% \bigskip\hrule\bigskip |
| 1045 |
% |
| 1046 |
% |\titleauthorpoem| resets both |\thepoemtitle| and |
| 1047 |
% |\thepoemauthor| to the values you submit. |
| 1048 |
% |
| 1049 |
% |poetry| also gives you hooks to control the appearance of |
| 1050 |
% these macros. |
| 1051 |
% \DescribeMacro{\poemtitleprehook}|\poemtitleprehook| is |
| 1052 |
% inserted by |poetry| prior to the title text, and |
| 1053 |
% \DescribeMacro{\poemtitleposthook}|\poemtitleposthook| is |
| 1054 |
% inserted afterward. For |\titleauthorpoem|, there is also |
| 1055 |
% \DescribeMacro{\poemauthorprehook}|\poemauthorprehook| and |
| 1056 |
% \DescribeMacro{\poemauthorposthook}|\poemauthorposthook|, |
| 1057 |
% inserted before and after the author. By default, the |
| 1058 |
% |pre| commands simply |\begin{center}|, while the |
| 1059 |
% |post| commands contain |\end{center}|, but you can |
| 1060 |
% certainly change their values to achieve the appearance |
| 1061 |
% you want: |
| 1062 |
% |
| 1063 |
% \bigskip\hrule\bigskip |
| 1064 |
% \begin{parcolumns}[colwidths={1=1.5in}]{2}% |
| 1065 |
% \colchunk[1]{ |
| 1066 |
% \begin{verbatim} |
| 1067 |
% \def\poemtitleprehook{% |
| 1068 |
% \bigskip\noindent} |
| 1069 |
% \def\poemtitleposthook{} |
| 1070 |
% \def\poemauthorprehook{\hfill} |
| 1071 |
% \def\poemauthorposthook{\bigskip} |
| 1072 |
% \titleauthorpoem{\poemblanktitle}{\poemblankauthor} |
| 1073 |
% \end{verbatim} |
| 1074 |
% }\colchunk[2]{% |
| 1075 |
% \def\poemtitleprehook{\bigskip\noindent}% |
| 1076 |
% \def\poemtitleposthook{}% |
| 1077 |
% \def\poemauthorprehook{\hfill}% |
| 1078 |
% \def\poemauthorposthook{\bigskip}% |
| 1079 |
% \titleauthorpoem{\poemblanktitle}{\poemblankauthor}% |
| 1080 |
% }\end{parcolumns} |
| 1081 |
% \bigskip\hrule\bigskip |
| 1082 |
% |
| 1083 |
% These settings are rather na\"\i{}ve, since they don't |
| 1084 |
% take the length of either author or title into account, |
| 1085 |
% but they suffice to show the power of using these hooks. |
| 1086 |
% |
| 1087 |
% There is also |
| 1088 |
% \DescribeMacro{\poemtitlestyle}|\poemtitlestyle|, which |
| 1089 |
% sets the styling of the title. By default, it is simply |
| 1090 |
% set with |\def\poemtitlestyle{\LARGE\bfseries}|. |
| 1091 |
% |
| 1092 |
% Similarly, there is |
| 1093 |
% \DescribeMacro{\poemauthorstyle}|\poemauthorstyle|, which |
| 1094 |
% provides the styles for the author (if one will be |
| 1095 |
% typeset). By default, this is |
| 1096 |
% |\def\poemauthorstyle{\Large}|. |
| 1097 |
% |
| 1098 |
% \subsection{Structural Features} |
| 1099 |
% \label{sub:structures} |
| 1100 |
% |
| 1101 |
% In addition to typesetting poems individually, |poetry| |
| 1102 |
% has some features to facilitate typesetting collections of |
| 1103 |
% poetry. Structurally, primarily we're dealing with poem |
| 1104 |
% groups (for which see Section \ref{subsub:poemgroups}); |
| 1105 |
% however, we also have significant power in indexing and |
| 1106 |
% tracking poems. |
| 1107 |
% |
| 1108 |
% \subsubsection{Poem Groups} |
| 1109 |
% \label{subsub:poemgroups} |
| 1110 |
% |
| 1111 |
% Poem groups are just what they sound like: groups of |
| 1112 |
% poems. They might be arranged by topic, by author, by |
| 1113 |
% style, or by any other criteria. As we have already seen |
| 1114 |
% in Section \ref{sub:othcounters}, the |poemno| counter |
| 1115 |
% tracks the number of poems individually within poem |
| 1116 |
% groups. Let's see a few of the commands we have for |
| 1117 |
% creating and dealing with these groups. |
| 1118 |
% |
| 1119 |
% \DescribeMacro{\poemgroup}|\poemgroup| starts a new poem |
| 1120 |
% group; it resets the |poemno| counter and adds one to the |
| 1121 |
% poem group counter. That's it; it's a purely structural |
| 1122 |
% command. Formatting title pages and the like for poem |
| 1123 |
% groups is another matter. |
| 1124 |
% \DescribeMacro{\endpoemgroup}|\endpoemgroup| can |
| 1125 |
% optionally be used to end the poem group. Like |\poem|, |
| 1126 |
% however, these can also be used like a \LaTeX\ |
| 1127 |
% environment, using |\begin{poemgroup}| and |
| 1128 |
% |\end{poemgroup}|. |
| 1129 |
% |
| 1130 |
% \DescribeMacro{poemgroupno}|poemgroupno| is the counter |
| 1131 |
% which keeps track of which poem group you're currently in. |
| 1132 |
% It is a standard \LaTeX\ counter, which can be reset, |
| 1133 |
% manipulated, formatted, and displayed in the usual ways. |
| 1134 |
% |
| 1135 |
% \DescribeMacro{\poemgroupheading}|\poemgroupheading| |
| 1136 |
% prints a heading for the poem group. This may or may not |
| 1137 |
% be on its own page; that's up to your formatting. |
| 1138 |
% |
| 1139 |
% \begin{center} |
| 1140 |
% \cmd{\poemgroupheading} \marg{title} \marg{other} |
| 1141 |
% \end{center} |
| 1142 |
% |
| 1143 |
% Both these arguments are mandatory, though of course one |
| 1144 |
% or the other might be empty. The first is the title of |
| 1145 |
% the poem group; the second is whatever else. It may be |
| 1146 |
% the author of the group; the style of poetry (e.g., |
| 1147 |
% anapestic, or alliterative); or any other criteria by |
| 1148 |
% which the poetry is broken into groups. |
| 1149 |
% |
| 1150 |
% |\poemgroupheading| also resets the value of |
| 1151 |
% \DescribeMacro{\thepoemgroupname}|\thepoemgroupname|, |
| 1152 |
% which is another bit of metadata that can used throughout |
| 1153 |
% that group. It resets it to the value of its first |
| 1154 |
% argument. If it is not reset, its value is simply the |
| 1155 |
% value of |
| 1156 |
% \DescribeMacro{\poemgroupblankname}|\poemgroupblankname|, |
| 1157 |
% which defaults to |Untitled Group|. By redefining this |
| 1158 |
% command, you can change the default group name. You can |
| 1159 |
% also redefine |\thepoemgroupname| separately, but be aware |
| 1160 |
% that calling |\poemgroupheading| will reset it again. |
| 1161 |
% |
| 1162 |
% The hooks listed to the left |
| 1163 |
% \DescribeMacro{\poemgrouptitleprehook} |
| 1164 |
% \DescribeMacro{\poemgrouptitleposthook} |
| 1165 |
% \DescribeMacro{\poemgroupotherprehook} |
| 1166 |
% \DescribeMacro{\poemgroupotherposthook} are inserted where |
| 1167 |
% their names imply into the heading. By default, all are |
| 1168 |
% defined to do nothing, but you can fix this with |\def| or |
| 1169 |
% |\renewcommand|. A common styling would involve putting |
| 1170 |
% |\begin{center}| and |\end{center}| into one or both of the |
| 1171 |
% |pre| and |post| hooks, respectively. Another common |
| 1172 |
% requirement would involve putting |\cleardoublepage| into |
| 1173 |
% |\poemgrouptitleprehook|, along with whatever else is |
| 1174 |
% required, in order to ensure a poem group starts on the |
| 1175 |
% next new recto (right-side and odd-numbered) page. |
| 1176 |
% |
| 1177 |
% The title can be styled by redefining |
| 1178 |
% \DescribeMacro{\poemgrouptitlestyle}|\poemgrouptitlestyle|, |
| 1179 |
% which by default simply contains |\Huge|. The ``other'' |
| 1180 |
% argument can be styled with |
| 1181 |
% \DescribeMacro{\poemgroupotherstyle}|\poemgroupotherstyle|, |
| 1182 |
% which by default contains simply |\LARGE|. |
| 1183 |
|
| 1184 |
% |
| 1185 |
% |
| 1186 |
% |
| 1187 |
% \subsubsection{List of Poems} |
| 1188 |
% \label{subsub:tocpoems} |
| 1189 |
% |
| 1190 |
% To go along with the table of contents, the list of |
| 1191 |
% figures, and the list of tables, |poetry| provides a list |
| 1192 |
% of poems. We use standard \LaTeX\ facilities to produce |
| 1193 |
% this list, so they should be pretty familiar to you. The |
| 1194 |
% source below can give the nitty-gritty. |
| 1195 |
% |
| 1196 |
% \DescribeMacro{\listofpoems}Just add |\listofpoems| |
| 1197 |
% wherever you want your list of poems to appear. Unlike |
| 1198 |
% |\tableofcontents| and the like, |\listofpoems| does |
| 1199 |
% \emph{not} start a new chapter or section, change the |
| 1200 |
% headings, and so forth; since |poetry| doesn't know what |
| 1201 |
% document class you're using, or how you want the list set |
| 1202 |
% up, it leaves the details up to you. This is easy enough |
| 1203 |
% to elaborate on; for example, to set up the list of poems |
| 1204 |
% like an unmarked chapter, like the table of contents: |
| 1205 |
% |
| 1206 |
% \begin{verbatim} |
| 1207 |
% \chapter*{\lopname} |
| 1208 |
% \listofpoems |
| 1209 |
% \end{verbatim} |
| 1210 |
% |
| 1211 |
% \DescribeMacro{\lopname}|\lopname| is a macro which simply |
| 1212 |
% contains whatever you want the title of the list of poems |
| 1213 |
% to be; by default, it is |List of Poems|. |
| 1214 |
% |
| 1215 |
% |poetry| also provides a little syntactic sugar to make |
| 1216 |
% adding entries to the list of poems easier. Rather than |
| 1217 |
% doing |\addcontentsline| and the like, simply use |
| 1218 |
% \DescribeMacro{\addtolop}|\addtolop|: |
| 1219 |
% |
| 1220 |
% \begin{center} |
| 1221 |
% \cmd{\addtolop} \marg{contents-line} |
| 1222 |
% \end{center} |
| 1223 |
% |
| 1224 |
% This will add an entry to the list of poems in the default |
| 1225 |
% style; this is set up much like a normal section entry |
| 1226 |
% without indentation. To alter this, redefine |
| 1227 |
% \DescribeMacro{\poemlopformat}|\poemlopformat|. By |
| 1228 |
% default, this is defined in a very \LaTeX-y way; the |
| 1229 |
% standard definition is shown on top below, with a |
| 1230 |
% different one underneath it: |
| 1231 |
% |
| 1232 |
% \begin{quote} |
| 1233 |
% |\def\poemlopformat{\@dottedtocline{1}{0em}{2.3em}}|\\ |
| 1234 |
% |\def\poemlopformat#1#2{\hbox to\linewidth{\textit{#1}\hfill#2}}| |
| 1235 |
% \end{quote} |
| 1236 |
% |
| 1237 |
% You can specify it however you like. |
| 1238 |
% |
| 1239 |
% There is an equivalent |
| 1240 |
% \DescribeMacro{\poemgrouplopformat}|\poemgrouplopformat|, |
| 1241 |
% which by default is designed to mimic |\chapter| lines in |
| 1242 |
% the standard \LaTeX\ classes. This can be redefined as |
| 1243 |
% necessary, too. You add a group to the list of poems by |
| 1244 |
% using \DescribeMacro{\addgrouptolop}|\addgrouptolop|, |
| 1245 |
% which functions just like |\addtolop| does. So something |
| 1246 |
% like this: |
| 1247 |
% |
| 1248 |
% \begin{quote} |
| 1249 |
% |\def\poemgrouplopformat#1#2{\hbox to\linewidth{#1\hfil#2}}|\\ |
| 1250 |
% |\addgrouptolop{Poem Group Name}| |
| 1251 |
% \end{quote} |
| 1252 |
% |
| 1253 |
% Note that none of our sectioning commands insert |
| 1254 |
% themselves into the table of contents or the list of poems |
| 1255 |
% by default. If you want this to happen automatically, |
| 1256 |
% best to write small wrappers macros around them. E.g.: |
| 1257 |
% |
| 1258 |
% \begin{verbatim} |
| 1259 |
% \def\makenewpoem#1{% |
| 1260 |
% \titlepoem{#1}% |
| 1261 |
% \addtolop{#1}% |
| 1262 |
% }% |
| 1263 |
% \end{verbatim} |
| 1264 |
% |
| 1265 |
% |
| 1266 |
% \subsubsection{Index of First Lines} |
| 1267 |
% \label{subsub:iofl} |
| 1268 |
% |
| 1269 |
% Few people remember ``Sonnet 18,'' but many people |
| 1270 |
% remember, ``Shall I compare thee to a summer's day?'' For |
| 1271 |
% this reason, an index of first lines is an important part |
| 1272 |
% of most books of poetry. |poetry| provides facilities to |
| 1273 |
% easily create them. |
| 1274 |
% |
| 1275 |
% |poetry| uses the |imakeidx| package to produce this |
| 1276 |
% index, so you can use the options it contains. To run the |
| 1277 |
% index, |poetry| uses the following configuration line: |
| 1278 |
% |
| 1279 |
% \begin{center} |
| 1280 |
% |\makeindex[intoc,columns=1,name={\jobname-iofl},title={\poemioflname}]| |
| 1281 |
% \end{center} |
| 1282 |
% |
| 1283 |
% Obviously, you can change this if you need to. This means |
| 1284 |
% that, by default, the index will appear in the table of |
| 1285 |
% contents (if there is one); the index will be set in one |
| 1286 |
% column; the index file name will be |\jobname-iofl| |
| 1287 |
% (|\jobname| is a \TeX\ variable that contains the name of |
| 1288 |
% your document, without its extension), and the title of |
| 1289 |
% the index (what appears on the top of the page) will be |
| 1290 |
% the value of the command |\poemioflname|. |
| 1291 |
% |
| 1292 |
% To change the title that appears at the top of the index, |
| 1293 |
% change \DescribeMacro{\poemioflname}|\poemioflname| to |
| 1294 |
% whatever you want; e.g., |\def\poemioflname{Index}|. |
| 1295 |
% |
| 1296 |
% \DescribeMacro{\printiofl}Use |\printiofl| at whatever |
| 1297 |
% point in your document you want the index to actually |
| 1298 |
% appear. |
| 1299 |
% |
| 1300 |
% To make entries in the index, you have two options. |
| 1301 |
% First, use \DescribeMacro{\poemfirstline}|\poemfirstline|, |
| 1302 |
% which takes a single argument, which is the entry you want |
| 1303 |
% to appear in the index. This command will \emph{not} |
| 1304 |
% typeset its argument in the document, only send it to the |
| 1305 |
% index. Second, you can use \DescribeMacro{\iofl}|\iofl|, |
| 1306 |
% which also takes a single argument; however, it will not |
| 1307 |
% only enter that line into the index, but it will also |
| 1308 |
% typeset it in the document. This means that you can wrap |
| 1309 |
% the first line of your poem in |\iofl| (\emph{without} the |
| 1310 |
% |\\|), and it will put it both in your poem and your |
| 1311 |
% index, without you having to type it twice. |
| 1312 |
% |
| 1313 |
% \section{Implementation} |
| 1314 |
% \label{sect:implem} |
| 1315 |
% |
| 1316 |
% \begin{macrocode} |
| 1317 |
\RequirePackage{modulus}% |
| 1318 |
\@ifundefined{c@poemline}{% |
| 1319 |
\newcounter{poemline}% |
| 1320 |
}{} |
| 1321 |
\newcount\poemlineno% |
| 1322 |
\newcounter{poemrtline}% |
| 1323 |
\newcount\poemrtlineno% |
| 1324 |
\renewcommand\thepoemrtline{}% |
| 1325 |
\newcounter{verseline}% |
| 1326 |
\newcount\vslineno% |
| 1327 |
\newcounter{stanzacount}% |
| 1328 |
\newcount\stanzano% |
| 1329 |
\newcounter{abspoemno}% |
| 1330 |
\newcount\poem@abspoemno% |
| 1331 |
\newcounter{poemno}% |
| 1332 |
\newcount\poem@poemno% |
| 1333 |
\newcounter{poemgroupno}\setcounter{poemgroupno}{0}% |
| 1334 |
\newcount\poem@groupno\poem@groupno=0% |
| 1335 |
\newcounter{poemlinenumsevery}\setcounter{poemlinenumsevery}{1}% |
| 1336 |
\newcount\poem@linenumsevery\poem@linenumsevery=\value{poemlinenumsevery}% |
| 1337 |
\newcounter{poemrtlinenumsevery}\setcounter{poemrtlinenumsevery}{1}% |
| 1338 |
\newcount\poem@rt@linenumsevery\poem@rt@linenumsevery=\value{poemrtlinenumsevery}% |
| 1339 |
\newlength{\poemindent}\setlength{\poemindent}{0pt}% |
| 1340 |
\newlength{\poemtopskip}\setlength{\poemtopskip}{1em}% |
| 1341 |
\newlength{\poembotskip}\setlength{\poembotskip}{1em}% |
| 1342 |
\newdimen\poem@topskip\newdimen\poem@botskip% |
| 1343 |
\newdimen\poem@defleftskip\poem@defleftskip=\the\poemindent% |
| 1344 |
\newdimen\poem@maxlinewd% |
| 1345 |
\newlength{\poemmaxlinewd}\setlength{\poemmaxlinewd}{\textwidth}% |
| 1346 |
\newdimen\poem@rt@maxlinewd% |
| 1347 |
\newlength{\poemrtmaxlinewd}\setlength{\poemrtmaxlinewd}{\textwidth}% |
| 1348 |
\newdimen\poem@hinwd\poem@hinwd=1em% |
| 1349 |
\newlength{\poemhinwd}\setlength{\poemhinwd}{1em}% |
| 1350 |
\newif\ifpoemlinenums\poemlinenumstrue% |
| 1351 |
\newif\ifpoemrtlinenums\poemrtlinenumstrue% |
| 1352 |
\def\poemlinenumright{% |
| 1353 |
\renewcommand{\thepoemrtline}{\arabic{poemline}}% |
| 1354 |
\renewcommand{\thepoemline}{}% |
| 1355 |
}% |
| 1356 |
\def\poemlinenumrighttrue{% |
| 1357 |
\renewcommand{\thepoemrtline}{\arabic{poemline}}% |
| 1358 |
\renewcommand{\thepoemline}{}% |
| 1359 |
}% |
| 1360 |
\def\poemlinenumrightfalse{% |
| 1361 |
\renewcommand{\thepoemline}{\arabic{poemline}}% |
| 1362 |
\renewcommand{\thepoemrtline}{}% |
| 1363 |
}% |
| 1364 |
\newdimen\poem@linenumboxwd\poem@linenumboxwd=2em% |
| 1365 |
\newlength{\poemlinenumboxwd}\setlength{\poemlinenumboxwd}{2em}% |
| 1366 |
\newdimen\poem@rt@linenumboxwd\poem@rt@linenumboxwd=2em% |
| 1367 |
\newlength{\poemrtlinenumboxwd}\setlength{\poemrtlinenumboxwd}{2em}% |
| 1368 |
\newdimen\poem@linenumboxgap\poem@linenumboxgap=0pt% |
| 1369 |
\newlength{\poemlinenumboxgap}\setlength{\poemlinenumboxgap}{0pt}% |
| 1370 |
\newdimen\poem@rt@linenumboxgap\poem@rt@linenumboxgap=0pt% |
| 1371 |
\newlength{\poemrtlinenumboxgap}\setlength{\poemrtlinenumboxgap}{0pt}% |
| 1372 |
\def\poemlinenumstyle{}% |
| 1373 |
\def\poemrtlinenumstyle{}% |
| 1374 |
\newdimen\poem@hangindent\poem@hangindent=1em% |
| 1375 |
\newlength{\poemhangindent}\setlength{\poemhangindent}{1em}% |
| 1376 |
\newcount\poem@indentevery\poem@indentevery=0% |
| 1377 |
\newcounter{poemindentevery}\setcounter{poemindentevery}{0}% |
| 1378 |
\newdimen\poem@verseskip\poem@verseskip=\baselineskip% |
| 1379 |
\newlength{\poemverseskip}\setlength{\poemverseskip}{\baselineskip}% |
| 1380 |
\newdimen\poem@buff% |
| 1381 |
\newcount\poem@tmp% |
| 1382 |
% From David Carlisle's answer on tex.stackexchange.com, |
| 1383 |
% question 57598; allows us to loop through a string in a |
| 1384 |
% command. We will use this for the verse indentation |
| 1385 |
% counter, as well as for the generic line indentatin |
| 1386 |
% counter and the right indentation counter, both in |\placelineno|. |
| 1387 |
\def\loopcommand{\hin}% |
| 1388 |
\def\poem@expandvsloop#1{\poem@xvsloop#1\relax}% |
| 1389 |
\def\poem@xvsloop#1{% |
| 1390 |
\ifx\relax#1\else% |
| 1391 |
\ifnum#1=\the\vslineno% |
| 1392 |
\loopcommand\relax% |
| 1393 |
\fi% |
| 1394 |
\expandafter\poem@xvsloop% |
| 1395 |
\fi% |
| 1396 |
}% |
| 1397 |
% from verse.sty |
| 1398 |
\newcommand{\poem@ifbang}[1]{\@ifnextchar !{\@firstoftwo{#1}}} |
| 1399 |
\newcommand{\poem@ifhyph}[1]{\@ifnextchar -{\@firstoftwo{#1}}} |
| 1400 |
\newcommand{\poem@ifstar}[1]{\@ifnextchar *{\@firstoftwo{#1}}} |
| 1401 |
\newcommand{\poem@ifques}[1]{\@ifnextchar ?{\@firstoftwo{#1}}} |
| 1402 |
\def\poemvsindentlines{}% |
| 1403 |
\def\poemnumlines{}% |
| 1404 |
\def\poemrtnumlines{}% |
| 1405 |
\def\tlap#1{\vbox to0pt{\vss\hbox{#1}}}% |
| 1406 |
\def\blap#1{\vbox to0pt{\hbox{#1}\vss}}% |
| 1407 |
\def\placelineno{% |
| 1408 |
\setcounter{verseline}{\the\vslineno}% |
| 1409 |
\setcounter{poemline}{\the\poemlineno}% |
| 1410 |
\setcounter{stanzacount}{\the\stanzano}% |
| 1411 |
\setcounter{poemrtline}{\the\poemrtlineno}% |
| 1412 |
\poem@linenumsevery=\value{poemlinenumsevery}% |
| 1413 |
\poem@rt@linenumsevery=\value{poemrtlinenumsevery}% |
| 1414 |
\poem@indentevery=\value{poemindentevery}% |
| 1415 |
\poem@linenumboxgap=\the\poemlinenumboxgap% |
| 1416 |
\poem@linenumboxwd=\the\poemlinenumboxwd% |
| 1417 |
\poem@rt@linenumboxgap=\the\poemrtlinenumboxgap% |
| 1418 |
\poem@rt@linenumboxwd=\the\poemrtlinenumboxwd% |
| 1419 |
\ifpoemlinenums% |
| 1420 |
\def\loopcommand{\poem@putlineno}% |
| 1421 |
\expandafter\poem@expandvsloop\expandafter{\poemnumlines}% |
| 1422 |
\def\loopcommand{\poem@rt@putlineno}% |
| 1423 |
\expandafter\poem@expandvsloop\expandafter{\poemrtnumlines}% |
| 1424 |
\ifnum\poem@linenumsevery=0\relax\else% |
| 1425 |
\modulo{\the\vslineno}{\the\poem@linenumsevery}% |
| 1426 |
\ifnum\remainder=0\poem@putlineno\fi% |
| 1427 |
\fi% |
| 1428 |
\ifnum\poem@rt@linenumsevery=0\relax\else% |
| 1429 |
\modulo{\the\vslineno}{\the\poem@rt@linenumsevery}% |
| 1430 |
\ifnum\remainder=0\poem@rt@putlineno\fi% |
| 1431 |
\fi% |
| 1432 |
\fi% |
| 1433 |
\ifnum\poem@indentevery=0\relax\else% |
| 1434 |
\modulo{\the\vslineno}{\the\poem@indentevery}% |
| 1435 |
\ifnum\remainder=0\hin\fi% |
| 1436 |
\fi% |
| 1437 |
\def\loopcommand{\hin}% |
| 1438 |
\expandafter\poem@expandvsloop\expandafter{\poemvsindentlines}% |
| 1439 |
\def\@currentlabel{\thepoemline}% |
| 1440 |
\phantomsection% |
| 1441 |
}% |
| 1442 |
\def\poem@putlineno{% |
| 1443 |
\hskip-\poem@linenumboxgap% |
| 1444 |
\llap{% |
| 1445 |
\tlap{% |
| 1446 |
\hbox to\poem@linenumboxwd{% |
| 1447 |
\poemlinenumstyle\thepoemline% |
| 1448 |
\hfil% |
| 1449 |
}\penalty10000% |
| 1450 |
}% |
| 1451 |
}% |
| 1452 |
\ifnum\poemlineno=1\relax\else% |
| 1453 |
\ifnum\vslineno=1% |
| 1454 |
\vskip-\baselineskip% |
| 1455 |
\fi% |
| 1456 |
\fi% |
| 1457 |
\penalty10000% |
| 1458 |
}% |
| 1459 |
\def\poem@rt@putlineno{% |
| 1460 |
\hskip0pt\tlap{% |
| 1461 |
\rlap{% |
| 1462 |
\hskip\poem@maxlinewd% |
| 1463 |
\hskip\poem@rt@linenumboxgap% |
| 1464 |
\hbox to\poem@rt@linenumboxwd{% |
| 1465 |
\hfil% |
| 1466 |
\poemrtlinenumstyle\thepoemrtline% |
| 1467 |
}% |
| 1468 |
}% |
| 1469 |
}% |
| 1470 |
\vskip-\baselineskip% |
| 1471 |
}% |
| 1472 |
\def\poem@endline{% |
| 1473 |
\par% |
| 1474 |
\advance\poemlineno by1% |
| 1475 |
\advance\vslineno by1% |
| 1476 |
\poem@defaultpars% |
| 1477 |
\leftskip=\poem@defleftskip% |
| 1478 |
\placelineno% |
| 1479 |
}% |
| 1480 |
\def\poem@endpart{% |
| 1481 |
\par% |
| 1482 |
\advance\poemlineno by1% |
| 1483 |
\advance\vslineno by1% |
| 1484 |
\poem@defaultpars% |
| 1485 |
\leftskip=\poem@defleftskip% |
| 1486 |
}% |
| 1487 |
\def\poem@resume{% |
| 1488 |
\placelineno% |
| 1489 |
}% |
| 1490 |
\def\*{% |
| 1491 |
\poem@resume% |
| 1492 |
}% |
| 1493 |
\def\poem@endverse{% |
| 1494 |
\par% |
| 1495 |
\vslineno=1% |
| 1496 |
\advance\poemlineno by1% |
| 1497 |
\advance\stanzano by1% |
| 1498 |
\poem@verseskip=\the\poemverseskip% |
| 1499 |
\vskip\poem@verseskip% |
| 1500 |
\leftskip=\poem@defleftskip% |
| 1501 |
\placelineno% |
| 1502 |
} |
| 1503 |
\def\poem@endversepart{% |
| 1504 |
\par% |
| 1505 |
\advance\poemlineno by1% |
| 1506 |
\vslineno=1% |
| 1507 |
\poem@defaultpars% |
| 1508 |
\leftskip=\poem@defleftskip% |
| 1509 |
} |
| 1510 |
\def\poem@defaultpars{% |
| 1511 |
\poem@hangindent=\the\poemhangindent% |
| 1512 |
\everypar={% |
| 1513 |
\parindent=0pt% |
| 1514 |
\hangindent=\poem@hangindent% |
| 1515 |
\hangafter=1% |
| 1516 |
}% |
| 1517 |
}% |
| 1518 |
\def\hin{% |
| 1519 |
\poem@hinwd=\the\poemhinwd% |
| 1520 |
\advance\leftskip by\the\poem@hinwd% |
| 1521 |
\penalty10000% |
| 1522 |
}% |
| 1523 |
\def\poemnew{% |
| 1524 |
\advance\poem@poemno by1\stepcounter{poemno}% |
| 1525 |
\advance\poem@abspoemno by1\stepcounter{abspoemno}% |
| 1526 |
}% |
| 1527 |
\def\poem{% |
| 1528 |
\widowpenalty=0\clubpenalty=0% |
| 1529 |
\def\\{% |
| 1530 |
\poem@ifbang{\poem@endverse}{% |
| 1531 |
\poem@ifhyph{\par\vskip\poem@botskip\relax}{% |
| 1532 |
\poem@ifstar{\poem@endpart}{% |
| 1533 |
\poem@ifques{\poem@endversepart}{\poem@endline}% |
| 1534 |
}% |
| 1535 |
}% |
| 1536 |
}% |
| 1537 |
}% |
| 1538 |
\poem@defleftskip=\the\poemindent% |
| 1539 |
\leftskip=\poem@defleftskip% |
| 1540 |
\poem@maxlinewd=\the\poemmaxlinewd% |
| 1541 |
\hsize=\the\poem@defleftskip% |
| 1542 |
\advance\hsize by\the\poem@maxlinewd% |
| 1543 |
\poemlineno=1% |
| 1544 |
\vslineno=1% |
| 1545 |
\stanzano=1% |
| 1546 |
\poem@topskip=\the\poemtopskip% |
| 1547 |
\poem@botskip=\the\poembotskip% |
| 1548 |
\vskip\poem@topskip% |
| 1549 |
\poem@defaultpars% |
| 1550 |
\noindent% |
| 1551 |
\poem@ifstar{}{\placelineno}% |
| 1552 |
}% |
| 1553 |
\def\endpoem{% |
| 1554 |
}% |
| 1555 |
\newdimen\poem@centlinewd |
| 1556 |
\def\centerpoemon#1{% |
| 1557 |
\settowidth{\poem@centlinewd}{#1}% |
| 1558 |
\ifdim\poem@centlinewd>\linewidth\poem@defleftskip=0pt% |
| 1559 |
\else |
| 1560 |
\poem@buff=\linewidth% |
| 1561 |
\advance\poem@buff by-\poem@centlinewd% |
| 1562 |
\divide\poem@buff by2% |
| 1563 |
\poem@defleftskip=\the\poem@buff% |
| 1564 |
\poemindent=\the\poem@buff% |
| 1565 |
\poem@maxlinewd=\the\poem@centlinewd% |
| 1566 |
\setlength{\poemmaxlinewd}{\poem@maxlinewd}% |
| 1567 |
\fi |
| 1568 |
}% |
| 1569 |
\def\centerpoemoff{% |
| 1570 |
\poem@defleftskip=0pt\setlength{\poemindent}{0pt}% |
| 1571 |
\poem@maxlinewd=\the\linewidth% |
| 1572 |
\setlength{\poemmaxlinewd}{\linewidth}% |
| 1573 |
}% |
| 1574 |
% \end{macrocode} |
| 1575 |
% Define a few variables for document metadata. |
| 1576 |
% \begin{macrocode} |
| 1577 |
\def\thepoemtitle{\poemblanktitle}% |
| 1578 |
\def\thepoemauthor{\poemblankauthor}% |
| 1579 |
\def\thepoemlicense{Public Domain}% |
| 1580 |
\def\poemdefaultlicense{Public Domain}% |
| 1581 |
\def\thepoempubdate{\today}% |
| 1582 |
% \end{macrocode} |
| 1583 |
% Here we begin the structural code; which, of course, uses |
| 1584 |
% a lot of the code above, particularly the counters. |
| 1585 |
% First, let's give folks a way to title their poems. But |
| 1586 |
% even before that, we need to define some more commands to |
| 1587 |
% help people style them. |
| 1588 |
% \begin{macrocode} |
| 1589 |
\def\poemblanktitle{Untitled}% |
| 1590 |
\def\poemblankauthor{Anonymous}% |
| 1591 |
\def\poemtitlestyle{\LARGE\bfseries}% |
| 1592 |
\def\poemauthorstyle{\Large}% |
| 1593 |
\def\poemtitleprehook{% |
| 1594 |
\begin{center}% |
| 1595 |
}% |
| 1596 |
\def\poemtitleposthook{% |
| 1597 |
\end{center}% |
| 1598 |
}% |
| 1599 |
\def\poemauthorprehook{% |
| 1600 |
\begin{center}% |
| 1601 |
}% |
| 1602 |
\def\poemauthorposthook{% |
| 1603 |
\end{center}% |
| 1604 |
}% |
| 1605 |
% \end{macrocode} |
| 1606 |
% Specifically, one for titles with no authors: |
| 1607 |
% \begin{macrocode} |
| 1608 |
\def\titlepoem#1{% |
| 1609 |
\advance\poem@poemno by1\stepcounter{poemno}% |
| 1610 |
\advance\poem@abspoemno by1\stepcounter{abspoemno}% |
| 1611 |
\def\thepoemtitle{#1}\def\thepoemauthor{\poemblankauthor}% |
| 1612 |
\begingroup% |
| 1613 |
\poemtitleprehook% |
| 1614 |
\poemtitlestyle #1% |
| 1615 |
\poemtitleposthook% |
| 1616 |
\endgroup% |
| 1617 |
}% |
| 1618 |
% \end{macrocode} |
| 1619 |
% Next, one for titles and authors: |
| 1620 |
% \begin{macrocode} |
| 1621 |
\def\titleauthorpoem#1#2{% |
| 1622 |
\advance\poem@poemno by1\stepcounter{poemno}% |
| 1623 |
\advance\poem@abspoemno by1\stepcounter{abspoemno}% |
| 1624 |
\def\thepoemtitle{#1}\def\thepoemauthor{#2}% |
| 1625 |
\begingroup% |
| 1626 |
\poemtitleprehook% |
| 1627 |
\poemtitlestyle #1% |
| 1628 |
\poemtitleposthook% |
| 1629 |
\endgroup% |
| 1630 |
\begingroup% |
| 1631 |
\poemauthorprehook% |
| 1632 |
\poemauthorstyle #2% |
| 1633 |
\poemauthorposthook% |
| 1634 |
\endgroup% |
| 1635 |
}% |
| 1636 |
% \end{macrocode} |
| 1637 |
% Now we define the poem group commands. These are pretty |
| 1638 |
% simple, essentially just resetting various variables to |
| 1639 |
% sensible values. We have the |\endpoemgroup| command here |
| 1640 |
% just to allow people to use them as environments, if they |
| 1641 |
% want. |
| 1642 |
% \begin{macrocode} |
| 1643 |
\def\poemgroup{% |
| 1644 |
\advance\poem@groupno by1% |
| 1645 |
\stepcounter{poemgroupno}% |
| 1646 |
\poem@poemno=0\setcounter{poemno}{0}% |
| 1647 |
\def\thepoemgroupname{\poemgroupblankname}% |
| 1648 |
}% |
| 1649 |
\def\endpoemgroup{% |
| 1650 |
}% |
| 1651 |
\def\poemgrouptitleprehook{}% |
| 1652 |
\def\poemgrouptitleposthook{}% |
| 1653 |
\def\poemgroupotherprehook{}% |
| 1654 |
\def\poemgroupotherposthook{}% |
| 1655 |
\def\poemgrouptitlestyle{\Huge}% |
| 1656 |
\def\poemgroupotherstyle{\LARGE}% |
| 1657 |
\def\poemgroupblankname{Untitled Group}% |
| 1658 |
\def\poemgroupname{\poemgroupblankname}% |
| 1659 |
\def\poemgroupheading#1#2{% |
| 1660 |
\def\thepoemgroupname{#1}% |
| 1661 |
\begingroup% |
| 1662 |
\poemgrouptitleprehook% |
| 1663 |
\poemgrouptitlestyle #1% |
| 1664 |
\poemgrouptitleposthook% |
| 1665 |
\endgroup% |
| 1666 |
\begingroup% |
| 1667 |
\poemgroupotherprehook% |
| 1668 |
\poemgroupotherstyle #2% |
| 1669 |
\poemgroupotherposthook% |
| 1670 |
\endgroup% |
| 1671 |
}% |
| 1672 |
% \end{macrocode} |
| 1673 |
% Now let's define the necessary commands for the list of |
| 1674 |
% poems. (\emph{Not} the index of first lines, yet.) |
| 1675 |
% \begin{macrocode} |
| 1676 |
\def\poemlopformat{% |
| 1677 |
\@dottedtocline{1}{0em}{2.3em}% |
| 1678 |
}% |
| 1679 |
\def\l@poem{\poemlopformat}% |
| 1680 |
\def\addtolop#1{% |
| 1681 |
\addcontentsline{lop}{poem}{#1}% |
| 1682 |
}% |
| 1683 |
\def\addgrouptolop#1{% |
| 1684 |
\addcontentsline{lop}{poemgroup}{#1}% |
| 1685 |
}% |
| 1686 |
\def\lopname{List of Poems}% |
| 1687 |
\def\listofpoems{% |
| 1688 |
\@starttoc{lop}% |
| 1689 |
}% |
| 1690 |
\def\poemgrouplopformat#1#2{% |
| 1691 |
\ifnum \c@tocdepth >\m@ne |
| 1692 |
\addpenalty{-\@highpenalty}% |
| 1693 |
\vskip 1.0em \@plus\p@ |
| 1694 |
\setlength\@tempdima{1.5em}% |
| 1695 |
\begingroup |
| 1696 |
\parindent \z@ \rightskip \@pnumwidth |
| 1697 |
\parfillskip -\@pnumwidth |
| 1698 |
\leavevmode \bfseries |
| 1699 |
\advance\leftskip\@tempdima |
| 1700 |
\hskip -\leftskip |
| 1701 |
#1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par |
| 1702 |
\penalty\@highpenalty |
| 1703 |
\endgroup |
| 1704 |
\fi% |
| 1705 |
}% |
| 1706 |
\def\l@poemgroup{\poemgrouplopformat}% |
| 1707 |
% \end{macrocode} |
| 1708 |
% Do some magic to ensure that the package works even if |
| 1709 |
% |hyperref| isn't loaded. |
| 1710 |
% \begin{macrocode} |
| 1711 |
\ifcsname phantomsection\endcsname% |
| 1712 |
\else% |
| 1713 |
\def\phantomsection{\relax}% |
| 1714 |
\fi% |
| 1715 |
% \end{macrocode} |
| 1716 |
% Now let's set up the index of first lines. We use the |
| 1717 |
% |imakeidx| package for this, so as not to interfere with |
| 1718 |
% any existing indices. |
| 1719 |
% \begin{macrocode} |
| 1720 |
\ifx\theindex\@undefined\else% |
| 1721 |
\RequirePackage{imakeidx} |
| 1722 |
\makeindex[intoc,columns=1,name={\jobname-iofl},title={\poemioflname}] |
| 1723 |
\def\poemioflname{Index of First Lines}% |
| 1724 |
\def\poemfirstline#1{% |
| 1725 |
\index[\jobname-iofl]{#1}% |
| 1726 |
}% |
| 1727 |
\def\iofl#1{% |
| 1728 |
\index[\jobname-iofl]{#1}% |
| 1729 |
#1% |
| 1730 |
}% |
| 1731 |
\def\printiofl{% |
| 1732 |
\printindex[\jobname-iofl]% |
| 1733 |
}% |
| 1734 |
\fi% |
| 1735 |
% \end{macrocode} |
| 1736 |
% \listofpoems |
| 1737 |
% \PrintIndex |