# texlive[46113] Master/texmf-dist: poemscol (21dec17)

commits+karl at tug.org commits+karl at tug.org
Fri Dec 22 00:56:38 CET 2017

Revision: 46113
http://tug.org/svn/texlive?view=revision&revision=46113
Author:   karl
Date:     2017-12-22 00:56:38 +0100 (Fri, 22 Dec 2017)
Log Message:
-----------
poemscol (21dec17)

Modified Paths:
--------------
trunk/Master/texmf-dist/doc/latex/poemscol/poemscol.pdf
trunk/Master/texmf-dist/source/latex/poemscol/poemscol.dtx
trunk/Master/texmf-dist/tex/latex/poemscol/poemscol.sty

Modified: trunk/Master/texmf-dist/doc/latex/poemscol/poemscol.pdf
===================================================================
(Binary files differ)

Modified: trunk/Master/texmf-dist/source/latex/poemscol/poemscol.dtx
===================================================================
--- trunk/Master/texmf-dist/source/latex/poemscol/poemscol.dtx	2017-12-21 23:56:23 UTC (rev 46112)
+++ trunk/Master/texmf-dist/source/latex/poemscol/poemscol.dtx	2017-12-21 23:56:38 UTC (rev 46113)
@@ -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{\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 at 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,14 +322,65 @@
% 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,
% its algorithm for justifying lines (in prose sections), and \LaTeX's
@@ -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,13 +487,16 @@
% 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
@@ -453,11 +503,22 @@
% 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 at 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 at 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 at 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,6 +1049,9 @@
% 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
@@ -978,11 +1058,13 @@
% 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,17 +1275,18 @@
% 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
@@ -1214,15 +1293,17 @@
% 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,17 +1753,56 @@
% \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
% \LaTeX\ complain about missing references during your first run,
@@ -1749,7 +1891,7 @@
% 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
@@ -1756,7 +1898,7 @@
% 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,18 +1936,12 @@
% contents.  (I didn't pursue this question for titles in notes
% sections, and in notes sections these commands simply concatenate a
% long title.)
+%
+% 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}.
%
-% 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.
-%
% Alternatively, you can just let \textsf{poemscol} handle the long
% titles by itself. If you are pretty sure that the author did not
% care how long titles were broken up, this would probably be the
@@ -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,7 +1974,8 @@
% \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
@@ -1877,9 +1982,12 @@
% 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 at p@emtitle|, to set the title in the main text and make the
-% label for use by the contents and notes sections, |\c at ntentsinfo| to
-% set the title in the table of contents, and |\t at xtnotesinfo|, which
-% sets the title in the notes sections.  (You should enclose the whole thing
-% between |\makeatletter| and |\makeatother|.)
-%
-%\DescribeMacro{\set at p@emtitle}
-% |\set at 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 at ntentsinfo}
-%|\c at 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 at xtnotesinfo}
-%  |\t at 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 at p@emtitle{#1}{\poemtitlepenalty}{\poemtitlefont}%
-% {\relax}{\nobreak\par\nobreak\afterpoemtitleskip\nobreak}{\z@}%
-% \c at ntentsinfo{#1}{\contentsindentone}{\contentspoemtitlefont}%
-% {\contentsindenttwoamount}%
-% \t at xtnotesinfo{#1}%
-% }
-% \makeatother
-% \end{verbatim}
-%
-% (The |\z@| which is the sixth argument to |\set at 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 at p@emtitle| or |\c at 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 at 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 at ntentsinfo| macro
+% for the relevant type of title. (For what |\c at 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 at p@emtitle|, to set the title in the main text and make the
+% label for use by the contents and notes sections, |\c at ntentsinfo| to
+% set the title in the table of contents, and |\t at xtnotesinfo|, which
+% sets the title in the notes sections.  (You should enclose the whole thing
+% between |\makeatletter| and |\makeatother|.)
+%
+%\DescribeMacro{\set at p@emtitle}
+% |\set at 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 at ntentsinfo}
+%|\c at 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 at xtnotesinfo}
+%  |\t at 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 at p@emtitle{#1}{\poemtitlepenalty}{\poemtitlefont}%
+% {\relax}{\nobreak\par\nobreak\afterpoemtitleskip\nobreak}{\z@}%
+% \c at ntentsinfo{#1}{\contentsindentone}{\contentspoemtitlefont}%
+% {\contentsindenttwoamount}%
+% \t at xtnotesinfo{#1}%
+% }
+% \makeatother
+% \end{verbatim}
+%
+% (The |\z@| which is the sixth argument to |\set at 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 at p@emtitle| or |\c at 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 at 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.
+% 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}
+% \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 at p@emtitle{#1}{\poemtitlepenalty}{\poemtitlefont}%
{\relax}{\nobreak\par\nobreak\afterpoemtitleskip\nobreak}{\z@}%
}
+\newcommand{\poemtitleonlycontents}[1]{%
+\c at ntentsinfo{#1}{\contentsindentone}{\contentspoemtitlefont}%
+{\contentsindenttwoamount}%
+}
+\newcommand{\poemtitleonlynotes}[1]{%
+\m at kep@emlabel
+\m at ken@teholder{#1}%
+\t at xtnotesinfo{#1}%
+}
+\newcommand{\poemtitlenonotes}[1]{%
+\set at p@emtitle{#1}{\poemtitlepenalty}{\poemtitlefont}%
+{\relax}{\nobreak\par\nobreak\afterpoemtitleskip\nobreak}{\z@}%
+\c at ntentsinfo{#1}{\contentsindentone}{\contentspoemtitlefont}%
+{\contentsindenttwoamount}%
+}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\poemtitleitalic} Poems with italic titles or other
@@ -6481,7 +6792,7 @@
}{}
%    \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 @@
\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,8 +7286,123 @@
\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
% mentioned above writes out textnotes as a ribbon one word wide,
% quoted poetry in the notes sections will leave a blank line at the

Modified: trunk/Master/texmf-dist/tex/latex/poemscol/poemscol.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/poemscol/poemscol.sty	2017-12-21 23:56:23 UTC (rev 46112)
+++ trunk/Master/texmf-dist/tex/latex/poemscol/poemscol.sty	2017-12-21 23:56:38 UTC (rev 46113)
@@ -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 at p@emtitle{#1}{\poemtitlepenalty}{\poemtitlefont}%
{\relax}{\nobreak\par\nobreak\afterpoemtitleskip\nobreak}{\z@}%
}
+\newcommand{\poemtitleonlycontents}[1]{%
+\c at ntentsinfo{#1}{\contentsindentone}{\contentspoemtitlefont}%
+{\contentsindenttwoamount}%
+}
+\newcommand{\poemtitleonlynotes}[1]{%
+\m at kep@emlabel
+\m at ken@teholder{#1}%
+\t at xtnotesinfo{#1}%
+}
+\newcommand{\poemtitlenonotes}[1]{%
+\set at p@emtitle{#1}{\poemtitlepenalty}{\poemtitlefont}%
+{\relax}{\nobreak\par\nobreak\afterpoemtitleskip\nobreak}{\z@}%
+\c at ntentsinfo{#1}{\contentsindentone}{\contentspoemtitlefont}%
+{\contentsindenttwoamount}%
+}
\newcommand{\poemtitleitalic}[2]{%
\poemtitle{#1}}
\newcommand{\firstlinesettings}{\singlelinetitlefalse
@@ -2371,6 +2403,111 @@
\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}%



More information about the tex-live-commits mailing list