From 3045d9add41e90eba12baa4f6449b6669a43d2b9 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Sat, 23 Aug 2014 22:47:09 +0000
Subject: poetrytex (23aug14)

git-svn-id: svn://tug.org/texlive/trunk@35028 c570f23f-e606-0410-a88d-b1316a301751
---
 .../source/latex/poetrytex/poetrytex.dtx           | 341 ++++++++++++++-------
 1 file changed, 236 insertions(+), 105 deletions(-)

(limited to 'Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx')

diff --git a/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx b/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx
index e5cc0c0e90d..04997dcd3a5 100644
--- a/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx
+++ b/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx
@@ -35,7 +35,6 @@
 \askforoverwritefalse
 
 \generate{\file{poetrytex.sty}{\from{poetrytex.dtx}{poetrytex}}}
-\generate{\file{poetrytex-style.sty}{\from{poetrytex.dtx}{doc-style}}}
 
 \obeyspaces
 \Msg{****************************************************}
@@ -56,13 +55,46 @@
 %
 %<*poetrytex>
 \NeedsTeXFormat{LaTeX2e}[1994/06/01]
-\ProvidesPackage{poetrytex}[2013/02/13]
+\ProvidesPackage{poetrytex}[2013/08/17]
 %</poetrytex>%
 %
 %<*driver>
 \documentclass[a4paper]{ltxdoc}
-\usepackage{poetrytex-style}
-\usepackage{poetrytex}
+\usepackage[pdfborder=0, bookmarks, colorlinks=false, hidelinks]{hyperref}
+\usepackage{fancyvrb,hologo,framed,multicol,tipa,url,textcomp,poetrytex}
+\usepackage[parfill]{parskip}
+
+\fvset{gobble=2}
+
+\newenvironment{Example}{%
+  \begingroup\setlength{\columnseprule}{.4pt}
+  \begin{minipage}{\textwidth}
+  \begin{multicols}{2}
+}{
+  \end{multicols}
+  \end{minipage}
+  \endgroup
+}
+
+\newcommand*{\gitdescribe}{%
+  \immediate\write18{%
+    rm -f gitdescribe.tex 2> /dev/null; (git describe --tags --dirty ||%
+      echo "v0.0.0") 2> /dev/null > gitdescribe.tex
+  }%
+  \InputIfFileExists{gitdescribe.tex}{}{}\unskip%
+  \immediate\write18{%
+    rm -f gitdescribe.tex 2> /dev/null
+  }%
+}
+
+\newcommand\XeLaTeX{\hologo{XeLaTeX}}
+
+\newcommand*\name[1]{\textsc{#1}}
+\newcommand*\fname[1]{\textsf{#1}}
+\newcommand*\pkg[1]{\textsf{#1}}
+\newcommand*\code[1]{\texttt{#1}}
+
+\renewcommand\partname{Part}
 \EnableCrossrefs
 \CodelineIndex
 \RecordChanges
@@ -73,11 +105,11 @@
 %
 % \fi
 %
-% \GetFileInfo{poetrytex.dtx}
+% \GetFileInfo{\jobname.dtx}
 % \makeatletter
 % \errorcontextlines=999
 %
-% \title{The \textsf{poetrytex} package}
+% \title{The \textsf{\jobname} package}
 % \author{
 %   \name{Sam Whited}\\*
 %   \texttt{sam@samwhited.com}
@@ -104,7 +136,8 @@
 % (generated via a modified version of Jeremy Ashkenas' literate programming
 % tool `docco'). However, as the source and scope of the project grew I decided
 % to move away from docco and start working on a proper package that would use
-% more traditional \TeX-style docs.
+% more traditional \TeX-style docs. As of version 2.0.0, I began using
+% \href{https://semver.org}{semantic versioning} to track releases.
 %
 % \subsection{License / about the source}
 %
@@ -123,11 +156,15 @@
 % \subsection{Acknowledgements}
 %
 % A special thanks is in order for Brittany Taylor. Though she probably has no
-% idea what \TeX\ is or that this project even exists it is due mostly to her
-% influence that it ever got off the ground.
+% idea what \TeX\ is, or that this project even exists, it is due mostly to her
+% influence that it ever got off the ground. Secondly: to Sarah Snyder, who
+% helped me to start writing again after many wasted years, and is always
+% obliging when I want to lose at Scrabble.
 %
 % \StopEventually{}
 % \changes{1.0}{2012/07/18}{Converted package to dtx}
+% \changes{2.1.0}{2013/09/04}{Removed \fname{poetrytex-style.sty} (documentation
+% style)}
 %
 % \section{Package building and loading}
 %
@@ -225,7 +262,6 @@
 %   \usepackage[numberpoems,clearpageafterpoem]{poetrytex}
 % \end{Verbatim}
 %
-%
 % \part{Document setup and structure}
 %
 % The \pkg{poetrytex} package is fairly simple as far as \TeX\ packages go, so
@@ -303,6 +339,10 @@
 % \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 track of untitled poems}
+% \begin{macro}{titledpoemnum}
+% \changes{2.1.0}{2013/09/01}{Create a new counter to track titled poems}
+% \begin{macro}{absolutetitledpoemnum}
+% \changes{2.1.0}{2013/09/01}{Create a new counter to track titled 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
@@ -317,6 +357,8 @@
 \newcounter{absolutepoemnum}
 \newcounter{untitledpoemnum}
 \newcounter{absoluteuntitledpoemnum}
+\newcounter{titledpoemnum}
+\newcounter{absolutetitledpoemnum}
 \newcounter{poemgroupnum}
 %    \end{macrocode}
 % \end{macro}
@@ -324,6 +366,8 @@
 % \end{macro}
 % \end{macro}
 % \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \begin{macro}{\poemvspace}
 % \changes{1.4}{2013/02/11}{Allow whitespace before every poem}
@@ -423,6 +467,22 @@
 % \end{macro}
 % \end{macro}
 %
+% \subsection{Annotation config}
+%
+% \begin{macro}{annotationnum}
+% \changes{2.1.0}{2013/09/04}{Create a new counter to track annotations}
+% \begin{macro}{absoluteannotationnum}
+% \changes{2.1.0}{2013/09/04}{Create a new counter to track annotations}
+% Like their poem counterparts, these counters are incremented each time an
+% annotation is created and the non-absolute version may be reset when the poem
+% group changes.
+%    \begin{macrocode}
+\newcounter{annotationnum}
+\newcounter{absoluteannotationnum}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
 % \begin{macro}{\ptannotationenv}
 % \changes{1.3}{2012/10/30}{Added an option to change the default annotation
 % environment}
@@ -444,9 +504,9 @@
 % redefine \code{\textbackslash ptdedication} to change the dedication text.
 %
 % To create a dedication page, the \code{\textbackslash makededication} command
-% can be called. By default, this command aligns everything to the right,
-% however, by adding an optional argument you can specify any environment to
-% wrap the dedication in.
+% can be called. By default, this command aligns everything to the right using
+% the \textsf{flushright} environment, however, by adding an optional argument
+% you can specify another environment to wrap the dedication in.
 %    \begin{macrocode}
 \newcommand*{\ptdedication}{Renew \textsf{\textbackslash ptdedication}}
 \newcommand*{\makededication}[1][flushright]{%
@@ -458,6 +518,25 @@
   \vspace*{\postdedicationvspace}
 }
 %    \end{macrocode}
+% For example, you might do something like the following:
+%
+% \begin{Example}
+% \begin{Verbatim}
+% \renewcommand*{\ptdedication}{%
+% Frontmatter haiku:\\*
+% This is dedicated to\\*
+% Someone else, not you.
+% }
+% \makededication[center]
+% \end{Verbatim}
+% \columnbreak
+% \renewcommand*{\ptdedication}{%
+% Frontmatter haiku:\\*
+% This is dedicated to\\*
+% Someone else, not you.
+% }
+% \makededication[center]
+% \end{Example}
 % \end{macro}
 % \end{macro}
 %
@@ -490,8 +569,8 @@
 % \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. \code{\textbackslash toptocentrytype} sets the default
-% entry type for the TOP in the TOC.
+% for poems in the ToP. \code{\textbackslash toptocentrytype} sets the default
+% entry type for the ToP in the ToC.
 %    \begin{macrocode}
 \newcommand*{\topname}{List of Poems}
 \newcommand*{\topentrytype}{subsection}
@@ -517,7 +596,7 @@
 %
 % We then set the \code{secnumdepth} and \code{tocdepth} counters to disable
 % chapter, section, and subsection numbering, and to limit the maximum depth of
-% entries in the TOC.
+% entries in the ToC.
 %
 %    \begin{macrocode}
 \setcounter{secnumdepth}{-1}
@@ -528,13 +607,12 @@
 % \begin{macro}{\maketoc}
 % \begin{macro}{\maketop}
 % \begin{macro}{\maketop*}
-% Once you've configured the TOC and TOP you probably want to insert them into
-% your document somewhere. While you could just use the \LaTeX\ commands \code{%
-% \textbackslash tableofcontents} and \code{\textbackslash listoftables}, we
-% provide alternatives that add a bit of formatting and clear the page. By
-% default the TOP creates a listing in the TOC---Using the star modifier
-% prevents this. An example table of poems can be found at the end of this
-% document.
+% Once you've configured the ToC and ToP you probably want to insert them into
+% your document somewhere. While you could just use the \LaTeX\ command
+% \code{\textbackslash tableofcontents} for the ToC, we provide an alternative
+% that adds a bit of formatting and clears the page. By default the ToP creates
+% a listing for itself in the ToC---using the star modifier prevents this. An
+% example table of poems can be found at the end of this document.
 %    \begin{macrocode}
 \newcommand*{\maketoc}{%
   \beforetoc
@@ -638,11 +716,12 @@
 % \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
+% Redefine \code{\textbackslash dedicationformat} to change how the dedication
 % 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.
+% dedication by redefining \code{\textbackslash prededicationvspace} and
+% \code{\textbackslash postdedicationvspace} or redefine the
+% \code{beforededication} and \code{afterdedication} hooks to insert content
+% around the dedication text.
 %    \begin{macrocode}
 \newcommand*{\dedicationformat}{\normalfont\itshape}
 \newlength{\prededicationvspace}
@@ -701,17 +780,6 @@
 % 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}
@@ -774,28 +842,62 @@
 %
 % \begin{macro}{\incipit}
 % \changes{2.0.0}{2013/03/06}{Allow the user to declare an incipit}
+% \begin{macro}{\incipit*}
+% \changes{2.2.0}{2014/08/21}{Add non-printing incipit command}
 % 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.
+% \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. \code{\textbackslash incipit*} will declare an incipit but will not
+% reprint its argument, for cases where the incipit differs from the actual
+% line.
 %    \begin{macrocode}
-\newcommand*{\incipit}[1]{%
+\newcommand*{\incipit}{%
+  \@ifstar{%
+    \@ptincipitStar
+  }{%
+    \@ptincipitNoStar
+  }
+}
+\newcommand*{\@ptincipitNoStar}[1]{%
   \global\expandafter\def%
     \csname%
       @poem\arabic{absolutepoemnum} incipit%
     \endcsname{##1}%
   ##1%
 }
+\newcommand*{\@ptincipitStar}[1]{%
+  \global\expandafter\def%
+    \csname%
+      @poem\arabic{absolutepoemnum} incipit%
+    \endcsname{##1}%
+}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+
+% \begin{macro}{\theincipit}
+% \changes{2.0.0}{2013/03/06}{Allow the user to insert the incipit}
+% After an incipit has been declared, this will expand to the text of the
+% incipit for the current poem.
+%
+%    \begin{macrocode}
+\newcommand*{\theincipit}{%
+  \csname @poem\arabic{absolutepoemnum} incipit\endcsname%
+}
 %    \end{macrocode}
 % \end{macro}
 %
-% An untitled poem with a default title and an incipit in the ToP might look
-% something like this:
+% This poem has a (slightly modified) default title and an incipit in the ToP:
 %
 % \begin{Example}
 % \begin{Verbatim}
 % \ptusedefaulttitles
 % \ptuseincipits
+% \renewcommand*{\ptdefaulttitle}{%
+% Untitled \textnumero\
+% \arabic{absoluteuntitledpoemnum}%
+% }
 % \begin{poem}{}{Traditional}
 % \incipit{Media vita in morte%
 %   sumus};\\*
@@ -812,6 +914,10 @@
 % \columnbreak
 % \ptusedefaulttitles
 % \ptuseincipits
+% \renewcommand*{\ptdefaulttitle}{%
+% Untitled \textnumero\
+% \arabic{absoluteuntitledpoemnum}%
+% }
 % \begin{poem}{}{Traditional}
 % \incipit{Media vita in morte%
 %   sumus};\\*
@@ -828,12 +934,15 @@
 %
 % Now we render the page header, title, and the actual poem:
 %    \begin{macrocode}
-  \poetryheadings
   \addtocounter{poemnum}{1}
   \addtocounter{absolutepoemnum}{1}
+  \poetryheadings
   \ifx&#2&%
     \addtocounter{untitledpoemnum}{1}
     \addtocounter{absoluteuntitledpoemnum}{1}
+  \else
+    \addtocounter{titledpoemnum}{1}
+    \addtocounter{absolutetitledpoemnum}{1}
   \fi
   \vspace*{\poemvspace}
   \begin{\pttitleenv}
@@ -910,7 +1019,7 @@
 %    \end{macrocode}
 % \end{environment}
 %
-% \section{Formatting}
+% \section{Formatting poems}
 %
 % The \code{poem} environment provides some reasonable defaults for formatting
 % your work but chances are you want a little more control.
@@ -918,10 +1027,11 @@
 % \subsection{Headings}
 %
 % \begin{macro}{\poetryheadings}
-% Every time a new \code{poem} or \code{annotation} environment is created we
-% automatically call \code{\textbackslash poetryheadings}. By redefining this
-% you can change how your headings look, use packages like \pkg{fancyhdr}, or
-% remove headers from poem pages altogether.
+% Every time a new \code{poem} environment is created we automatically call
+% \code{\textbackslash poetryheadings}. By redefining this you can change how
+% your headings look, use packages like
+% \pkg{\href{http://ctan.org/pkg/fancyhdr}{fancyhdr}}, or remove headers from
+% poem pages altogether.
 %    \begin{macrocode}
 \newcommand*{\poetryheadings}[0]{%
   \pagestyle{myheadings}
@@ -935,11 +1045,12 @@
 %
 % \begin{macro}{\resetnumongroup}
 % \begin{macro}{\numberpoems}
-% These commands determine if the \code{poemnum} counter 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.
+% 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{macrocode}
 \newcommand*{\resetnumongroup}{%
   \newcommand*{\@ptresetnumongroup}{}%
@@ -1149,6 +1260,47 @@
 %    \begin{macrocode}
 \newcommand*{\poemtitleformat}{\normalfont\bfseries\large}
 %    \end{macrocode}
+%
+% This can be used for everything from changing the font size to adding
+% interesting effects:
+%
+% \begin{Example}
+% \begin{Verbatim}
+% \renewcommand*{\poemtitleformat}
+% {\normalfont\bfseries%
+% {\rule{5em}{0.2em}}\\*}
+% \begin{poem}{Excelsior}
+% {Henry Wadsworth Longfellow\\*
+%  1841}
+% The shades of night were falling%
+% fast,\\*
+% As through an Alpine village%
+% passed\\*
+% A youth, who bore, `mid snow and
+% ice,\\*
+% A banner with the strange%
+% device,\\*
+% Excelsior!
+% \end{poem}
+% \end{Verbatim}
+% \columnbreak
+% \renewcommand*{\poemtitleformat}
+% {\normalfont\bfseries%
+% {\rule{5em}{0.2em}}\\*}
+% \begin{poem}{Excelsior}
+% {Henry Wadsworth Longfellow\\*
+%  1841}
+% The shades of night were falling%
+% fast,\\*
+% As through an Alpine village%
+% passed\\*
+% A youth, who bore, `mid snow and
+% ice,\\*
+% A banner with the strange%
+% device,\\*
+% Excelsior!
+% \end{poem}
+% \end{Example}
 % \end{macro}
 %
 % \begin{macro}{\incipittopformat}
@@ -1290,7 +1442,7 @@
 % \begin{macro}{\poemgroup*}
 % 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
+% 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.
@@ -1303,6 +1455,8 @@
   \else
     \setcounter{poemnum}{0}
     \setcounter{untitledpoemnum}{0}
+    \setcounter{titledpoemnum}{0}
+    \setcounter{annotationnum}{0}
   \fi
   \beforepoemgroup
   \vspace*{\pregroupvspace}
@@ -1335,18 +1489,21 @@
 % \begin{environment}{annotation}
 % \changes{1.1}{2012/07/20}{Added optional `environment' argument}
 % Annotations allow you to insert prose that relates to a specific poem into
-% your document. It uses \code{\textbackslash poetryheadings}, clears the page
-% twice, and adds itself to the TOC (but not the TOP). The page is also cleared
-% again after the annotation.
+% your document. It uses \code{\textbackslash annotationheadings} (see below),
+% clears the page twice, and adds itself to the ToC (but not the ToP). The page
+% is also cleared again after the annotation.
 %
 % Like the \code{poetry} environment, an optional first argument can be used to
 % specify the environment in which the annotation will be wrapped. The default
-% is \code{flushleft} and can be changed by redefining \code{ptannotationenv}.
+% is \code{flushleft} and can be changed by redefining \code{\textbackslash
+% ptannotationenv}.
 %    \begin{macrocode}
 \newenvironment{annotation}[2][\ptannotationenv]{%
   \newcommand*{\@ptwrapenvironment}{#1}
   \cleardoublepage
-  \poetryheadings
+  \addtocounter{annotationnum}{1}
+  \addtocounter{absoluteannotationnum}{1}
+  \annotationheadings
   \begin{\@ptwrapenvironment}
   \subsection{#2}
   \nopagebreak
@@ -1358,6 +1515,24 @@
 %    \end{macrocode}
 % \end{environment}
 %
+%
+% \section{Formatting annotations}
+%
+% \subsection{Headings}
+%
+% \begin{macro}{\annotationheadings}
+% \changes{2.1.0}{2013/08/29}{Allow separate headings on annotation pages}
+% The \code{\textbackslash annotationheadings} macro is automatically called
+% every time a new \code{annotation} environment is created. By default, it
+% simply calls \code{\textbackslash poetryheadings}, but it can be redefined to
+% give your annotation pages a different heading style than your poem pages.
+%    \begin{macrocode}
+\newcommand*{\annotationheadings}[0]{\poetryheadings}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+%
 % Now that everything is defined we can process any
 % \hyperlink{POETRYTEX:OPTIONS}{options} that were passed in by the user:
 %    \begin{macrocode}
@@ -1388,49 +1563,5 @@
 % \Finale
 %
 % \iffalse
-%<*doc-style>
-%    \begin{macrocode}
-\ProvidesPackage{poetrytex-style}
-
-\usepackage{fancyvrb,hologo,framed,multicol,tipa,url}
-\usepackage[pdfborder=0, bookmarks, colorlinks=false, hidelinks]{hyperref}
-\usepackage[parfill]{parskip}
-
-\fvset{gobble=2}
-
-\newenvironment{Example}{%
-  \begingroup\setlength{\columnseprule}{.4pt}
-  \begin{minipage}{\textwidth}
-  \begin{multicols}{2}
-}{
-  \end{multicols}
-  \end{minipage}
-  \endgroup
-}
-
-\newcommand*{\gitdescribe}{%
-  \immediate\write18{%
-    rm gitdescribe.tex 2> /dev/null; (git describe --tags --dirty ||%
-      echo "v0.0") 2> /dev/null > gitdescribe.tex
-  }%
-  \InputIfFileExists{gitdescribe.tex}{}{}\unskip%
-  \immediate\write18{%
-    rm gitdescribe.tex 2> /dev/null
-  }%
-}
-
-\newcommand\XeTeX{\hologo{XeTeX}}
-\newcommand\XeLaTeX{\hologo{XeLaTeX}}
-\newcommand\LuaTeX{\hologo{LuaTeX}}
-\newcommand\LuaLaTeX{\hologo{LuaLaTeX}}
-
-\newcommand*\name[1]{\textsc{#1}}
-\newcommand*\fname[1]{\textsf{#1}}
-\newcommand*\pkg[1]{\textsf{#1}}
-\newcommand*\code[1]{\texttt{#1}}
-
-\renewcommand\partname{Part}
-%    \end{macrocode}
-%</doc-style>
 %\fi
 \endinput
-- 
cgit v1.2.3

