summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx')
-rw-r--r--Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx341
1 files changed, 236 insertions, 105 deletions
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