diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/poetrytex/poetrytex.dtx | 341 |
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&% \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 |