poemscol (21dec17)

git-svn-id: svn://tug.org/texlive/trunk@46113 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 892 insertions, 329 deletions

diff --git a/Master/texmf-dist/doc/latex/poemscol/poemscol.pdf b/Master/texmf-dist/doc/latex/poemscol/poemscol.pdf
index 442a6a64df5..e6dc7355805 100644
--- a/Master/texmf-dist/doc/latex/poemscol/poemscol.pdf
+++ b/Master/texmf-dist/doc/latex/poemscol/poemscol.pdf
diff --git a/Master/texmf-dist/source/latex/poemscol/poemscol.dtx b/Master/texmf-dist/source/latex/poemscol/poemscol.dtx
index 0ca30b17bf8..790ed06fa10 100644
--- a/Master/texmf-dist/source/latex/poemscol/poemscol.dtx
+++ b/Master/texmf-dist/source/latex/poemscol/poemscol.dtx
@@ -19,7 +19,7 @@
 % \iffalse
 %<package>\NeedsTeXFormat{LaTeX2e}[1997/12/01]
 %<package>\ProvidesPackage{poemscol}
-%<package>   [2017/11/30 v2.9 poemscol file] 
+%<package>   [2017/12/20 v2.95 poemscol file] 
 %
 %<*driver>
 \documentclass{ltxdoc}
@@ -33,7 +33,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{8158}
+% \CheckSum{8443}
 %
 % \CharacterTable
 %  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -225,6 +225,10 @@
 % \changes{v2.88}{2017/10/29}{Revisions to manual.}
 % \changes{v2.89}{2017/11/30}{Append the date to the end of the poem.}
 % \changes{v2.9}{2017/12/02}{Date aligns with left margin of poem even when poem is centered.}
+% \changes{v2.95}{2017/12/20}{Long poems can put firstline---lastline in running header. 
+% Revisions to manual. Textual notes, emendation notes, and explanatory notes can also be 
+% placed at the end of the poem rather than at the bottom of the page or in an endnote section.
+% Commands to set the title only in the contents and only in the notes.}
 % \DoNotIndex{\newcommand,\newenvironment,\def,\edef,\else,\renewcommand,\makeatletter,\makeatother}
 % \DoNotIndex{\abovedisplayskip,\belowdisplayskip,\abovedisplayshortskip,\belowdisplayshortskip}
 % \DoNotIndex{\newcommand, \section, \subsection, \subsubsection,
@@ -257,15 +261,15 @@
 % \textsc, \unskip} 
 % \setcounter{IndexColumns}{2} 
 % \MakeShortVerb{|}
-% \def\fileversion{2.9} 
-% \def\filedate{2 December 2017} 
-% \def\docdate{2 December 2017}
+% \def\fileversion{2.95} 
+% \def\filedate{20 December 2017} 
+% \def\docdate{20 December 2017}
 %  \title{Typesetting Poetry Collections with
 % \textsf{poemscol}\thanks{This document corresponds to
 % \textsf{poemscol}~\fileversion, dated \filedate.}} 
 % \author{John Burt
 % \\ \texttt{burt@brandeis.edu}} 
-% \date{2 December 2017} 
+% \date{20 December 2017} 
 % \maketitle
 % \begin{abstract} \textsf{poemscol} provides macros for \LaTeX\ for
 % setting collections of poetry.  It is especially suited for setting
@@ -281,14 +285,9 @@
 % critical edition of a volume of poems or of a collection of a poet's
 % works.  \textsf{poemscol} numbers the lines, and produces separate,
 % formatted endnote sections for emendations, textual collations, and
-% explanatory notes (or, optionally, multi-layered footnotes), tying
-% each note to the number of the line upon which it is a comment.  It
-% also automatically generates a table of contents, an index of titles
-% and first lines, and divider pages for the sections of the volumes.
-% It produces running headers of the form ``Emendations to pp.~xx-yy''
-% for the note sections.  And it marks occasions when a stanza break
-% falls at a page break.
-% 
+% explanatory notes (or, optionally, multiple layers of footnotes), tying
+% each note to the range of lines upon which it is a comment.  
+%
 % Producing line numbers for verse is something for which \LaTeX\
 % would seem to be especially suited.  A line of verse, after all, is
 % not a carriage return but a logical unit, an element of
@@ -301,6 +300,18 @@
 % note, emendation, or explanatory note with the range of line 
 % numbers to which it applies. 
 %
+% Editions of Collected Poetry might also require special structures
+% to reflect the fact that they are made up of the contents of several
+% volumes of poetry.  In particular, such editions require 
+% facilities for setting up specially formatted divider pages between
+% volumes. They also require tables of contents and other front matter, as well
+% as an index of titles and first lines (or, optionally, several separate indices)
+% and other sorts of back matter.
+% \textsf{poemscol} automatically generates a table of contents, an index of titles
+% and first lines, and divider pages for the sections of the volumes.
+% It produces running headers of the form ``Emendations to pp.~xx-yy''
+% for the note sections.  
+%
 % In poetry which does not have a regular stanzaic form, it is useful
 % to be able to mark automatically occasions where there is a stanza
 % break at the bottom of a page which the reader might not notice. 
@@ -311,13 +322,64 @@
 % process, so that the editor need never worry about it, automatically
 % marking cases where the page break coincides with a stanza break
 % with a symbol. 
+%  
+% \textsf{poemscol} includes facilities for typesetting parallel text editions
+% of poems, for instance to compare different versions or translations of the same poem
+% on the recto and verso pages. \textsf{poemscol} will keep the line 
+% numbering of the two texts separate, will provide separate endnote sections
+% for textual notes, emendations, and explanatory notes for the different texts,
+% and will also make marginal markers to tie lines in the verso text to the 
+% equivalent line in the recto text. 
 % 
-% Editions of Collected Poetry might also require special structures
-% to reflect the fact that they are made up of the contents of several
-% volumes of poetry.  In particular, such editions require special
-% structures for setting up specially formatted divider pages between
-% volumes. They also require tables of contents and other front matter. 
-% \textsf{poemscol} provides these structures.
+% \textsf{poemscol} is also suited for verse drama, and the package
+% \textsf{dramatist} has been modified to work with \textsf{poemscol}.
+%
+% \textsf{poemscol} can provide line numbers and notes for prose
+% sections such as the author's introduction or prose poetry. (It
+% can also handle inset prose passages in the midst of verse, pausing and 
+% restarting verse line numbering as the editor desires.)
+%  It also has some limited facilities for typesetting and annotating 
+% line-numbered parallel passages in prose.
+% \textsf{poemscol} is not, however, designed for typesetting critical editions of large
+% scale prose works, although very possibly it could be tweaked to 
+% work.  For critical editions of prose works, several
+% other packages are available, including the \texttt{EDMAC} format, a
+% \TeX\ format analogous to but distinct from \LaTeX, by John
+% Lavagnino and Dominik Wujastyk, or \textsf{ledmac}, a port of
+% \texttt{EDMAC} into \LaTeX\  originally by Peter Wilson and
+% now maintained  as \textsf{reledmac} by Ma\"{\i}eul Rouquette, or \textsf{ednotes}, a
+% completely independent set of macros for critical editions which
+% builds on \textsf{manypar} and \textsf{lineno}, by Uwe L\"{u}ck.
+%
+% \textsf{poemscol} can annotate prose marked in ``paragraph number: sentence number''
+% format (or bible chapter and verse).
+% 
+% \textsf{poemscol} also provides 
+% the ability to make cross references to verse line numbers, to line numbers in prose sections,
+% or to paragraph and sentence numbers in sections with ``paragraph and sentence'' annotation.
+% 
+% \textsf{poemscol} also provides a few bells and whistles, such as the ability
+% to create new endnote or footnote sections on the fly, the ability
+% to center a poem on the longest line (or to move the margin of the
+% verse block wherever you wish), and the ability to place a mark in the margin
+% indicating where in the apparatus commentary on that line can be found.
+% For long poems,  \textsf{poemscol} can provide a
+% a special running header which indicates which lines are to be
+% found on the page. 
+% It has a special command to place 
+% the publication date under the poem just at the left margin of the verse block even
+% when the verse block is centered.
+% \textsf{poemscol} also provides notes
+% to be placed just after a poem (rather than at the bottom of the page 
+% or in the endnote sections). It gives the user 
+% fine control over the placement of line numbers and the placement and format of titles
+% including multi-line titles.
+% The user can choose whether to concatenate the notes for a poem into a single paragraph,
+% or to give each note a separate paragraph. The user can print the notes
+% in single or multicolumn format. The names of things like the Contents can
+% be changed to facilitate editions in languages other than English.
+% Just about every feature of \textsf{poemscol} can be 
+% easily customized.
 % 
 % The best features of \textsf{poemscol} are of course simply that it 
 % is \TeX: it uses \TeX's automatic kerning and setting of ligatures, 
@@ -326,7 +388,7 @@
 % 
 % Using \LaTeX\ to typeset critical editions offers more advantages
 % than simply the ability to automate tedious and easy to fumble
-% tasks.  Modern \TeX\ compilers have the ability to produce
+% tasks.  \TeX\ compilers have the ability to produce
 % output in Adobe pdf format.  Adobe pdf output can be used as camera
 % ready copy, saving your publisher time and expense, and perhaps
 % making a marginally economic critical edition a bit easier to bring
@@ -343,10 +405,11 @@
 % sources for your edition are in ASCII, or perhaps Unicode, they provide a permanent
 % record of your local intentions at every point in your edition,
 % whether or not those who wish to consult your files have access to a
-% \LaTeX\ compiler, or indeed whether or not they can read \LaTeX\
+% \LaTeX\ compiler, or indeed (since most of the macros have self-explanatory names) 
+% whether or not they can read \LaTeX\
 % code.
 %
-% Finally, although \LaTeX\ is a typesetting language, not a content
+% Although \LaTeX\ is a typesetting language, not a content
 % markup language, the ability to create new commands which the
 % language offers comes very close to enabling one to realize the
 % ideal of completely separating content markup from formatting.  One
@@ -359,23 +422,7 @@
 % would largely (although not entirely) be a matter of performing a
 % series of global search-and-replaces, and could conceivably be done
 % with a perl script.
-% 
-% \textsf{poemscol} is also suited for verse drama, and the package
-% \textsf{dramatist} has been modified to work with \textsf{poemscol}.
-% \textsf{poemscol} can provide line numbers and notes for prose
-% sections such as the author's introduction or prose poetry, and it
-% can also handle inset prose passages in the midst of verse.
-% \textsf{poemscol} is not, however, designed for typesetting large
-% scale prose works, although very possibly it could be tweaked to 
-% work.  For critical editions of prose works, several
-% other packages are available, including the \texttt{EDMAC} format, a
-% \TeX\ format analogous to but distinct from \LaTeX, by John
-% Lavagnino and Dominik Wujastyk, or \textsf{ledmac}, a port of
-% \texttt{EDMAC} into \LaTeX\  originally by Peter Wilson and
-% now maintained  as \textsf{eledmac} by Ma\"{\i}eul Rouquette, or \textsf{ednotes}, a
-% completely independent set of macros for critical editions which
-% builds on \textsf{manypar} and \textsf{lineno}, by Uwe L\"{u}ck.
-% 
+%
 % \section{Dependencies and compatibility with other packages}
 %
 %\subsection{~General}
@@ -385,15 +432,6 @@
 % and \textsf{multicol} for managing the index, \textsf{geometry}, and
 % \textsf{ifthen} and \textsf{keyval} to simplify page geometry. 
 %
-%  If
-% you are using the |\JHpoemtitle| alternate form of the |\poemtitle|
-% command, you need to add \textsf{mparhack} to your package list, to
-% make sure that the marginal references |\JHpoemtitle| adds appear on
-% the correct side of the page.  You should make sure that
-% \textsf{poemscol} is the very last package you load in your
-% preamble, or at least is loaded after those packages upon which it
-% depends.
-% 
 % If you are planning to generate multiple indices, substitute 
 % \textsf{splitindex} for \textsf{makeidx} in your list of packages.
 % 
@@ -433,6 +471,15 @@
 % that there is no room for a |\newcount|. If this happens, 
 % issue |\usepackage{etex}| and |\reserveinserts|.
 %
+% \subsection{~Special running header for long poems}
+% For long poems, it is a convenience to have a running header 
+% that includes information about what lines of the poem appear
+% on that page in the form firstline--lastline. The fancypagestyle |longpoem|
+% will set that information in the running header.  That page style
+% uses the |\marks| mechanism, and requires more |\marks| than
+% are available by default. To use it, you will need to add the \textsf{etex} and 
+% \textsf{emarks} packages to your preamble. 
+%
 % \subsection{~Verse drama and \textsf{dramatist}}
 % Massimiliano Dominici has made his \textsf{dramatist} package
 % compatible with \textsf{poemscol}, for which I am very grateful. 
@@ -440,24 +487,38 @@
 % versions 2.3 or later of \textsf{poemscol}. 
 %
 %
-% \subsection{~Parallel text editions} If you are using the |\keeptitlestraight|
-% hack described below  at \ref{parallelhack}, you should add \textsf{etoolbox}
-% to your package list. If you are using the six pre-defined endnote sections
+% \subsection{~Parallel text editions} 
+% \begin{sloppypar}
+% If you are using the six pre-defined endnote sections
 % for parallel text editions (|\rectotexnote|, |\versotextnote|, |\rectoemendation|, |\versoemendation|,
 % |\rectoexplanatory|, |\versoexplanatory| and their prose equivalents |\rectoprosetextnote|
-% and so on) you do not need to use this hack. You only need to use this hack if 
-% you are defining your own endnote sections using |\definenewnotetype|. 
+% and so on) you won't need to add any new packages. If  
+% you are defining your own endnote sections using |\definenewnotetype| you may need
+% the |\keeptitlestraight| hack described below  at section \ref{parallelhack}, 
+% page \pageref{parallelhack}. If you use |\keeptitlesstraight| you should add \textsf{etoolbox}
+% to your package list.\end{sloppypar}
 % 
 % \subsection{~Crop marks}
 % \textsf{poemscol} no longer provides cropmarks, but is compatible with 
 % the style packages that do. I use \textsf{crop}, with the 
 % letter,pdftex,cam, and center options.
 %
+% \subsection{~Poem titles with marginal references}
+%  If
+% you are using the |\JHpoemtitle| alternate form of the |\poemtitle|
+% command, you need to add \textsf{mparhack} to your package list, to
+% make sure that the marginal references |\JHpoemtitle| adds appear on
+% the correct side of the page.  You should make sure that
+% \textsf{poemscol} is the very last package you load in your
+% preamble, or at least is loaded after those packages upon which it
+% depends.
+% 
+%
 %
 % \subsection{~Incompatibility with \textsf{memoir} and \textsf{verse}}
 % Unfortunately, \textsf{poemscol} is not compatible with the
 % \textsf{memoir} class and the \textsf{verse} package, because they
-% share some command names. I am preparing a workaround for this 
+% share some command names. I will eventually prepare a workaround for this 
 % problem. 
 %
 % \subsection{~Conflict with \textsf{BibLaTeX} }
@@ -530,15 +591,17 @@
 % page breaks between the title and the poem. But for the first
 % section of a poetic sequence, or the first section of a poem in
 % sections, one does not want to encourage \LaTeX\ to break the page 
-% before the title, since that would leave the title of the sequence
-% or the title of the larger poem as a widow on the previous page.
+% before the section title, since that would leave the title of the sequence
+% or the title of the larger poem as an orphan on the previous page.
 % |\sequencefirstsectiontitle| and its siblings are designed for this 
 % situation. Although all commands like |\sequencefirstsectiontitle| 
 % discourage page breaks before the title (and all of the commands
-% discourage page breaks after the title), they will still sometimes 
+% discourage page breaks after the title), widowed or orphaned titles,
+% and widowed or orphaned first lines will still sometimes 
 % happen, particularly if you have a multi-line sequence title
-% followed by a multi-line section title. For these cases, page
-% breaks will have to be explicitly issued.
+% followed by a multi-line section title. For these cases, a page
+% break at some other suitable point will have to be explicitly issued to
+% move widowed or orphaned lines to better places.
 % 
 % \subsection{~The title of the poem}
 % 
@@ -552,7 +615,8 @@
 % (with the page number), typesets the title in the textual notes
 % (adding the page number, and checking to see whether there is room
 % enough on the page), and prepares similar entries in the lists of
-% emendations and in the explanatory notes (if you need them).
+% emendations and in the explanatory notes (if you need them)
+% as well as in the endnote sections for any species of endnote you have defined for yourself.
 % \textsf{poemscol} gives default values for
 % such things as the font size, the separation between the top of the
 % title and the bottom of the previous poem, the separation between
@@ -575,9 +639,9 @@
 % If you don't want the entry in the notes section for this poem to include
 % the page number of the poem, issue |\putpagenumberinnotesfalse|. A
 % complete list of all of the special commands for setting font sizes,
-% skips, and penalties, is in section \ref{changingfontsandleading} below.
+% skips, and penalties, is in section \ref{changingfontsandleading}, page 
+% \pageref{changingfontsandleading}, below.
 % 
-
 % Multiple line titles (if it matters how they are broken up on page), 
 % titles of subsections of poems, titles of
 % sequences of poems, and titles of the elements of a sequence of
@@ -608,8 +672,16 @@
 % environment from the standard \LaTeX\ definition, increasing the
 % indentation used for run over lines, in order to make the difference
 % between the indented run over portion of a long line, on one hand,
-% and an explicitly indented second line, more obvious in the output.
+% and an explicitly indented second line, on the other, more obvious in the output.
+% \textsf{poemscol}  also adds a little bit
+% more white space between stanzas than the standard \LaTeX\ |verse|
+% environment does.  (I found that the standard stanza breaks did not
+% leap out on the page as stanza breaks.) 
+% The verse environment for \textsf{poemscol} is pmclverse, defined
+% below on page \pageref{versedefine}. If you want to change any of these things
+% consult the definition of the stanza environment below at page \pageref{stanzadefine}.
 %
+% \DescribeMacro{\versewidth} 
 % The |poem| environment takes an optional argument. If your poem has 
 % short lines, and you wish to center it on the page, rather than set 
 % it against the left margin of the normal |poem| environment, you can 
@@ -617,11 +689,12 @@
 % argument. Alternatively, the length |\versewidth| can be used as the 
 % argument. You can set the length of |\versewidth| to the proper 
 % amount using |\settowidth| as follows:
-% \DescribeMacro{\versewidth} \label{centeringtextblock}
+% \label{centeringtextblock}
 % |\settowidth{\versewidth}{Text of line to use for centering}|. To use |\versewidth|
 % to center the poem on a sample line, enter the |poem| environment this way:
 % |\begin{poem}[\versewidth]|.
 %
+% \DescribeMacro{\linenumberscenteredwithverse} 
 % If you center the verse on the page using this option, you probably also want 
 % to move the line numbers in, so as to be closer to the line. 
 % \textsf{poemscol} will do this by default. If you wish to leave the line 
@@ -639,7 +712,7 @@
 % \DescribeMacro{iftextcenteringturnedon} Suppose you have marked up poems with 
 % the optional second argument to |\begin{poem}| which would cause the text 
 % block to be centered on the longest line. You can turn off centering, without 
-% erasing all of the second arguments, by issuing |\textcenteringturnonfalse|. 
+% erasing all of the second arguments, by issuing |\textcenteringturnedonfalse|. 
 % You can turn on centering the text block again by issuing 
 % |\textcenteringturnedontrue|.
 %
@@ -679,11 +752,6 @@
 % marking the beginning and end of every stanza makes the logical
 % structure of the poem (and the editor's intentions about it) clear
 % to readers of your source code.  
-%
-% \textsf{poemscol} adds a little bit
-% more white space between stanzas than the standard \LaTeX\ |verse|
-% environment does.  (I found that the standard stanza breaks did not
-% leap out on the page as stanza breaks.)
 % 
 % \DescribeMacro{\stanzaatbottom}
 % \DescribeMacro{\nostanzaatbottom}
@@ -754,6 +822,7 @@
 % |\pmclsideparvshift|. The default value is
 % |\setlength{\pmclsideparvshift}{0ex}|. 
 %
+% % \DescribeMacro{\versemarginadjust} 
 % You can adjust the placement of the verse block by changing the value of the 
 % length |\versemarginadjust|. For most commonly used type sizes, setting 
 % |\versemarginadjust| to 28pts will put the verse block at the left margin.
@@ -932,20 +1001,28 @@
 % \section{Making a table of contents}
 % \subsection{~Setup}
 % \DescribeMacro{\makepoemcontents} 
-% I found the normal \LaTeX\ macros for making tables of contents
-% unsuited to poetry, so I have provided my own.  To make a table of
+% I found the normal \LaTeX\ macros for making tables of contents for scholarly works
+% unsuited for making tables of contents of poetry, so I have provided my own.  To make a table of
 % contents for your poems, issue |\makepoemcontents|.  It might seem
 % as though you would want to issue this command in your preamble.  In
-% fact it is better, for reasons explained below, to issue it
-% immediately after issuing the |\putpoemcontents|, the command which
-% inputs and typesets a table of contents from a prior run.
+% fact it is better to issue it in the body of the document,
+% immediately \emph{after} issuing the |\putpoemcontents|, the command which
+% inputs and typesets a table of contents from a prior run. If you issue |\makepoemcontents|
+% before issuing |\putpoemcontents|, you will simply erase the table of contents
+% from the prior run (the one which will have all the contents information you
+% are intending to use) and enter an empty table of contents into your document.
 % Information for your table of contents will be written to an
-% external file with the extension .ctn.  You may need to run your
+% external file with the extension .ctn. |\makepoemcontents| creates this file, and 
+% opens an output channel to send information to it. |\putpoemcontents| closes
+% the file and reads it into your document. You will need to run your
 % book through \LaTeX\ twice in order to generate a table of contents,
-% the first time to generate the correct page numbers, and the second
-% time to set the table of contents.  (Under some circumstances --- if
+% the first time to generate the titles and the references for the page numbers, and the second
+% time to use the labels to which the references point
+% to enter the page numbers.  (Under some circumstances --- if
 % you have an index, for instance --- you may need three passes rather
-% than two.)  |\makepoemcontents| takes an optional argument, which
+% than two.)  
+
+% |\makepoemcontents| takes an optional argument, which
 % sets the page number for the table of contents.  If your publisher
 % wishes to add some front matter so that the contents will appear on
 % page vii, you should issue |\makepoemcontents{7}|.
@@ -957,14 +1034,14 @@
 % volume title, a poem title, or something else), then the title
 % itself.  If the entry is for a poem, for a section of a poem, or for
 % a section of a poetic sequence, a slash follows the title, followed
-% by the page number.  If you wish to give \emph{all} your entries a
-% different look altogether, modify the |\c@ntentsinfo| macro below
-% (see section \ref{poemtitlecode}, page \pageref{poemtitlecode}).  To
+% by the page number.  To
 % change the appearance of a \emph{particular} kind of entry (for all
 % sequences of poems, for instance), go to the definition of the title
 % of that kind of entry (e.g. |\sequencetitle|) below, find the line
 % where it calls the |\c@ntentsinfo| macro, and change the arguments
-% to that macro to suit you.
+% to that macro to suit you. If you wish to give \emph{all} your entries a
+% different look altogether, modify the |\c@ntentsinfo| macro below
+% (see section \ref{poemtitlecode}, page \pageref{poemtitlecode}).  
 %
 %\DescribeMacro{\setcontentsleaders} By default the title and the page 
 % are separated by a slash (actually by |~/~|). If you wish to change 
@@ -972,17 +1049,22 @@
 % as the argument to |\setcontentsleaders|, as for instance 
 % |\setcontentsleaders{\poemdotfill}|, which will flush the number to 
 % the right margin, and insert leading dots up to the number.
+% The argument to |\setcontentsleaders| can be whatever you wish
+% to use to separate the title from the page number, such as a colon,
+% a hard space (|~|), or even |\hfil| to flush the page number to the left margin.
 % 
 % \DescribeMacro{\putpoemcontents}\label{putpoemcontents} 
 % |\putpoemcontents| will input the table of contents file if it
 % exists, and complain on your log file if it does not.  Because the
 % table of contents uses a special page style and special fonts
 % |\putpoemcontents| restores the default fancy page style once it has
-% input the contents, and restores |\normalfont| as well.  Be sure to
+% input the contents, and restores |\normalfont| as well.  
+%
+% Be sure to
 % reset the style of page numbering (from |\pagenumbering{roman}| to
 % |\pagenumbering{arabic}|) after issuing |\putpoemcontents|, since
 % when you read in the external file created by |\makepoemcontents|
-% the page numbering will be set to roman.  The command
+% the page numbering will be set to roman numerals.  The command
 % |\resetpagestyle| (which is called by |\putpoemcontents|) will reset
 % the fancy page style to that used in the main body of the volume,
 % but it won't change the page numbering to arabic, in case there is
@@ -996,13 +1078,6 @@
 % recognize them as numbers, and you will get the infamous ``Missing
 % Number'' error that puzzles so many users of \LaTeX.
 % 
-% Because |\putpoemcontents| uses the table of contents file from a
-% prior run, you should issue |\putpoemcontents| \emph{before} issuing
-% |\makepoemcontents|.  That sounds counterintuitive.  But remember
-% that |\putpoemcontents| will read in the contents file you made on a
-% previous run, and |\makepoemcontents| will over-write that file and
-% start a new one.  You should issue |\makepoemcontents| just
-% \emph{after} issuing |\putpoemcontents|.
 % 
 % \subsection{~Contents entries for notes sections and the index}
 %
@@ -1010,21 +1085,23 @@
 % \DescribeMacro{\putemendations}
 % \DescribeMacro{\putexplanatory} 
 % |\puttextnotes|, and its siblings |\putemendations| and
-% |\putexplanatory|, input the formatted notes
-% sections, and put entries for them into your table of contents.  
-% You will have to run \LaTeX\ again to set the
-% table of contents properly.  The first run sets a label to find the
+% |\putexplanatory|, input the formatted endnotes
+% sections into your document, and put entries for them into your table of contents.  
+% You will have to run \LaTeX\ again to set the page numbers of those sections
+% in the 
+% table of contents properly.  The first run sets the title of the endnotes section and a label to find the
 % page number to add to the table of contents, and the second run
-% actually sets the table of contents.  (These commands are described
+% actually sets page number.  (These commands are described
 % below, in section \ref{putexternalfiles}.)  All of these commands
-% also restore normal hyphenation.  \end{sloppypar}
+% also restore normal hyphenation for the endnotes sections.  \end{sloppypar}
 %
 % \DescribeMacro{\putpoemindex}
-% |\putpoemindex| inputs the formatted index, and adds an entry 
+% |\putpoemindex| inputs the formatted index (after your raw entries have been
+% processed by MakeIndex), and adds an entry 
 % for it into the table of contents.
 % Remember that if you are making an index of titles and first lines
-% you may need to run your file through \LaTeX\ after running
-% MakeIndex, to put the entry for the index into your table of
+% you may need to run your file through \LaTeX\ twice more after running
+% MakeIndex, to put the entry for the index and its correct page number into your table of
 % contents.  
 %
 % \DescribeMacro{\putmultiplepoemindex}
@@ -1057,15 +1134,17 @@
 % volume, issue |\indexingontrue| in your preamble.  This will create
 % the external file for your index information and send that file the
 % typesetting information for its title.  You must process this
-% external file (the .idx file) with MakeIndex and run your book
-% through \LaTeX\ again in order to set a properly organized and
+% external file (the .idx file) with MakeIndex to create a properly organized and
 % formatted index.  MakeIndex sorts the various multi-level ``index
 % cards'' generated by all of the |\index| commands in your source
-% files.  Once you have processed your .idx file with MakeIndex, and
+% files.  
+%
+% \DescribeMacro{\putpoemindex}
+%Once you have processed your .idx file with MakeIndex, and
 % generated the sorted and formatted .ind file for your book, the
 % |\putpoemindex| command will insert the typeset index where you
 % issue it, and put an entry for your index in your table of contents.
-% You will have to run your file through \LaTeX\ again to make the
+% You will have to run your file through \LaTeX\  twice again to make the
 % page number for that entry correct.
 % 
 % \textsf{poemscol} sets up a two-column index with a simple running
@@ -1133,12 +1212,12 @@
 % entry ``First Line Index.''
 % \section{Collections with multiple volumes}
 % \DescribeEnv{volumetitlepage} \DescribeEnv{maintitlepage}
-% The |\volumetitlepage| environment is an
+% The |volumetitlepage| environment is an
 % environment for divider pages in collections made up of several
-% volumes.  Volume title pages will always appear on recto pages. 
-% \textsf{poemscol} will automatically create a blank verso page
+% volumes.  Volume title pages will always appear on recto pages with blank verso pages. 
+% \textsf{poemscol} will also automatically create a blank verso page
 % preceding the volume title page if it necessary.  The
-% |\maintitlepage| environment is for the title page of the whole
+% |maintitlepage| environment is for the title page of the whole
 % book.  The main title page will also automatically always be on a
 % recto page. These divider pages have special
 % page styles, with no page numbers and no running headers.
@@ -1165,7 +1244,7 @@
 % volume.  In addition to setting the text in the body of your
 % edition, these commands send the title (and the formatting
 % information about it) to the table of contents file and to the
-% textnotes file.\end{sloppypar}
+% various endnotes files.\end{sloppypar}
 %
 % \DescribeMacro{\volumeepigraph} \DescribeMacro{\volumeattribution}
 % \DescribeMacro{\volumeheader} \DescribeMacro{\leftheader}
@@ -1179,9 +1258,8 @@
 % pages, the table of contents, the notes sections, and other special
 % cases).  Normally that is the name of the entire book.
 % 
-% \section{Recording textual notes}\label{recordingtextualnotes}
-% \subsection{~Setup for sections for
-% textual notes, emendations, and explanatory notes.}
+% \section{Recording textual notes, emendations, and explanatory notes}\label{recordingtextualnotes}
+% \subsection{~Setup for endnote sections}
 % \DescribeMacro{\makeemendations} \DescribeMacro{\maketextnotes}
 % \DescribeMacro{\makeexplanatorynotes} 
 % To collect emendations, issue |\makeemendations| in your preamble. 
@@ -1197,32 +1275,35 @@
 % with |\puttextnotes|, |\putexplanatory|, or |\putemendations|, or at
 % the end (if you use the |\finish| command).
 %  These commands  also send to the external files the commands for typesetting the
-% title of each section (e.g. Explanatory Notes) and for modifying the
+% title of each section (e.g. Explanatory Notes), for making an entry in the table
+% of contents for each endnote section, and for modifying the
 % running headers of the notes sections to xx--yy format (e.g.
 % ``Explanatory Notes to pp.~55--7'').
 % 
-% If you wish to use multi-level footnotes rather than endnotes, you 
+% If you wish to use multi-layer footnotes rather than endnotes, you 
 % do not need to issue |\maketextnotes| or its relatives (but you 
 % should of course issue |\textnotesatfoot| or its relatives). You can mix 
 % footnotes or endnotes as you wish. You may, for instance, wish to 
 % set explanatory notes as footnotes, and textual notes and 
 % emendations as endnotes. Instructions for setting up 
-% \textsf{poemscol} to make footnotes are in section 
+% \textsf{poemscol} to make such footnotes are in section 
 % \ref{makingfootnotes} below.
 % 
 % In end note sections \textsf{poemscol} opens an entry (headed with
 % the title and page of the poem in the text) in the textual notes
 % section for every poem (since, minimally, you want to include
 % information about the variants and copy text of the poem), but only
-% opens entries in the emendations or explanatory notes sections if
+% opens entries in the emendations or explanatory notes sections
+% (or any other endnote sections  you may create) if
 % you actually have emendations or explanatory notes on that poem.
 %
 % The notes for each poem are set in a block paragraph, with a new
 % paragraph for every |\poemtitle| command, and the line counter for
 % the notes is reset to 1 with every |\begin{poem}|.  (For long poems
-% in books or cantos, it would be wise to use |\poemtitle| for the
-% canto names or numbers, setting the poem title in some other way,
-% perhaps with |\volumetitle| described above.)
+% in books or cantos, it you might use |\poemtitle| for the
+% canto names or numbers, or perhaps you might want to design a new species
+% of title using the commands described below at section \ref{customizing titles}, 
+% page \pageref{customizing titles}.)
 % 
 % By default, there is one paragraph per poem, with a hanging indent to give 
 % prominence to the page number.
@@ -1237,7 +1318,8 @@
 % with the other notes to that poem. To do this, you need to set 
 % the relevant boolean. Issue |\textnotessinglepartrue| 
 % |\emendationssingplepartrue| or |\explanationssinglepartrue| to give
-% each such note a separate paragraph.By default, these notes will have a 
+% each such note a separate paragraph. (Similar booleans will be automatically
+% defined for any species of endnote you create.) By default, these notes will have a 
 % hanging indent, to give prominence to the line number.
 % \end{sloppypar}
 %
@@ -1247,9 +1329,10 @@
 % a good idea for multiple paragraph notes.  There are two ways of approaching
 % this problem.  The first way is to change all of the paragraphs of the notes to
 % normal indentation, which you can do by issuing
-% |\literaltextnote{\setlength{\parindent}{\noteindentation}}| (you can pick the 
-% indentation, but the default value is 1 em)
-% just after issuing |\maketextnotes.| You should remember to issue similar 
+% |\literaltextnote{\setlength{\parindent}{\noteindentation}}| just after issuing |\maketextnotes| . 
+% You can change the amoutn of indentation by changing the value of the 
+% length |\noteindentation| (the default value is 1 em).
+% You should remember to issue similar 
 % commands for emendations, explanatory notes, and whatever kinds of notes you 
 % create using |\definenewnotetype|. 
 % \end{sloppypar}
@@ -1265,7 +1348,9 @@
 % \DescribeMacro{\ifemendationstwocol}
 % \DescribeMacro{\ifexplanationstwocol}
 % By default, notes are set in single columns. To set them in two column mode, 
-% set the relevant booleans to true, e.g. |\textnotestwocoltrue|.
+% set the relevant booleans to true, e.g. |\textnotestwocoltrue|. Again, any note type
+% you create with |\definenewnotetype| will automatically define the ``twocol'' boolean
+% that goes with it.
 %
 % \DescribeMacro{\putpagenumberinnotesfalse}
 % \DescribeMacro{\puttitleinnotesfalse}
@@ -1490,6 +1575,24 @@
 % |\tsvariant{}| commands in those places. For information about 
 % |\definenewnotetype| see section \ref{definingnewnotes}.
 %
+% \DescribeMacro{\margreftextnote}
+% \DescribeMacro{\margrefexplanatory}
+% \DescribeMacro{\margrefemendation}
+% Some editions include a marginal mark in the text showing where in the 
+% apparatus a textual note on that line can be found. 
+% |\margreftextnote| sets a label in the textual notes section, and 
+% sets a marginal note with a page reference to that label in the main text. Issue 
+% |\margreftextnote| \emph{before} issuing the |\verseline| or 
+% |\end{stanza}| that closes the line to which it refers. (The textual 
+% note itself can be an ordinary |\textnote|, and should be placed, as 
+% usual, \emph{after} the |\verseline| or |\end{stanza}|.)
+% |\margrefexplanatory| does the same thing for explanatory notes, and
+% |\margrefemendation| does the same thing for emendations. 
+% If you define a new kind of endnote with |\definenewnotetype|, you
+% will automatically also define a new |\margref| command for that kind of note. For
+% details about how these markers work, see 
+% section \ref{margreftextnote}, page \pageref{margreftextnote}.
+%
 % \section{Creating new kinds of endnote} \label{definingnewnotes}
 % \DescribeMacro{\definenewnotetype} The |\definenewnotetype| macro
 % can be used to create new kinds of endnote, in case the kinds
@@ -1585,7 +1688,7 @@
 % You do not need to issue |\maketextnotes|, |\makeemendations| or
 % |\makeexplanatorynotes| if you set those notes as footnotes.  If you
 % use |\literaltextnote| anywhere in your file, however, you will lose
-% the text it would have put in your textnotes, since |\literaltext|
+% the text it would have put in your textnotes, since |\literaltextnote|
 % just writes its argument onto the external file for textual notes.
 % 
 % 
@@ -1650,16 +1753,55 @@
 % \DescribeMacro{\makepoemendnotes}
 % \DescribeMacro{\putpoemendnotes}
 % You may wish, rather than using endnotes or footnotes, simply to print your
-% notes at the end of each poem.  To do this, issue |\makepoemendnotes| just
+% notes at the end of each poem.  To do this for simple notes, issue |\makepoemendnotes| just
 % after |\begin{poem}|.  Issue |\poemendnote| where you wish to make a note,
 % using the same conventions you use for |\textnote|.  Where you want to output
-% the notes, issue |\putpoemendnotes|. These notes can have mult-line lemmas, 
+% the notes, issue |\putpoemendnotes|. These notes can have multi-line lemmas, 
 % just like textual notes.
 %
-%
 % \DescribeMacro{\ifpoemendnotessinglepar} 
 % By default, each poem end note is given its own paragraph. To concatenate 
-% them into a single paragraph, issue |\poemendnotessingleparfalse|.
+% them into one big paragraph, issue |\poemendnotessingleparfalse|.
+%
+% \DescribeMacro{\poemendemendationnote}
+% \DescribeMacro{\makepoemendemendationnotes}
+% \DescribeMacro{\putpoemendemendationnotes}
+% You can print a list of emendations at the end of each poem.
+%  To do this, issue |\makepoemendemendationnotes| just
+% after |\begin{poem}|.  Issue |\poemendemendationnote| where you wish to make a note,
+% using the same conventions you use for |\textnote|.  Where you want to output
+% the notes, issue |\putpoemendemendationnotes|. These notes can have multi-line lemmas, 
+% just like textual notes.
+%
+% By default, each poem end note is given its own paragraph. To concatenate 
+% them into one big paragraph, issue |\poemendemendationnotessingleparfalse|.
+%
+% \DescribeMacro{\poemendexplanatorynote}
+% \DescribeMacro{\makepoemendexplanatorynotes}
+% \DescribeMacro{\putpoemendexplanatorynotes}
+% You can print explanatory notes at the end of each poem.
+% To do this, issue |\makepoemendexplanatorynotes| just
+% after |\begin{poem}|.  Issue |\poemendexplanatorynote| where you wish to make a note,
+% using the same conventions you use for |\textnote|.  Where you want to output
+% the notes, issue |\putpoemendexplanatorynotes|. These notes can have multi-line lemmas, 
+% just like textual notes.
+%
+% By default, each poem end note is given its own paragraph. To concatenate 
+% them into one big paragraph, issue |\poemendexplanatorynotessingleparfalse|.
+%
+% \DescribeMacro{\poemendtextnote}
+% \DescribeMacro{\makepoemendtextnotes}
+% \DescribeMacro{\putpoemendtextnotes}
+% You can print textual
+% notes at the end of each poem.  To do this, issue |\makepoemendtextnotes| just
+% after |\begin{poem}|.  Issue |\poemendtextnote| where you wish to make a note,
+% using the same conventions you use for |\textnote|.  Where you want to output
+% the notes, issue |\putpoemendtextnotes|. These notes can have multi-line lemmas, 
+% just like textual notes.
+%
+% \DescribeMacro{\ifpoemendtextnotessinglepar} 
+% By default, each poem end note is given its own paragraph. To concatenate 
+% them into one big paragraph, issue |\poemendtextnotessingleparfalse|.
 %
 % \section{Printing endnotes and index} 
 % \DescribeMacro{\testforauxonfirstrun} If you don't want to listen to
@@ -1749,14 +1891,14 @@
 % by changing the value of the length |\dateindent|. If you wish to change
 % |\dateindent| you will have to issue |\setlength{\dateindent}{your value}| before
 % each instance of |\poemdate|, since \textsf{poemscol} recalculates 
-% |\dateident| freshly for every poem.
+% |\dateindent| freshly for every poem.
 %
 % There is a slight bug in |\poemdate|. If there is a page turn between the last line of the 
 % poem and the date, and the last line has a runover portion, the date will be set
 % flush with the indented runover portion of the line rather than with the beginning
 % of the line. This should not in practice
 % be a problem, because you should use |\longpage| or several |\shortpage| commands
-% to get rid of the orphan date line.  (For |\longpage| and |\shortpage| see section \ref{longpage},
+% to move the orphan date line anyway.  (For |\longpage| and |\shortpage| see section \ref{longpage},
 % page \pageref{longpage}.)
 % 
 % \subsection{~Pausing line numbering}
@@ -1775,12 +1917,15 @@
 % different handling. To provide line numbers and notes for such 
 % prose sections, see section \ref{prosesections}.
 % 
+% \subsection{~Quoted verse}
+% Sometimes you wish to quote verse within verse (as when a speaker 
+% in a verse play quotes a poem). \DescribeMacro{\quotedverse} The 
+% |quotedverse| environment is desiged for this contingency.
+% 
 % \subsection{~Multiline poem titles}\label{multilinetitles}
 % \DescribeMacro{\poemtitlefirstline}
 % \DescribeMacro{\poemtitlemiddleline}
 % \DescribeMacro{\poemtitlelastline}
-% \DescribeMacro{\poemtitlenocontents}
-% \DescribeMacro{\poemtitlebaretitle}
 %  Very long titles present special problems.  In the first place, they
 % require special provisions to make sure that page breaks don't
 % happen in the middle of a title, or immediately after a title.  In
@@ -1791,17 +1936,11 @@
 % contents.  (I didn't pursue this question for titles in notes
 % sections, and in notes sections these commands simply concatenate a
 % long title.) 
-% 
-% If you wish to set the titles differently in the text and in the
-% contents, you can set the title in the text and notes with
-% |\poemtitlenocontents{}| and send a differently formatted entry to
-% the table of contents file using |\literalcontents{}|. (Remember 
-% that you will have to send not only the title of the poem to the 
-% contents, but also the other formatting information, such as the 
-% indentation, the slash, and the label for the page number.)
-% |\poemtitlebaretitle{}| simply sets the title in the text, enabling
-% you to use |\literalcontents{}| and |literaltextnotes{}| to produce
-% whatever effect you wish.
+%
+% There are similar commands for most but not all of the whole series of 
+% titles for sequences, sequence sections, sequence subsections, and so on.
+% If you need macros for a kind of multi-line title that is not already
+% defined, see below at section \ref{customizing titles}, page \pageref{customizing titles}.
 % 
 % Alternatively, you can just let \textsf{poemscol} handle the long 
 % titles by itself. If you are pretty sure that the author did not 
@@ -1812,41 +1951,6 @@
 % may get a complaint on your log file about an overfull |\hbox| if 
 % you do this, however.
 %
-% \subsection{~Empty poem titles and italicized poem titles} 
-% 
-% \DescribeMacro{\poemtitlenotitle{}}
-% |\poemtitlenotitle{}|, with its paradoxical name, is for poems 
-% without formal titles. Usually such poems are referred to by their 
-% first lines. This macro does not produce a title in the text, but 
-% sets its argument in the table of contents and in the notes. Usually 
-% you use the first line as the moral equivalent of a title.
-% 
-% \DescribeMacro{\poemtitleitalic{}{}} 
-% Titles
-% with italics or other special formatting posed special problems in
-% earlier versions (before version 1.7) since the typesetting commands
-% gummed up how I passed parameters around that I was unable to solve
-% using |\protect|.  All of these commands are obsolete now, but are
-% retained for backward compatibility.
-% |\poemtitleitalic{}{}| takes
-% two arguments.  The first is the title of the poem with the italics
-% (or small capitals or international characters or what have you),
-% for typesetting, and the second is the title without the commands,
-% for cross reference purposes.  (Actually, now that \textsf{poemscol}
-% no longer needs to treat italics in titles in a different way, it can
-% be anything you want, since the second argument is discarded.)
-
-% 
-%  \DescribeMacro{\poemtitlenotitleitalic{}{}}
-%  |\poemtitlenotitleitalic{}{}|, with its doubly paradoxical name, 
-% is for poems without formal titles but with italicized words in their 
-% first lines.  |\poemtitlenotitleitalic{}{}| takes two arguments. The 
-% first is the first line with the italics (for typesetting 
-% purposes), and the second is the 
-% first line without the italics (for crossreference purposes). This command
-% is obsolete now that italics in titles no longer require special 
-% handing, but is retained for backwards compatibility.
-% 
 % \subsection{~Poems in sections}
 % 
 % \begin{sloppypar}
@@ -1857,7 +1961,7 @@
 % of a poem with many sections.  (It differs from |\poemsectiontitle|
 % in that it tries to make it harder for a page break to separate the
 % title of a poem from the title of its first section.)
-% |\poemsectiontitlefirstline{}|, |\poemsectiontitlemiddleline|,
+% |\poemsectiontitlefirstline{}|, |\poemsectiontitlemiddleline{}|,
 % |\poemsectiontitlelastline{}|, |\poemsectiontitlenocontents{}|, and
 % |\poemsectiontitlebaretitle{}|), as their titles imply, are used for
 % special cases such as long section titles, if you wish to specify
@@ -1870,16 +1974,20 @@
 % \subsection{~Poetic sequences}\label{poeticsequences}
 % 
 % \DescribeMacro{\sequencetitle} \DescribeMacro{\sequencesectiontitle}
-% \DescribeMacro{\sequencefirstsectiontitle} Sequences of related
+% \DescribeMacro{\sequencefirstsectiontitle} 
+% \DescribeMacro{\sequencesubsectiontitle} Sequences of related
 % poems, perhaps with an over-title, demand special handling in the
 % text, in the notes sections, and in the table of contents.  (A
 % moment's thought will show that they are different in some ways from
 % poems in sections.  For one thing, a sequence manifests a different
 % relationship between part and whole than a poem in sections does,
 % and often provides stronger experiences of momentary closure between
-% sections.) |\sequencetitle{}| sets the title of the sequence, and 
+% sections.) |\sequencetitle{}| sets the title of the sequence,
 % |\sequencesectiontitle{}| sets the titles of the sections of the 
-% sequence. |\sequencefirstsectiontitle{}| gives a little more
+% sequence, and |\sequencesubsectiontitle{}| sets the titles of 
+% subsections of the sequence (there is even a command for the title
+% of sub-subsections, |\sequencesubsbusectiontitle{}|). 
+% |\sequencefirstsectiontitle{}| gives a little more
 % vertical space between the main title and the first section title
 % than |\sequencesectiontitle{}| gives between adjacent sections later
 % on in the sequence (since the over-title for the sequence is in
@@ -1911,10 +2019,12 @@
 % \item |\poemtitlefirstline|
 % \item |\poemtitlemiddleline|
 % \item |\poemtitlelastline|
+% \item |\poemsubtitle|
 % \item |\poemtitlenotitle|
 % \item |\poemtitlenocontents|
 % \item |\poemtitlebaretitle|
-% \item |\poemsubtitle|	
+% \item |\poemonlycontents|	
+% \item |\poemonlynotes|
 % 	\end{itemize}
 %      \item Poems in Sections
 %      \begin{itemize}
@@ -1971,86 +2081,8 @@
 % \item |\sequencefirstsubsubsectiontitlenocontents|
 % \end{itemize}
 % \end{itemize}
-% 	
-% 	
-% \subsection{~Customizing titles} \label{customizing titles} \textsf{poemscol} provides a large
-% number of ways of setting titles, but conceivably you may wish to
-% define your own.  Here is a template for designing a new kind of
-% title.  Suppose you wish to create a kind of title called
-% |\mytitle{}|.  It would take one argument, which would be the title
-% itself.  The macro defining the |\mytitle| command should call three macros,
-% |\set@p@emtitle|, to set the title in the main text and make the
-% label for use by the contents and notes sections, |\c@ntentsinfo| to
-% set the title in the table of contents, and |\t@xtnotesinfo|, which
-% sets the title in the notes sections.  (You should enclose the whole thing
-% between |\makeatletter| and |\makeatother|.) 
-%
-%\DescribeMacro{\set@p@emtitle}
-% |\set@p@emtitle|
-% takes six arguments, which are, in order, (1) the title (which, if
-% you are calling this command inside of the definition of |\mytitle|
-% should just be |#1|), (2) commands to be issued before setting the
-% title (minimally, a penalty, such as |\poemtitlepenalty|), (3) the
-% font size in which the title is to be set in the text (such as
-% |\poemtitlefont| or |\large|), (4) any indentation of the title
-% (|\relax| for |\poemtitle|, or |\titleindent| for
-% |\sequencesectiontitle|), (5) commands to be issued after the
-% title is set (such as |\afterpoemtitleskip|) and (6) the amount 
-% overrun lines in the title should be indented.  
-%
-%\DescribeMacro{\c@ntentsinfo}
-%|\c@ntentsinfo| takes
-% four arguments, which are, in order, (1) the title, (2) the
-% indentation of the title in the table of contents (such as
-% |\contentsindentone|), (3), the font size in which the title
-% should be set (such as |\contentspoemtitlefont|) and (4) the amount 
-% overrun lines in the table of contents should be indented (such as 
-% |\contentsindenttwoamount|). 
-%
-% \DescribeMacro{\t@xtnotesinfo}
-%  |\t@xtnotesinfo|
-% takes one argument, the title. 
-%
-%  So, for example, to create a new kind of title called |\mytitle| which looks
-% just like |\poemtitle|, issue
-% \begin{verbatim}
-% \makeatletter
-% \newcommand{\mytitle}[1]{%
-% \set@p@emtitle{#1}{\poemtitlepenalty}{\poemtitlefont}%
-% {\relax}{\nobreak\par\nobreak\afterpoemtitleskip\nobreak}{\z@}%
-% \c@ntentsinfo{#1}{\contentsindentone}{\contentspoemtitlefont}%
-% {\contentsindenttwoamount}%
-% \t@xtnotesinfo{#1}%
-% }
-% \makeatother
-% \end{verbatim}
-%
-% (The |\z@| which is the sixth argument to |\set@p@emtitle| above is
-% a constant set to zero. You will also notice that I became completely hysterical
-% on the subject of preventing a page break after a poem title.)
-
-% By default, \textsf{poemscol} 
-% does not indent the overrun portion of titles relative to the first 
-% line of the title, but if that first line is indented will set the 
-% overrun portions to be indented the same amount. Overrun portions 
-% of titles in the table of contents will be indented by one 
-% |\contentsindentamount| more than the first line is indented. Both 
-% of these behaviors can be changed by changing the arguments to 
-% |\set@p@emtitle| or |\c@ntentsinfo|. 
-% 
-% If you wish to design a title which might have multiple lines, 
-% and you wish to specify how those lines are broken up, you
-% will need to write three macros: one for the first line, one for
-% middle lines, and one for the last lines. 
-% (This only matters if you care how the title is broken up. You 
-% can choose to let \LaTeX\ do the breaking if you wish.) Before issuing
-% |\set@p@emtitle| issue |\firstlinesettings|, |\middlelinesettings|,
-% or |\lastlinesettings| (as the case may require).  And issue
-% |\restoresinglelinesettings| last of all in each of your three
-% macros.  The lines will be broken in the table of contents and in
-% the body of the text in the same way, but will be run in in the
-% notes sections.
 % 
+% \subsection{~Titles with marginal markers}
 % \DescribeMacro{\JHpoemtitle}
 % In his edition of the poetry of Jos\'e Maria Heredia, Tilmann 
 % Altenberg placed a marker in the margin next to poem titles with a
@@ -2091,7 +2123,7 @@
 % |\JHpoemtitle{}{}|, with the second argument being any commands you 
 % want to be issued while the title is being processed.
 % 
-% \DescribeMacro{\margreftextnote}
+% \DescribeMacro{\margreftextnote}\label{margreftextnote}
 % Another feature of Altenberg's Heredia edition is a marginal mark 
 % attached to lines to which text notes refer showing where in the 
 % apparatus a comment upon that line is to be found. 
@@ -2100,7 +2132,7 @@
 % |\margreftextnote| \emph{before} issuing the |\verseline| or 
 % |\end{stanza}| that closes the line to which it refers. (The textual 
 % note itself can be an ordinary |\textnote|, and should be placed, as 
-% usual, \emph{after} the |\verseline| or |\end{stanza}|.
+% usual, \emph{after} the |\verseline| or |\end{stanza}|.)
 % 
 % |\margreftextnote| generates its own label, so there is no need to 
 % make up one yourself. 
@@ -2137,11 +2169,185 @@
 % \DescribeMacro{\margrefexplanatory}|\margrefexplanatory| is a 
 % version of |\margreftextnote| for explanatory notes.
 %
-% \subsection{~Quoted verse}
-% Sometimes you wish to quote verse within verse (as when a speaker 
-% in a verse play quotes a poem). \DescribeMacro{\quotedverse} The 
-% |quotedverse| environment is desiged for this contingency.
+% \subsection{~Empty poem titles and italicized poem titles} 
+% 
+% \DescribeMacro{\poemtitlenotitle{}}
+% |\poemtitlenotitle{}|, with its paradoxical name, is for poems 
+% without formal titles. Usually such poems are referred to by their 
+% first lines. This macro does not produce a title in the text, but 
+% sets its argument in the table of contents and in the notes. Usually 
+% you use the first line as the moral equivalent of a title.
+% 
+% \DescribeMacro{\poemtitleitalic{}{}} 
+% Titles
+% with italics or other special formatting posed special problems in
+% earlier versions (before version 1.7) since the typesetting commands
+% gummed up how I passed parameters around that I was unable to solve
+% using |\protect|.  All of these commands are obsolete now, but are
+% retained for backward compatibility.
+% |\poemtitleitalic{}{}| takes
+% two arguments.  The first is the title of the poem with the italics
+% (or small capitals or international characters or what have you),
+% for typesetting, and the second is the title without the commands,
+% for cross reference purposes.  (Actually, now that \textsf{poemscol}
+% no longer needs to treat italics in titles in a different way, it can
+% be anything you want, since the second argument is discarded.)
+% 
+%  \DescribeMacro{\poemtitlenotitleitalic{}{}}
+%  |\poemtitlenotitleitalic{}{}|, with its doubly paradoxical name, 
+% is for poems without formal titles but with italicized words in their 
+% first lines.  |\poemtitlenotitleitalic{}{}| takes two arguments. The 
+% first is the first line with the italics (for typesetting 
+% purposes), and the second is the 
+% first line without the italics (for crossreference purposes). This command
+% is obsolete now that italics in titles no longer require special 
+% handing, but is retained for backwards compatibility.
 % 	
+% \subsection{~Problem titles}
+% \DescribeMacro{\poemtitlebaretitle}
+% \DescribeMacro{\poemtitleonlycontents}
+% \DescribeMacro{\poemtitleonlynotes}
+% A user planned to attach a footnote to a poem title, but didn't want the mark or the text of the
+% note to show up in the contents or in the endnotes. I would usually
+% have advised him to use |\sources| to send the text of the note to the endnotes,
+% but he really wanted the title to include the footnote mark and to put the footnote
+% on the same page. The solution to this problem
+% was to set the title in the text separately from setting it in the notes and in the contents.
+% If you have a problem title, one for instance
+% in which the title in the text might cause problems in the contents or in the notes,
+% you can send information
+% separately to the places it will be used.
+% |\poemtitlebaretitle{}|, for instance simply sets the title in the text. Then
+% you can use |\poemtitleonlycontents{}| to send the title to the contents
+% and |\poemtitleonlynotes{}| to send the title to the notes. These commands
+% are defined for poem titles, and for some but not all of  the whole range of titles including
+% sequence titles, sequence section titles, sequence section subtitles, and so on. But
+% it would be easy to roll your own versions of these commands by looking below at
+% section \ref{customizing titles}, page \pageref{customizing titles}, or at the
+% models in the code below at  section \ref{poemtitlecode}, page \pageref{poemtitlecode}.
+%
+% \DescribeMacro{\poemtitlenocontents}
+% \DescribeMacro{\poemtitlenonotes}
+% \DescribeMacro{\poemtitlenotitle{}}
+% There are also macros to send information to any two of the relevant locations
+% but not the third. |\poemtitlenocontents| sends the title to the text and to the notes,
+% but not to the contents. |\poemtitlenonotes| sends the title to the text and to the 
+% contents, but not to the notes. |\poemtitlenotitle| sends the title to the contents and the
+% notes, but not to the main text.
+%
+% Remember that in the last resort, you can send information to the contents section
+% with |\literalcontents|. To actually set a contents entry using |\literalcontents| is a tall order,
+% however, since you would have to include all the information from the |\c@ntentsinfo| macro
+% for the relevant type of title. (For what |\c@ntentsinfo| does, 
+% see section \ref{customizing titles}, below.) 
+% For instance, for a poem called 
+% Test Poem that is the first in the volume, that would be:
+%
+% \begin{verbatim}
+% \literalcontents{\setlength\contentsentryoverrun{\contentsindenttwoamount }
+% \begin{contentsentryenvironment}
+% \contentsindentone
+% {\contentspoemtitlefont
+% Test
+% Poem}
+% \contentsleaders
+% \pageref{testpoemlabel} % pick a unique label
+% \end{contentsentryenvironment}
+% \par}
+% \end{verbatim}
+%
+% Another tricky thing about this method is the |\pageref| line in the above, which is a pageref to find 
+% the page the poem appears on. You should put |\label{testpoemlabel}|, with any unique
+% text for the label, on the page of the text where the poem occurs, in order to capture
+% the correct page number. (Alternatively, you could just put the actual page number in 
+% here instead of the pageref line.)
+%
+% Remember also that you can send information to the relevant notes sections using 
+% |\literaltextnote|, |\literalexplain|, and |\literalemend|.
+% 
+% 	
+% \subsection{~Customizing titles} \label{customizing titles} \textsf{poemscol} provides a large
+% number of ways of setting titles, but conceivably you may wish to
+% define your own.  Here is a template for designing a new kind of
+% title.  Suppose you wish to create a kind of title called
+% |\mytitle{}|.  It would take one argument, which would be the title
+% itself.  The macro defining the |\mytitle| command should call three macros,
+% |\set@p@emtitle|, to set the title in the main text and make the
+% label for use by the contents and notes sections, |\c@ntentsinfo| to
+% set the title in the table of contents, and |\t@xtnotesinfo|, which
+% sets the title in the notes sections.  (You should enclose the whole thing
+% between |\makeatletter| and |\makeatother|.) 
+%
+%\DescribeMacro{\set@p@emtitle}
+% |\set@p@emtitle|
+% takes six arguments, which are, in order, (1) the title (which, if
+% you are calling this command inside of the definition of |\mytitle|
+% should just be |#1|), (2) commands to be issued before setting the
+% title (minimally, a penalty, such as |\poemtitlepenalty|), (3) the
+% font size in which the title is to be set in the text (such as
+% |\poemtitlefont| or |\large|), (4) any indentation of the title
+% (|\relax| for |\poemtitle|, or |\titleindent| for
+% |\sequencesectiontitle|), (5) commands to be issued after the
+% title is set (such as |\afterpoemtitleskip|) and (6) the amount 
+% overrun lines in the title should be indented.  
+%
+%\DescribeMacro{\c@ntentsinfo}
+%|\c@ntentsinfo| takes
+% four arguments, which are, in order, (1) the title, (2) the
+% indentation of the title in the table of contents (such as
+% |\contentsindentone|), (3), the font size in which the title
+% should be set (such as |\contentspoemtitlefont|) and (4) the amount 
+% overrun lines in the table of contents should be indented (such as 
+% |\contentsindenttwoamount|). 
+%
+% \DescribeMacro{\t@xtnotesinfo}
+%  |\t@xtnotesinfo|
+% takes one argument, the title. 
+%
+%  So, for example, to create a new kind of title called |\mytitle| which looks
+% just like |\poemtitle|, issue
+% \begin{verbatim}
+% \makeatletter
+% \newcommand{\mytitle}[1]{%
+% \set@p@emtitle{#1}{\poemtitlepenalty}{\poemtitlefont}%
+% {\relax}{\nobreak\par\nobreak\afterpoemtitleskip\nobreak}{\z@}%
+% \c@ntentsinfo{#1}{\contentsindentone}{\contentspoemtitlefont}%
+% {\contentsindenttwoamount}%
+% \t@xtnotesinfo{#1}%
+% }
+% \makeatother
+% \end{verbatim}
+%
+% (The |\z@| which is the sixth argument to |\set@p@emtitle| above is
+% a constant set to zero. You will also notice that I became completely hysterical
+% on the subject of preventing a page break after a poem title.)
+
+% By default, \textsf{poemscol} 
+% does not indent the overrun portion of titles relative to the first 
+% line of the title, but if that first line is indented will set the 
+% overrun portions to be indented the same amount. Overrun portions 
+% of titles in the table of contents will be indented by one 
+% |\contentsindentamount| more than the first line is indented. Both 
+% of these behaviors can be changed by changing the arguments to 
+% |\set@p@emtitle| or |\c@ntentsinfo|. 
+% 
+%\DescribeMacro{\firstlinesettings}
+%\DescribeMacro{\middlelinesettings}
+%\DescribeMacro{\lastlinesettings}
+%\DescribeMacro{\restoresinglelinesettings}
+% If you wish to design a title which might have multiple lines, 
+% and you wish to specify how those lines are broken up, you
+% will need to write three macros: one for the first line, one for
+% middle lines, and one for the last lines. 
+% (This only matters if you care how the title is broken up. You 
+% can choose to let \LaTeX\ do the breaking if you wish.) Before issuing
+% |\set@p@emtitle| issue |\firstlinesettings|, |\middlelinesettings|,
+% or |\lastlinesettings| (as the case may require).  And issue
+% |\restoresinglelinesettings| last of all in each of your three
+% macros.  The lines will be broken in the table of contents and in
+% the body of the text in the same way, but will be run in in the
+% notes sections.
+%	
 % \subsection{~Visual formatting}
 % \DescribeMacro{\longpage}
 % \DescribeMacro{\shortpage}
@@ -2164,7 +2370,7 @@
 % |\longpage| and |\shortpage| are cumulative: issuing |\longpage| twice lengthens the
 % page by two lines, and issuing  |\shortpage| twice shortens the page by two lines.
 % 
-% \section{Customizing page geometry}
+% \section{Customizing page geometry and page styles}
 % 
 % 
 % \subsection{~Font sizes, skips, sinks, indents, and penalties}
@@ -2235,15 +2441,41 @@
 %     epigraphquoterightmargin & 1.5em & \relax \\
 %     \end{tabular}
 % 
-% \subsection{~Page styles}
-% \textsf{poemscol} also sets several default page styles, defined 
-% below. The main page style is ``fancy'' (defined below), used for 
-% prose frontmatter (such as introductions), the main body of the 
-% poetry, and the endnotes sections. ``Volumefirststyle'' is for the 
+% \subsection{~Customizing page styles}
+% \textsf{poemscol} sets several default page styles, defined 
+% below. The main page style is ``fancy,''  which is used for 
+%the main body of the  poetry,
+% prose frontmatter (such as introductions),  and the endnotes sections. 
+% ``Volumefirststyle'' is for the 
 % first page of a volume of poems. ``Volumetitlestyle'' is for the 
 % title page of a volume of poems. The external file for the table of 
 % contents redefines ``fancy,'' so you should issue |\resetpagestyle| 
-% after issuing |\putpoemcontents|. 
+% after issuing |\putpoemcontents|. |\resetpagestyle| resets the page
+% style to ``main'' (which is the same as  the original ``fancy'').
+%
+%You can change the text in the left running head
+% by issuing |\leftheader{your header}| or |\volumeheader{your header}|. (The commands
+% are synonyms.) You can change the text in the right running head by issuing 
+% |\rightheader{your header}|. 
+%
+%If you want to change to look of the headers, you
+% can't just issue, say |\fancyhead[RO]{{\small\textrm{\thepage}}}|. You must
+% redefine the fancypage style ``fancy'' or ``main.''  You can find the default
+% definitions of those page styles below at \ref{pagestyledefs}, page \pageref{pagestyledefs}.
+%
+% \subsection{~Special page style for long poems} The fancy page style ``longpoem'' 
+% will add information of the form ``firstline--lastline'' to the running header.  This
+% page style otherwise resembles ``main,'' and ``fancy.''
+% Issue |\pagestyle{longpoem}| to use this page style. If you use ``longpoem,'' be sure to
+% call \textsf{etex} and \textsf{emarks} in your preamble. Also, when a poem ends, be sure
+% to issue |\newpage|, otherwise the running header will list the first line  on the page from the 
+% first poem and the last  line on the page from the second poem.
+%
+% The header will include the abbreviation l. (for a single line) or ll. (for a range of lines).
+% You can change either abbreviation with |\changesinglelineabbrev| or
+% |\changemultiplelineabbrev|. So, for instance, to get rid of the abbreviations
+% entirely, issue |\changemultiplelineabbrev{\relax}| and |\changesinglelineabbrev{\relax}|. 
+%
 % 
 % \subsection{~Page geometry and type leading}
 % 
@@ -2257,8 +2489,8 @@
 % 
 % \begin{tabular}{l l}
 %     textheight&6.75in\\
-%     marginparsep&0pc\\
-%     marginparwidth&0pc\\
+%     marginparsep&18pt\\
+%     marginparwidth&18pt\\
 %     headheight& 14pt\\
 % paperwidth&6in\\
 % paperheight& 9in\\
@@ -2270,14 +2502,16 @@
 %\bigskip
 % 
 %% 
-%% In my own book I also, strictly to save money, and at the price of
-%% some ugliness, changed the definition of |\normalsize| and |\small|,
-%% so that the former was 10 pt type on 11 pt leading (rather than 12
-%% pt), and that the latter was 9 pt type on 10 pt leading.  You can
-%% reproduce this setting by issuing |\tightleading|, although I would
-%% advise not doing so unless you are under financial constraints.
-% 
-% \section{Prose Sections with line numbers} \label{prosesections} \textsf{poemscol}
+% In my own book I also, strictly to save money, and at the price of
+% some ugliness, changed the definition of |\normalsize| and |\small|,
+% so that the former was 10 pt type on 11 pt leading (rather than 12
+% pt), and that the latter was 9 pt type on 10 pt leading.  You can
+% reproduce this setting by issuing |\tightleading|, although I would
+% advise not doing so unless you are under financial constraints.
+% 
+% \section{Prose Sections with line numbers} \label{prosesections} 
+% \subsection{Setup}
+%\textsf{poemscol}
 % uses the \textsf{lineno} package to make marginal line numbers for
 % prose sections such as the Author's Introduction, Afterword,
 % Author's Notes, or such prose interludes or prose poems the volume
@@ -2321,7 +2555,7 @@
 % 
 % \textsf{poemscol} may deal with rather long stretches of prose, but
 % it is not designed to be used for critical editions of extended
-% prose texts, as \texttt{EDMAC}, \textsf{ledmac}, or \textsf{ednotes}
+% prose texts, as \texttt{EDMAC}, \textsf{reledmac}, or \textsf{ednotes}
 % are.  The method of entering line ranges into notes in prose
 % contexts is something of a hack, and rather a worse one than the one
 % employed in verse contexts, since it involves using two labels for
@@ -2336,8 +2570,9 @@
 % you must specify a ``dummy'' title to use in the note and contents
 % sections.)  They will be formatted in the notes and contents
 % sections as poems are.  Alternatively, you can use
-% |\literalcontents| and |\literaltextnotes| to set such titles as you
-% please.
+% the macros for defining new kinds of titles, in section 
+% \ref{customizing titles}, page \pageref{customizing titles},
+% to make new kinds of titles for prose sections.
 % 
 %\DescribeMacro{prosesection}
 % Prose sections should be enclosed in a |prosesection| environment
@@ -2354,7 +2589,6 @@
 % some value different for that from verse contexts, issue the new 
 % modulo as the argument to |\setprosemodulo{}|.
 % 
-% 
 % It is possible, if a prose section is interpolated in the midst of
 % verse, to number the prose and verse continuously.  To move from a
 % verse passage to a prose passage, just before the |\end{poem}| at
@@ -2383,7 +2617,7 @@
 % |\poemlinelabel|. 
 %
 % 
-%
+% \subsection{Endnotes for prose sections}
 % \DescribeMacro{\prosetextnote}
 % \DescribeMacro{\prosemendation}
 % \DescribeMacro{\proseexplanatory}
@@ -2540,10 +2774,11 @@
 % 
 %
 % |\runningsentencenumberformat| sets the format of running sentence
-% numbers.  Currently it is |\textsuperscript| and |\tiny|.  You can
-% change this with |\renewcommand|.  The format of marginal sentence
+% numbers.  Currently it is |\textsuperscript| (the numbers are set as superscripts) and |\tiny|.  
+% The format of marginal sentence
 % numbers is set by |\marginsentencenumberformat|.  Currently it is
-% |\tiny|.  You can change this with |\renewcommmand|.
+% |\tiny|.  Definitions of both commands are found at section \ref{runningsentencenumberformat},
+% page \pageref{runningsentencenumberformat}. You can change either with |\renewcommmand|.
 % 
 % \DescribeMacro{\pmpara}
 % \DescribeMacro{\pmsentencebypara}
@@ -2563,9 +2798,13 @@
 % 
 % If you begin a paragraph with |\pmpara| \textsf{poemscol} will 
 % assume that you intend to include the paragraph number in your 
-% notes (in the form \emph{paragraph: sentence:} for simple 
-% references, or \emph{firstparagraph: firstsentence: -- 
-% lastparagraph: lastentence:} for ranges of sentences) even if you do not reset 
+% notes (in the form \textless \emph{paragraph
+% number}\textgreater:\textless \emph{sentence number}\textgreater\ for simple 
+% references, or  \textless  \emph{first paragraph
+% number}\textgreater:\textless \emph{first sentence number}\textgreater\ -- 
+%  \textless  \emph{lastparagraph
+% number}\textgreater:\textless \emph{last sentence number}\textgreater\ 
+% for ranges of sentences) even if you do not reset 
 % the sentence number at the beginning of each paragraph. Normally 
 % you would not issue |\pmpara| if you are not resetting the sentence 
 % number at the beginning of each paragraph, since under those 
@@ -2578,11 +2817,12 @@
 % 
 % \DescribeMacro{\pmpararunningformat}\DescribeMacro{\pmparmarformat}
 % The format of running paragraph numbers is set 
-% by |\pmparrunningformat|. Currently it is 
+% by |\pmpararunningformat|. Currently it is 
 % |\textbf| and |\small|.
 % The format of marginal paragraph numbers is set by 
 % |\pmparmarformat|. Currently it is 
-% |\textbf| and |\small|. Either can 
+% |\textbf| and |\small|.  The definitions of these commands are found at 
+% section \ref{pmparrunningformat}, page \pageref{pmparrunningformat}, Either can 
 % be changed with |\renewcommand|.
 % 
 % \subsection{~Cross references by sentence and paragraph}
@@ -2609,8 +2849,8 @@
 % commands will write the sentence number at the head of each note,
 % where the line number would usually go.  If you have issued
 % |\pmsentencebypara|, these commands will issue both the paragraph
-% and sentence number, in the format \textless paragraph
-% number\textgreater:\textless sentence number\textgreater.  You can
+% and sentence number, in the format \textless \emph{paragraph
+% number}\textgreater:\textless \emph{sentence number}\textgreater.  You can
 % refer to ranges of sentences (or paragraphs and sentences) in a way
 % very similar to how you do so in verse sections.  At the end of the
 % range, issue a |\sentencelabel| command, with a unique label.  At
@@ -2623,6 +2863,10 @@
 % issued |\pmsentencebypara|, the range will simply be the range of
 % sentence numbers.  If you have issued |\pmsentencebypara|, the range
 % will include paragraph and sentence numbers, like this:
+%\textless  \emph{first paragraph
+% number}\textgreater:\textless \emph{first sentence number}\textgreater\ -- 
+%  \textless  \emph{lastparagraph
+% number}\textgreater:\textless \emph{last sentence number}\textgreater, for example: 
 % 4:12--6:13.\end{sloppypar}
 % 
 % |\sources| needs no special handling if you are annotating by 
@@ -2700,7 +2944,7 @@
 % if you are making a parallel text of Wordsworth's 1805 and 1850
 % versions of \emph{The Prelude}, you might want to use something
 % like |\versopoemtitle{The Prelude (1805 Version)}| and 
-% |\rectopoemtitle{The Prelude{1850 Version)}|.
+% |\rectopoemtitle{The Prelude (1850 Version)}|.
 % I have also made versions of these commands that do not make
 % entries in the table of contents, should the need arise for them. 
 % If you wish to make titles for other things,
@@ -2799,21 +3043,21 @@
 %  You can use all of these without issuing the moral equivalent of |\keeptitlesstraight| and 
 % |\resettitleinnotes|.
 %
-%  \DescribeMacro{\makerectotexnote}
-%  \DescribeMacro{\makerectoemendation}
-%  \DescribeMacro{\makerectoexplanatory}
+%  \DescribeMacro{\makerectotexnotes}
+%  \DescribeMacro{\makerectoemendations}
+%  \DescribeMacro{\makerectoexplanatorynotes}
 %To use these
-% kind of note, issue |\makeversotextnotes|, |\makeversoemendations|, 
+% kinds of note, issue |\makeversotextnotes|, |\makeversoemendations|, 
 % |\makeversoexplanatorynotes| or their recto equivalents in your preamble. You can mark
 % up your texts with these notes 
 % just as you would do with  |\textnote|,  |\emendation| or |\explanatory| (or |\literalversotextnote|
-% |\literalversoemend| and |\literalversoexplain|), without any of the special hacks
+% |\literalversoemendation| and |\literalversoexplain|), without any of the special hacks
 % I have just described.
 %
 % \DescribeMacro{\changerectotextnotesname}
 % \DescribeMacro{\changerectotextnotesheader}
 % \DescribeMacro{\rectotextnotessinglepar}
-% \DescribeMacro{\rectotextnotessingletwocol}
+% \DescribeMacro{\rectotextnotestwocol}
 % I have given the endnotes sections generated by these notes rather
 % generic names (|\rectotextnote| and |\versotextnote| for instance, both open endnote sections
 % with the title TEXTUAL NOTES, with a running header of the form ``Textual Notes to pp.~xx--yy''
@@ -2904,8 +3148,10 @@
 % \LaTeX\ would naturally break the page. Because how \LaTeX\ justifies text is a little
 % unpredictable, however, you may find that the line before the page break, which filled 
 % the line before you added the page break, is actually a little shorter, and thus is 
-% no longer justified, once you add the page break. 
-% To fix this, add an |\hfil| between each word of the last line.
+% no longer justified, once you add the page break. You may well not be able to exactly
+% fill out the line by trial and error, adding a word or even just a syllable, to the line at a time.
+% You can kludge around the problem, however, by adding 
+% an  |\hfil| between each word of the last line.
 %
 % \section{Using \textsf{poemscol} in a multilingual world}
 % 
@@ -2929,6 +3175,7 @@
 % To change the name for 
 % the textual notes in the table of contents issue 
 % |\changetextnotescontentsname{your version}|.
+%
 % \DescribeMacro{\changesinglepageabbrev}
 % \DescribeMacro{\changemultiplepageabbrev}
 % Running headers refer to single pages with the English 
@@ -3197,7 +3444,9 @@
 
 
 %    \begin{macro}{\tightgeometry} There's no reason why you should use the
-% page geometry I specify here. If you issue |\tightgeometry| in your 
+% page geometry I used in \emph{The Collected Poems of Robert Penn Warren}, 
+% and there are many reasons not to. But I include it just to show what is possible.
+% If you issue |\tightgeometry| in your 
 % preamble, you will have the geometry I have used. If you issue 
 % |\tightleading|  you will 
 % redefine |\normalsize| and |\small| to use tighter leading. 
@@ -3391,6 +3640,7 @@
 % distinguish the automatic indentation of run over lines from the 
 % explicitly declared indentation of indented lines. You can change 
 % the amount of indentation of runover lines with |\runoverindent{}|.
+% \label{versedefine}
 %    \begin{macrocode}
 \def\makeatletter{\catcode`\@=11}
 \def\makeatother{\catcode`\@=12 }
@@ -3665,7 +3915,7 @@
 \explanfootnotesparafalse
 %    \end{macrocode}
 
-% \subsection{~Page styles} These define several special page styles. 
+% \subsection{~Defining page styles} \label{pagestyledefs} These define several special page styles. 
 % To use them you must have the \textsf{fancyhdr} package installed. 
 % First, the default running headers: the right side (|\volumeheader|)
 % is the title of the volume in a multivolume edition, and the left
@@ -3705,6 +3955,10 @@
 \fancyfoot[CO]{\hfil{\small \botmark}}
 \renewcommand{\headrulewidth}{0pt}
 \renewcommand{\footrulewidth}{0pt}
+%    \end{macrocode}
+%    \end{macro}
+%    \begin{macro}{\pagestyle{main}}
+%    \begin{macrocode}
 \fancypagestyle{main}{%
 \fancyhead{}
 \fancyfoot{}
@@ -3720,11 +3974,11 @@
 }    
 %    \end{macrocode}
 %    \end{macro}
-
 % Style for the first page of every volume in a Collected Poems. You 
 % don't have to call this style explicitly. It is called by the |\volumetitlepage| 
 % environment. But of course if you want to change the style of those 
 % pages, you should do it here.
+%    \begin{macro}{volumefirststyle}
 %    \begin{macrocode}
 \fancypagestyle{volumefirststyle}{%
 \fancyhf{}
@@ -3733,7 +3987,9 @@
 \renewcommand{\footrulewidth}{0pt}
 }
 %    \end{macrocode}
+%    \end{macro}
 % Style for plain pages.
+%    \begin{macro}{plain}
 %    \begin{macrocode}
 \fancypagestyle{plain}{%
 \fancyhf{}
@@ -3742,7 +3998,41 @@
 \renewcommand{\footrulewidth}{0pt}
 }
 %    \end{macrocode}
+%    \end{macro}
+% Style for long poems.
+%    \begin{macro}{\myversemarks}
+%    \begin{macrocode}
+\newtoks{\singlelineabbrev}
+\singlelineabbrev={l.\ }
+\newcommand{\changesinglelineabbrev}[1]{\singlelineabbrev={#1}}
+\newtoks{\multiplelineabbrev}
+\newcommand{\changemultiplelineabbrev}[1]{\multiplelineabbrev={#1}}
+\multiplelineabbrev{ll.\ }
+\newcommand{\myversemarks}{%
+  \ifthenelse{\equal{\thefirstmarks{verselinemark}}{\thebotmarks{verselinemark}}}%
+        {\unskip ~\the\singlelineabbrev~\thefirstmarks{verselinemark}}% if equal
+{\unskip ~\the\multiplelineabbrev\thefirstmarks{verselinemark}--\thebotmarks{verselinemark}}} % if not equal
+%    \end{macrocode}
+%    \end{macro}
+%    \begin{macro}{longpoem}
+%    \begin{macrocode}
+\fancypagestyle{longpoem}{%
+\fancyhead{}
+\fancyfoot{}
+\fancyhfoffset[RO,LE]{\headoffsetlength}
+\fancyhead[RO]{{\small\textrm{\thepage}}}
+\fancyhead[LE]{{\small\textrm{\thepage}}}
+\fancyhead[CO]{\hfil{\small{\em \leftheadervalue ~ \myversemarks}}\hfil}
+\fancyhead[CE]{\hfil{\small{\em \volumeheadervalue ~ \myversemarks}}\hfil}
+\fancyfoot[CE]{{\small \botmark}\hfil}
+\fancyfoot[CO]{\hfil{\small \botmark}}
+\renewcommand{\headrulewidth}{0pt}
+\renewcommand{\footrulewidth}{0pt}
+} 
+%    \end{macrocode}
+%    \end{macro}
 % Style for divider pages between volumes
+%    \begin{macro}{volumetitlestyle}
 %    \begin{macrocode}
 \fancypagestyle{volumetitlestyle}{%
 \fancyhf{}
@@ -3750,7 +4040,7 @@
 \renewcommand{\footrulewidth}{0pt}
 }
 %    \end{macrocode}
-
+%    \end{macro}
 %    \begin{macro}{\resetpagestyle}
 % |\resetpagestyle| restores the fancy page style of the main sections of the
 % book. |\putpoemcontents| changes the fancy page style, and |\resetpagestyle|,
@@ -3801,7 +4091,7 @@
 %    \subsection{~Environments: poem, and stanza} Here are definitions 
 % of the poem and stanza environments, and of the |\verseline|  and 
 % |\stanzalinestraddle| macros.
-%    \begin{macro}{stanza}
+%    \begin{macro}{stanza} \label{stanzadefine}
 % Page breaks are slightly encouraged in stanza breaks.  Notice that
 % entering a stanza sets the mark to |\relax| and leaving it sets the
 % mark to * (the default value of |\stanzaatbottom|).  If you want to
@@ -4193,8 +4483,14 @@
 \speciallinelockfalse%
 \nolinebreak\\
 }
+% \newif\iflongpoemon
+% \longpoemonfalse
 \newcommand{\incrementverselinenumber}{%
 \nolinebreak\addtocounter{verselinenumber}{1}%
+%\iflongpoemon\marksthe{verselinemark}{\theverselinenumber}\fi%
+\makeatletter
+ \@ifundefined{marksthe}{\relax}{\marksthe{verselinemark}{\theverselinenumber}}
+\makeatother
   \addtocounter{printlineindex}{1}%
   \ifnum\theprintlineindex>\thelineindexrepeat%
     \ifverselinenumbers\nobreak%
@@ -4888,6 +5184,21 @@
 \set@p@emtitle{#1}{\poemtitlepenalty}{\poemtitlefont}%
 {\relax}{\nobreak\par\nobreak\afterpoemtitleskip\nobreak}{\z@}%
 }
+\newcommand{\poemtitleonlycontents}[1]{%
+\c@ntentsinfo{#1}{\contentsindentone}{\contentspoemtitlefont}%
+{\contentsindenttwoamount}%
+}
+\newcommand{\poemtitleonlynotes}[1]{%
+\m@kep@emlabel
+\m@ken@teholder{#1}%
+\t@xtnotesinfo{#1}%
+}
+\newcommand{\poemtitlenonotes}[1]{%
+\set@p@emtitle{#1}{\poemtitlepenalty}{\poemtitlefont}%
+{\relax}{\nobreak\par\nobreak\afterpoemtitleskip\nobreak}{\z@}%
+\c@ntentsinfo{#1}{\contentsindentone}{\contentspoemtitlefont}%
+{\contentsindenttwoamount}%
+}
 %    \end{macrocode}
 %    \end{macro}
 %    \begin{macro}{\poemtitleitalic} Poems with italic titles or other 
@@ -6481,7 +6792,7 @@ r@#2\endcsname{}{}\@nil
 }{}
 %    \end{macrocode}
 % Formatting for sentence numbers in the running text and in the 
-% margin.
+% margin. \label{runningsentencenumberformat}
 %    \begin{macrocode}
 \newcommand{\runningsentencenumberformat}[1]{\nobreak%
 \textsuperscript{\scriptsize{#1}}\unskip\nobreak}
@@ -6679,7 +6990,7 @@ r@#2\endcsname{}{}\@nil
 \newif{\ifpmsentencebypara}% reset sentence counter every paragraph
 \pmsentencebyparatrue
 %    \end{macrocode}
-% Formatting marginal and running paragraph numbers, printing them.
+% Formatting marginal and running paragraph numbers, printing them. \label{pmparrunningformat}
 %    \begin{macrocode}
 \newcommand{\pmparmarformat}[1]{\textbf{{\small #1}}}
 \newcommand{\pmpararunningformat}[1]{\textbf{\small #1}}
@@ -6975,6 +7286,121 @@ r@#2\endcsname{}{}\@nil
 \else
  \relax
 \fi}
+%    \begin{macro}{\poemendemendationnote}
+%    \begin{macrocode}
+\newif\ifpoemendemendationnoteson
+\poemendemendationnotesontrue
+\newif\ifpoemendemendationnotessinglepar
+\poemendemendationnotessinglepartrue
+\newcommand{\makepoemendemendationnotes}{
+  \global\verselinenumberstrue
+  \newwrite\poemendemendationnotes
+  \immediate\openout\poemendemendationnotes=\jobname.pmd
+  \literalpoemendemendationnote{\bigskip}
+ }
+\newcommand{\poemendemendationnote}[2][0]{%
+\ifpoemendemendationnoteson
+    \setlemmarange{#1}%
+    \immediate\write\poemendemendationnotes{\checknoteheaders}
+    \literalpoemendemendationnote{#2}%
+    \ifpoemendemendationnotessinglepar%
+    \literalpoemendemendationnote{\par}%
+    \fi%
+    \fi 
+\resetlemmacounters
+}
+\newcommand{\literalpoemendemendationnote}[1]{%
+     \begingroup
+        \def\next{#1}%
+        \newlinechar='40
+        \immediate\write\poemendemendationnotes{\expandafter\strip\meaning\next}%
+     \endgroup
+ }
+\newcommand{\putpoemendemendationnotes}{
+\ifpoemendemendationnoteson
+   \immediate\closeout\poemendemendationnotes
+   \input \jobname.pmd
+\else
+ \relax
+\fi}
+%    \end{macrocode}
+%    \end{macro}
+%    \begin{macro}{\poemendexplanatorynote}
+%    \begin{macrocode}
+\newif\ifpoemendexplanatorynoteson
+\poemendexplanatorynotesontrue
+\newif\ifpoemendexplanatorynotessinglepar
+\poemendexplanatorynotessinglepartrue
+\newcommand{\makepoemendexplanatorynotes}{
+  \global\verselinenumberstrue
+  \newwrite\poemendexplanatorynotes
+  \immediate\openout\poemendexplanatorynotes=\jobname.pxd
+  \literalpoemendexplanatorynote{\bigskip}
+ }
+\newcommand{\poemendexplanatorynote}[2][0]{%
+\ifpoemendexplanatorynoteson
+    \setlemmarange{#1}%
+    \immediate\write\poemendexplanatorynotes{\checknoteheaders}
+    \literalpoemendexplanatorynote{#2}%
+    \ifpoemendexplanatorynotessinglepar%
+    \literalpoemendexplanatorynote{\par}%
+    \fi%
+    \fi 
+\resetlemmacounters
+}
+\newcommand{\literalpoemendexplanatorynote}[1]{%
+     \begingroup
+        \def\next{#1}%
+        \newlinechar='40
+        \immediate\write\poemendexplanatorynotes{\expandafter\strip\meaning\next}%
+     \endgroup
+ }
+\newcommand{\putpoemendexplanatorynotes}{
+\ifpoemendexplanatorynoteson
+   \immediate\closeout\poemendexplanatorynotes
+   \input \jobname.pxd
+\else
+ \relax
+\fi}
+%    \end{macrocode}
+%    \end{macro}
+%    \begin{macro}{\poemendtextnote}
+%    \begin{macrocode}
+\newif\ifpoemendtextnoteson
+\poemendtextnotesontrue
+\newif\ifpoemendtextnotessinglepar
+\poemendtextnotessinglepartrue
+\newcommand{\makepoemendtextnotes}{
+  \global\verselinenumberstrue
+  \newwrite\poemendtextnotes
+  \immediate\openout\poemendtextnotes=\jobname.pmd
+  \literalpoemendtextnote{\bigskip}
+ }
+\newcommand{\poemendtextnote}[2][0]{%
+\ifpoemendtextnoteson
+    \setlemmarange{#1}%
+    \immediate\write\poemendtextnotes{\checknoteheaders}
+    \literalpoemendtextnote{#2}%
+    \ifpoemendtextnotessinglepar%
+    \literalpoemendtextnote{\par}%
+    \fi%
+    \fi 
+\resetlemmacounters
+}
+\newcommand{\literalpoemendtextnote}[1]{%
+     \begingroup
+        \def\next{#1}%
+        \newlinechar='40
+        \immediate\write\poemendtextnotes{\expandafter\strip\meaning\next}%
+     \endgroup
+ }
+\newcommand{\putpoemendtextnotes}{
+\ifpoemendtextnoteson
+   \immediate\closeout\poemendtextnotes
+   \input \jobname.pmd
+\else
+ \relax
+\fi}
 %    \end{macrocode}
 %    \end{macro}
 %    \subsection{~Embarrassing kludges} Because the dirty trick 
diff --git a/Master/texmf-dist/tex/latex/poemscol/poemscol.sty b/Master/texmf-dist/tex/latex/poemscol/poemscol.sty
index f7f4556987a..6cfc4fceb8a 100644
--- a/Master/texmf-dist/tex/latex/poemscol/poemscol.sty
+++ b/Master/texmf-dist/tex/latex/poemscol/poemscol.sty
@@ -22,18 +22,11 @@
 %% in the same archive or directory.)
 \NeedsTeXFormat{LaTeX2e}[1997/12/01]
 \ProvidesPackage{poemscol}
-   [2017/11/30 v2.9 poemscol file]
-
+   [2017/12/20 v2.95 poemscol file]
 
 
 
 %%
-%% In my own book I also, strictly to save money, and at the price of
-%% some ugliness, changed the definition of |\normalsize| and |\small|,
-%% so that the former was 10 pt type on 11 pt leading (rather than 12
-%% pt), and that the latter was 9 pt type on 10 pt leading.  You can
-%% reproduce this setting by issuing |\tightleading|, although I would
-%% advise not doing so unless you are under financial constraints.
 
 
 
@@ -289,7 +282,6 @@
 \renewcommand{\headrulewidth}{0pt}
 \renewcommand{\footrulewidth}{0pt}
 }
-
 \fancypagestyle{volumefirststyle}{%
 \fancyhf{}
 \fancyfoot[C]{\hfil{\small \botmark}\hfil}
@@ -302,12 +294,34 @@
 \renewcommand{\headrulewidth}{0pt}
 \renewcommand{\footrulewidth}{0pt}
 }
+\newtoks{\singlelineabbrev}
+\singlelineabbrev={l.\ }
+\newcommand{\changesinglelineabbrev}[1]{\singlelineabbrev={#1}}
+\newtoks{\multiplelineabbrev}
+\newcommand{\changemultiplelineabbrev}[1]{\multiplelineabbrev={#1}}
+\multiplelineabbrev{ll.\ }
+\newcommand{\myversemarks}{%
+  \ifthenelse{\equal{\thefirstmarks{verselinemark}}{\thebotmarks{verselinemark}}}%
+        {\unskip ~\the\singlelineabbrev~\thefirstmarks{verselinemark}}% if equal
+{\unskip ~\the\multiplelineabbrev\thefirstmarks{verselinemark}--\thebotmarks{verselinemark}}} % if not equal
+\fancypagestyle{longpoem}{%
+\fancyhead{}
+\fancyfoot{}
+\fancyhfoffset[RO,LE]{\headoffsetlength}
+\fancyhead[RO]{{\small\textrm{\thepage}}}
+\fancyhead[LE]{{\small\textrm{\thepage}}}
+\fancyhead[CO]{\hfil{\small{\em \leftheadervalue ~ \myversemarks}}\hfil}
+\fancyhead[CE]{\hfil{\small{\em \volumeheadervalue ~ \myversemarks}}\hfil}
+\fancyfoot[CE]{{\small \botmark}\hfil}
+\fancyfoot[CO]{\hfil{\small \botmark}}
+\renewcommand{\headrulewidth}{0pt}
+\renewcommand{\footrulewidth}{0pt}
+}
 \fancypagestyle{volumetitlestyle}{%
 \fancyhf{}
 \renewcommand{\headrulewidth}{0pt}
 \renewcommand{\footrulewidth}{0pt}
 }
-
  \newcommand{\resetpagestyle}{\pagestyle{main}
 }
  \newcommand{\clearemptydoublepage}{\newpage{\pagestyle{empty}\cleardoublepage}}
@@ -516,6 +530,9 @@
 }
 \newcommand{\incrementverselinenumber}{%
 \nolinebreak\addtocounter{verselinenumber}{1}%
+\makeatletter
+ \@ifundefined{marksthe}{\relax}{\marksthe{verselinemark}{\theverselinenumber}}
+\makeatother
   \addtocounter{printlineindex}{1}%
   \ifnum\theprintlineindex>\thelineindexrepeat%
     \ifverselinenumbers\nobreak%
@@ -941,6 +958,21 @@
 \set@p@emtitle{#1}{\poemtitlepenalty}{\poemtitlefont}%
 {\relax}{\nobreak\par\nobreak\afterpoemtitleskip\nobreak}{\z@}%
 }
+\newcommand{\poemtitleonlycontents}[1]{%
+\c@ntentsinfo{#1}{\contentsindentone}{\contentspoemtitlefont}%
+{\contentsindenttwoamount}%
+}
+\newcommand{\poemtitleonlynotes}[1]{%
+\m@kep@emlabel
+\m@ken@teholder{#1}%
+\t@xtnotesinfo{#1}%
+}
+\newcommand{\poemtitlenonotes}[1]{%
+\set@p@emtitle{#1}{\poemtitlepenalty}{\poemtitlefont}%
+{\relax}{\nobreak\par\nobreak\afterpoemtitleskip\nobreak}{\z@}%
+\c@ntentsinfo{#1}{\contentsindentone}{\contentspoemtitlefont}%
+{\contentsindenttwoamount}%
+}
 \newcommand{\poemtitleitalic}[2]{%
 \poemtitle{#1}}
 \newcommand{\firstlinesettings}{\singlelinetitlefalse
@@ -2371,6 +2403,111 @@ r@#2\endcsname{}{}\@nil
 \else
  \relax
 \fi}
+\newif\ifpoemendemendationnoteson
+\poemendemendationnotesontrue
+\newif\ifpoemendemendationnotessinglepar
+\poemendemendationnotessinglepartrue
+\newcommand{\makepoemendemendationnotes}{
+  \global\verselinenumberstrue
+  \newwrite\poemendemendationnotes
+  \immediate\openout\poemendemendationnotes=\jobname.pmd
+  \literalpoemendemendationnote{\bigskip}
+ }
+\newcommand{\poemendemendationnote}[2][0]{%
+\ifpoemendemendationnoteson
+    \setlemmarange{#1}%
+    \immediate\write\poemendemendationnotes{\checknoteheaders}
+    \literalpoemendemendationnote{#2}%
+    \ifpoemendemendationnotessinglepar%
+    \literalpoemendemendationnote{\par}%
+    \fi%
+    \fi
+\resetlemmacounters
+}
+\newcommand{\literalpoemendemendationnote}[1]{%
+     \begingroup
+        \def\next{#1}%
+        \newlinechar='40
+        \immediate\write\poemendemendationnotes{\expandafter\strip\meaning\next}%
+     \endgroup
+ }
+\newcommand{\putpoemendemendationnotes}{
+\ifpoemendemendationnoteson
+   \immediate\closeout\poemendemendationnotes
+   \input \jobname.pmd
+\else
+ \relax
+\fi}
+\newif\ifpoemendexplanatorynoteson
+\poemendexplanatorynotesontrue
+\newif\ifpoemendexplanatorynotessinglepar
+\poemendexplanatorynotessinglepartrue
+\newcommand{\makepoemendexplanatorynotes}{
+  \global\verselinenumberstrue
+  \newwrite\poemendexplanatorynotes
+  \immediate\openout\poemendexplanatorynotes=\jobname.pxd
+  \literalpoemendexplanatorynote{\bigskip}
+ }
+\newcommand{\poemendexplanatorynote}[2][0]{%
+\ifpoemendexplanatorynoteson
+    \setlemmarange{#1}%
+    \immediate\write\poemendexplanatorynotes{\checknoteheaders}
+    \literalpoemendexplanatorynote{#2}%
+    \ifpoemendexplanatorynotessinglepar%
+    \literalpoemendexplanatorynote{\par}%
+    \fi%
+    \fi
+\resetlemmacounters
+}
+\newcommand{\literalpoemendexplanatorynote}[1]{%
+     \begingroup
+        \def\next{#1}%
+        \newlinechar='40
+        \immediate\write\poemendexplanatorynotes{\expandafter\strip\meaning\next}%
+     \endgroup
+ }
+\newcommand{\putpoemendexplanatorynotes}{
+\ifpoemendexplanatorynoteson
+   \immediate\closeout\poemendexplanatorynotes
+   \input \jobname.pxd
+\else
+ \relax
+\fi}
+\newif\ifpoemendtextnoteson
+\poemendtextnotesontrue
+\newif\ifpoemendtextnotessinglepar
+\poemendtextnotessinglepartrue
+\newcommand{\makepoemendtextnotes}{
+  \global\verselinenumberstrue
+  \newwrite\poemendtextnotes
+  \immediate\openout\poemendtextnotes=\jobname.pmd
+  \literalpoemendtextnote{\bigskip}
+ }
+\newcommand{\poemendtextnote}[2][0]{%
+\ifpoemendtextnoteson
+    \setlemmarange{#1}%
+    \immediate\write\poemendtextnotes{\checknoteheaders}
+    \literalpoemendtextnote{#2}%
+    \ifpoemendtextnotessinglepar%
+    \literalpoemendtextnote{\par}%
+    \fi%
+    \fi
+\resetlemmacounters
+}
+\newcommand{\literalpoemendtextnote}[1]{%
+     \begingroup
+        \def\next{#1}%
+        \newlinechar='40
+        \immediate\write\poemendtextnotes{\expandafter\strip\meaning\next}%
+     \endgroup
+ }
+\newcommand{\putpoemendtextnotes}{
+\ifpoemendtextnoteson
+   \immediate\closeout\poemendtextnotes
+   \input \jobname.pmd
+\else
+ \relax
+\fi}
 \newcommand{\quotedversecorrectiontextnote}[1][0pt]
 {\iftextnoteson%
 \immediate\write\textnotes{\string\noindent\string\kern-#1}%