summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/poetrytex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-12-12 23:11:04 +0000
committerKarl Berry <karl@freefriends.org>2014-12-12 23:11:04 +0000
commit35e43230f4164d6cd6df0258ea993101bcb6b5ef (patch)
tree70df22455f252619c28f3d64e32230e3ce2e199b /Master/texmf-dist/source/latex/poetrytex
parent9a0113b42082225c611243ab9dbfecf28bcc1923 (diff)
poetrytex (12dec14)
git-svn-id: svn://tug.org/texlive/trunk@35807 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/poetrytex')
-rw-r--r--Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx219
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}