summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/poetry
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/poetry
Initial commit
Diffstat (limited to 'macros/latex/contrib/poetry')
-rw-r--r--macros/latex/contrib/poetry/CHANGES8
-rw-r--r--macros/latex/contrib/poetry/README24
-rw-r--r--macros/latex/contrib/poetry/lppl.txt416
-rw-r--r--macros/latex/contrib/poetry/poetry.dtx1734
-rw-r--r--macros/latex/contrib/poetry/poetry.ins64
-rw-r--r--macros/latex/contrib/poetry/poetry.pdfbin0 -> 261288 bytes
6 files changed, 2246 insertions, 0 deletions
diff --git a/macros/latex/contrib/poetry/CHANGES b/macros/latex/contrib/poetry/CHANGES
new file mode 100644
index 0000000000..42cc519f2e
--- /dev/null
+++ b/macros/latex/contrib/poetry/CHANGES
@@ -0,0 +1,8 @@
+2 May 1203 (2 May 2019): Added ability to arbitrarily label
+both the left and right sides of the line. Version 2.0.
+
+X Sept 1202 (10 Sept 2018): Removed *requirement* for
+hyperref by inserting a fake definition for \phantomsection,
+which is the only hyperref command used.
+
+17 June 1201 (19 June 2017): Version 1.0, initial release.
diff --git a/macros/latex/contrib/poetry/README b/macros/latex/contrib/poetry/README
new file mode 100644
index 0000000000..744d14d54b
--- /dev/null
+++ b/macros/latex/contrib/poetry/README
@@ -0,0 +1,24 @@
++AMDG
+
+This document is copyright 2019 by Donald P. Goodman, and is
+released publicly under the LaTeX Project Public License. The
+distribution and modification of this work is constrained by the
+conditions of that license. See
+ http://www.latex-project.org/lppl.txt
+for the text of the license. This document is released
+under version 1.3c of that license, and this work may be distributed
+or modified under the terms of that license or, at your option, any
+later version.
+
+This work has the LPPL maintenance status 'maintained'.
+
+The Current Maintainer of this work is Donald P. Goodman
+(dgoodmaniii@gmail.com).
+
+This work consists of the files poetry.ins and
+poetry.dtx, along with derived files poetry.sty and
+poetry.pdf.
+
+This package should run properly on any properly running LaTeX
+system. It's been tested specifically with TeXLive on
+GNU/Linux.
diff --git a/macros/latex/contrib/poetry/lppl.txt b/macros/latex/contrib/poetry/lppl.txt
new file mode 100644
index 0000000000..2244313901
--- /dev/null
+++ b/macros/latex/contrib/poetry/lppl.txt
@@ -0,0 +1,416 @@
+The LaTeX Project Public License
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+
+LPPL Version 1.3c 2008-05-04
+
+Copyright 1999 2002-2008 LaTeX3 Project
+ Everyone is allowed to distribute verbatim copies of this
+ license document, but modification of it is not allowed.
+
+
+PREAMBLE
+========
+
+The LaTeX Project Public License (LPPL) is the primary license under
+which the LaTeX kernel and the base LaTeX packages are distributed.
+
+You may use this license for any work of which you hold the copyright
+and which you wish to distribute. This license may be particularly
+suitable if your work is TeX-related (such as a LaTeX package), but
+it is written in such a way that you can use it even if your work is
+unrelated to TeX.
+
+The section `WHETHER AND HOW TO DISTRIBUTE WORKS UNDER THIS LICENSE',
+below, gives instructions, examples, and recommendations for authors
+who are considering distributing their works under this license.
+
+This license gives conditions under which a work may be distributed
+and modified, as well as conditions under which modified versions of
+that work may be distributed.
+
+We, the LaTeX3 Project, believe that the conditions below give you
+the freedom to make and distribute modified versions of your work
+that conform with whatever technical specifications you wish while
+maintaining the availability, integrity, and reliability of
+that work. If you do not see how to achieve your goal while
+meeting these conditions, then read the document `cfgguide.tex'
+and `modguide.tex' in the base LaTeX distribution for suggestions.
+
+
+DEFINITIONS
+===========
+
+In this license document the following terms are used:
+
+ `Work'
+ Any work being distributed under this License.
+
+ `Derived Work'
+ Any work that under any applicable law is derived from the Work.
+
+ `Modification'
+ Any procedure that produces a Derived Work under any applicable
+ law -- for example, the production of a file containing an
+ original file associated with the Work or a significant portion of
+ such a file, either verbatim or with modifications and/or
+ translated into another language.
+
+ `Modify'
+ To apply any procedure that produces a Derived Work under any
+ applicable law.
+
+ `Distribution'
+ Making copies of the Work available from one person to another, in
+ whole or in part. Distribution includes (but is not limited to)
+ making any electronic components of the Work accessible by
+ file transfer protocols such as FTP or HTTP or by shared file
+ systems such as Sun's Network File System (NFS).
+
+ `Compiled Work'
+ A version of the Work that has been processed into a form where it
+ is directly usable on a computer system. This processing may
+ include using installation facilities provided by the Work,
+ transformations of the Work, copying of components of the Work, or
+ other activities. Note that modification of any installation
+ facilities provided by the Work constitutes modification of the Work.
+
+ `Current Maintainer'
+ A person or persons nominated as such within the Work. If there is
+ no such explicit nomination then it is the `Copyright Holder' under
+ any applicable law.
+
+ `Base Interpreter'
+ A program or process that is normally needed for running or
+ interpreting a part or the whole of the Work.
+
+ A Base Interpreter may depend on external components but these
+ are not considered part of the Base Interpreter provided that each
+ external component clearly identifies itself whenever it is used
+ interactively. Unless explicitly specified when applying the
+ license to the Work, the only applicable Base Interpreter is a
+ `LaTeX-Format' or in the case of files belonging to the
+ `LaTeX-format' a program implementing the `TeX language'.
+
+
+
+CONDITIONS ON DISTRIBUTION AND MODIFICATION
+===========================================
+
+1. Activities other than distribution and/or modification of the Work
+are not covered by this license; they are outside its scope. In
+particular, the act of running the Work is not restricted and no
+requirements are made concerning any offers of support for the Work.
+
+2. You may distribute a complete, unmodified copy of the Work as you
+received it. Distribution of only part of the Work is considered
+modification of the Work, and no right to distribute such a Derived
+Work may be assumed under the terms of this clause.
+
+3. You may distribute a Compiled Work that has been generated from a
+complete, unmodified copy of the Work as distributed under Clause 2
+above, as long as that Compiled Work is distributed in such a way that
+the recipients may install the Compiled Work on their system exactly
+as it would have been installed if they generated a Compiled Work
+directly from the Work.
+
+4. If you are the Current Maintainer of the Work, you may, without
+restriction, modify the Work, thus creating a Derived Work. You may
+also distribute the Derived Work without restriction, including
+Compiled Works generated from the Derived Work. Derived Works
+distributed in this manner by the Current Maintainer are considered to
+be updated versions of the Work.
+
+5. If you are not the Current Maintainer of the Work, you may modify
+your copy of the Work, thus creating a Derived Work based on the Work,
+and compile this Derived Work, thus creating a Compiled Work based on
+the Derived Work.
+
+6. If you are not the Current Maintainer of the Work, you may
+distribute a Derived Work provided the following conditions are met
+for every component of the Work unless that component clearly states
+in the copyright notice that it is exempt from that condition. Only
+the Current Maintainer is allowed to add such statements of exemption
+to a component of the Work.
+
+ a. If a component of this Derived Work can be a direct replacement
+ for a component of the Work when that component is used with the
+ Base Interpreter, then, wherever this component of the Work
+ identifies itself to the user when used interactively with that
+ Base Interpreter, the replacement component of this Derived Work
+ clearly and unambiguously identifies itself as a modified version
+ of this component to the user when used interactively with that
+ Base Interpreter.
+
+ b. Every component of the Derived Work contains prominent notices
+ detailing the nature of the changes to that component, or a
+ prominent reference to another file that is distributed as part
+ of the Derived Work and that contains a complete and accurate log
+ of the changes.
+
+ c. No information in the Derived Work implies that any persons,
+ including (but not limited to) the authors of the original version
+ of the Work, provide any support, including (but not limited to)
+ the reporting and handling of errors, to recipients of the
+ Derived Work unless those persons have stated explicitly that
+ they do provide such support for the Derived Work.
+
+ d. You distribute at least one of the following with the Derived Work:
+
+ 1. A complete, unmodified copy of the Work;
+ if your distribution of a modified component is made by
+ offering access to copy the modified component from a
+ designated place, then offering equivalent access to copy
+ the Work from the same or some similar place meets this
+ condition, even though third parties are not compelled to
+ copy the Work along with the modified component;
+
+ 2. Information that is sufficient to obtain a complete,
+ unmodified copy of the Work.
+
+7. If you are not the Current Maintainer of the Work, you may
+distribute a Compiled Work generated from a Derived Work, as long as
+the Derived Work is distributed to all recipients of the Compiled
+Work, and as long as the conditions of Clause 6, above, are met with
+regard to the Derived Work.
+
+8. The conditions above are not intended to prohibit, and hence do not
+apply to, the modification, by any method, of any component so that it
+becomes identical to an updated version of that component of the Work as
+it is distributed by the Current Maintainer under Clause 4, above.
+
+9. Distribution of the Work or any Derived Work in an alternative
+format, where the Work or that Derived Work (in whole or in part) is
+then produced by applying some process to that format, does not relax or
+nullify any sections of this license as they pertain to the results of
+applying that process.
+
+10. a. A Derived Work may be distributed under a different license
+ provided that license itself honors the conditions listed in
+ Clause 6 above, in regard to the Work, though it does not have
+ to honor the rest of the conditions in this license.
+
+ b. If a Derived Work is distributed under a different license, that
+ Derived Work must provide sufficient documentation as part of
+ itself to allow each recipient of that Derived Work to honor the
+ restrictions in Clause 6 above, concerning changes from the Work.
+
+11. This license places no restrictions on works that are unrelated to
+the Work, nor does this license place any restrictions on aggregating
+such works with the Work by any means.
+
+12. Nothing in this license is intended to, or may be used to, prevent
+complete compliance by all parties with all applicable laws.
+
+
+NO WARRANTY
+===========
+
+There is no warranty for the Work. Except when otherwise stated in
+writing, the Copyright Holder provides the Work `as is', without
+warranty of any kind, either expressed or implied, including, but not
+limited to, the implied warranties of merchantability and fitness for a
+particular purpose. The entire risk as to the quality and performance
+of the Work is with you. Should the Work prove defective, you assume
+the cost of all necessary servicing, repair, or correction.
+
+In no event unless required by applicable law or agreed to in writing
+will The Copyright Holder, or any author named in the components of the
+Work, or any other party who may distribute and/or modify the Work as
+permitted above, be liable to you for damages, including any general,
+special, incidental or consequential damages arising out of any use of
+the Work or out of inability to use the Work (including, but not limited
+to, loss of data, data being rendered inaccurate, or losses sustained by
+anyone as a result of any failure of the Work to operate with any other
+programs), even if the Copyright Holder or said author or said other
+party has been advised of the possibility of such damages.
+
+
+MAINTENANCE OF THE WORK
+=======================
+
+The Work has the status `author-maintained' if the Copyright Holder
+explicitly and prominently states near the primary copyright notice in
+the Work that the Work can only be maintained by the Copyright Holder
+or simply that it is `author-maintained'.
+
+The Work has the status `maintained' if there is a Current Maintainer
+who has indicated in the Work that they are willing to receive error
+reports for the Work (for example, by supplying a valid e-mail
+address). It is not required for the Current Maintainer to acknowledge
+or act upon these error reports.
+
+The Work changes from status `maintained' to `unmaintained' if there
+is no Current Maintainer, or the person stated to be Current
+Maintainer of the work cannot be reached through the indicated means
+of communication for a period of six months, and there are no other
+significant signs of active maintenance.
+
+You can become the Current Maintainer of the Work by agreement with
+any existing Current Maintainer to take over this role.
+
+If the Work is unmaintained, you can become the Current Maintainer of
+the Work through the following steps:
+
+ 1. Make a reasonable attempt to trace the Current Maintainer (and
+ the Copyright Holder, if the two differ) through the means of
+ an Internet or similar search.
+
+ 2. If this search is successful, then enquire whether the Work
+ is still maintained.
+
+ a. If it is being maintained, then ask the Current Maintainer
+ to update their communication data within one month.
+
+ b. If the search is unsuccessful or no action to resume active
+ maintenance is taken by the Current Maintainer, then announce
+ within the pertinent community your intention to take over
+ maintenance. (If the Work is a LaTeX work, this could be
+ done, for example, by posting to comp.text.tex.)
+
+ 3a. If the Current Maintainer is reachable and agrees to pass
+ maintenance of the Work to you, then this takes effect
+ immediately upon announcement.
+
+ b. If the Current Maintainer is not reachable and the Copyright
+ Holder agrees that maintenance of the Work be passed to you,
+ then this takes effect immediately upon announcement.
+
+ 4. If you make an `intention announcement' as described in 2b. above
+ and after three months your intention is challenged neither by
+ the Current Maintainer nor by the Copyright Holder nor by other
+ people, then you may arrange for the Work to be changed so as
+ to name you as the (new) Current Maintainer.
+
+ 5. If the previously unreachable Current Maintainer becomes
+ reachable once more within three months of a change completed
+ under the terms of 3b) or 4), then that Current Maintainer must
+ become or remain the Current Maintainer upon request provided
+ they then update their communication data within one month.
+
+A change in the Current Maintainer does not, of itself, alter the fact
+that the Work is distributed under the LPPL license.
+
+If you become the Current Maintainer of the Work, you should
+immediately provide, within the Work, a prominent and unambiguous
+statement of your status as Current Maintainer. You should also
+announce your new status to the same pertinent community as
+in 2b) above.
+
+
+WHETHER AND HOW TO DISTRIBUTE WORKS UNDER THIS LICENSE
+======================================================
+
+This section contains important instructions, examples, and
+recommendations for authors who are considering distributing their
+works under this license. These authors are addressed as `you' in
+this section.
+
+Choosing This License or Another License
+----------------------------------------
+
+If for any part of your work you want or need to use *distribution*
+conditions that differ significantly from those in this license, then
+do not refer to this license anywhere in your work but, instead,
+distribute your work under a different license. You may use the text
+of this license as a model for your own license, but your license
+should not refer to the LPPL or otherwise give the impression that
+your work is distributed under the LPPL.
+
+The document `modguide.tex' in the base LaTeX distribution explains
+the motivation behind the conditions of this license. It explains,
+for example, why distributing LaTeX under the GNU General Public
+License (GPL) was considered inappropriate. Even if your work is
+unrelated to LaTeX, the discussion in `modguide.tex' may still be
+relevant, and authors intending to distribute their works under any
+license are encouraged to read it.
+
+A Recommendation on Modification Without Distribution
+-----------------------------------------------------
+
+It is wise never to modify a component of the Work, even for your own
+personal use, without also meeting the above conditions for
+distributing the modified component. While you might intend that such
+modifications will never be distributed, often this will happen by
+accident -- you may forget that you have modified that component; or
+it may not occur to you when allowing others to access the modified
+version that you are thus distributing it and violating the conditions
+of this license in ways that could have legal implications and, worse,
+cause problems for the community. It is therefore usually in your
+best interest to keep your copy of the Work identical with the public
+one. Many works provide ways to control the behavior of that work
+without altering any of its licensed components.
+
+How to Use This License
+-----------------------
+
+To use this license, place in each of the components of your work both
+an explicit copyright notice including your name and the year the work
+was authored and/or last substantially modified. Include also a
+statement that the distribution and/or modification of that
+component is constrained by the conditions in this license.
+
+Here is an example of such a notice and statement:
+
+ %% pig.dtx
+ %% Copyright 2005 M. Y. Name
+ %
+ % This work may be distributed and/or modified under the
+ % conditions of the LaTeX Project Public License, either version 1.3
+ % of this license or (at your option) any later version.
+ % The latest version of this license is in
+ % http://www.latex-project.org/lppl.txt
+ % and version 1.3 or later is part of all distributions of LaTeX
+ % version 2005/12/01 or later.
+ %
+ % This work has the LPPL maintenance status `maintained'.
+ %
+ % The Current Maintainer of this work is M. Y. Name.
+ %
+ % This work consists of the files pig.dtx and pig.ins
+ % and the derived file pig.sty.
+
+Given such a notice and statement in a file, the conditions
+given in this license document would apply, with the `Work' referring
+to the three files `pig.dtx', `pig.ins', and `pig.sty' (the last being
+generated from `pig.dtx' using `pig.ins'), the `Base Interpreter'
+referring to any `LaTeX-Format', and both `Copyright Holder' and
+`Current Maintainer' referring to the person `M. Y. Name'.
+
+If you do not want the Maintenance section of LPPL to apply to your
+Work, change `maintained' above into `author-maintained'.
+However, we recommend that you use `maintained', as the Maintenance
+section was added in order to ensure that your Work remains useful to
+the community even when you can no longer maintain and support it
+yourself.
+
+Derived Works That Are Not Replacements
+---------------------------------------
+
+Several clauses of the LPPL specify means to provide reliability and
+stability for the user community. They therefore concern themselves
+with the case that a Derived Work is intended to be used as a
+(compatible or incompatible) replacement of the original Work. If
+this is not the case (e.g., if a few lines of code are reused for a
+completely different task), then clauses 6b and 6d shall not apply.
+
+
+Important Recommendations
+-------------------------
+
+ Defining What Constitutes the Work
+
+ The LPPL requires that distributions of the Work contain all the
+ files of the Work. It is therefore important that you provide a
+ way for the licensee to determine which files constitute the Work.
+ This could, for example, be achieved by explicitly listing all the
+ files of the Work near the copyright notice of each file or by
+ using a line such as:
+
+ % This work consists of all files listed in manifest.txt.
+
+ in that place. In the absence of an unequivocal list it might be
+ impossible for the licensee to determine what is considered by you
+ to comprise the Work and, in such a case, the licensee would be
+ entitled to make reasonable conjectures as to which files comprise
+ the Work.
+
diff --git a/macros/latex/contrib/poetry/poetry.dtx b/macros/latex/contrib/poetry/poetry.dtx
new file mode 100644
index 0000000000..de710f3239
--- /dev/null
+++ b/macros/latex/contrib/poetry/poetry.dtx
@@ -0,0 +1,1734 @@
+% \iffalse
+% +AMDG
+%
+% This document is copyright 2019 by Donald P. Goodman, and is
+% released publicly under the LaTeX Project Public License. The
+% distribution and modification of this work is constrained by the
+% conditions of that license. See
+% http://www.latex-project.org/lppl.txt
+% for the text of the license. This document is released
+% under version 1.3c of that license, and this work may be distributed
+% or modified under the terms of that license or, at your option, any
+% later version.
+%
+% This work has the LPPL maintenance status 'maintained'.
+%
+% The Current Maintainer of this work is Donald P. Goodman
+% (dgoodmaniii@gmail.com).
+%
+% This work consists of poetry.dtx, poetry.ins, and
+% derived files poetry.sty and poetry.pdf.
+% \fi
+
+% \iffalse
+%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\ProvidesPackage{poetry}[2019/05/02 v2.0 support for typesetting poetry]
+%<*driver>
+\documentclass{ltxdoc}
+
+\usepackage{doc}
+\usepackage{xellipsis}
+\usepackage{parcolumns}
+\usepackage{array}
+\usepackage{xcolor}
+\usepackage{lettrine}
+ \setcounter{DefaultLines}{3}
+ \setlength{\DefaultFindent}{2pt}
+ \renewcommand{\LettrineFontHook}{\color{red}}
+\usepackage{url}
+\usepackage{poetry}
+\usepackage{spverbatim}
+\usepackage[typeone]{dozenal}
+\usepackage{makeidx}
+\usepackage[colorlinks]{hyperref}
+\EnableCrossrefs
+\PageIndex
+\CodelineNumbered
+\RecordChanges
+\makeindex
+\DoNotIndex{\?,\{,\},\|,\DeclareFontFamily,\DeclareFontShape,
+ \if,\else,\fi,\def,\divide,\clubpenalty,\widowpenalty,\ifdim,\fi,
+ \ifnum,\fi, \ifx, \fi, \Huge, \Large, \LARGE, \begin, \end,
+ \bfseries, \baselineskip, \begingroup,\endgroup,
+ \jobname, \l@poem,\leftskip, \linewidth, \index,
+ \@dottedtocline, \@firstoftwo, \@ifnextchar, \@starttoc,
+ \addcontentsline, \advance, \everypar, \expandafter,
+ \hangafter, \hangindent, \hbox, \hfil, \hsize, \hskip,
+ \multiply, \linewidth, \llap, \blap, \rlap, \tlap,
+ \makeindex, \newcommand, \newcount, \newcounter,
+ \newdimen, \newif, \newlength, \noindent, \par,
+ \parindent, \penalty, \ProvidesPackage, \relax,
+ \RequirePackage, \setcounter, \setlength, \settowidth,
+ \stepcounter, \textwidth, \the, \today, \value, \vbox,
+ \vskip, \vss,
+}
+
+\def\example#1#2{%
+ \begin{parcolumns}{2}
+ \colchunk[1]{#1}%
+ \colchunk[2]{#1}%
+ \end{parcolumns}
+}%
+
+\tracingmacros=3
+\begin{document}
+\DocInput{poetry.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \title{The |poetry| Package, v2.0}
+% \author{Donald P.\ Goodman III}
+% \date{\today}
+%
+% \maketitle
+%
+% \begin{abstract}
+% The |poetry| package provides some macros and general
+% doodads for typesetting poetry. There is, of course,
+% already the excellent |verse| package, and the |poetrytex|
+% package provides some extra functionality on top of it.
+% But |poetry| provides much of the same functionality in a
+% bit of a different way, and with a few additional
+% abilities, such as facilities for a list of poems, an
+% index of first lines, and some structural commands.
+% \end{abstract}
+%
+% \tableofcontents
+%
+% \section{Introduction}
+%
+% The |verse| package provides some truly excellent verse
+% typesetting abilities. Its documentation, particularly,
+% is a great demonstration of (1) how to write \LaTeX\
+% documentation, and (2) how difficult typesetting poetry
+% with \LaTeX\ was before |verse| came along. And yet,
+% occasionally one comes to some things that it doesn't seem
+% able to do. At least, I personally did; when lines
+% wrapped, the line number was placed along the
+% \emph{bottom} of the line, rather than the top, and there
+% doesn't seem to be any way to fix this rather odd
+% behavior.
+%
+% So, the |poetry| package was born. It endeavors to
+% provide all the same functionality as |verse|, in a
+% (mostly) compatible way; but also to fill in this little
+% lacuna, plus any others I happened across while doing it.
+% It also endeavors to add similar functionality as I found
+% in the other major \LaTeX\ poetry package, |poetrytex|,
+% which includes some great ideas for document structure.
+% Finally, it adds some new functionality which is not, to
+% my knowledge, included elsewhere.
+%
+% This document is written in accordance with the \LaTeX\
+% \textsc{docstrip} utility, which allows the automatic
+% extraction of package code and documentation.
+%
+% The numbering in this document is in \emph{dozenal}; that
+% is, numbering goes 1, 2, 3, 4, 5, 6, 7, 8, 9, \x, \e, 10,
+% 11\xelip It uses the |dozenal| \LaTeX\ package to make
+% this happen. For more information, visit
+% \url{http://www.dozenal.org}.
+%
+% \section{Typesetting Verse}
+% \label{sect:verse}
+%
+% \subsection{Basics}
+% \label{sub:basics}
+%
+% |poetry|'s basic environment is, as one would expect, the
+% |poem| environment. \DescribeEnv{poem}|\begin{poem}|
+% and |\end{poem}| will get your poem off and running, no
+% questions asked. The environment redefines certain
+% commands, particularly |\\|, so be aware that you can't
+% use |\\| just anywhere within your poem. Alternatively,
+% you can use \DescribeMacro{\poem}|\poem| to begin the
+% poem, and just use the normal |\\-| to end it (about which
+% more in a moment).
+%
+% Conceptually, each line of the poem is a paragraph, so in
+% order to ensure proper paragraph setting, the |poem|
+% environment also resets |\parindent|, |\hangindent|, and
+% |\hangafter| to appropriate values. We will see how to
+% customize those values in Section \ref{sub:custspace}.
+%
+% End each line of your poem with \DescribeMacro{\\}|\\|,
+% which will end the line and also number the next line. By
+% default, every line is numbered; if you want some other
+% behavior, you will find how to customize line numbering in
+% Section \ref{sub:custlineno}.
+%
+% If the poem has stanzas, end them with the command
+% \DescribeMacro{\\!}|\\!|; this will insert the appropriate
+% amount of vertical spacing, as well as reset the verse
+% line number counter.
+%
+% To end the entire poem, after the last line use
+% \DescribeMacro{\\-}|\\-| (double backslash followed by a
+% hyphen). This clearly differentiates normal line endings;
+% line endings which also end stanzas; and the final line of
+% the poem.
+%
+% If you wish to end the poem for a moment, then resume it
+% later, use \DescribeMacro{\\*}|\\*|. You can then insert
+% whatever you want (e.g., a subpart heading, or some
+% annotations). When you want to start the poetry again,
+% begin the line with \DescribeMacro{\*}|\*|. This allows
+% you insert mostly arbitrary material without leaving the
+% |\poem| environment.
+%
+% Finally, if you want to end the poem for a moment (that
+% is, insert some non-poetical material, like a subpart
+% heading or some annotations), but also want to end a
+% verse, you can use \DescribeMacro{\\?}|\\?|. This
+% combines |\\!| and |\\*|; it has the same visual effect as
+% the latter, but the semantic meaning of the former. Since
+% non-poetical material will follow, it does \emph{not}
+% insert the inter-stanza spacing. You must still use |\*|
+% when you restart poetical material.
+%
+% The idea behind these commands is not to make life
+% difficult for the typesetter, but to mark semantic
+% concepts; that is, to mark very clearly when a line ends;
+% when a line ending is also a stanza ending; when a line
+% ending is followed by non-poetry material; and when a line
+% ending is also the final line of the poem. This kind of
+% information makes it much easier for format converters to
+% work, as well as for semantic readers to figure out what's
+% going on.
+%
+% If you need to include some non-poetry material right at
+% the beginning of a poem, use the starred version to begin
+% it: \DescribeMacro{\poetry*}|\poetry*| or
+% \DescribeMacro{\begin\{poem\}*}|\begin{poem}*|. This will
+% suppress the first line number. When you're ready to
+% begin your first line, begin it with |\*| to insert the
+% first line number.
+%
+% If a line needs some extra indentation, indent it with
+% \DescribeMacro{\hin}|\hin|. This adds the space
+% |\poemhinwd| to the left margin of that particular line and
+% no other. All other paragraph settings are adjusted
+% accordingly. This command can be repeated as needed to
+% produce specific indentation.
+%
+% An example of this basic usage:
+%
+% \begin{verbatim}
+% \begin{poem}
+% Let me not to the marriage of true minds \\
+% \hin Admit impediments. Love is not love \\
+% Which alters when it alteration finds, \\
+% \hin Or bends with the remover to remove: \\!
+%
+% O, no! it is an ever-fixed mark, \\
+% \hin That looks on tempests and is never shaken; \\
+% It is the star to every wandering bark, \\
+% \hin Whose worth's unknown, although his height be taken. \\-
+% \end{poem}
+% \end{verbatim}
+%
+% Which produces (with drastically reduced line length, to
+% show how wrapping will work in these cases; though keep in
+% mind that all these lengths are customizable):
+%
+% \setlength{\poemindent}{1.5in}
+% \setlength{\poemmaxlinewd}{2in}
+% \begin{poem}
+% Let me not to the marriage of true minds \\
+% \hin Admit impediments. Love is not love \\
+% Which alters when it alteration finds, \\
+% \hin Or bends with the remover to remove: \\!
+%
+% O, no! it is an ever-fixed mark, \\
+% \hin That looks on tempests and is never shaken; \\
+% It is the star to every wandering bark, \\
+% \hin Whose worth's unknown, although his height be taken. \\-
+% \end{poem}
+%
+% \subsection{Customizing Spacing and Indentation}
+% \label{sub:custspace}
+%
+% |poetry| inserts some space above and below the typeset
+% poems (unless you tell it not to).
+% \DescribeMacro{\poemtopskip}|\poemtopskip| is inserted
+% above the poem, and
+% \DescribeMacro{\poembotskip}|\poembotskip| is inserted
+% below it. These are standard \LaTeX\ lengths, and can be
+% reset in the usual way. By default, both are set at
+% |1em|.
+%
+% \DescribeMacro{\poemindent}|\poemindent| is the length
+% that governs how far the poem will be indented from the
+% left margin. Reset it as usual with \LaTeX's |\setlength|
+% command; e.g., |\setlength{\poemindent}{1.5in}| to indent
+% the entire poem 1.5in from the left margin. By default,
+% |\poemindent| is |0pt|, meaning that verses are flush with
+% the left margin. This also means that line numbers, if
+% they are on the left, will hang into the left margin.
+%
+% It may be that you wish to control the overall widths of
+% lines; for example, you may want poetry lines to be
+% shorter than the actual text lines. For this, use
+% \DescribeMacro{\poemmaxlinewd}|\poemmaxlinewd|. By
+% default, this standard \LaTeX\ length is set to equal
+% |\linewidth|, so poetry lines can equal the length of the
+% text block. If you don't want this, then you can set it
+% as you please. E.g., if your text block is |5in| wide and
+% you want a half inch of space on either side of your
+% poetry lines, set |\poemmaxlinewd| to |4in| and
+% |\poemindent| to |0.5in|.
+%
+% When lines wrap, |poetry| applies a certain |\hangindent|
+% to make them look nice. To change the length of this
+% hanging indent, reset the value of the standard \LaTeX\
+% length \DescribeMacro{\poemhangindent}|\poemhangindent|,
+% in any of the usual ways (e.g., |\setlength|). By
+% default, |\poemhangindent| is |1em|.
+%
+% Often, particularly when a poem (or lyrics) are simply a
+% small portion of a largely prosaic work, we want the lines
+% more-or-less centered within the text block. The |verse|
+% package does this by providing an optional argument to the
+% |verse| environment, giving the length of a line which
+% will serve as the basis for centering the entire poem.
+% |poetry| instead provides the |\centerpoem| commands.
+% \DescribeMacro{\centerpoemon}|\centerpoemon| sets the
+% centering mechanism on, and (obviously)
+% \DescribeMacro{\centerpoemoff}|\centerpoemoff| turns it
+% off. |\centerpoemon| takes a mandatory argument, the line
+% which you wish to serve as the basis for the centering:
+%
+% \begin{center}
+% \cmd{\centerpoemon} \marg{line-to-use-for-centering}
+% \end{center}
+%
+% What this command does is measures the length of the line,
+% compares it to the text block, and then centers that line;
+% all other lines in the poem will share a left and right
+% margin with that line. E.g.:
+%
+% \begin{verbatim}
+% \centerpoemon{The ship has weather'd every rack, the prize we sought is won}
+% \begin{poem}
+% O captain! my captain! The fearful trip is done; \\
+% The ship has weather'd every rack, the prize we sought is won;\\-
+% \end{poem}
+% \end{verbatim}
+%
+% Which gives us:
+%
+% \setlength{\poemmaxlinewd}{\textwidth}
+% \centerpoemon{The ship has weather'd every rack, the
+% prize we sought is won}
+% \begin{poem}
+% O captain! my captain! The fearful trip is done; \\
+% The ship has weather'd every rack, the prize we sought is won;\\-
+% \end{poem}
+%
+% Note that this \emph{does} set the maximum line width to
+% the width of that line, as well. You can reset this after
+% issuing |\centerpoemon| if that's not the behavior you
+% want; that is, if you want to center on that particular
+% line but still allow other lines to be longer. This
+% behavior makes it default that your poem will actually be
+% centered on the width of the line you've entered; however,
+% if you're really just looking for an approximate optical
+% centering, with lines extending longer if necessary, set
+% |\poemmaxlinewd| to what you want your longest line to be.
+% Just make sure that you set it \emph{after} you set
+% |\centerpoemon|.
+%
+% |\centerpoemoff| simply resets |\poemindent| to |0pt| and
+% |\poemmaxlinewd| to |\textwidth|.
+%
+% The indentation given by |\hin| is controlled by the
+% \LaTeX\ length \DescribeMacro{\poemhinwd}|\poemhinwd|,
+% which can be set however the user wishes. By default, it
+% is |1em|. E.g.:
+%
+% \begin{verbatim}
+% \centerpoemon{Alas, poor Yorick! I knew him. Horatio!}
+% \settowidth{\poemhinwd}{Alas, poor Yorick! I knew him. }
+% \begin{poem}
+% Alas, poor Yorick! I knew him.\\
+% \hin Horatio! \\
+% \setlength{\poemhinwd}{2em}
+% A fellow of infinite jest, of most excellent fancy. \\
+% \hin He hath borne me on his back a thousand times, \\
+% and now, how abhorred in my imagination it is! \\
+% My gorge rises at it. Here hung those lips\xelip\\-
+% \end{poem}
+% \end{verbatim}
+%
+% This is a common requirement when the meter of one line is
+% continued onto the next, as in this famous line(s) from
+% \textit{Hamlet}:
+%
+% \centerpoemon{Alas, poor Yorick! I knew him. Horatio!}
+% \begin{poem}
+% \settowidth{\poemhinwd}{Alas, poor Yorick! I knew him. }
+% Alas, poor Yorick! I knew him.\\
+% \hin Horatio! \\
+% \setlength{\poemhinwd}{2em}
+% A fellow of infinite jest, of most excellent fancy. \\
+% \hin He hath\label{ln:ex} borne me on his back a thousand times, \\
+% and now, how abhorred in my imagination it is! \\
+% My gorge rises at it. Here hung those lips\xelip\\-
+% \end{poem}
+%
+% This way we can advance the second line so that it's
+% clearly a continuation of the first. The second |\hin|
+% command here is just to show that the lengths can be
+% adjusted at will throughout the poem, and it doesn't
+% effect the line numbering in any way.
+%
+% Using |\hin| manually works fine, but sometimes it's a
+% hassle, particularly when the indentation pattern is
+% regular. E.g., when every second line is to be indented,
+% why should you manually have to insert |\hin| every second
+% line? That's the sort of thing computers are good at.
+% Fortunately, |poetry| agrees with you, and offers the
+% \DescribeMacro{poemindentevery}|poemindentevery| counter.
+% This is a standard \LaTeX\ counter. If its value is |0|,
+% it has no effect whatsoever; if its value is any other
+% integer, however, it will indent every multiple of that
+% line number. E.g.:
+%
+% \begin{verbatim}
+% \setcounter{poemindentevery}{3}
+% \setcounter{poemlinenumsevery}{2}
+% \begin{poem}
+% Once upon a midnight dreary, while I pondered, weak and weary,\\
+% Over many a quaint and curious volume of forgotten lore---\\
+% While I nodded, nearly napping, suddenly there came a tapping,\\
+% As of someone gently rapping, rapping at my chamber door.\\
+% ``'Tis some visitor,'' I muttered, ``tapping at my chamber door---\\
+% Only this and nothing more.''\\-
+% \end{poem}
+% \end{verbatim}
+%
+% Which will give us this:
+%
+% \setcounter{poemindentevery}{3}
+% \setcounter{poemlinenumsevery}{2}
+% \begin{poem}
+% Once upon a midnight dreary, while I pondered, weak and weary,\\
+% Over many a quaint and curious volume of forgotten lore---\\
+% While I nodded, nearly napping, suddenly there came a tapping,\\
+% As of someone gently rapping, rapping at my chamber door.\\
+% ``'Tis some visitor,'' I muttered, ``tapping at my chamber door---\\
+% Only this and nothing more.''\\-
+% \end{poem}
+% \setcounter{poemindentevery}{0}
+% \setcounter{poemlinenumsevery}{1}
+%
+% Notice that line numbers are also unaffected by this
+% setting; line numbers will be placed where needed, and
+% indents will be added as needed, without regard for one
+% another. (We will officially meet the counter
+% |poemlinenumsevery| in Section \ref{subsub:basiclineno}.)
+%
+% Sometimes, however, indenting every third line (or
+% whatever) isn't the right solution; sometimes each
+% \emph{verse} has a particular indentation pattern. For
+% that, |poetry| offers the command
+% \DescribeMacro{\poemvsindentlines}|\poemvsindentlines|.
+% Redefine this command to contain a list of the line
+% numbers (by verse) you wish to indent, and |poetry| will dutifully
+% indent them. E.g.:
+%
+% \begin{verbatim}
+% \def\poemvsindentlines{23}%
+% \begin{poem}
+% I saw you starting for another war,\\
+% The emblem of adventure and of youth,\\
+% So that men trembled, saying: He forsooth\\
+% Has gone, has gone, and shall return no more.\\-
+% \end{poem}
+% \end{verbatim}
+%
+% \def\poemvsindentlines{23}%
+% \begin{poem}
+% I saw you starting for another war,\\
+% The emblem of adventure and of youth,\\
+% So that men trembled, saying: He forsooth\\
+% Has gone, has gone, and shall return no more.\\-
+% \end{poem}
+% \def\poemvsindentlines{0}%
+%
+% If you give a line number larger than the number of lines
+% in a verse, it will be quietly ignored.
+%
+% Note that |\poemvsindentlines| and |poemindentevery| will
+% \emph{stack}; if a line qualifies for both, it will be
+% indented twice.
+%
+% |\poemvsindentlines| allows you to arrange the indentation
+% on each verse with very fine detail, assuming that all
+% your verses are indented the same way.
+%
+% Finally, you should meet
+% \DescribeMacro{\poemverseskip}|\poemverseskip|, which
+% controls the distance between verses (stanzas) of the
+% poem. By default, this is set equal to |\baselineskip|,
+% leaving about one full line between stanzas. This is a
+% standard \LaTeX\ length, and can be reset in the usual
+% way.
+%
+% \subsection{Customizing Line Numbering}
+% \label{sub:custlineno}
+%
+% \subsubsection{Basics of Line Numbering}
+% \label{subsub:basiclineno}
+%
+% Line numbers, unlike in |verse|, \emph{are} typeset by
+% default. To turn them off, just say
+% \DescribeMacro{\poemlinenumsfalse}|\poemlinenumsfalse|.
+% Of course, issuing
+% \DescribeMacro{\poemlinenumstrue}|\poemlinenumstrue| will
+% do the opposite.
+%
+% \centerpoemoff
+% \begin{verbatim}
+% \poemlinenumsfalse
+% \begin{poem}
+% O captain! my captain! The fearful trip is done; \\
+% \poemlinenumstrue
+% The ship has weather'd every rack, the prize we sought is won;\\
+% The port is near, the bells I hear, the people all exulting, \\
+% While follow eyes the steady keel, the vessel grim and daring; \\-
+% \end{poem}
+% \end{verbatim}
+%
+% Which gives us:
+%
+% \poemindent=0pt
+% \poemlinenumsfalse
+% \begin{poem}
+% O captain! my captain! The fearful trip is done; \\
+% \poemlinenumstrue
+% The ship has weather'd every rack, the prize we sought is won;\\
+% The port is near, the bells I hear, the people all exulting, \\
+% While follow eyes the steady keel, the vessel grim and daring; \\-
+% \end{poem}
+%
+% Notice that |poetry| actually sets the line number
+% \emph{before} the rest of the line; so when turning line
+% numbers on again, you need to put |\poemlinenumstrue| one
+% line earlier than you might expect.
+%
+% Line numbers aren't just on or off, however; you can have
+% them every certain number of lines, for example. The
+% command for this is
+% \DescribeMacro{\poemlinenumsevery}|\poemlinenumsevery|; note that
+% this is a \emph{counter}, so redefine it with
+% |\setcounter| and friends. By default, its value is |1|.
+% The value works as one would expect; |2| means a number
+% every two lines, |3| every three lines, and so on. For
+% example:
+%
+% \begin{verbatim}
+% \setcounter{poemlinenumsevery}{2}
+% \poemlinenumstrue
+% \begin{poem}
+% O captain! my captain! The fearful trip is done; \\
+% The ship has weather'd every rack, the prize we sought is won;\\
+% The port is near, the bells I hear, the people all exulting, \\
+% While follow eyes the steady keel, the vessel grim and daring; \\-
+% \end{poem}
+% \end{verbatim}
+%
+% Gives us this:
+%
+% \setcounter{poemlinenumsevery}{2}
+% \poemlinenumstrue
+% \begin{poem}
+% O captain! my captain! The fearful trip is done; \\
+% The ship has weather'd every rack, the prize we sought is won;\\
+% The port is near, the bells I hear, the people all exulting, \\
+% While follow eyes the steady keel, the vessel grim and daring; \\-
+% \end{poem}
+% \setcounter{poemlinenumsevery}{0}
+%
+% This can, of course, be set to any value, though typically
+% 1--4 are reasonable ones. A sufficiently high number will
+% essentially turn off line numbering; e.g., 84, as by the
+% time you've seen the 84th line you won't remember what the
+% last line number was. But I'm certainly not going to make
+% it impossible.
+%
+% Often, though, you won't want to print line numbers every
+% arbitrary number of lines throughout the poem, but on
+% certain lines by verse. E.g., perhaps you want to number
+% lines 2, 3, and 5 of a poem, but not 1, 4, and 6. To
+% accomplish this, use the \DescribeMacro{\poemnumlines}|\poemnumlines|
+% macro. If empty, it has no effect, and by default it is
+% empty. However, if you put in a list of numbers,
+% then the lines of each stanza corresponding to that list
+% of numbers will be numbered accordingly. So, for example,
+% to number 2, 3, and 5 only:
+%
+% \begin{verbatim}
+% \def\poemnumlines{235}
+% \begin{poem}
+% Once upon a midnight dreary, while I pondered, weak and weary,\\
+% Over many a quaint and curious volume of forgotten lore---\\
+% While I nodded, nearly napping, suddenly there came a tapping,\\
+% As of someone gently rapping, rapping at my chamber door.\\
+% ``'Tis some visitor,'' I muttered, ``tapping at my chamber door---\\
+% Only this and nothing more.''\\-
+% \end{poem}
+% \def\poemnumlines{}
+% \end{verbatim}
+%
+% Yields the following:
+% \def\poemnumlines{235}
+% \begin{poem}
+% Once upon a midnight dreary, while I pondered, weak and weary,\\
+% Over many a quaint and curious volume of forgotten lore---\\
+% While I nodded, nearly napping, suddenly there came a tapping,\\
+% As of someone gently rapping, rapping at my chamber door.\\
+% ``'Tis some visitor,'' I muttered, ``tapping at my chamber door---\\
+% Only this and nothing more.''\\-
+% \end{poem}
+% \def\poemnumlines{}
+%
+% This pattern will repeat for each verse until you set
+% |\poemnumline| to something else.
+%
+% Finally, line numbers can be placed on either the right or the
+% left. |poetry| v2.0 introduces significantly more
+% flexibility into this mechanic; however, to preserve
+% backward compatibility, the old commands are still
+% recognized. To place line numbers on the right, use
+% \DescribeMacro{\poemlinenumrighttrue}|\poemlinenumrighttrue|;
+% to put them back on the left, use the corresponding
+% command
+% \DescribeMacro{\poemlinenumrightfalse}|\poemlinenumrightfalse|.
+% Note that these commands merely set the right-hand line
+% number spot to equal the poem line counter; this will make
+% sense to you later.
+%
+% \begin{verbatim}
+% \poemlinenumrighttrue
+% \setcounter{poemlinenumsevery}{1}
+% \begin{poem}
+% O captain! my captain! The fearful trip is done; \\
+% \poemlinenumrightfalse
+% The ship has weather'd every rack, the prize we sought is won;\\
+% The port is near, the bells I hear, the people all exulting, \\
+% While follow eyes the steady keel, the vessel grim and daring; \\-
+% \end{poem}
+% \end{verbatim}
+%
+% Which gives us this (notice that right-side line numbers
+% are placed after |\poemmaxlinewd|):
+%
+% \poemlinenumrighttrue
+% \setcounter{poemlinenumsevery}{1}
+% \begin{poem}
+% O captain! my captain! The fearful trip is done; \\
+% \poemlinenumrightfalse
+% The ship has weather'd every rack, the prize we sought is won;\\
+% The port is near, the bells I hear, the people all exulting, \\
+% While follow eyes the steady keel, the vessel grim and daring; \\-
+% \end{poem}
+%
+% Notice again that the line's line number is printed
+% \emph{first}, before the line; so you need to put this
+% command one line earlier than you'd expect.
+%
+% Please notice also that \emph{the line numbers are
+% \emph{not} part of the line when calculating widths}.
+% They are boxes which overhang the end or beginning of the
+% line. Please keep that in mind when you're planning your
+% formats.
+%
+% As of v2.0, |poetry| allows numbering to appearing on both
+% the right \emph{and} left side of the poem. This is a
+% much more flexible mechanism than before, and should be
+% used in preference to the old |\poemlinenumsrighttrue|
+% mechanism in any new work.
+%
+% Any of the line numbering variables beginning with |\poem|
+% have corresponding versions beginning with |\poemrt|. You
+% can then set the variables arbitrarily for the left and
+% right sides, which will not effect one another.
+% E.g., perhaps you want to show total line numbers on the
+% left, and verse line numbers on the right, both on every
+% two lines:
+%
+% \begin{quote}
+% |\renewcommand{\thepoemline}{\arabic{poemline}}|\\
+% |\setcounter{poemlinenumsevery}{2}|\\
+% |\setcounter{poemrtlinenumsevery}{2}|\\
+% |\renewcommand{\thepoemrtline}{\arabic{verseline}}|\\
+% \end{quote}
+%
+% \renewcommand{\thepoemline}{\arabic{poemline}}
+% \setcounter{poemlinenumsevery}{2}
+% \setcounter{poemrtlinenumsevery}{2}
+% \renewcommand{\thepoemrtline}{\arabic{verseline}}
+% \centerpoemon{Whose woods these are I think I know.}
+% \begin{poem}
+% Whose woods these are I think I know. \\
+% His house is in the village though; \\
+% He will not see me stopping here \\
+% To watch his woods fill up with snow. \\!
+%
+% My little horse must think it queer \\
+% To stop without a farmhouse near \\
+% Between the woods and frozen lake \\
+% The darkest evening of the year. \\-
+% \end{poem}
+% \setcounter{poemlinenumsevery}{0}
+% \setcounter{poemrtlinenumsevery}{0}
+%
+% This is useful for those volumes that wish to list a
+% stanza number as well as a line numbers, one on each side.
+% |poetry| offers the stanza number as the counter
+% \DescribeMacro{stanzacount}|stanzacount|. For example, to
+% put the line count on the right, with a stanza count on the
+% first line of each stanza on the left:
+%
+% \begin{quote}
+% |\def\poemnumlines{1}|\\
+% |\renewcommand{\thepoemline}{\arabic{stanzacount}}|\\
+% |\setcounter{poemrtlinenumsevery}{1}|\\
+% |\renewcommand{\thepoemrtline}{\arabic{poemline}}|\\
+% \end{quote}
+%
+% \def\poemnumlines{1}
+% \renewcommand{\thepoemline}{\arabic{stanzacount}}
+% \setcounter{poemrtlinenumsevery}{1}
+% \renewcommand{\thepoemrtline}{\arabic{poemline}}
+% \centerpoemon{Whose woods these are I think I know.}
+% \begin{poem}
+% Whose woods these are I think I know. \\
+% His house is in the village though; \\
+% He will not see me stopping here \\
+% To watch his woods fill up with snow. \\!
+%
+% My little horse must think it queer \\
+% To stop without a farmhouse near \\
+% Between the woods and frozen lake \\
+% The darkest evening of the year. \\-
+% \end{poem}
+%
+% We can occasionally do some truly interesting things this
+% way. For example, to have odd-numbered lines marked on
+% the left and even on the right:
+%
+% \begin{quote}
+% |\renewcommand{\thepoemline}{\arabic{poemline}}|\\
+% |\renewcommand{\thepoemrtline}{\arabic{poemline}}|\\
+% |\def\poemnumlines{13}|\\
+% |\def\poemrtnumlines{24}|\\
+% \end{quote}
+%
+% \setcounter{poemlinenumsevery}{99}
+% \setcounter{poemrtlinenumsevery}{99}
+% \renewcommand{\thepoemline}{\arabic{poemline}}
+% \renewcommand{\thepoemrtline}{\arabic{poemline}}
+% \def\poemnumlines{13}
+% \def\poemrtnumlines{24}
+% \centerpoemon{Whose woods these are I think I know.}
+% \begin{poem}
+% Whose woods these are I think I know. \\
+% His house is in the village though; \\
+% He will not see me stopping here \\
+% To watch his woods fill up with snow. \\!
+%
+% My little horse must think it queer \\
+% To stop without a farmhouse near \\
+% Between the woods and frozen lake \\
+% The darkest evening of the year. \\!
+%
+% He gives his harness bells a shake \\
+% To ask if there is some mistake. \\
+% The only other sound's the sweep \\
+% Of easy wind and downy flake. \\-
+% \end{poem}
+%
+% \subsubsection{Styling Line Numbers}
+% \label{subsub:stylelineno}
+%
+% As mentioned before, the line numbers are set in boxes
+% which overhang either the left or right margins of the
+% line, depending on the value of |\ifpoemlinenumright|
+% (that is, on whether you've isseud |\poemlinenumrighttrue|
+% or not). The size of that box, and how much it overhangs
+% the margin, are both within your control.
+%
+% By default, the box is |2em| wide, and it's separated from
+% the margin by |0pt|. To change the space between the box
+% and the line itself, use the standard \LaTeX\ length
+% \DescribeMacro{\poemlinenumboxgap}|\poemlinenumboxgap|;
+% below, see some lines from \textit{Henry V} to
+% demonstrate. The first two lines are set with default
+% line number spacing; the second two with
+% |\poemlinenumboxgap| set to |1em|:
+%
+% \centerpoemon{We few, we happy few; we band of brothers;}
+%
+% \poemlinenumrightfalse
+% \begin{poem}
+% We few, we happy few; we band of brothers; \\
+% \setlength{\poemlinenumboxgap}{1em}
+% for he today who sheds his blood with me \\
+% shall be my brother; be he ne'er so vile \\
+% this day shall gentle his condition. \\-
+% \end{poem}
+%
+% The width of the line number box itself is controlled by
+% \DescribeMacro{\poemlinenumboxwd}|\poemlinenumboxwd|,
+% another standard \LaTeX\ length which can be reset, as
+% usual, with |\setlength|. Below, we have some more of
+% \textit{Henry V}, this time with varying line number box
+% widths; the first two lines have the default, the second
+% two have a width of |1em|:
+%
+% \centerpoemon{shall think themselves accurs'd they were not here,}
+% \poemlinenumrighttrue
+% \begin{poem}
+% And gentlemen in England now abed \\
+% \setlength{\poemrtlinenumboxwd}{1em}
+% shall think themselves accurs'd they were not here, \\
+% and hold their manhoods cheap whilst any speaks \\
+% that fought with us, upon St.~Crispin's day. \\-
+% \end{poem}
+%
+% The line number itself is held in the \LaTeX\ macro
+% \DescribeMacro{\thepoemline}|\thepoemline|; so you can
+% style this as you wish. However, in the event you want
+% line numbers to look a certain way in the poem itself,
+% but a different way when you use them elsehwere, you can
+% use \DescribeMacro{\poemlinenumstyle}|\poemlinenumstyle|
+% to change their appearance. For example, the following
+% uses |\def\poemlinenumstyle{\footnotesize\color{green}}|
+% and |\def\poemrtlinenumstyle{\LARGE\color{red}}|:
+%
+% \centerpoemon{Thou see'st the world, Volumnius, how it goes; }
+% \renewcommand{\thepoemline}{\arabic{poemline}}
+% \renewcommand{\thepoemrtline}{\arabic{poemline}}
+% \def\poemnumlines{13}
+% \def\poemrtnumlines{24}
+% \def\poemlinenumstyle{\footnotesize\color{green}}
+% \def\poemrtlinenumstyle{\LARGE\color{red}}
+% \begin{poem}
+% Thou see'st the world, Volumnius, how it goes; \\
+% our enemies have beat us to the pit. \\
+% It would be better to jump in ourselves, \\
+% than tarry till they push us. \\-
+% \end{poem}
+%
+% The right line style is an insane choice; but it does
+% demonstrate how things work. By default, both
+% |\poemlinenumstyle| and |\poemrtlinenumstyle| do nothing.
+% \def\poemlinenumstyle{}
+% \def\poemrtlinenumstyle{}
+% \def\poemrtnumlines{}
+%
+% Labels can be placed on any line of poetry, and refer back
+% to that line. Make references with the usual \LaTeX\
+% |\ref| and |\label| commands; for example, ``line
+% \ref{ln:ex}'' refers to line 4 of the quotation from
+% \textit{Hamlet} we gave you earlier. If you've loaded
+% |hyperref|, these will correctly turn into hyperlinks, as
+% well.
+%
+%
+% \section{Document Structure}
+% \label{sect:structure}
+%
+% |poetry| actually provides some significant structural
+% commands, as well, which may make it easier to typeset
+% larger amounts of poetry. It was inspired here more by
+% |poetrytex| than by |verse|; indeed, this area is really
+% where |poetrytex| shines. However, |poetry| does add some
+% functionality to it. We'll explore first counters,
+% then sectioning.
+%
+% \subsection{Other Counters}
+% \label{sub:othcounters}
+%
+% |poetry| provides several other counters, which will
+% probably rarely be useful when typesetting poetry, but
+% which are provided just in case.
+%
+% Besides |\thepoemline|, we also have
+% \DescribeMacro{verseline}|verseline|, a counter which
+% keeps track of what line in a given verse is currently
+% being typeset. It's reset every time you call |\\!|, to
+% signify the end of a verse (or, more properly for poetry,
+% stanza). It's typeset with |\theverseline|, which can be
+% redefined in the normal \LaTeX\ ways. For example, to
+% number each verse with the poem line number, a colon, and
+% a verse line number, try:
+%
+% \begin{center}
+% |\renewcommand{\thepoemline}{\arabic{poemline}:\arabic{verseline}}|
+% \end{center}
+%
+% You'll get something like this:
+%
+% \renewcommand{\thepoemline}{\arabic{poemline}:\arabic{verseline}}
+% \centerpoemon{Whose woods these are I think I know.}
+% \begin{poem}
+% Whose woods these are I think I know. \\
+% His house is in the village though; \\
+% He will not see me stopping here \\
+% To watch his woods fill up with snow. \\!
+%
+% My little horse must think it queer \\
+% To stop without a farmhouse near \\
+% Between the woods and frozen lake \\
+% The darkest evening of the year. \\-
+% \end{poem}
+%
+% We also have a counter for the number of poems themselves;
+% two, actually. First is
+% \DescribeMacro{abspoemno}|abspoemno|, which keeps track of
+% the poem numbers throughout the entire document.
+% |abspoemno| is typeset, as always with \LaTeX\ counters,
+% with |\theabspoemno|. This number can be useful with sets
+% of poems, such as Shakespeare's sonnets; or with
+% anthologies which include untitled poems, which might
+% otherwise be difficult to list in a table of contents.
+%
+% Second, there is the \emph{poem group} counter, or
+% \DescribeMacro{poemno}|poemno|. |poemno| equals
+% |abspoemno| unless you're utilizing poem groups (for which
+% see Section \ref{sub:structures}). Starting a new poem
+% group resets |poemno| but not |abspoemno|.
+%
+% We will see some poetry-specific sectioning commands in
+% Section \ref{subsub:usemeta}. These commands increment
+% |poemno| and |abspoemno|; so if you're not using those
+% sectioning commands, these numbers won't be incremented.
+% If for some reason you don't use a visible title for your
+% poem, or wish to use your own sectioning commands, but
+% still want it counted for the purposes of these counters,
+% you need to tell |poetry| so. Issue
+% \DescribeMacro{\poemnew}|\poemnew| prior to starting your
+% |poem| environment; it will increment your counters
+% without putting anything in your text.
+%
+% These counters are formatted, as always, with the \LaTeX\
+% |\the| commands: |\thepoemno|, |\theabspoemno|.
+%
+% \subsection{Other Variables}
+% \label{sub:othervars}
+%
+% |poetry| gives a few variables that we can use to fill in
+% gaps when we have them.
+%
+% \DescribeMacro{\poemblanktitle}|\poemblanktitle| is the
+% word that |poetry| will use when it's asked to typeset a
+% title but it doesn't have one; by default, this is set as
+% |Untitled|. Reset this with |\def| or |\renewcommand|;
+% e.g., |\renewcommand{\poemblanktitle}{Not Titled}|. Then,
+% when you are expected to input a title and you don't have
+% one (possible in, for example, the |\titlepoem| command,
+% for which see Section \ref{sub:metadata}), instead of
+% printing ``Untitled'', |poetry| will print ``Not Titled''.
+%
+% There is a corresponding
+% \DescribeMacro{\poemblankauthor}|\poemblankauthor|, which
+% does the same thing. Its default value is |Anonymous|.
+%
+% \subsection{Metadata}
+% \label{sub:metadata}
+%
+% All poems have authors, even if we don't know who; and
+% some also have titles. In other words, poems have
+% \emph{metadata}, data about themselves, and |poetry|
+% provides easy ways to deal with these things, whether we
+% have the information or not. Sometimes it will be
+% convenient to use the variables from Section
+% \ref{sub:othervars} in these commands.
+%
+% |poetry| keeps the issue of \emph{having} the metadata
+% separate from \emph{typesetting} it. You can set these
+% variables but never have them appear in the final
+% document. In theory, this information could instead by
+% embedded in the |pdf| for document readers to use, or
+% things of that nature. At present, pdf doesn't have any
+% means to embed metadata about individual parts of a
+% document; however, should such a capability be added,
+% |poetry| will be ready.
+%
+% \subsubsection{Setting Metadata Values}
+% \label{subsub:setmeta}
+%
+% \DescribeMacro{\thepoemtitle}|\thepoemtitle| holds the
+% currently defined poem title, if any. You might find this
+% handy for running headers, TOC entries, and the like.
+%
+% \DescribeMacro{\thepoemauthor}|\thepoemauthor| corresponds
+% to |\thepoemtitle|, and is useful for the same sorts of
+% things.
+%
+% Most written works these days have \emph{licenses};
+% |poetry| makes it easy to specify that, as well. The
+% variable is
+% \DescribeMacro{\thepoemlicense}|\thepoemlicense|, and
+% defaults to the string |Public Domain|. To alter this,
+% simply redefine it with |\def| or |\renewcommand|; e.g.,
+% |\renewcommand{\thepoemlicense}{CC-BY-SA}|. To change the
+% default, redefine
+% \DescribeMacro{\poemdefaultlicense}|\poemdefaultlicense|.
+%
+% Publication date can also be important, particularly when
+% combined with certain types of licensing. To specify
+% this, redefine
+% \DescribeMacro{\thepoempubdate}|\thepoempubdate|, which
+% defaults to the value of |\today|.
+%
+% \subsubsection{Using Metadata}
+% \label{subsub:usemeta}
+%
+% The most obvious way of using the metadata you've set for
+% a poem is to \emph{typeset} it. |poetry| offers a number
+% of ways to do this.
+%
+% If you're only interested in printing the poem's title,
+% you can use the \DescribeMacro{\titlepoem}|\titlepoem|
+% command:
+%
+% \begin{center}
+% \cmd{\titlepoem} \marg{title}
+% \end{center}
+%
+% E.g., with the default settings:
+%
+% \bigskip\hrule\bigskip
+% \begin{parcolumns}[rulebetween]{2}%
+% \colchunk[1]{
+% |\titlepoem{\poemblanktitle}|
+% }\colchunk[2]{%
+% \titlepoem{\poemblanktitle}
+% }\end{parcolumns}%
+% \bigskip\hrule\bigskip
+%
+% If you have multiple untitled poems to typeset, it may be
+% convenient to use |\thepoemno| or |\theabspoemno| to
+% different them; e.g.,
+%
+% \begin{center}
+% |\titlepoem{Untitled No.\ \thepoemno}|
+% \end{center}
+%
+% |\titlepoem| will reset the variable |\thepoemtitle| to
+% whatever argument you give it. This will be available
+% later for other uses.
+%
+% If you want to typeset both the title and the author,
+% |poetry| provides you with
+% \DescribeMacro{\titleauthorpoem}|\titleauthorpoem|:
+%
+% \begin{center}
+% \cmd{\titlepoem} \marg{title} \marg{author}
+% \end{center}
+%
+% \bigskip\hrule\bigskip
+% \begin{parcolumns}[rulebetween]{2}%
+% \colchunk[1]{
+% \noindent|\titleauthorpoem|\par
+% \quad|{\poemblanktitle}|\par
+% \quad|{\poemblankauthor}|
+% }\colchunk[2]{%
+% \titleauthorpoem{\poemblanktitle}{\poemblankauthor}
+% }\end{parcolumns}%
+% \bigskip\hrule\bigskip
+%
+% |\titleauthorpoem| resets both |\thepoemtitle| and
+% |\thepoemauthor| to the values you submit.
+%
+% |poetry| also gives you hooks to control the appearance of
+% these macros.
+% \DescribeMacro{\poemtitleprehook}|\poemtitleprehook| is
+% inserted by |poetry| prior to the title text, and
+% \DescribeMacro{\poemtitleposthook}|\poemtitleposthook| is
+% inserted afterward. For |\titleauthorpoem|, there is also
+% \DescribeMacro{\poemauthorprehook}|\poemauthorprehook| and
+% \DescribeMacro{\poemauthorposthook}|\poemauthorposthook|,
+% inserted before and after the author. By default, the
+% |pre| commands simply |\begin{center}|, while the
+% |post| commands contain |\end{center}|, but you can
+% certainly change their values to achieve the appearance
+% you want:
+%
+% \bigskip\hrule\bigskip
+% \begin{parcolumns}[colwidths={1=1.5in}]{2}%
+% \colchunk[1]{
+% \begin{verbatim}
+% \def\poemtitleprehook{%
+% \bigskip\noindent}
+% \def\poemtitleposthook{}
+% \def\poemauthorprehook{\hfill}
+% \def\poemauthorposthook{\bigskip}
+% \titleauthorpoem{\poemblanktitle}{\poemblankauthor}
+% \end{verbatim}
+% }\colchunk[2]{%
+% \def\poemtitleprehook{\bigskip\noindent}%
+% \def\poemtitleposthook{}%
+% \def\poemauthorprehook{\hfill}%
+% \def\poemauthorposthook{\bigskip}%
+% \titleauthorpoem{\poemblanktitle}{\poemblankauthor}%
+% }\end{parcolumns}
+% \bigskip\hrule\bigskip
+%
+% These settings are rather na\"\i{}ve, since they don't
+% take the length of either author or title into account,
+% but they suffice to show the power of using these hooks.
+%
+% There is also
+% \DescribeMacro{\poemtitlestyle}|\poemtitlestyle|, which
+% sets the styling of the title. By default, it is simply
+% set with |\def\poemtitlestyle{\LARGE\bfseries}|.
+%
+% Similarly, there is
+% \DescribeMacro{\poemauthorstyle}|\poemauthorstyle|, which
+% provides the styles for the author (if one will be
+% typeset). By default, this is
+% |\def\poemauthorstyle{\Large}|.
+%
+% \subsection{Structural Features}
+% \label{sub:structures}
+%
+% In addition to typesetting poems individually, |poetry|
+% has some features to facilitate typesetting collections of
+% poetry. Structurally, primarily we're dealing with poem
+% groups (for which see Section \ref{subsub:poemgroups});
+% however, we also have significant power in indexing and
+% tracking poems.
+%
+% \subsubsection{Poem Groups}
+% \label{subsub:poemgroups}
+%
+% Poem groups are just what they sound like: groups of
+% poems. They might be arranged by topic, by author, by
+% style, or by any other criteria. As we have already seen
+% in Section \ref{sub:othcounters}, the |poemno| counter
+% tracks the number of poems individually within poem
+% groups. Let's see a few of the commands we have for
+% creating and dealing with these groups.
+%
+% \DescribeMacro{\poemgroup}|\poemgroup| starts a new poem
+% group; it resets the |poemno| counter and adds one to the
+% poem group counter. That's it; it's a purely structural
+% command. Formatting title pages and the like for poem
+% groups is another matter.
+% \DescribeMacro{\endpoemgroup}|\endpoemgroup| can
+% optionally be used to end the poem group. Like |\poem|,
+% however, these can also be used like a \LaTeX\
+% environment, using |\begin{poemgroup}| and
+% |\end{poemgroup}|.
+%
+% \DescribeMacro{poemgroupno}|poemgroupno| is the counter
+% which keeps track of which poem group you're currently in.
+% It is a standard \LaTeX\ counter, which can be reset,
+% manipulated, formatted, and displayed in the usual ways.
+%
+% \DescribeMacro{\poemgroupheading}|\poemgroupheading|
+% prints a heading for the poem group. This may or may not
+% be on its own page; that's up to your formatting.
+%
+% \begin{center}
+% \cmd{\poemgroupheading} \marg{title} \marg{other}
+% \end{center}
+%
+% Both these arguments are mandatory, though of course one
+% or the other might be empty. The first is the title of
+% the poem group; the second is whatever else. It may be
+% the author of the group; the style of poetry (e.g.,
+% anapestic, or alliterative); or any other criteria by
+% which the poetry is broken into groups.
+%
+% |\poemgroupheading| also resets the value of
+% \DescribeMacro{\thepoemgroupname}|\thepoemgroupname|,
+% which is another bit of metadata that can used throughout
+% that group. It resets it to the value of its first
+% argument. If it is not reset, its value is simply the
+% value of
+% \DescribeMacro{\poemgroupblankname}|\poemgroupblankname|,
+% which defaults to |Untitled Group|. By redefining this
+% command, you can change the default group name. You can
+% also redefine |\thepoemgroupname| separately, but be aware
+% that calling |\poemgroupheading| will reset it again.
+%
+% The hooks listed to the left
+% \DescribeMacro{\poemgrouptitleprehook}
+% \DescribeMacro{\poemgrouptitleposthook}
+% \DescribeMacro{\poemgroupotherprehook}
+% \DescribeMacro{\poemgroupotherposthook} are inserted where
+% their names imply into the heading. By default, all are
+% defined to do nothing, but you can fix this with |\def| or
+% |\renewcommand|. A common styling would involve putting
+% |\begin{center}| and |\end{center}| into one or both of the
+% |pre| and |post| hooks, respectively. Another common
+% requirement would involve putting |\cleardoublepage| into
+% |\poemgrouptitleprehook|, along with whatever else is
+% required, in order to ensure a poem group starts on the
+% next new recto (right-side and odd-numbered) page.
+%
+% The title can be styled by redefining
+% \DescribeMacro{\poemgrouptitlestyle}|\poemgrouptitlestyle|,
+% which by default simply contains |\Huge|. The ``other''
+% argument can be styled with
+% \DescribeMacro{\poemgroupotherstyle}|\poemgroupotherstyle|,
+% which by default contains simply |\LARGE|.
+
+%
+%
+%
+% \subsubsection{List of Poems}
+% \label{subsub:tocpoems}
+%
+% To go along with the table of contents, the list of
+% figures, and the list of tables, |poetry| provides a list
+% of poems. We use standard \LaTeX\ facilities to produce
+% this list, so they should be pretty familiar to you. The
+% source below can give the nitty-gritty.
+%
+% \DescribeMacro{\listofpoems}Just add |\listofpoems|
+% wherever you want your list of poems to appear. Unlike
+% |\tableofcontents| and the like, |\listofpoems| does
+% \emph{not} start a new chapter or section, change the
+% headings, and so forth; since |poetry| doesn't know what
+% document class you're using, or how you want the list set
+% up, it leaves the details up to you. This is easy enough
+% to elaborate on; for example, to set up the list of poems
+% like an unmarked chapter, like the table of contents:
+%
+% \begin{verbatim}
+% \chapter*{\lopname}
+% \listofpoems
+% \end{verbatim}
+%
+% \DescribeMacro{\lopname}|\lopname| is a macro which simply
+% contains whatever you want the title of the list of poems
+% to be; by default, it is |List of Poems|.
+%
+% |poetry| also provides a little syntactic sugar to make
+% adding entries to the list of poems easier. Rather than
+% doing |\addcontentsline| and the like, simply use
+% \DescribeMacro{\addtolop}|\addtolop|:
+%
+% \begin{center}
+% \cmd{\addtolop} \marg{contents-line}
+% \end{center}
+%
+% This will add an entry to the list of poems in the default
+% style; this is set up much like a normal section entry
+% without indentation. To alter this, redefine
+% \DescribeMacro{\poemlopformat}|\poemlopformat|. By
+% default, this is defined in a very \LaTeX-y way; the
+% standard definition is shown on top below, with a
+% different one underneath it:
+%
+% \begin{quote}
+% |\def\poemlopformat{\@dottedtocline{1}{0em}{2.3em}}|\\
+% |\def\poemlopformat#1#2{\hbox to\linewidth{\textit{#1}\hfill#2}}|
+% \end{quote}
+%
+% You can specify it however you like.
+%
+% There is an equivalent
+% \DescribeMacro{\poemgrouplopformat}|\poemgrouplopformat|,
+% which by default is designed to mimic |\chapter| lines in
+% the standard \LaTeX\ classes. This can be redefined as
+% necessary, too. You add a group to the list of poems by
+% using \DescribeMacro{\addgrouptolop}|\addgrouptolop|,
+% which functions just like |\addtolop| does. So something
+% like this:
+%
+% \begin{quote}
+% |\def\poemgrouplopformat#1#2{\hbox to\linewidth{#1\hfil#2}}|\\
+% |\addgrouptolop{Poem Group Name}|
+% \end{quote}
+%
+% Note that none of our sectioning commands insert
+% themselves into the table of contents or the list of poems
+% by default. If you want this to happen automatically,
+% best to write small wrappers macros around them. E.g.:
+%
+% \begin{verbatim}
+% \def\makenewpoem#1{%
+% \titlepoem{#1}%
+% \addtolop{#1}%
+% }%
+% \end{verbatim}
+%
+%
+% \subsubsection{Index of First Lines}
+% \label{subsub:iofl}
+%
+% Few people remember ``Sonnet 18,'' but many people
+% remember, ``Shall I compare thee to a summer's day?'' For
+% this reason, an index of first lines is an important part
+% of most books of poetry. |poetry| provides facilities to
+% easily create them.
+%
+% |poetry| uses the |imakeidx| package to produce this
+% index, so you can use the options it contains. To run the
+% index, |poetry| uses the following configuration line:
+%
+% \begin{center}
+% |\makeindex[intoc,columns=1,name={\jobname-iofl},title={\poemioflname}]|
+% \end{center}
+%
+% Obviously, you can change this if you need to. This means
+% that, by default, the index will appear in the table of
+% contents (if there is one); the index will be set in one
+% column; the index file name will be |\jobname-iofl|
+% (|\jobname| is a \TeX\ variable that contains the name of
+% your document, without its extension), and the title of
+% the index (what appears on the top of the page) will be
+% the value of the command |\poemioflname|.
+%
+% To change the title that appears at the top of the index,
+% change \DescribeMacro{\poemioflname}|\poemioflname| to
+% whatever you want; e.g., |\def\poemioflname{Index}|.
+%
+% \DescribeMacro{\printiofl}Use |\printiofl| at whatever
+% point in your document you want the index to actually
+% appear.
+%
+% To make entries in the index, you have two options.
+% First, use \DescribeMacro{\poemfirstline}|\poemfirstline|,
+% which takes a single argument, which is the entry you want
+% to appear in the index. This command will \emph{not}
+% typeset its argument in the document, only send it to the
+% index. Second, you can use \DescribeMacro{\iofl}|\iofl|,
+% which also takes a single argument; however, it will not
+% only enter that line into the index, but it will also
+% typeset it in the document. This means that you can wrap
+% the first line of your poem in |\iofl| (\emph{without} the
+% |\\|), and it will put it both in your poem and your
+% index, without you having to type it twice.
+%
+% \section{Implementation}
+% \label{sect:implem}
+%
+% \begin{macrocode}
+\ProvidesPackage{poetry}%
+\RequirePackage{modulus}%
+\newcounter{poemline}%
+\newcount\poemlineno%
+\newcounter{poemrtline}%
+\newcount\poemrtlineno%
+\renewcommand\thepoemrtline{}%
+\newcounter{verseline}%
+\newcount\vslineno%
+\newcounter{stanzacount}%
+\newcount\stanzano%
+\newcounter{abspoemno}%
+\newcount\poem@abspoemno%
+\newcounter{poemno}%
+\newcount\poem@poemno%
+\newcounter{poemgroupno}\setcounter{poemgroupno}{0}%
+\newcount\poem@groupno\poem@groupno=0%
+\newcounter{poemlinenumsevery}\setcounter{poemlinenumsevery}{1}%
+\newcount\poem@linenumsevery\poem@linenumsevery=\value{poemlinenumsevery}%
+\newcounter{poemrtlinenumsevery}\setcounter{poemrtlinenumsevery}{1}%
+\newcount\poem@rt@linenumsevery\poem@rt@linenumsevery=\value{poemrtlinenumsevery}%
+\newlength{\poemindent}\setlength{\poemindent}{0pt}%
+\newlength{\poemtopskip}{\setlength{\poemtopskip}{1em}%
+\newlength{\poembotskip}{\setlength{\poembotskip}{1em}%
+\newdimen\poem@topskip\newdimen\poem@botskip%
+\newdimen\poem@defleftskip\poem@defleftskip=\the\poemindent%
+\newdimen\poem@maxlinewd%
+\newlength{\poemmaxlinewd}\setlength{\poemmaxlinewd}{\textwidth}%
+\newdimen\poem@rt@maxlinewd%
+\newlength{\poemrtmaxlinewd}\setlength{\poemrtmaxlinewd}{\textwidth}%
+\newdimen\poem@hinwd\poem@hinwd=1em%
+\newlength{\poemhinwd}\setlength{\poemhinwd}{1em}%
+\newif\ifpoemlinenums\poemlinenumstrue%
+\newif\ifpoemrtlinenums\poemrtlinenumstrue%
+\def\poemlinenumright{%
+ \renewcommand{\thepoemrtline}{\arabic{poemline}}%
+ \renewcommand{\thepoemline}{}%
+}%
+\def\poemlinenumrighttrue{%
+ \renewcommand{\thepoemrtline}{\arabic{poemline}}%
+ \renewcommand{\thepoemline}{}%
+}%
+\def\poemlinenumrightfalse{%
+ \renewcommand{\thepoemline}{\arabic{poemline}}%
+ \renewcommand{\thepoemrtline}{}%
+}%
+\newdimen\poem@linenumboxwd\poem@linenumboxwd=2em%
+\newlength{\poemlinenumboxwd}\setlength{\poemlinenumboxwd}{2em}%
+\newdimen\poem@rt@linenumboxwd\poem@rt@linenumboxwd=2em%
+\newlength{\poemrtlinenumboxwd}\setlength{\poemrtlinenumboxwd}{2em}%
+\newdimen\poem@linenumboxgap\poem@linenumboxgap=0pt%
+\newlength{\poemlinenumboxgap}\setlength{\poemlinenumboxgap}{0pt}%
+\newdimen\poem@rt@linenumboxgap\poem@rt@linenumboxgap=0pt%
+\newlength{\poemrtlinenumboxgap}\setlength{\poemrtlinenumboxgap}{0pt}%
+\def\poemlinenumstyle{}%
+\def\poemrtlinenumstyle{}%
+\newdimen\poem@hangindent\poem@hangindent=1em%
+\newlength{\poemhangindent}\setlength{\poemhangindent}{1em}%
+\newcount\poem@indentevery\poem@indentevery=0%
+\newcounter{poemindentevery}\setcounter{poemindentevery}{0}%
+\newdimen\poem@verseskip\poem@verseskip=\baselineskip%
+\newlength{\poemverseskip}\setlength{\poemverseskip}{\baselineskip}%
+\newdimen\poem@buff%
+\newcount\poem@tmp%
+% From David Carlisle's answer on tex.stackexchange.com,
+% question 57598; allows us to loop through a string in a
+% command. We will use this for the verse indentation
+% counter, as well as for the generic line indentatin
+% counter and the right indentation counter, both in |\placelineno|.
+\def\loopcommand{\hin}%
+\def\poem@expandvsloop#1{\poem@xvsloop#1\relax}%
+\def\poem@xvsloop#1{%
+ \ifx\relax#1\else%
+ \ifnum#1=\the\vslineno%
+ \loopcommand\relax%
+ \fi%
+ \expandafter\poem@xvsloop%
+ \fi%
+}%
+% from verse.sty
+\newcommand{\poem@ifbang}[1]{\@ifnextchar !{\@firstoftwo{#1}}}
+\newcommand{\poem@ifhyph}[1]{\@ifnextchar -{\@firstoftwo{#1}}}
+\newcommand{\poem@ifstar}[1]{\@ifnextchar *{\@firstoftwo{#1}}}
+\newcommand{\poem@ifques}[1]{\@ifnextchar ?{\@firstoftwo{#1}}}
+\def\poemvsindentlines{}%
+\def\poemnumlines{}%
+\def\poemrtnumlines{}%
+\def\tlap#1{\vbox to0pt{\vss\hbox{#1}}}%
+\def\blap#1{\vbox to0pt{\hbox{#1}\vss}}%
+\def\placelineno{%
+ \setcounter{verseline}{\the\vslineno}%
+ \setcounter{poemline}{\the\poemlineno}%
+ \setcounter{stanzacount}{\the\stanzano}%
+ \setcounter{poemrtline}{\the\poemrtlineno}%
+ \poem@linenumsevery=\value{poemlinenumsevery}%
+ \poem@rt@linenumsevery=\value{poemrtlinenumsevery}%
+ \poem@indentevery=\value{poemindentevery}%
+ \poem@linenumboxgap=\the\poemlinenumboxgap%
+ \poem@linenumboxwd=\the\poemlinenumboxwd%
+ \poem@rt@linenumboxgap=\the\poemrtlinenumboxgap%
+ \poem@rt@linenumboxwd=\the\poemrtlinenumboxwd%
+ \ifpoemlinenums%
+ \def\loopcommand{\poem@putlineno}%
+ \expandafter\poem@expandvsloop\expandafter{\poemnumlines}%
+ \def\loopcommand{\poem@rt@putlineno}%
+ \expandafter\poem@expandvsloop\expandafter{\poemrtnumlines}%
+ \ifnum\poem@linenumsevery=0\relax\else%
+ \modulo{\the\vslineno}{\the\poem@linenumsevery}%
+ \ifnum\remainder=0\poem@putlineno\fi%
+ \fi%
+ \ifnum\poem@rt@linenumsevery=0\relax\else%
+ \modulo{\the\vslineno}{\the\poem@rt@linenumsevery}%
+ \ifnum\remainder=0\poem@rt@putlineno\fi%
+ \fi%
+ \fi%
+ \ifnum\poem@indentevery=0\relax\else%
+ \modulo{\the\vslineno}{\the\poem@indentevery}%
+ \ifnum\remainder=0\hin\fi%
+ \fi%
+ \def\loopcommand{\hin}%
+ \expandafter\poem@expandvsloop\expandafter{\poemvsindentlines}%
+ \def\@currentlabel{\thepoemline}%
+ \phantomsection%
+}%
+\def\poem@putlineno{%
+ \hskip-\poem@linenumboxgap%
+ \llap{%
+ \tlap{%
+ \hbox to\poem@linenumboxwd{%
+ \poemlinenumstyle\thepoemline%
+ \hfil%
+ }\penalty10000%
+ }%
+ }%
+ \ifnum\poemlineno=1\relax\else%
+ \ifnum\vslineno=1%
+ \vskip-\baselineskip%
+ \fi%
+ \fi%
+ \penalty10000%
+}%
+\def\poem@rt@putlineno{%
+ \hskip0pt\tlap{%
+ \rlap{%
+ \hskip\poem@maxlinewd%
+ \hskip\poem@rt@linenumboxgap%
+ \hbox to\poem@rt@linenumboxwd{%
+ \hfil%
+ \poemrtlinenumstyle\thepoemrtline%
+ }%
+ }%
+ }%
+ \vskip-\baselineskip%
+}%
+\def\poem@endline{%
+ \par%
+ \advance\poemlineno by1%
+ \advance\vslineno by1%
+ \poem@defaultpars%
+ \leftskip=\poem@defleftskip%
+ \placelineno%
+}%
+\def\poem@endpart{%
+ \par%
+ \advance\poemlineno by1%
+ \advance\vslineno by1%
+ \poem@defaultpars%
+ \leftskip=\poem@defleftskip%
+}%
+\def\poem@resume{%
+ \placelineno%
+}%
+\def\*{%
+ \poem@resume%
+}%
+\def\poem@endverse{%
+ \par%
+ \vslineno=1%
+ \advance\poemlineno by1%
+ \advance\stanzano by1%
+ \poem@verseskip=\the\poemverseskip%
+ \vskip\poem@verseskip%
+ \leftskip=\poem@defleftskip%
+ \placelineno%
+}
+\def\poem@endversepart{%
+ \par%
+ \advance\poemlineno by1%
+ \vslineno=1%
+ \poem@defaultpars%
+ \leftskip=\poem@defleftskip%
+}
+\def\poem@defaultpars{%
+ \poem@hangindent=\the\poemhangindent%
+ \everypar={%
+ \parindent=0pt%
+ \hangindent=\poem@hangindent%
+ \hangafter=1%
+ }%
+}%
+\def\hin{%
+ \poem@hinwd=\the\poemhinwd%
+ \advance\leftskip by\the\poem@hinwd%
+ \penalty10000%
+}%
+\def\poemnew{%
+ \advance\poem@poemno by1\stepcounter{poemno}%
+ \advance\poem@abspoemno by1\stepcounter{abspoemno}%
+}%
+\def\poem{%
+ \widowpenalty=0\clubpenalty=0%
+ \def\\{%
+ \poem@ifbang{\poem@endverse}{%
+ \poem@ifhyph{\par\vskip\poem@botskip\relax}{%
+ \poem@ifstar{\poem@endpart}{%
+ \poem@ifques{\poem@endversepart}{\poem@endline}%
+ }%
+ }%
+ }%
+ }%
+ \poem@defleftskip=\the\poemindent%
+ \leftskip=\poem@defleftskip%
+ \poem@maxlinewd=\the\poemmaxlinewd%
+ \hsize=\the\poem@defleftskip%
+ \advance\hsize by\the\poem@maxlinewd%
+ \poemlineno=1%
+ \vslineno=1%
+ \stanzano=1%
+ \poem@topskip=\the\poemtopskip%
+ \poem@botskip=\the\poembotskip%
+ \vskip\poem@topskip%
+ \poem@defaultpars%
+ \noindent%
+ \poem@ifstar{}{\placelineno}%
+}%
+\def\endpoem{%
+}%
+\newdimen\poem@centlinewd
+\def\centerpoemon#1{%
+ \settowidth{\poem@centlinewd}{#1}%
+ \ifdim\poem@centlinewd>\linewidth\poem@defleftskip=0pt%
+ \else
+ \poem@buff=\linewidth%
+ \advance\poem@buff by-\poem@centlinewd%
+ \divide\poem@buff by2%
+ \poem@defleftskip=\the\poem@buff%
+ \poemindent=\the\poem@buff%
+ \poem@maxlinewd=\the\poem@centlinewd%
+ \setlength{\poemmaxlinewd}{\poem@maxlinewd}%
+ \fi
+}%
+\def\centerpoemoff{%
+ \poem@defleftskip=0pt\setlength{\poemindent}{0pt}%
+ \poem@maxlinewd=\the\linewidth%
+ \setlength{\poemmaxlinewd}{\linewidth}%
+}%
+% \end{macrocode}
+% Define a few variables for document metadata.
+% \begin{macrocode}
+\def\thepoemtitle{\poemblanktitle}%
+\def\thepoemauthor{\poemblankauthor}%
+\def\thepoemlicense{Public Domain}%
+\def\poemdefaultlicense{Public Domain}%
+\def\thepoempubdate{\today}%
+% \end{macrocode}
+% Here we begin the structural code; which, of course, uses
+% a lot of the code above, particularly the counters.
+% First, let's give folks a way to title their poems. But
+% even before that, we need to define some more commands to
+% help people style them.
+% \begin{macrocode}
+\def\poemblanktitle{Untitled}%
+\def\poemblankauthor{Anonymous}%
+\def\poemtitlestyle{\LARGE\bfseries}%
+\def\poemauthorstyle{\Large}%
+\def\poemtitleprehook{%
+ \begin{center}%
+}%
+\def\poemtitleposthook{%
+ \end{center}%
+}%
+\def\poemauthorprehook{%
+ \begin{center}%
+}%
+\def\poemauthorposthook{%
+ \end{center}%
+}%
+% \end{macrocode}
+% Specifically, one for titles with no authors:
+% \begin{macrocode}
+\def\titlepoem#1{%
+ \advance\poem@poemno by1\stepcounter{poemno}%
+ \advance\poem@abspoemno by1\stepcounter{abspoemno}%
+ \def\thepoemtitle{#1}\def\thepoemauthor{\poemblankauthor}%
+ \begingroup%
+ \poemtitleprehook%
+ \poemtitlestyle #1%
+ \poemtitleposthook%
+ \endgroup%
+}%
+% \end{macrocode}
+% Next, one for titles and authors:
+% \begin{macrocode}
+\def\titleauthorpoem#1#2{%
+ \advance\poem@poemno by1\stepcounter{poemno}%
+ \advance\poem@abspoemno by1\stepcounter{abspoemno}%
+ \def\thepoemtitle{#1}\def\thepoemauthor{#2}%
+ \begingroup%
+ \poemtitleprehook%
+ \poemtitlestyle #1%
+ \poemtitleposthook%
+ \endgroup%
+ \begingroup%
+ \poemauthorprehook%
+ \poemauthorstyle #2%
+ \poemauthorposthook%
+ \endgroup%
+}%
+% \end{macrocode}
+% Now we define the poem group commands. These are pretty
+% simple, essentially just resetting various variables to
+% sensible values. We have the |\endpoemgroup| command here
+% just to allow people to use them as environments, if they
+% want.
+% \begin{macrocode}
+\def\poemgroup{%
+ \advance\poem@groupno by1%
+ \stepcounter{poemgroupno}%
+ \poem@poemno=0\setcounter{poemno}{0}%
+ \def\thepoemgroupname{\poemgroupblankname}%
+}%
+\def\endpoemgroup{%
+}%
+\def\poemgrouptitleprehook{}%
+\def\poemgrouptitleposthook{}%
+\def\poemgroupotherprehook{}%
+\def\poemgroupotherposthook{}%
+\def\poemgrouptitlestyle{\Huge}%
+\def\poemgroupotherstyle{\LARGE}%
+\def\poemgroupblankname{Untitled Group}%
+\def\poemgroupname{\poemgroupblankname}%
+\def\poemgroupheading#1#2{%
+ \def\thepoemgroupname{#1}%
+ \begingroup%
+ \poemgrouptitleprehook%
+ \poemgrouptitlestyle #1%
+ \poemgrouptitleposthook%
+ \endgroup%
+ \begingroup%
+ \poemgroupotherprehook%
+ \poemgroupotherstyle #2%
+ \poemgroupotherposthook%
+ \endgroup%
+}%
+% \end{macrocode}
+% Now let's define the necessary commands for the list of
+% poems. (\emph{Not} the index of first lines, yet.)
+% \begin{macrocode}
+\def\poemlopformat{%
+ \@dottedtocline{1}{0em}{2.3em}%
+}%
+\def\l@poem{\poemlopformat}%
+\def\addtolop#1{%
+ \addcontentsline{lop}{poem}{#1}%
+}%
+\def\addgrouptolop#1{%
+ \addcontentsline{lop}{poemgroup}{#1}%
+}%
+\def\lopname{List of Poems}%
+\def\listofpoems{%
+ \@starttoc{lop}%
+}%
+\def\poemgrouplopformat#1#2{%
+ \ifnum \c@tocdepth >\m@ne
+ \addpenalty{-\@highpenalty}%
+ \vskip 1.0em \@plus\p@
+ \setlength\@tempdima{1.5em}%
+ \begingroup
+ \parindent \z@ \rightskip \@pnumwidth
+ \parfillskip -\@pnumwidth
+ \leavevmode \bfseries
+ \advance\leftskip\@tempdima
+ \hskip -\leftskip
+ #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
+ \penalty\@highpenalty
+ \endgroup
+ \fi%
+}%
+\def\l@poemgroup{\poemgrouplopformat}%
+% \end{macrocode}
+% Do some magic to ensure that the package works even if
+% |hyperref| isn't loaded.
+% \begin{macrocode}
+ \ifcsname phantomsection\endcsname%
+ \else%
+ \def\phantomsection{\relax}%
+ \fi%
+% \end{macrocode}
+% Now let's set up the index of first lines. We use the
+% |imakeidx| package for this, so as not to interfere with
+% any existing indices.
+% \begin{macrocode}
+\RequirePackage{imakeidx}
+\makeindex[intoc,columns=1,name={\jobname-iofl},title={\poemioflname}]
+\def\poemioflname{Index of First Lines}%
+\def\poemfirstline#1{%
+ \index[\jobname-iofl]{#1}%
+}%
+\def\iofl#1{%
+ \index[\jobname-iofl]{#1}%
+ #1%
+}%
+\def\printiofl{%
+ \printindex[\jobname-iofl]%
+}%
+% \end{macrocode}
+% \listofpoems
+% \PrintIndex
diff --git a/macros/latex/contrib/poetry/poetry.ins b/macros/latex/contrib/poetry/poetry.ins
new file mode 100644
index 0000000000..ecc4db043f
--- /dev/null
+++ b/macros/latex/contrib/poetry/poetry.ins
@@ -0,0 +1,64 @@
+% +AMDG This document was begun on 3 June 1201, and it is
+% humbly dedicated to St. Francis de Sales, St. John the
+% Apostle, and the Immaculate Heart of Mary, for their
+% prayers, and to the Sacred Heart of Jesus, for His mercy.
+%
+% This document is copyright 2019 by Donald P. Goodman, and is
+% released publicly under the LaTeX Project Public License. The
+% distribution and modification of this work is constrained by the
+% conditions of that license. See
+% http://www.latex-project.org/lppl.txt
+% for the text of the license. This document is released
+% under version 1.3c of that license, and this work may be distributed
+% or modified under the terms of that license or, at your option, any
+% later version.
+%
+% This work has the LPPL maintenance status 'maintained'.
+%
+% The Current Maintainer of this work is Donald P. Goodman
+% (dgoodmaniii@gmail.com).
+%
+% This work consists of poetry.dtx, poetry.ins, and
+% derived files poetry.sty and poetry.pdf.
+
+\input docstrip.tex
+
+\preamble
+This is a generated file.
+
+This document is copyright 2014 by Donald P. Goodman, and is
+released publicly under the LaTeX Project Public License. The
+distribution and modification of this work is constrained by the
+conditions of that license. See
+ http://www.latex-project.org/lppl.txt
+for the text of the license. This document is released
+under version 1.3c of that license, and this work may be distributed
+or modified under the terms of that license or, at your option, any
+later version.
+
+This work has the LPPL maintenance status 'maintained'.
+
+The Current Maintainer of this work is Donald P. Goodman
+(dgoodmaniii@gmail.com).
+
+This work consists of poetry.dtx, poetry.ins, and
+derived files poetry.sty and poetry.pdf.
+\endpreamble
+
+\keepsilent
+\generate{\file{poetry.sty}{\from{poetry.dtx}{package}}}
+
+\Msg{******************************************************}
+\Msg{*}
+\Msg{* To finish the installation you have to move the}
+\Msg{* following file into a directory searched by TeX:}
+\Msg{*}
+\Msg{* \space\space poetry.sty}
+\Msg{*}
+\Msg{* To produce the documentation run the file poetry.dtx}
+\Msg{* through LaTeX.}
+\Msg{*}
+\Msg{* Happy TeXing!}
+\Msg{******************************************************}
+
+\endbatchfile
diff --git a/macros/latex/contrib/poetry/poetry.pdf b/macros/latex/contrib/poetry/poetry.pdf
new file mode 100644
index 0000000000..f22f9cee84
--- /dev/null
+++ b/macros/latex/contrib/poetry/poetry.pdf
Binary files differ