poetrytex (12dec14)

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

1 files changed, 143 insertions, 76 deletions

diff --git a/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx b/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx
index 04997dcd3a5..8c0a3b1c3fa 100644
--- a/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx
+++ b/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx
@@ -23,9 +23,9 @@
 
   ___________
   Maintainer: Sam Whited
-  Website:    https://samwhited.com
+  Website:    https://blog.samwhited.com
   Contact:    sam@samwhited.com
-  Public key: 0xEC2C9934
+  Public key: 0x54083AE104EA7AD3
 
   This work consists of this file poetrytex.dtx
             and the derived files poetrytex.sty
@@ -55,7 +55,7 @@
 %
 %<*poetrytex>
 \NeedsTeXFormat{LaTeX2e}[1994/06/01]
-\ProvidesPackage{poetrytex}[2013/08/17]
+\ProvidesPackage{poetrytex}[2014/12/12]
 %</poetrytex>%
 %
 %<*driver>
@@ -175,17 +175,18 @@
 % \paragraph{Building}
 %
 % Before building \pkg{poetrytex} you should verify that the following
-% dependencies are installed:
+% dependencies are installed (note that you do not need to include these lines
+% in your project; just install the packages mentioned):
 % \changes{1.0}{2012/07/18}{Removed \pkg{fontspec} / \pkg{xelatex} dependency}
 % \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)}
+% \changes{3.0.0}{2014/12/12}{Don't load hyperref by default}
 %    \begin{macrocode}
 \RequirePackage{expl3}
 \RequirePackage{tocloft}
-\AtEndOfPackage{\RequirePackage{hyperref}}
 %    \end{macrocode}
 % Once you have all the required packages, building \pkg{poetrytex} from source
 % can be accomplished in multiple ways. If the Makefile is present running
@@ -217,34 +218,33 @@
 %
 % \hypertarget{POETRYTEX:OPTIONS}{}
 % \changes{1.2}{2012/10/03}{Added various package options}
-% \begin{macro}{verse}
+% \changes{3.0.0}{2014/12/11}{Remove the redundant `clearpageafterpoems' option}
+% \changes{3.0.0}{2014/12/12}{Don't pass unrecognized options to hyperref}
 % \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{macro}{clearpageafterannotation}
+% \changes{3.0.0}{2014/12/11}{Add an option to clear the page after annotations}
+% The package can also be loaded with any of the following options. If you're
+% unsure what an option does, check the documentation for the macro that is
+% associated with it in the code below:
 %    \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{usedefaulttitles}{\usedefaulttitles}
+\DeclareOption{useincipits}{\useincipits}
 \DeclareOption{clearpageafterpoem}{\clearpageafterpoem}
-\DeclareOption{clearpageafterpoems}{\clearpageafterpoem}
-\DeclareOption*{%
-  \PassOptionsToPackage{\CurrentOption}{hyperref}%
-}
+\DeclareOption{clearpageafterannotation}{\clearpageafterannotation}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
@@ -254,7 +254,6 @@
 % \end{macro}
 % \end{macro}
 % \end{macro}
-% \end{macro}
 %
 % For instance:
 %
@@ -348,8 +347,8 @@
 % 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{%
-% poetrytex} while \code{poemnum} may sometimes be reset to 0 (at the beginning
-% of a new \code{poemgroup} for instance). The \code{untitledpoemnum} and
+% poetrytex} while \code{poemnum} will be be reset to 0 at the beginning of a
+% new \code{poemgroup}. The \code{untitledpoemnum} and
 % \code{absoluteuntitledpoemnum} are similar except that they are only
 % incremented when the poem does not have a title.
 %    \begin{macrocode}
@@ -409,28 +408,38 @@
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}{\ptusedefaulttitles}
+% \begin{macro}{\usedefaulttitles}
+% \changes{3.0.0}{2014/12/12}{Change name of \code{\textbackslash ptusedefaulttitles} to \code{\textbackslash usedefaulttitles}}
+% \begin{macro}{\nousedefaulttitles}
+% \changes{3.0.0}{2014/12/12}{Add macro to stop using default titles}
 % \begin{macro}{\ptdefaulttitle}
 % \changes{1.4}{2013/02/12}{Add a default poem title}
-% \begin{macro}{\ptuseincipits}
+% \begin{macro}{\useincipits}
 % \changes{2.0.0}{2013/03/06}{Add option for using incipits in the ToP}
+% \changes{3.0.0}{2014/12/12}{Change name of \code{\textbackslash ptuseincipits} to \code{\textbackslash useincipits}}
+% \begin{macro}{\nouseincipits}
+% \changes{3.0.0}{2014/12/12}{Add macro to stop using incipits}
 % The default title for poems that don't include one. If
-% \code{\textbackslash ptusedefaulttitles} is called the default title will be
+% \code{\textbackslash usedefaulttitles} 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*{\usedefaulttitles}{\newcommand*{\@ptusedefaulttitles}{}}
+\newcommand*{\nousedefaulttitles}{\let\@ptusedefaulttitles\@ptundefined}
 \newcommand*{\ptdefaulttitle}{%
   Untitled No. \arabic{absoluteuntitledpoemnum}%
 }
-\newcommand*{\ptuseincipits}{\newcommand*{\@ptuseincipits}{}}
+\newcommand*{\useincipits}{\newcommand*{\@ptuseincipits}{}}
+\newcommand*{\nouseincipits}{\let\@ptuseincipits\@ptundefined}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
 % \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \begin{macro}{\ptdefaultenv}
 % \changes{1.2}{2012/09/20}{Added an option to change the default environment}
@@ -551,9 +560,7 @@
 % 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}.
+% redefining the \code{\textbackslash resetnumon} macro.
 %    \begin{macrocode}
 \newcommand*{\resetnumon}{}
 \newlistof[\resetnumon]{poem}{top}{\topname}
@@ -582,6 +589,8 @@
 %
 % \begin{macro}{\listpoemsintoc}
 % \changes{2.0.0}{2013/08/17}{List poems in the table of contents}
+% \begin{macro}{\nolistpoemsintoc}
+% \changes{3.0.0}{2014/12/12}{Add macro to stop poems being listed in the ToC}
 % \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
@@ -589,10 +598,12 @@
 % \code{\textbackslash topentrytype}.
 %    \begin{macrocode}
 \newcommand*{\listpoemsintoc}{\newcommand*{\@ptlistpoemsintoc}{}}
+\newcommand*{\nolistpoemsintoc}{\let\@ptlistpoemsintoc\@ptundefined}
 \newcommand*{\tocentrytype}{\topentrytype}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
+% \end{macro}
 %
 % We then set the \code{secnumdepth} and \code{tocdepth} counters to disable
 % chapter, section, and subsection numbering, and to limit the maximum depth of
@@ -649,14 +660,23 @@
 % \begin{macro}{\numbertop}
 % \begin{macro}{\numbertoc}
 % \changes{2.0.0}{2012/08/17}{Number poems in the table of contents}
+% \begin{macro}{\nonumbertop}
+% \changes{3.0.0}{2014/12/11}{Add command to stop numbering the ToP}
+% \begin{macro}{\nonumbertoc}
+% \changes{3.0.0}{2014/12/11}{Add command to stop numbering the ToC}
 % Placing one of these commands in your document preamble will cause the table
-% of poems or table of contents to be numbered.
+% of poems or table of contents to be numbered (or stop them from being
+% numbered).
 %    \begin{macrocode}
 \newcommand*{\numbertop}{\newcommand*{\@ptnumbertop}{}}
 \newcommand*{\numbertoc}{\newcommand*{\@ptnumbertoc}{}}
+\newcommand*{\nonumbertop}{\let\@ptnumbertop\@ptundefined}
+\newcommand*{\nonumbertoc}{\let\@ptnumbertoc\@ptundefined}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \section{Hooks and formatting}
 % \changes{2.0.0}{2013/03/08}{Refactor hooks into new section}
@@ -892,8 +912,8 @@
 %
 % \begin{Example}
 % \begin{Verbatim}
-% \ptusedefaulttitles
-% \ptuseincipits
+% \usedefaulttitles
+% \useincipits
 % \renewcommand*{\ptdefaulttitle}{%
 % Untitled \textnumero\
 % \arabic{absoluteuntitledpoemnum}%
@@ -912,8 +932,8 @@
 % \end{poem}
 % \end{Verbatim}
 % \columnbreak
-% \ptusedefaulttitles
-% \ptuseincipits
+% \usedefaulttitles
+% \useincipits
 % \renewcommand*{\ptdefaulttitle}{%
 % Untitled \textnumero\
 % \arabic{absoluteuntitledpoemnum}%
@@ -984,7 +1004,11 @@
         \fi%
       }%
     \fi%
-    \hypertarget{\@ptpoemlabeltext\arabic{absolutepoemnum}}{}
+    \ifx\hypertarget\@ptundefined%
+      \relax%
+    \else%
+      \hypertarget{\@ptpoemlabeltext\arabic{absolutepoemnum}}{}%
+    \fi%
     {\poemtitleformat%
       \ifx\@ptnumberpoems\@ptundefined
         \relax
@@ -1009,12 +1033,12 @@
     \begingroup\setlength{\parskip}{\stanzaparskip}%
 }{%
     \endgroup
-  \end{\@ptwrapenvironment}
-  \ifx\@ptclearpageafterpoem\@ptundefined
-    \relax
-  \else
-    \clearpage
-  \fi
+  \end{\@ptwrapenvironment}%
+  \ifx\@ptclearpageafterpoem\@ptundefined%
+    \relax%
+  \else%
+    \clearpage%
+  \fi%
 }
 %    \end{macrocode}
 % \end{environment}
@@ -1043,20 +1067,16 @@
 %
 % \subsection{Numbering}
 %
-% \begin{macro}{\resetnumongroup}
 % \begin{macro}{\numberpoems}
-% These commands determine if the non-absolute \code{poemnum} and
-% \code{annotationnum} counters should be reset when the poem group changes and
-% if the poems should display their number above the title. Generally these
-% should be called from the preamble but they can be defined at any point in
-% your document to change how numbering works, or to turn on numbering from that
-% point forward.
+% \begin{macro}{\nonumberpoems}
+% \changes{3.0.0}{2014/12/11}{Add command to stop numbering poems}
+% This command determines if the poems should display their number above the
+% title. Generally these should be called from the preamble but they can be
+% 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}{}%
-  \renewcommand*{\resetnumon}{poemgroupnum}%
-}
 \newcommand*{\numberpoems}{\newcommand*{\@ptnumberpoems}{}}
+\newcommand*{\nonumberpoems}{\let\@ptnumberpoems\@ptundefined}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
@@ -1095,16 +1115,18 @@
 %
 % \begin{macro}{\titlepoemnum}
 % \changes{1.4}{2012/02/18}{Add hook for poem number formatting}
+% \changes{3.0.0}{2014/12/10}{Use absolute poem nums by default}
 % \begin{macro}{\toppoemnum}
 % \changes{1.4}{2012/02/18}{Add hook for Table of Poems poem number formatting}
+% \changes{3.0.0}{2014/12/10}{Use absolute poem nums by default}
 % \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*{\toppoemnum}{\arabic{poemnum}.\ }
+\newcommand*{\titlepoemnum}{\arabic{absolutepoemnum}\\*}
+\newcommand*{\toppoemnum}{\arabic{absolutepoemnum}.\ }
 \newcommand*{\tocpoemnum}{\toppoemnum}
 %    \end{macrocode}
 % \end{macro}
@@ -1178,12 +1200,24 @@
 % \end{macro}
 %
 % \begin{macro}{\clearpageafterpoem}
-% \code{clearpageafterpoem} causes the page to be cleared after every poem
-% environment.
+% \begin{macro}{\noclearpageafterpoem}
+% \begin{macro}{\clearpageafterannotation}
+% \changes{3.0.0}{2014/12/11}{Make clearing the page after an annotation optional behavior}
+% \begin{macro}{\noclearpageafterannotation}
+% \changes{3.0.0}{2014/12/11}{Add command to stop page clearing after annotations}
+% \code{clearpageafterpoem} and \code{clearpageafterannotation} cause the page
+% to be cleared after every poem environment or annotation environment
+% respectively.
 %    \begin{macrocode}
 \newcommand*{\clearpageafterpoem}{\newcommand*{\@ptclearpageafterpoem}{}}
+\newcommand*{\clearpageafterannotation}{\newcommand*{\@ptclearpageafterannotation}{}}
+\newcommand*{\noclearpageafterpoem}{\let\@ptclearpageafterpoem\@ptundefined}
+\newcommand*{\noclearpageafterannotation}{\let\@ptclearpageafterannotation\@ptundefined}
 %    \end{macrocode}
 % \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \begin{macro}{\ptgap}
 % \begin{macro}{\ptind}
@@ -1321,15 +1355,16 @@
 %
 % \begin{macro}{\ptspacergap}
 % \begin{macro}{\ptspacerchar}
-% \begin{macro}{\ptspacernum}
+% \begin{macro}{ptspacernum}
+% \changes{3.0.0}{2014/12/10}{Change ptspacernum into a counter}
 % The \code{ptspacergap} length is the indentation of the spacer, and\code{%
 % \textbackslash ptspacerchar} is the actual character that will be printed
-% \code{\textbackslash ptspacernum} times.
+% \code{ptspacernum} times.
 %    \begin{macrocode}
 \newlength{\ptspacergap}
 \setlength{\ptspacergap}{4em}
 \newcommand*{\ptspacerchar}{\S}
-\newcommand*{\ptspacernum}{3}
+\newcounter{ptspacernum}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
@@ -1350,11 +1385,11 @@
 }
 \newcommand*{\@ptspacerStar}{%
   \hspace*{\ptspacergap}%
-  \@ptrepeat{\ptspacernum}{\ptspacerchar}%
+  \@ptrepeat{\value{ptspacernum}}{\ptspacerchar}%
 }
 \newcommand*{\@ptspacerNoStar}{%
   \hspace{\ptspacergap}%
-  \@ptrepeat{\ptspacernum}{\ptspacerchar}%
+  \@ptrepeat{\value{ptspacernum}}{\ptspacerchar}%
 }
 \ExplSyntaxOn
 \cs_new_eq:NN \@ptrepeat \prg_replicate:nn
@@ -1368,7 +1403,7 @@
 % \begin{Example}
 % \begin{Verbatim}
 % \renewcommand{\ptspacerchar}{\o}
-% \renewcommand{\ptspacernum}{2}
+% \setcounter{ptspacernum}{2}
 % \begin{poem}{The Love Song%
 % of J. Alfred Prufrock}
 % {T.S. Eliot}
@@ -1390,7 +1425,7 @@
 % \end{Verbatim}
 % \columnbreak
 % \renewcommand{\ptspacerchar}{\o}
-% \renewcommand{\ptspacernum}{2}
+% \setcounter{ptspacernum}{2}
 % \begin{poem}{The Love Song%
 % of J. Alfred Prufrock}
 % {T.S. Eliot}
@@ -1422,42 +1457,52 @@
 % \begin{macro}{\linktopoem}
 % \changes{1.1}{2012/07/24}{Fix spacing and multiple use issues}
 % \changes{1.2}{2012/09/20}{Use \code{hyperlink} when linking to a poem}
+% \changes{3.0.0}{2014/12/12}{Don't create links unless \pkg{hyperref} is loaded}
 % We can \emph{\linktopoem[1]{link}} \emph{\linktopoem[2]{to}}%
 % \emph{\linktopoem[3]{poems}} easily enough by providing \code{linktopoem} with
 % the text for the link and, optionally, the number of the poem to link to. If
 % only one argument is given it is used as both the link destination and text.
+% This macro only works if the \pkg{hyperref} package is loaded; otherwise, text
+% is just passed through.
 %    \begin{macrocode}
 \newcommand*{\linktopoem}[2][ptnull]{%
-  \ifx{#1}{ptnull}
-    \hyperlink{\@ptpoemlabeltext#2}{#2}\relax
+  \ifx\hyperlink\@ptundefined
+    #2\relax%
   \else
-    \hyperlink{\@ptpoemlabeltext#1}{#2}\relax
+    \ifx{#1}{ptnull}
+      \hyperlink{\@ptpoemlabeltext#2}{#2}\relax
+    \else
+      \hyperlink{\@ptpoemlabeltext#1}{#2}\relax
+    \fi
   \fi
 }
 %    \end{macrocode}
 % \end{macro}
 %
+% \changes{3.0.0}{2014/12/10}{Always reset poemnum on group change}
 % \begin{macro}{\ptgroup}
 % \begin{macro}{\poemgroup}
 % \begin{macro}{\poemgroup*}
+% \begin{macro}{\setpoemgroup}
+% \changes{3.0.0}{2014/12/12}{Add macro to change group without creating a titlepage}
+% \begin{macro}{\setpoemgroup*}
+% \changes{3.0.0}{2014/12/12}{Add macro to change group without creating a titlepage or adding group to the ToC/ToP}
 % Dividing poems up into groups can be accomplished with the \code{%
 % \textbackslash poemgroup} command. The command creates a title-page for the
 % group at the current location and adds entries to the ToP and ToC unless the
 % starred version of the command is used. The \code{\textbackslash ptgroup}
 % command will always contain a reference to the current group in case you need
-% to refer to it later.
+% to refer to it later. If you want to change the group, but don't want to
+% create a title page, use the \code{\textbackslash setpoemgroup} command. The
+% starred version also doesn't add an entry in the ToP and ToC.
 %    \begin{macrocode}
 \newcommand*{\ptgroup}{}
 \newcommand*{\poemgroup}[1]{%
   \addtocounter{poemgroupnum}{1}
-  \ifx\@ptresetnumongroup\@ptundefined
-    \relax
-  \else
-    \setcounter{poemnum}{0}
-    \setcounter{untitledpoemnum}{0}
-    \setcounter{titledpoemnum}{0}
-    \setcounter{annotationnum}{0}
-  \fi
+  \setcounter{poemnum}{0}
+  \setcounter{untitledpoemnum}{0}
+  \setcounter{titledpoemnum}{0}
+  \setcounter{annotationnum}{0}
   \beforepoemgroup
   \vspace*{\pregroupvspace}
   \renewcommand*{\ptgroup}{#1}
@@ -1479,10 +1524,29 @@
   \section{#1}
   \addcontentsline{top}{section}{#1}
 }
+\newcommand*{\setpoemgroup}[1]{%
+  \addtocounter{poemgroupnum}{1}
+  \setcounter{poemnum}{0}
+  \setcounter{untitledpoemnum}{0}
+  \setcounter{titledpoemnum}{0}
+  \setcounter{annotationnum}{0}
+  \renewcommand*{\ptgroup}{#1}
+  \@ifstar{%
+    \relax%
+  }{%
+    \@ptsetpoemgroupNoStar{#1}
+  }
+}
+\newcommand*{\@ptsetpoemgroupNoStar}[1]{%
+  \addcontentsline{top}{section}{#1}
+  \addcontentsline{toc}{section}{#1}
+}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
 % \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \section{The \code{annotation} environment}
 %
@@ -1508,9 +1572,12 @@
   \subsection{#2}
   \nopagebreak
 }{%
-
-  \end{\@ptwrapenvironment}
-  \clearpage
+  \end{\@ptwrapenvironment}%
+  \ifx\@ptclearpageafterannotation\@ptundefined%
+    \relax%
+  \else%
+    \clearpage%
+  \fi%
 }
 %    \end{macrocode}
 % \end{environment}