Debian Codegraph @

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

raw
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