poetrytex (18aug13)

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

1 files changed, 376 insertions, 91 deletions

diff --git a/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx b/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx
index 8d8dcee0400..e5cc0c0e90d 100644
--- a/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx
+++ b/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx
@@ -79,10 +79,10 @@
 %
 % \title{The \textsf{poetrytex} package}
 % \author{
-%   \name{Sam Whited}\\
+%   \name{Sam Whited}\\*
 %   \texttt{sam@samwhited.com}
 % }
-% \date{\today\\\gitdescribe}
+% \date{\today\\*\gitdescribe}
 %
 % \maketitle
 % \maketoc
@@ -143,8 +143,11 @@
 % \changes{1.2}{2012/10/03}{Removed \pkg{parskip} dependency}
 % \changes{1.2}{2012/10/03}{Removed default \pkg{hyperref} options}
 % \changes{1.3}{2012/10/03}{Load \pkg{hyperref} at end of package}
+% \changes{2.0.0}{2013/02/23}{Require \pkg{tcloft} package}
+% \changes{2.0.0}{2013/08/17}{Begin using semantic versioning (semver.org)}
 %    \begin{macrocode}
 \RequirePackage{expl3}
+\RequirePackage{tocloft}
 \AtEndOfPackage{\RequirePackage{hyperref}}
 %    \end{macrocode}
 % Once you have all the required packages, building \pkg{poetrytex} from source
@@ -178,19 +181,28 @@
 % \hypertarget{POETRYTEX:OPTIONS}{}
 % \changes{1.2}{2012/10/03}{Added various package options}
 % \begin{macro}{verse}
+% \begin{macro}{poemsintoc}
+% \changes{2.0.0}{2012/08/17}{Add option to insert poems in the ToC}
 % \begin{macro}{numbertop}
+% \begin{macro}{numbertoc}
+% \changes{2.0.0}{2012/08/17}{Add option to number poems in the ToC}
 % \begin{macro}{resetnumongroup}
 % \begin{macro}{numberpoems}
 % \begin{macro}{usedefaulttitles}
 % \changes{1.4}{2012/02/13}{Add package option to use default titles}
+% \begin{macro}{useincipits}
+% \changes{2.0.0}{2012/03/06}{Add package option to use incipits}
 % \begin{macro}{clearpageafterpoem}
 % The package can also be loaded with any of the following options:
 %    \begin{macrocode}
 \DeclareOption{verse}{\usepackage{verse}}
+\DeclareOption{poemsintoc}{\listpoemsintoc}
 \DeclareOption{numbertop}{\numbertop}
+\DeclareOption{numbertoc}{\numbertoc}
 \DeclareOption{resetnumongroup}{\resetnumongroup}
 \DeclareOption{numberpoems}{\numberpoems}
 \DeclareOption{usedefaulttitles}{\ptusedefaulttitles}
+\DeclareOption{useincipits}{\ptuseincipits}
 \DeclareOption{clearpageafterpoem}{\clearpageafterpoem}
 \DeclareOption{clearpageafterpoems}{\clearpageafterpoem}
 \DeclareOption*{%
@@ -203,6 +215,9 @@
 % \end{macro}
 % \end{macro}
 % \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % For instance:
 %
@@ -253,11 +268,15 @@
 % We then use these properties to set the document title, author, and date:
 %    \begin{macrocode}
 \title{%
-  \pttitle%
-  \ifx\ptsubtitle\@ptundefined\relax\else\\\ptsubtitle\fi%
+  \beforetitle\pttitle\aftertitle%
+  \ifx\ptsubtitle\@ptundefined%
+    \relax%
+  \else%
+    \\*\beforesubtitle\ptsubtitle\aftersubtitle%
+  \fi%
 }
-\author{\ptauthor}
-\date{\ptdate}
+\author{\beforeauthor\ptauthor\afterauthor}
+\date{\beforedate\ptdate\afterdate}
 %    \end{macrocode}
 % Since \code{\textbackslash maketitle} clears the internal title, author, and
 % date we use the \code{\textbackslash pt} equivalents so that we can refer to
@@ -281,11 +300,11 @@
 % \begin{macro}{poemnum}
 % \begin{macro}{absolutepoemnum}
 % \begin{macro}{untitledpoemnum}
-% \changes{1.4}{2013/02/12}{Create a new counter to keep track of untitled%
-% poems}
+% \changes{1.4}{2013/02/12}{Create a new counter to track untitled poems}
 % \begin{macro}{absoluteuntitledpoemnum}
-% \changes{1.4}{2013/02/12}{Create a new counter to keep track of untitled%
-% poems}
+% \changes{1.4}{2013/02/12}{Create a new counter to track of untitled poems}
+% \begin{macro}{poemgroupnum}
+% \changes{2.0.0}{2013/02/23}{Create a new counter to track poem groups}
 % The \code{poemnum} and \code{absolutepoemnum} counters will be incremented
 % every time we include a poem in our document and can be used later to number
 % the poems. The \code{absolutepoemnum} counter will never be reset by \pkg{%
@@ -298,11 +317,13 @@
 \newcounter{absolutepoemnum}
 \newcounter{untitledpoemnum}
 \newcounter{absoluteuntitledpoemnum}
+\newcounter{poemgroupnum}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
 % \end{macro}
 % \end{macro}
+% \end{macro}
 %
 % \begin{macro}{\poemvspace}
 % \changes{1.4}{2013/02/11}{Allow whitespace before every poem}
@@ -347,19 +368,25 @@
 % \begin{macro}{\ptusedefaulttitles}
 % \begin{macro}{\ptdefaulttitle}
 % \changes{1.4}{2013/02/12}{Add a default poem title}
-% The default title for poems that don't include one. If \code{\textbackslash
-% ptusedefaulttitles} is called the default title will be displayed above the
-% poem itself as well as in the table of contents. Otherwise the title is left
-% blank.
+% \begin{macro}{\ptuseincipits}
+% \changes{2.0.0}{2013/03/06}{Add option for using incipits in the ToP}
+% The default title for poems that don't include one. If
+% \code{\textbackslash ptusedefaulttitles} is called the default title will be
+% displayed above the poem itself as well as in the table of contents. Otherwise
+% the title is left blank. We can also use incipits in the ToP by calling
+% \code{\textbackslash ptuseincipits}. This will override the default title in
+% the ToP, but will not be displayed atop the poem itself.
 %
 %    \begin{macrocode}
 \newcommand*{\ptusedefaulttitles}{\newcommand*{\@ptusedefaulttitles}{}}
 \newcommand*{\ptdefaulttitle}{%
   Untitled No. \arabic{absoluteuntitledpoemnum}%
 }
+\newcommand*{\ptuseincipits}{\newcommand*{\@ptuseincipits}{}}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
+% \end{macro}
 %
 % \begin{macro}{\ptdefaultenv}
 % \changes{1.2}{2012/09/20}{Added an option to change the default environment}
@@ -374,6 +401,28 @@
 % \end{macro}
 % \end{macro}
 %
+% \begin{macro}{\ptdefaultgroupenv}
+% \changes{2.0.0}{2013/03/09}{Allow changing of the default group environment}
+% \begin{macro}{\grouppagestyle}
+% \changes{2.0.0}{2013/03/09}{Allow changing of group page style}
+% \begin{macro}{\pregroupvspace}
+% \changes{2.0.0}{2013/03/09}{Allow change in vspace before group}
+% \begin{macro}{\postgroupvspace}
+% \changes{2.0.0}{2013/03/09}{Allow change in vspace after group}
+% The following macros can be used to configure how the poem group page looks.
+%    \begin{macrocode}
+\newcommand*{\ptdefaultgroupenv}{center}
+\newcommand*{\grouppagestyle}{empty}
+\newlength{\pregroupvspace}
+\newlength{\postgroupvspace}
+\setlength{\pregroupvspace}{\fill}
+\setlength{\postgroupvspace}{\fill}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
 % \begin{macro}{\ptannotationenv}
 % \changes{1.3}{2012/10/30}{Added an option to change the default annotation
 % environment}
@@ -402,11 +451,11 @@
 \newcommand*{\ptdedication}{Renew \textsf{\textbackslash ptdedication}}
 \newcommand*{\makededication}[1][flushright]{%
   \thispagestyle{empty}
-  \vspace*{\fill}
+  \vspace*{\prededicationvspace}
   \begin{#1}
-    \emph{\ptdedication}
+    \beforededication{\dedicationformat\ptdedication}\afterdedication
   \end{#1}
-  \vspace*{\fill}
+  \vspace*{\postdedicationvspace}
 }
 %    \end{macrocode}
 % \end{macro}
@@ -416,14 +465,52 @@
 %
 % Next we setup the table of contents and list of poems:
 %
-% \begin{macro}{\toptitle}
+% \begin{macro}{\listofpoems}
+% \changes{2.0.0}{2013/02/23}{Use custom table for list of poems}
+% \begin{macro}{\resetnumon}
+% \changes{2.0.0}{2013/02/23}{Allow user to reset poem nums on counter change}
+% The \code{\textbackslash listofpoems} command is nothing more than a
+% convenient alias for \code{\textbackslash listofpoem} as defined by the
+% \pkg{tocloft} package. We can reset poem numbering at a given point by
+% redefining the \code{\textbackslash resetnumon} macro. This should probably
+% not be changed by users directly. Instead, use the built in macro
+% \code{\textbackslash resetnumongroup}.
+%    \begin{macrocode}
+\newcommand*{\resetnumon}{}
+\newlistof[\resetnumon]{poem}{top}{\topname}
+\newcommand*{\listofpoems}{\listofpoem}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\topname}
+% \changes{2.0.0}{2013/03/16}{Rename from \code{\textbackslash toptitle}}
 % \begin{macro}{\topentrytype}
-% The value of \code{\textbackslash toptitle} will be rendered atop the Table of
+% \begin{macro}{\toptocentrytype}
+% \changes{2.0.0}{2013/03/07}{Add hook to change ToP entry type in ToC}
+% The value of \code{\textbackslash topname} will be rendered atop the Table of
 % Poems, and \code{\textbackslash topentrytype} will set the default entry type
-% for poems in the TOP.
+% for poems in the TOP. \code{\textbackslash toptocentrytype} sets the default
+% entry type for the TOP in the TOC.
 %    \begin{macrocode}
-\newcommand*{\toptitle}{List of Poems}
+\newcommand*{\topname}{List of Poems}
 \newcommand*{\topentrytype}{subsection}
+\newcommand*{\toptocentrytype}{section}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\listpoemsintoc}
+% \changes{2.0.0}{2013/08/17}{List poems in the table of contents}
+% \begin{macro}{\tocentrytype}
+% \changes{2.0.0}{2013/08/17}{Sets the entry type for poems in the ToC}
+% Using these commands you can cause poems to be listed in the ToC and set the
+% entry type just like the ToP. By default, the ToC entry type is set to
+% \code{\textbackslash topentrytype}.
+%    \begin{macrocode}
+\newcommand*{\listpoemsintoc}{\newcommand*{\@ptlistpoemsintoc}{}}
+\newcommand*{\tocentrytype}{\topentrytype}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
@@ -435,30 +522,9 @@
 %    \begin{macrocode}
 \setcounter{secnumdepth}{-1}
 \setcounter{tocdepth}{2}
-\renewcommand*{\listtablename}{\toptitle}
+\renewcommand*{\listtablename}{\topname}
 %    \end{macrocode}
 %
-% \begin{macro}{\beforetoc}
-% \changes{1.4}{2012/02/18}{Add hook before table of contents}
-% \begin{macro}{\aftertoc}
-% \changes{1.4}{2012/02/18}{Add hook after table of contents}
-% \begin{macro}{\beforetop}
-% \changes{1.4}{2012/02/18}{Add hook before table of poems}
-% \begin{macro}{\aftertop}
-% \changes{1.4}{2012/02/18}{Add hook after table of poems}
-% Several hooks are provided which allow you to insert content before or after
-% the tables:
-%    \begin{macrocode}
-\newcommand{\beforetoc}{}
-\newcommand{\aftertoc}{}
-\newcommand{\beforetop}{}
-\newcommand{\aftertop}{}
-%    \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
 % \begin{macro}{\maketoc}
 % \begin{macro}{\maketop}
 % \begin{macro}{\maketop*}
@@ -482,7 +548,7 @@
 \newcommand*{\@ptmaketopStar}{%
   \cleardoublepage
   \beforetop
-  \listoftables
+  \listofpoems
   \pagestyle{plain}
   \aftertop
   \clearpage
@@ -491,8 +557,8 @@
   \cleardoublepage
   \beforetop
   \phantomsection
-  \addcontentsline{toc}{section}{\toptitle}
-  \listoftables
+  \addcontentsline{toc}{\toptocentrytype}{\topname}
+  \listofpoems
   \pagestyle{plain}
   \aftertop
   \clearpage
@@ -503,12 +569,131 @@
 % \end{macro}
 %
 % \begin{macro}{\numbertop}
-% Placing this command in your document preamble will cause the table of poems
-% to be numbered.
+% \begin{macro}{\numbertoc}
+% \changes{2.0.0}{2012/08/17}{Number poems in the table of contents}
+% Placing one of these commands in your document preamble will cause the table
+% of poems or table of contents to be numbered.
 %    \begin{macrocode}
 \newcommand*{\numbertop}{\newcommand*{\@ptnumbertop}{}}
+\newcommand*{\numbertoc}{\newcommand*{\@ptnumbertoc}{}}
 %    \end{macrocode}
 % \end{macro}
+% \end{macro}
+%
+% \section{Hooks and formatting}
+% \changes{2.0.0}{2013/03/08}{Refactor hooks into new section}
+% A great many commands are provided to act as hooks into various parts of
+% \pkg{poetrytex}. These commands don't do anything initially, but can be
+% redefined to customize the way \pkg{poetrytex} behaves.
+%
+% \subsection{Title page}
+%
+% \begin{macro}{\beforetitle}
+% \changes{2.0.0}{2013/03/08}{Add hook before title}
+% \begin{macro}{\aftertitle}
+% \changes{2.0.0}{2013/03/08}{Add hook after title}
+% \begin{macro}{\beforesubtitle}
+% \changes{2.0.0}{2013/03/08}{Add hook before subtitle}
+% \begin{macro}{\aftersubtitle}
+% \changes{2.0.0}{2013/03/08}{Add hook after subtitle}
+% \begin{macro}{\beforeauthor}
+% \changes{2.0.0}{2013/03/08}{Add hook before author}
+% \begin{macro}{\afterauthor}
+% \changes{2.0.0}{2013/03/08}{Add hook after author}
+% \begin{macro}{\beforedate}
+% \changes{2.0.0}{2013/03/08}{Add hook before date}
+% \begin{macro}{\afterdate}
+% \changes{2.0.0}{2013/03/08}{Add hook after date}
+% These hooks get inserted before or after elements on the title page or
+% dedication. If the element has formatting, they will be inserted outside of
+% the formatted block, but inside of any enclosing environments.
+%    \begin{macrocode}
+\newcommand*{\beforetitle}{}
+\newcommand*{\aftertitle}{}
+\newcommand*{\beforesubtitle}{}
+\newcommand*{\aftersubtitle}{}
+\newcommand*{\beforeauthor}{}
+\newcommand*{\afterauthor}{}
+\newcommand*{\beforedate}{}
+\newcommand*{\afterdate}{}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Dedication}
+%
+% \begin{macro}{\dedicationformat}
+% \changes{2.0.0}{2013/03/08}{Allow customization of dedication format}
+% \begin{macro}{\prededicationvspace}
+% \changes{2.0.0}{2013/03/08}{Add length for setting the pre-dedication vspace}
+% \begin{macro}{\postdedicationvspace}
+% \changes{2.0.0}{2013/03/08}{Add length for setting the post-dedication vspace}
+% \begin{macro}{\beforededication}
+% \changes{2.0.0}{2013/03/08}{Add hook before dedication}
+% \begin{macro}{\afterdedication}
+% \changes{2.0.0}{2013/03/08}{Add hook after dedication}
+% Redefine \code{\textbackslash dedicationformat} to change how the dedicaton
+% text is formatted. You can change the length of the vspace around the
+% dedication using \code{\textbackslash pre} and \code{\textbackslash
+% postdedicationvspace} or use the \code{before} and \code{afterdedication}
+% hooks to insert text around the deciation text.
+%    \begin{macrocode}
+\newcommand*{\dedicationformat}{\normalfont\itshape}
+\newlength{\prededicationvspace}
+\newlength{\postdedicationvspace}
+\setlength{\prededicationvspace}{\fill}
+\setlength{\postdedicationvspace}{\fill}
+\newcommand*{\beforededication}{}
+\newcommand*{\afterdedication}{}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Tables and links}
+%
+% \begin{macro}{\beforetoc}
+% \changes{1.4}{2012/02/18}{Add hook before table of contents}
+% \begin{macro}{\aftertoc}
+% \changes{1.4}{2012/02/18}{Add hook after table of contents}
+% \begin{macro}{\beforetop}
+% \changes{1.4}{2012/02/18}{Add hook before table of poems}
+% \begin{macro}{\aftertop}
+% \changes{1.4}{2012/02/18}{Add hook after table of poems}
+% Several hooks are provided which allow you to insert content before or after
+% the tables:
+%    \begin{macrocode}
+\newcommand{\beforetoc}{}
+\newcommand{\aftertoc}{}
+\newcommand{\beforetop}{}
+\newcommand{\aftertop}{}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Poem group}
+%
+% \begin{macro}{\beforepoemgroup}
+% \changes{2.0.0}{2013/03/09}{Add hook before group}
+% \begin{macro}{\afterpoemgroup}
+% \changes{2.0.0}{2013/03/09}{Add hook after group}
+% The following hooks occur before and after a new poem group.
+%    \begin{macrocode}
+\newcommand*{\beforepoemgroup}{\cleardoublepage}
+\newcommand*{\afterpoemgroup}{\clearpage}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
 %
 % \part{Poems and annotations}
 %
@@ -516,10 +701,22 @@
 % properties out of the way, it's time to move on to the core functionality of
 % \pkg{poetrytex}: displaying and organizing poems!
 %
+% \begin{macro}{\theincipit}
+% \changes{2.0.0}{2013/03/06}{Allow the user to insert the incipit}
+% This will expand to the incipit for the current poem if one has been declared.
+%
+%    \begin{macrocode}
+\newcommand*{\theincipit}{%
+  \csname @poem\arabic{absolutepoemnum} incipit\endcsname%
+}
+%    \end{macrocode}
+% \end{macro}
+%
 % \section{The \code{poem} environment}
 %
 % \begin{environment}{poem}
 % \changes{1.2}{2012/09/20}{Use \code{hypertarget} instead of \code{label}}
+% \changes{2.0.0}{2013/08/15}{Prevent orphan / widow lines in stanzas (\href{https://github.com/SamWhited/poetrytex/issues/7}{Issue \#7)}}
 % Inserting a poem or other writing into your anthology is accomplished by
 % wrapping it in the \code{poem} environment. This environment takes in two
 % arguments, the title and subtitle (or author, date, etc.) of the poem.
@@ -575,6 +772,60 @@
 % \end{poem}
 % \end{Example}
 %
+% \begin{macro}{\incipit}
+% \changes{2.0.0}{2013/03/06}{Allow the user to declare an incipit}
+% An incipit can be declared within the poem environment using the
+% \code{\textbackslash incipit} command. This will reprint the first argument so
+% you don't have to write your first line twice. This is useful for untitled
+% poems as you can put their incipit in the ToP in place of a default title.
+%    \begin{macrocode}
+\newcommand*{\incipit}[1]{%
+  \global\expandafter\def%
+    \csname%
+      @poem\arabic{absolutepoemnum} incipit%
+    \endcsname{##1}%
+  ##1%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% An untitled poem with a default title and an incipit in the ToP might look
+% something like this:
+%
+% \begin{Example}
+% \begin{Verbatim}
+% \ptusedefaulttitles
+% \ptuseincipits
+% \begin{poem}{}{Traditional}
+% \incipit{Media vita in morte%
+%   sumus};\\*
+% Quem qu\ae rimus adjutorem nisi%
+%   te, Domine?\\*
+% Qui pro peccatis nostris juste%
+%   irasceris\\*
+% Sancte Deus, Sancte fortis,%
+%   Sancte et misericors
+%   Salvator,\\*
+% Amar\ae morti ne tradas nos.
+% \end{poem}
+% \end{Verbatim}
+% \columnbreak
+% \ptusedefaulttitles
+% \ptuseincipits
+% \begin{poem}{}{Traditional}
+% \incipit{Media vita in morte%
+%   sumus};\\*
+% Quem qu\ae rimus adjutorem nisi%
+%   te, Domine?\\*
+% Qui pro peccatis nostris juste%
+%   irasceris\\*
+% Sancte Deus, Sancte fortis,%
+%   Sancte et misericors%
+%   Salvator,\\*
+% Amar\ae morti ne tradas nos.
+% \end{poem}
+% \end{Example}
+%
 % Now we render the page header, title, and the actual poem:
 %    \begin{macrocode}
   \poetryheadings
@@ -586,19 +837,44 @@
   \fi
   \vspace*{\poemvspace}
   \begin{\pttitleenv}
+    \refstepcounter{poem}%
     \phantomsection%
-    \addcontentsline{lot}{\topentrytype}{%
+    \addcontentsline{top}{\topentrytype}{%
       \ifx\@ptnumbertop\@ptundefined%
         \relax%
       \else%
         \toppoemnum%
       \fi%
       \ifx&#2&%
-        \ptdefaulttitle%
+        \ifx\@ptuseincipits\@ptundefined%
+          \ptdefaulttitle%
+        \else%
+          {\incipittopformat \theincipit}%
+        \fi%
       \else%
         #2%
       \fi%
     }%
+    \ifx\@ptlistpoemsintoc\@ptundefined%
+      \relax%
+    \else%
+      \addcontentsline{toc}{\tocentrytype}{%
+        \ifx\@ptnumbertoc\@ptundefined%
+          \relax%
+        \else%
+          \tocpoemnum%
+        \fi%
+        \ifx&#2&%
+          \ifx\@ptuseincipits\@ptundefined%
+            \ptdefaulttitle%
+          \else%
+            {\incipittocformat \theincipit}%
+          \fi%
+        \else%
+          #2%
+        \fi%
+      }%
+    \fi%
     \hypertarget{\@ptpoemlabeltext\arabic{absolutepoemnum}}{}
     {\poemtitleformat%
       \ifx\@ptnumberpoems\@ptundefined
@@ -611,14 +887,15 @@
           \relax%
         \else%
           \hspace*{\pttitleleftspace}\ptdefaulttitle%
-          \hspace*{\pttitlerightspace}\\%
+          \hspace*{\pttitlerightspace}\\*%
         \fi%
       \else
-        \hspace*{\pttitleleftspace}#2\hspace*{\pttitlerightspace}\\%
+        \hspace*{\pttitleleftspace}#2\hspace*{\pttitlerightspace}\\*%
       \fi%
     }%
     \hspace*{\ptsubtitleleftspace}#3\hspace*{\ptsubtitlerightspace}
   \end{\pttitleenv}
+  \nopagebreak
   \begin{\@ptwrapenvironment}
     \begingroup\setlength{\parskip}{\stanzaparskip}%
 }{%
@@ -664,7 +941,10 @@
 % defined at any point in your document to change how numbering works, or to
 % turn on numbering from that point forward.
 %    \begin{macrocode}
-\newcommand*{\resetnumongroup}{\newcommand*{\@ptresetnumongroup}{}}
+\newcommand*{\resetnumongroup}{%
+  \newcommand*{\@ptresetnumongroup}{}%
+  \renewcommand*{\resetnumon}{poemgroupnum}%
+}
 \newcommand*{\numberpoems}{\newcommand*{\@ptnumberpoems}{}}
 %    \end{macrocode}
 % \end{macro}
@@ -706,15 +986,19 @@
 % \changes{1.4}{2012/02/18}{Add hook for poem number formatting}
 % \begin{macro}{\toppoemnum}
 % \changes{1.4}{2012/02/18}{Add hook for Table of Poems poem number formatting}
-% These commands are used to insert the poem number into the poem title and the
-% table of poems respectively. By redefining them you can customize how the
-% numbering looks.
+% \begin{macro}{\tocpoemnum}
+% \changes{2.0.0}{2013/08/17}{Add hook for Table of Contents poem number formatting}
+% These commands are used to insert the poem number into the poem title, the
+% table of poems, and the table of contents respectively. By redefining them you
+% can customize how the numbering looks.
 %    \begin{macrocode}
-\newcommand*{\titlepoemnum}{\arabic{poemnum}\\}
+\newcommand*{\titlepoemnum}{\arabic{poemnum}\\*}
 \newcommand*{\toppoemnum}{\arabic{poemnum}.\ }
+\newcommand*{\tocpoemnum}{\toppoemnum}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
+% \end{macro}
 %
 % If we want to use uppercase roman numerals on the poems, and lowercase roman
 % numerals in the \code{\hyperlink{POETRYTEX:TOP}{Table of Poems}}, we could
@@ -867,6 +1151,18 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{\incipittopformat}
+% \changes{2.0.0}{2013/02/23}{Add hook for incipit formatting in the ToP}
+% \begin{macro}{\incipittocformat}
+% \changes{2.0.0}{2013/08/17}{Add hook for incipit formatting in the ToC}
+% Similarly we can change how the incipit is rendered in the Table of Poems or
+% Table of Contents:
+%    \begin{macrocode}
+\newcommand*{\incipittopformat}{\itshape}
+\newcommand*{\incipittocformat}{\incipittopformat}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
 %
 % If you want a stylistic marker between two poems, or between sections
 % or stanzas within a poem, the following commands are your friend.
@@ -1000,47 +1296,34 @@
 % to refer to it later.
 %    \begin{macrocode}
 \newcommand*{\ptgroup}{}
-\newcommand*{\poemgroup}{%
-  \@ifstar{%
-    \@ptpoemgroupStar
-  }{%
-    \@ptpoemgroupNoStar
-  }
-}
-\newcommand*{\@ptpoemgroupStar}[1]{%
+\newcommand*{\poemgroup}[1]{%
+  \addtocounter{poemgroupnum}{1}
   \ifx\@ptresetnumongroup\@ptundefined
     \relax
   \else
     \setcounter{poemnum}{0}
     \setcounter{untitledpoemnum}{0}
   \fi
-  \cleardoublepage
-  \vspace*{\fill}
+  \beforepoemgroup
+  \vspace*{\pregroupvspace}
   \renewcommand*{\ptgroup}{#1}
-  \pagestyle{empty}
-  \begin{center}
-    \section*{#1}
-  \end{center}
-  \vspace*{\fill}
-  \clearpage
+  \pagestyle{\grouppagestyle}
+  \begin{\ptdefaultgroupenv}
+    \@ifstar{%
+      \@ptpoemgroupStar{#1}
+    }{%
+      \@ptpoemgroupNoStar{#1}
+    }
+  \end{\ptdefaultgroupenv}
+  \vspace*{\postgroupvspace}
+  \afterpoemgroup
+}
+\newcommand*{\@ptpoemgroupStar}[1]{%
+  \section*{#1}
 }
 \newcommand*{\@ptpoemgroupNoStar}[1]{%
-  \ifx\@ptresetnumongroup\@ptundefined
-    \relax
-  \else
-    \setcounter{poemnum}{0}
-    \setcounter{untitledpoemnum}{0}
-  \fi
-  \cleardoublepage
-  \vspace*{\fill}
-  \renewcommand*{\ptgroup}{#1}
-  \pagestyle{empty}
-  \begin{center}
-    \section{#1}
-    \addcontentsline{lot}{section}{#1}
-  \end{center}
-  \vspace*{\fill}
-  \clearpage
+  \section{#1}
+  \addcontentsline{top}{section}{#1}
 }
 %    \end{macrocode}
 % \end{macro}
@@ -1066,6 +1349,7 @@
   \poetryheadings
   \begin{\@ptwrapenvironment}
   \subsection{#2}
+  \nopagebreak
 }{%
 
   \end{\@ptwrapenvironment}
@@ -1084,7 +1368,7 @@
 % \clearpage
 % \setcounter{IndexColumns}{2}
 % \phantomsection
-% \addcontentsline{toc}{section}{Index}
+% \addcontentsline{toc}{part}{Index}
 % \PrintIndex
 %
 % \makeatletter
@@ -1095,9 +1379,10 @@
 % \makeatother
 % \clearpage
 % \phantomsection
-% \addcontentsline{toc}{section}{Change History}
+% \addcontentsline{toc}{part}{Change History}
 % \PrintChanges
 % \changes{1.1}{2012/07/19}{Added an example table of poems}
+% \renewcommand*{\toptocentrytype}{part}
 % \renewcommand*{\beforetop}{\hypertarget{POETRYTEX:TOP}{}}
 % \maketop
 % \Finale