From 35e43230f4164d6cd6df0258ea993101bcb6b5ef Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 12 Dec 2014 23:11:04 +0000 Subject: poetrytex (12dec14) git-svn-id: svn://tug.org/texlive/trunk@35807 c570f23f-e606-0410-a88d-b1316a301751 --- .../source/latex/poetrytex/poetrytex.dtx | 219 ++++++++++++++------- 1 file changed, 143 insertions(+), 76 deletions(-) (limited to 'Master/texmf-dist/source/latex/poetrytex') 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] %% % %<*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} -- cgit v1.2.3