From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/poetrytex/Makefile | 160 +++ macros/latex/contrib/poetrytex/README | 28 + macros/latex/contrib/poetrytex/poetrytex.dtx | 1634 ++++++++++++++++++++++++++ macros/latex/contrib/poetrytex/poetrytex.pdf | Bin 0 -> 292864 bytes 4 files changed, 1822 insertions(+) create mode 100644 macros/latex/contrib/poetrytex/Makefile create mode 100644 macros/latex/contrib/poetrytex/README create mode 100644 macros/latex/contrib/poetrytex/poetrytex.dtx create mode 100644 macros/latex/contrib/poetrytex/poetrytex.pdf (limited to 'macros/latex/contrib/poetrytex') diff --git a/macros/latex/contrib/poetrytex/Makefile b/macros/latex/contrib/poetrytex/Makefile new file mode 100644 index 0000000000..fd8cc1ace8 --- /dev/null +++ b/macros/latex/contrib/poetrytex/Makefile @@ -0,0 +1,160 @@ +# Makefile for poetrytex. + +SHELL = /bin/sh +.SUFFIXES: +.SILENT: + +builddir=build + + +help: + @echo 'POETRYTEX makefile targets:' + @echo ' ' + @echo ' help - (this message)' + @echo ' unpack - extracts all files' + @echo ' doc - compile documentation' + @echo ' gendoc - compile git-aware documentation' + @echo ' ctan - generate archive for CTAN' + @echo ' all - unpack & doc' + @echo ' world - all & ctan' + @echo ' clean - remove all generated and built files' + @echo ' preview - preview the documentation' + @echo ' ' + @echo ' install - install the complete package into your home texmf tree' + @echo ' sty-install - install the package code only' + @echo ' install TEXMFROOT= - install the package into the path ' + + +NAME = poetrytex +DOC = $(NAME).pdf +DTX = $(NAME).dtx + +# Redefine this to print output if you need: +REDIRECT = > /dev/null + +# Files grouped by generation mode +COMPILED = $(DOC) +UNPACKED = poetrytex.sty +SOURCE = $(DTX) Makefile README +GENERATED = $(COMPILED) $(UNPACKED) + +CTAN_FILES = $(SOURCE) $(COMPILED) + +UNPACKED_DOC = + +RUNFILES = $(filter-out $(UNPACKED_DOC), $(UNPACKED)) +DOCFILES = $(COMPILED) README $(UNPACKED_DOC) +SRCFILES = $(DTX) Makefile + +ALL_FILES = $(RUNFILES) $(DOCFILES) $(SRCFILES) + +# Installation locations +FORMAT = latex +RUNDIR = $(TEXMFROOT)/tex/$(FORMAT)/$(NAME) +DOCDIR = $(TEXMFROOT)/doc/$(FORMAT)/$(NAME) +SRCDIR = $(TEXMFROOT)/source/$(FORMAT)/$(NAME) +TEXMFROOT = $(shell kpsewhich --var-value TEXMFHOME) + +CTAN_ZIP = $(NAME).zip +TDS_ZIP = $(NAME).tds.zip +ZIPS = $(CTAN_ZIP) $(TDS_ZIP) + +DO_LATEX = pdflatex --interaction=nonstopmode $< $(REDIRECT) +DO_LATEX_WRITE18 = pdflatex --shell-escape --interaction=nonstopmode $< $(REDIRECT) +DO_TEX = tex --interaction=nonstopmode $< $(REDIRECT) +DO_MAKEINDEX = makeindex -s gind.ist $(subst .dtx,,$<) $(REDIRECT) 2>&1 +DO_MAKECHANGES = makeindex -s gglo.ist -o $(NAME).gls $(NAME).glo $< $(REDIRECT) 2>&1 + +all: $(GENERATED) +doc: $(COMPILED) +unpack: $(UNPACKED) +ctan: $(CTAN_ZIP) +tds: $(TDS_ZIP) +world: all ctan + +gendoc: $(DTX) + @echo "Compiling documentation" + $(DO_LATEX_WRITE18) + $(DO_MAKEINDEX) + $(DO_MAKECHANGES) + while ($(DO_LATEX_WRITE18) ; \ + grep -q "Rerun to get" $(NAME).log ) do true; \ + done + +COMMAND = command -v $(1) >/dev/null 2>&1 +preview: $(DOC) + ($(COMMAND) evince && evince $(NAME).pdf) || ($(COMMAND) open && open $(NAME).pdf) + +$(DOC): $(DTX) + @echo "Compiling documentation" + $(DO_LATEX) + $(DO_MAKEINDEX) + $(DO_MAKECHANGES) + while ($(DO_LATEX) ; \ + grep -q "Rerun to get" $(NAME).log ) do true; \ + done + + +$(UNPACKED): $(DTX) + @$(DO_TEX) + +$(CTAN_ZIP): $(CTAN_FILES) + @echo "Making $@ for CTAN upload." + @$(RM) -- $@ + @mkdir -p $(NAME)/ + @cp $^ $(NAME)/ + @rm -f $(NAME)/*.zip + @zip -9 $@ $(NAME)/* >/dev/null + @rm -rf $(NAME)/ + +define run-install +@mkdir -p $(RUNDIR) && cp $(RUNFILES) $(RUNDIR) +@mkdir -p $(DOCDIR) && cp $(DOCFILES) $(DOCDIR) +@mkdir -p $(SRCDIR) && cp $(SRCFILES) $(SRCDIR) +endef + +define run-sty-install +@mkdir -p $(RUNDIR) && cp $(RUNFILES) $(RUNDIR) +endef + +$(TDS_ZIP): TEXMFROOT=./tmp-texmf +$(TDS_ZIP): $(ALL_FILES) + @echo "Making TDS-ready archive $@." + @$(RM) -- $@ + $(run-install) + @cd $(TEXMFROOT) && zip -9 ../$@ -r . >/dev/null + @$(RM) -r -- $(TEXMFROOT) + +# Rename the README for CTAN +README: README.md + cp $< $@ + +.PHONY: install manifest clean mrproper + +install: $(ALL_FILES) + @if test ! -n "$(TEXMFROOT)" ; then \ + echo "Cannot locate your home texmf tree. Specify manually with\n\n make install TEXMFROOT=/path/to/texmf\n" ; \ + false ; \ + fi ; + @echo "Installing in '$(TEXMFROOT)'." + $(run-install) + +sty-install: $(RUNFILES) + @if test ! -n "$(TEXMFROOT)" ; then \ + echo "Cannot locate your home texmf tree. Specify manually with\n\n make install TEXMFROOT=/path/to/texmf\n" ; \ + false ; \ + fi ; + @echo "Installing in '$(TEXMFROOT)'." + $(run-install) + +manifest: + @echo "Source files:" + @for f in $(SOURCE); do echo $$f; done + @echo "" + @echo "Derived files:" + @for f in $(GENERATED); do echo $$f; done + +clean: + @$(RM) -- *.log *.aux *.toc *.idx *.ind *.ilg *.glo *.gls *.example *.out *.synctex* *.tmp *.ins poetrytex*.pdf poetrytex*.dvi README *.lot + @$(RM) -- $(GENERATED) $(ZIPS) + @$(RM) -- $(builddir)/* diff --git a/macros/latex/contrib/poetrytex/README b/macros/latex/contrib/poetrytex/README new file mode 100644 index 0000000000..e923a16424 --- /dev/null +++ b/macros/latex/contrib/poetrytex/README @@ -0,0 +1,28 @@ +# PoetryTeX + +**PoetryTeX** is a TeX package designed to aid in the formatting of anthologies +of poetry and other writings. + +## Download + +Development of this package occurs primarily on +[Bitbucket](https://bitbucket.org/SamWhited/poetrytex). +[Issues](https://bitbucket.org/SamWhited/poetrytex/issues) and +[pull requests](https://bitbucket.org/SamWhited/poetrytex/pull-requests) should +be submitted there. + +The current release version of PoetryTeX is available from +[CTAN](http://ctan.org/pkg/poetrytex). + +## License + +Copyright 2012–2016 [Sam Whited](https://blog.samwhited.com) + +This project may be distributed and/or modified under the conditions of the +LaTeX Project Public License, either version 1.3c of this license or (at your +option) any later version. The latest version of this license is in: + +http://www.latex-project.org/lppl.txt + +and version 1.3c or later is part of all distributions of LaTeX version +2008/05/04 or later. diff --git a/macros/latex/contrib/poetrytex/poetrytex.dtx b/macros/latex/contrib/poetrytex/poetrytex.dtx new file mode 100644 index 0000000000..df83c9d0da --- /dev/null +++ b/macros/latex/contrib/poetrytex/poetrytex.dtx @@ -0,0 +1,1634 @@ +% \iffalse +%<*internal> +\begingroup +\input docstrip.tex +\keepsilent +\usedir{tex/latex/poetrytex} +\preamble + + Copyright 2012 Samuel Whited + + This file may be distributed and/or modified under the + conditions of the LaTeX Project Public License, either + version 1.3c of this license or (at your option) any later + version. The latest version of this license is in: + + http://www.latex-project.org/lppl.txt + + and version 1.3c or later is part of all distributions of + LaTeX version 2008/05/04 or later. + +\endpreamble +\postamble + + ___________ + Maintainer: Sam Whited + Website: https://blog.samwhited.com + Contact: sam@samwhited.com + Public key: 0x54083AE104EA7AD3 + + This work consists of this file poetrytex.dtx + and the derived files poetrytex.sty + and poetrytex.pdf + +\endpostamble +\askforoverwritefalse + +\generate{\file{poetrytex.sty}{\from{poetrytex.dtx}{poetrytex}}} + +\obeyspaces +\Msg{****************************************************} +\Msg{* *} +\Msg{* To finish the installation you have to move the *} +\Msg{* following file into a directory searched by TeX: *} +\Msg{* *} +\Msg{* poetrytex.sty *} +\Msg{* *} +\Msg{****************************************************} + +\endgroup +% +% +%<*driver> +\ProvidesFile{poetrytex.dtx} +% +% +%<*poetrytex> +\NeedsTeXFormat{LaTeX2e}[1994/06/01] +\ProvidesPackage{poetrytex}[2014/12/12] +%% +% +%<*driver> +\documentclass[a4paper]{ltxdoc} +\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 +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +% +% +% \fi +% +% \GetFileInfo{\jobname.dtx} +% \makeatletter +% \errorcontextlines=999 +% +% \title{The \textsf{\jobname} package} +% \author{ +% \name{Sam Whited}\\* +% \texttt{sam@samwhited.com} +% } +% \date{\today\\*\gitdescribe} +% +% \maketitle +% \maketoc +% +% \section{Introduction} +% +% The \pkg{poetrytex} package is designed to aid in the formatting and +% typesetting of anthologies of poetry. +% +% \subsection{History} +% +% The package started out as a collection of macros for automating simple tasks +% that I often had to perform while working on a collection of poetry and prose. +% After a time, I decided to turn it into an STY file which would be geared +% more towards the idea of an anthology or a collection of works and less about +% typesetting the verse itself (for which there were already several good +% packages on CTAN). While the file was small this worked well---Learning to +% use the package was easily accomplished by reading the annotated source code +% (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. As of version 2.0.0, I began using +% \href{https://semver.org}{semantic versioning} to track releases. +% +% \subsection{License / about the source} +% +% This project may be distributed and/or modified under the conditions of the +% \LaTeX\ Project Public License, either version 1.3c of this license or (at +% your opinion) any later version. The latest version of this license is in: +% +% \url{http://www.latex-project.org/lppl.txt} +% +% and version 1.3c or later is part of all distributions of \LaTeX\ version +% 2008/05/04 or later. +% +% Contributions are welcome, and the latest development version of the project +% can always be found at \url{https://bitbucket.org/SamWhited/poetrytex}. +% +% \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. 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} +% +% \begin{macrocode} +%<*poetrytex> +% \end{macrocode} +% +% \paragraph{Building} +% +% Before building \pkg{poetrytex} you should verify that the following +% 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} +% \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 +% \code{make help} will tell you everything you need to know. To manually +% extract the files and generate the documentation simply run \code{pdflatex} +% or \XeLaTeX\ against \fname{poetrytex.dtx}: +% +% \begin{Verbatim} +% pdflatex poetrytex.dtx +% \end{Verbatim} +% +% You can also use the \code{-{}-shell-escape} option to generate documentation +% which includes the current git commit short-hash in the version number: +% +% \begin{Verbatim} +% pdflatex --shell-escape poetrytex.dtx +% \end{Verbatim} +% +% It should be noted that this option is extremely unsafe and you should only +% use it if you understand the risks. +% +% \paragraph{Loading} +% +% Using \pkg{poetrytex} in your project works exactly as you'd expect: +% +% \begin{Verbatim} +% \usepackage{poetrytex} +% \end{Verbatim} +% +% \hypertarget{POETRYTEX:OPTIONS}{} +% \changes{1.2}{2012/10/03}{Added various package options} +% \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}{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} +% \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{poemsintoc}{\listpoemsintoc} +\DeclareOption{numbertop}{\numbertop} +\DeclareOption{numbertoc}{\numbertoc} +\DeclareOption{numberpoems}{\numberpoems} +\DeclareOption{usedefaulttitles}{\usedefaulttitles} +\DeclareOption{useincipits}{\useincipits} +\DeclareOption{clearpageafterpoem}{\clearpageafterpoem} +\DeclareOption{clearpageafterannotation}{\clearpageafterannotation} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% For instance: +% +% \begin{Verbatim} +% \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 +% it's worth taking a look at how it works internally. +% +% \section{Environment setup and defaults} +% +% First we setup our environment, define some useful properties, and choose some +% default values for those properties. +% +% \subsection{Title page} +% +% We'll start with the title page: +% +% \begin{macro}{\pttitle} +% \begin{macro}{\ptsubtitle} +% \begin{macro}{\ptauthor} +% \begin{macro}{\ptdate} +% These properties will affect the appearance of \code{\textbackslash% +% maketitle}: +% \begin{macrocode} +\newcommand*{\pttitle}{Title} +\newcommand*{\ptsubtitle}{Subtitle} +\newcommand*{\ptauthor}{Author} +\newcommand*{\ptdate}{\today} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% Since we define them as commands, you can change the appearance of your +% title page by redefining them in your preamble like so: +% +% \begin{Verbatim} +% \renewcommand*{\pttitle}{My Title} +% \renewcommand*{\ptauthor}{The Author} +% \end{Verbatim} +% +% We then use these properties to set the document title, author, and date: +% \begin{macrocode} +\title{% + \beforetitle\pttitle\aftertitle% + \ifx\ptsubtitle\@ptundefined% + \relax% + \else% + \\*\beforesubtitle\ptsubtitle\aftersubtitle% + \fi% +} +\author{\beforeauthor\ptauthor\afterauthor} +\date{\beforedate\ptdate\afterdate} +% \end{macrocode} +% Since \code{\textbackslash maketitle} clears the internal title, author, and +% date we use the \code{\textbackslash pt} equivalents so that we can refer to +% them again later, or redefine them throughout the document---in anthologies +% with works by multiple authors, for instance. +% +% \subsection{Poem config} +% +% \begin{macro}{\@ptpoemlabeltext} +% Each time you create a poem in your document we automatically assign it a +% special label that can be used to link to it later. This label is prefixed +% with \code{\textbackslash @ptpoemlabeltext} to prevent it from conflicting +% with user defined labels, or labels defined in other packages. +% \begin{macrocode} +\newcommand*{\@ptpoemlabeltext}{poetrytexpoem:} +% \end{macrocode} +% \end{macro} +% +% Chances are you'll never need to touch this. +% +% \begin{macro}{poemnum} +% \begin{macro}{absolutepoemnum} +% \begin{macro}{untitledpoemnum} +% \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 +% 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} 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} +\newcounter{poemnum} +\newcounter{absolutepoemnum} +\newcounter{untitledpoemnum} +\newcounter{absoluteuntitledpoemnum} +\newcounter{titledpoemnum} +\newcounter{absolutetitledpoemnum} +\newcounter{poemgroupnum} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\poemvspace} +% \changes{1.4}{2013/02/11}{Allow whitespace before every poem} +% Sometimes you might want to insert a certain amount of vertical space before +% every poem. For instance, maybe you have several poems without titles and you +% need a visual cue to let your readers know that a new poem is starting. This +% can be acomplished by setting \code{\textbackslash poemvspace}: +% +% \begin{macrocode} +\newlength{\poemvspace} +\setlength{\poemvspace}{0em} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\pttitleleftspace} +% \changes{1.4}{2013/02/14}{Add macro to define poem title left hspace} +% \begin{macro}{\pttitlerightspace} +% \changes{1.4}{2013/02/14}{Add macro to define poem title right hspace} +% \begin{macro}{\ptsubtitleleftspace} +% \changes{1.4}{2013/02/14}{Add macro to define poem subtitle left hspace} +% \begin{macro}{\ptsubtitlerightspace} +% \changes{1.4}{2013/02/14}{Add macro to define poem subtitle right hspace} +% To indent the poems title or subtitle to the left or the right, set the length +% of \code{\textbackslash pttitleleftspace} and \code{\textbackslash% +% pttitlerightspace}. +% +% \begin{macrocode} +\newlength{\pttitleleftspace} +\setlength{\pttitleleftspace}{0em} +\newlength{\pttitlerightspace} +\setlength{\pttitlerightspace}{0em} +\newlength{\ptsubtitleleftspace} +\setlength{\ptsubtitleleftspace}{0em} +\newlength{\ptsubtitlerightspace} +\setlength{\ptsubtitlerightspace}{0em} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \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}{\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 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*{\usedefaulttitles}{\newcommand*{\@ptusedefaulttitles}{}} +\newcommand*{\nousedefaulttitles}{\let\@ptusedefaulttitles\@ptundefined} +\newcommand*{\ptdefaulttitle}{% + Untitled No. \arabic{absoluteuntitledpoemnum}% +} +\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} +% \begin{macro}{\pttitleenv} +% \changes{1.4}{2013/02/13}{Allow changing of the poem title environment} +% These macros contain the names of the default environments in which we should +% wrap poems and poem titles. +% \begin{macrocode} +\newcommand*{\ptdefaultenv}{verse} +\newcommand*{\pttitleenv}{center} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\ptdefaultgroupenv} +% \changes{2.0.0}{2013/03/09}{Allow changing of the default group environment} +% \begin{macro}{\grouppagestyle} +% \changes{2.0.0}{2013/03/09}{Allow changing of group page style} +% \begin{macro}{\pregroupvspace} +% \changes{2.0.0}{2013/03/09}{Allow change in vspace before group} +% \begin{macro}{\postgroupvspace} +% \changes{2.0.0}{2013/03/09}{Allow change in vspace after group} +% The following macros can be used to configure how the poem group page looks. +% \begin{macrocode} +\newcommand*{\ptdefaultgroupenv}{center} +\newcommand*{\grouppagestyle}{empty} +\newlength{\pregroupvspace} +\newlength{\postgroupvspace} +\setlength{\pregroupvspace}{\fill} +\setlength{\postgroupvspace}{\fill} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \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} +% This contains the name of the default environment in which we should wrap +% annotations. +% \begin{macrocode} +\newcommand*{\ptannotationenv}{flushleft} +% \end{macrocode} +% \end{macro} +% +% \subsection{Dedication} +% +% After your title page you might want to add a dedication page. +% +% \begin{macro}{\ptdedication} +% \begin{macro}{\makededication} +% \changes{1.1}{2012/07/21}{Added optional `environment' argument} +% As with the \code{\textbackslash pttitle} and author commands you can simply +% 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 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]{% + \thispagestyle{empty} + \vspace*{\prededicationvspace} + \begin{#1} + \beforededication{\dedicationformat\ptdedication}\afterdedication + \end{#1} + \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} +% +% \subsection{Tables and links} +% +% Next we setup the table of contents and list of poems: +% +% \begin{macro}{\listofpoems} +% \changes{2.0.0}{2013/02/23}{Use custom table for list of poems} +% \begin{macro}{\resetnumon} +% \changes{2.0.0}{2013/02/23}{Allow user to reset poem nums on counter change} +% 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. +% \begin{macrocode} +\newcommand*{\resetnumon}{} +\newlistof[\resetnumon]{poem}{top}{\topname} +\newcommand*{\listofpoems}{\listofpoem} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\topname} +% \changes{2.0.0}{2013/03/16}{Rename from \code{\textbackslash toptitle}} +% \begin{macro}{\topentrytype} +% \begin{macro}{\toptocentrytype} +% \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. +% \begin{macrocode} +\newcommand*{\topname}{List of Poems} +\newcommand*{\topentrytype}{subsection} +\newcommand*{\toptocentrytype}{section} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \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 +% entry type just like the ToP. By default, the ToC entry type is set to +% \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 +% entries in the ToC. +% +% \begin{macrocode} +\setcounter{secnumdepth}{-1} +\setcounter{tocdepth}{2} +\renewcommand*{\listtablename}{\topname} +% \end{macrocode} +% +% \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\ 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 + \tableofcontents + \pagestyle{plain} + \aftertoc + \clearpage + \thispagestyle{empty} +} +\newcommand*{\maketop}{\@ifstar{\@ptmaketopStar}{\@ptmaketopNoStar}} +\newcommand*{\@ptmaketopStar}{% + \cleardoublepage + \beforetop + \listofpoems + \pagestyle{plain} + \aftertop + \clearpage +} +\newcommand*{\@ptmaketopNoStar}{% + \cleardoublepage + \beforetop + \phantomsection + \addcontentsline{toc}{\toptocentrytype}{\topname} + \listofpoems + \pagestyle{plain} + \aftertop + \clearpage +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \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 (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} +% A great many commands are provided to act as hooks into various parts of +% \pkg{poetrytex}. These commands don't do anything initially, but can be +% redefined to customize the way \pkg{poetrytex} behaves. +% +% \subsection{Title page} +% +% \begin{macro}{\beforetitle} +% \changes{2.0.0}{2013/03/08}{Add hook before title} +% \begin{macro}{\aftertitle} +% \changes{2.0.0}{2013/03/08}{Add hook after title} +% \begin{macro}{\beforesubtitle} +% \changes{2.0.0}{2013/03/08}{Add hook before subtitle} +% \begin{macro}{\aftersubtitle} +% \changes{2.0.0}{2013/03/08}{Add hook after subtitle} +% \begin{macro}{\beforeauthor} +% \changes{2.0.0}{2013/03/08}{Add hook before author} +% \begin{macro}{\afterauthor} +% \changes{2.0.0}{2013/03/08}{Add hook after author} +% \begin{macro}{\beforedate} +% \changes{2.0.0}{2013/03/08}{Add hook before date} +% \begin{macro}{\afterdate} +% \changes{2.0.0}{2013/03/08}{Add hook after date} +% These hooks get inserted before or after elements on the title page or +% dedication. If the element has formatting, they will be inserted outside of +% the formatted block, but inside of any enclosing environments. +% \begin{macrocode} +\newcommand*{\beforetitle}{} +\newcommand*{\aftertitle}{} +\newcommand*{\beforesubtitle}{} +\newcommand*{\aftersubtitle}{} +\newcommand*{\beforeauthor}{} +\newcommand*{\afterauthor}{} +\newcommand*{\beforedate}{} +\newcommand*{\afterdate}{} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Dedication} +% +% \begin{macro}{\dedicationformat} +% \changes{2.0.0}{2013/03/08}{Allow customization of dedication format} +% \begin{macro}{\prededicationvspace} +% \changes{2.0.0}{2013/03/08}{Add length for setting the pre-dedication vspace} +% \begin{macro}{\postdedicationvspace} +% \changes{2.0.0}{2013/03/08}{Add length for setting the post-dedication vspace} +% \begin{macro}{\beforededication} +% \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 dedication +% text is formatted. You can change the length of the vspace around the +% 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} +\newlength{\postdedicationvspace} +\setlength{\prededicationvspace}{\fill} +\setlength{\postdedicationvspace}{\fill} +\newcommand*{\beforededication}{} +\newcommand*{\afterdedication}{} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Tables and links} +% +% \begin{macro}{\beforetoc} +% \changes{1.4}{2012/02/18}{Add hook before table of contents} +% \begin{macro}{\aftertoc} +% \changes{1.4}{2012/02/18}{Add hook after table of contents} +% \begin{macro}{\beforetop} +% \changes{1.4}{2012/02/18}{Add hook before table of poems} +% \begin{macro}{\aftertop} +% \changes{1.4}{2012/02/18}{Add hook after table of poems} +% Several hooks are provided which allow you to insert content before or after +% the tables: +% \begin{macrocode} +\newcommand{\beforetoc}{} +\newcommand{\aftertoc}{} +\newcommand{\beforetop}{} +\newcommand{\aftertop}{} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Poem group} +% +% \begin{macro}{\beforepoemgroup} +% \changes{2.0.0}{2013/03/09}{Add hook before group} +% \begin{macro}{\afterpoemgroup} +% \changes{2.0.0}{2013/03/09}{Add hook after group} +% The following hooks occur before and after a new poem group. +% \begin{macrocode} +\newcommand*{\beforepoemgroup}{\cleardoublepage} +\newcommand*{\afterpoemgroup}{\clearpage} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \part{Poems and annotations} +% +% Now that we've got all the boilerplate, configuration, titles, tables, and +% properties out of the way, it's time to move on to the core functionality of +% \pkg{poetrytex}: displaying and organizing poems! +% +% \section{The \code{poem} environment} +% +% \begin{environment}{poem} +% \changes{1.2}{2012/09/20}{Use \code{hypertarget} instead of \code{label}} +% \changes{2.0.0}{2013/08/15}{Prevent orphan / widow lines in stanzas (\href{https://github.com/SamWhited/poetrytex/issues/7}{Issue \#7)}} +% Inserting a poem or other writing into your anthology is accomplished by +% wrapping it in the \code{poem} environment. This environment takes in two +% arguments, the title and subtitle (or author, date, etc.) of the poem. +% \begin{macrocode} +\newenvironment{poem}[3][\ptdefaultenv]{% +% \end{macrocode} +% +% \begin{macro}{\@ptwrapenvironment} +% By default \code{poem} re-wraps your text in the \code{verse} environment. +% However, this can be changed by passing in an optional argument with the name +% of another environment to wrap it in (eg. \code{center}) or, for all poems, by +% redefining \code{ptdefaultenv}. +% \begin{macrocode} + \newcommand*{\@ptwrapenvironment}{#1} +% \end{macrocode} +% \end{macro} +% +% For example, a poem wrapped in the \code{center} environment might look like +% this: +% +% \begin{Example} +% \begin{Verbatim} +% \begin{poem}[center] +% {The Sea Bell}{J.R.R. Tolkien} +% I walked by the sea, +% and there came to me,\\ +% as a star-beam on the wet sand,\\ +% a white shell like a sea-bell;\\ +% trembling it lay +% in my wet hand.\\ +% In my fingers shaken +% I heard waken\\ +% a ding within, by a harbour bar\\ +% a buoy swinging, a call ringing\\ +% over endless seas, +% faint now and far\ldots +% \end{poem} +% \end{Verbatim} +% \columnbreak +% \begin{poem}[center] +% {The Sea Bell} +% {J.R.R. Tolkien} +% I walked by the sea, +% and there came to me,\\ +% as a star-beam on the wet sand,\\ +% a white shell like a sea-bell;\\ +% trembling it lay in my wet hand.\\ +% In my fingers shaken I heard waken\\ +% a ding within, by a harbour bar\\ +% a buoy swinging, a call ringing\\ +% over endless seas, +% faint now and far\ldots +% \end{poem} +% \end{Example} +% +% \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*} will declare an incipit but will not +% reprint its argument, for cases where the incipit differs from the actual +% line. +% \begin{macrocode} +\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} +% +% This poem has a (slightly modified) default title and an incipit in the ToP: +% +% \begin{Example} +% \begin{Verbatim} +% \usedefaulttitles +% \useincipits +% \renewcommand*{\ptdefaulttitle}{% +% Untitled \textnumero\ +% \arabic{absoluteuntitledpoemnum}% +% } +% \begin{poem}{}{Traditional} +% \incipit{Media vita in morte% +% sumus};\\* +% Quem qu\ae rimus adjutorem nisi% +% te, Domine?\\* +% Qui pro peccatis nostris juste% +% irasceris\\* +% Sancte Deus, Sancte fortis,% +% Sancte et misericors +% Salvator,\\* +% Amar\ae morti ne tradas nos. +% \end{poem} +% \end{Verbatim} +% \columnbreak +% \usedefaulttitles +% \useincipits +% \renewcommand*{\ptdefaulttitle}{% +% Untitled \textnumero\ +% \arabic{absoluteuntitledpoemnum}% +% } +% \begin{poem}{}{Traditional} +% \incipit{Media vita in morte% +% sumus};\\* +% Quem qu\ae rimus adjutorem nisi% +% te, Domine?\\* +% Qui pro peccatis nostris juste% +% irasceris\\* +% Sancte Deus, Sancte fortis,% +% Sancte et misericors% +% Salvator,\\* +% Amar\ae morti ne tradas nos. +% \end{poem} +% \end{Example} +% +% Now we render the page header, title, and the actual poem: +% \begin{macrocode} + \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} + \refstepcounter{poem}% + \phantomsection% + \addcontentsline{top}{\topentrytype}{% + \ifx\@ptnumbertop\@ptundefined% + \relax% + \else% + \toppoemnum% + \fi% + \ifx&% + \ifx\@ptuseincipits\@ptundefined% + \ptdefaulttitle% + \else% + {\incipittopformat \theincipit}% + \fi% + \else% + #2% + \fi% + }% + \ifx\@ptlistpoemsintoc\@ptundefined% + \relax% + \else% + \addcontentsline{toc}{\tocentrytype}{% + \ifx\@ptnumbertoc\@ptundefined% + \relax% + \else% + \tocpoemnum% + \fi% + \ifx&% + \ifx\@ptuseincipits\@ptundefined% + \ptdefaulttitle% + \else% + {\incipittocformat \theincipit}% + \fi% + \else% + #2% + \fi% + }% + \fi% + \ifx\hypertarget\@ptundefined% + \relax% + \else% + \hypertarget{\@ptpoemlabeltext\arabic{absolutepoemnum}}{}% + \fi% + {\poemtitleformat% + \ifx\@ptnumberpoems\@ptundefined + \relax + \else + \titlepoemnum + \fi% + \ifx&% + \ifx\@ptusedefaulttitles\@ptundefined% + \relax% + \else% + \hspace*{\pttitleleftspace}\ptdefaulttitle% + \hspace*{\pttitlerightspace}\\*% + \fi% + \else + \hspace*{\pttitleleftspace}#2\hspace*{\pttitlerightspace}\\*% + \fi% + }% + \hspace*{\ptsubtitleleftspace}#3\hspace*{\ptsubtitlerightspace} + \end{\pttitleenv} + \nopagebreak + \begin{\@ptwrapenvironment} + \begingroup\setlength{\parskip}{\stanzaparskip}% +}{% + \endgroup + \end{\@ptwrapenvironment}% + \ifx\@ptclearpageafterpoem\@ptundefined% + \relax% + \else% + \clearpage% + \fi% +} +% \end{macrocode} +% \end{environment} +% +% \section{Formatting poems} +% +% The \code{poem} environment provides some reasonable defaults for formatting +% your work but chances are you want a little more control. +% +% \subsection{Headings} +% +% \begin{macro}{\poetryheadings} +% 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} + \markboth{\ |\ \textsc{\pttitle}\hfill } + {\hfill\textsc{\ptgroup}\ |\ } +} +% \end{macrocode} +% \end{macro} +% +% \subsection{Numbering} +% +% \begin{macro}{\numberpoems} +% \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*{\numberpoems}{\newcommand*{\@ptnumberpoems}{}} +\newcommand*{\nonumberpoems}{\let\@ptnumberpoems\@ptundefined} +% \end{macrocode} +% \end{macro} +% \end{macro} +% Using \code{\textbackslash numberpoems} results in: +% +% \begin{Example} +% \begin{Verbatim} +% \numberpoems +% \numbertop +% +% \begin{poem}{The Highwayman} +% {Alfred Noyes} +% The wind was a torrent of +% darkness among the gusty trees,\\ +% The moon was a ghostly galleon +% tossed upon cloudy seas,\\ +% The road was a ribbon of +% moonlight over the purple moor% +% \ldots +% \end{poem} +% \end{Verbatim} +% \columnbreak +% \numberpoems +% \numbertop +% +% \begin{poem}{The Highwayman}{Alfred Noyes} +% The wind was a torrent of +% darkness among the gusty trees,\\ +% The moon was a ghostly galleon +% tossed upon cloudy seas,\\ +% The road was a ribbon of +% moonlight over the purple moor% +% \ldots +% \end{poem} +% \end{Example} +% +% \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{absolutepoemnum}\\*} +\newcommand*{\toppoemnum}{\arabic{absolutepoemnum}.\ } +\newcommand*{\tocpoemnum}{\toppoemnum} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% If we want to use uppercase roman numerals on the poems, and lowercase roman +% numerals in the \code{\hyperlink{POETRYTEX:TOP}{Table of Poems}}, we could +% redefine them like so: +% +% \begin{Example} +% \begin{Verbatim} +% \numberpoems +% \numbertop +% \renewcommand*{\titlepoemnum}{% +% \unskip\Roman{poemnum}\\} +% \renewcommand*{\toppoemnum}{ +% \unskip\roman{poemnum}.\ } +% +% \begin{poem}% +% {The Lady of Shalott}% +% {Alfred Tennyson (1842)} +% On either side the river lie\\ +% Long fields of barley and +% of rye,\\ +% That clothe the wold and meet +% the sky;\\ +% And through the field the road +% runs by\\ +% To many-towered Camelot;\\ +% And up and down the people go,\\ +% Gazing where the lilies blow\\ +% Round an island there below,\\ +% The island of Shalott--- +% \end{poem} +% \end{Verbatim} +% \columnbreak +% \numberpoems +% \numbertop +% \renewcommand*{\titlepoemnum}{% +% \unskip\Roman{poemnum}\\} +% \renewcommand*{\toppoemnum}{ +% \unskip\roman{poemnum}.\ } +% +% \begin{poem}% +% {The Lady of Shalott}% +% {Alfred Tennyson (1842)} +% On either side the river lie\\ +% Long fields of barley and +% of rye,\\ +% That clothe the wold and meet +% the sky;\\ +% And through the field the road +% runs by\\ +% To many-towered Camelot;\\ +% And up and down the people go,\\ +% Gazing where the lilies blow\\ +% Round an island there below,\\ +% The island of Shalott--- +% \end{poem} +% \end{Example} +% +% \subsection{Spacing and indentation} +% +% \begin{macro}{\stanzaparskip} +% This length is used to change the \code{parskip} within a poem environment. +% \begin{macrocode} +\newlength{\stanzaparskip} +\setlength{\stanzaparskip}{0.7em} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\clearpageafterpoem} +% \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} +% \begin{macro}{\ptind*} +% The \code{\textbackslash ptgap} length and \code{\textbackslash ptind} +% command are two of those places where \pkg{poetrytex} strays a bit into the +% realm of poetry typesetting. They overlap with the \pkg{verse} package's +% \code{\textbackslash vgap} and \code{\textbackslash vin} commands and insert +% indentation at at the beginning of a line. This is useful for typesetting +% poems consistently when the \pkg{verse} package is not loaded. Redefine +% \code{\textbackslash ptgap} to change the length that \code{\textbackslash% +% ptind} indents by. The starred version of \code{ptind} uses\code{% +% \textbackslash hspace*}. +% \begin{macrocode} +\newlength{\ptgap} +\setlength{\ptgap}{2em} +\newcommand*{\ptind}{% + \@ifstar{% + \@ptindStar + }{% + \@ptindNoStar + } +} +\newcommand*{\@ptindStar}{\hspace*{\ptgap}} +\newcommand*{\@ptindNoStar}{\hspace{\ptgap}} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% Using it works something like this: +% +% \begin{Example} +% \begin{Verbatim} +% \setlength{\ptgap}{2em} +% \begin{poem}[flushleft]{PoE\TeX} +% {An {\tipaencoding +% /Ig"zA:mp@l/} poem} +% There once was a poem called% +% PoE\TeX\\* +% That's name sounded somewhat% +% {\tipaencoding /p@"TEtEk/}.\\* +% \ptind It was really quite% +% sad,\\* +% \ptind to see pronunciation% +% so bad,\\* +% And to read such a terrible% +% {\tipaencoding /"lIme(@)rEk/}! +% \end{poem} +% \end{Verbatim} +% \columnbreak +% \setlength{\ptgap}{2em} +% \begin{poem}[flushleft]{PoE\TeX} +% {An {\tipaencoding +% /Ig"zA:mp@l/} poem} +% There once was a poem called% +% PoE\TeX\\* +% That's name sounded somewhat% +% {\tipaencoding /p@"TEtEk/}.\\* +% \ptind It was really quite% +% sad,\\* +% \ptind to see pronunciation% +% so bad,\\* +% And to read such a terrible% +% {\tipaencoding /"lIme(@)rEk/}! +% \end{poem} +% \end{Example} +% +% \subsection{Style} +% +% \begin{macro}{\poemtitleformat} +% By redefining \code{\textbackslash poemtitleformat} we can change how the poem +% title is rendered. +% \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} +% \changes{2.0.0}{2013/02/23}{Add hook for incipit formatting in the ToP} +% \begin{macro}{\incipittocformat} +% \changes{2.0.0}{2013/08/17}{Add hook for incipit formatting in the ToC} +% Similarly we can change how the incipit is rendered in the Table of Poems or +% Table of Contents: +% \begin{macrocode} +\newcommand*{\incipittopformat}{\itshape} +\newcommand*{\incipittocformat}{\incipittopformat} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% If you want a stylistic marker between two poems, or between sections +% or stanzas within a poem, the following commands are your friend. +% +% \begin{macro}{\ptspacergap} +% \begin{macro}{\ptspacerchar} +% \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{ptspacernum} times. +% \begin{macrocode} +\newlength{\ptspacergap} +\setlength{\ptspacergap}{4em} +\newcommand*{\ptspacerchar}{\S} +\newcounter{ptspacernum} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\ptspacer} +% \changes{1.0}{2012/07/17}{Repeat \code{\textbackslash ptspacernum} times} +% \begin{macro}{\ptspacer*} +% The starred version of the \code{ptspacer} command uses \code{\textbackslash% +% hspace*} for indention. +% \begin{macrocode} +\newcommand*{\ptspacer}{% + \@ifstar{% + \@ptspacerStar + }{% + \@ptspacerNoStar + } +} +\newcommand*{\@ptspacerStar}{% + \hspace*{\ptspacergap}% + \@ptrepeat{\value{ptspacernum}}{\ptspacerchar}% +} +\newcommand*{\@ptspacerNoStar}{% + \hspace{\ptspacergap}% + \@ptrepeat{\value{ptspacernum}}{\ptspacerchar}% +} +\ExplSyntaxOn +\cs_new_eq:NN \@ptrepeat \prg_replicate:nn +\ExplSyntaxOff +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% For example: +% +% \begin{Example} +% \begin{Verbatim} +% \renewcommand{\ptspacerchar}{\o} +% \setcounter{ptspacernum}{2} +% \begin{poem}{The Love Song% +% of J. Alfred Prufrock} +% {T.S. Eliot} +% \ldots I should have been a pair% +% of ragged claws\\ +% Scuttling across the floors of% +% silent seas. +% +% \ptspacer +% +% And the afternoon, the evening, +% sleeps so peacefully!\\ +% Smoothed by long fingers,\\ +% Asleep\ldots\ tired\ldots\ or% +% it malingers,\\ +% Stretched on the floor, here% +% beside you and me\ldots +% \end{poem} +% \end{Verbatim} +% \columnbreak +% \renewcommand{\ptspacerchar}{\o} +% \setcounter{ptspacernum}{2} +% \begin{poem}{The Love Song% +% of J. Alfred Prufrock} +% {T.S. Eliot} +% \ldots I should have been a pair% +% of ragged claws\\ +% Scuttling across the floors of% +% silent seas. +% +% \ptspacer +% +% And the afternoon, the evening, +% sleeps so peacefully!\\ +% Smoothed by long fingers,\\ +% Asleep\ldots\ tired\ldots\ or% +% it malingers,\\ +% Stretched on the floor, here% +% beside you and me\ldots +% \end{poem} +% \end{Example} +% +% \subsection{Groups and linking} +% +% When putting together a large collection of poetry and prose you most likely +% need a way to organize your works and find them quickly. While the table of +% poems helps we might also want to link directly to poems, or further subdivide +% the collection into groups of related works (by year written, or subject +% matter for instance). +% +% \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\hyperlink\@ptundefined + #2\relax% + \else + \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 \code{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. 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} + \setcounter{poemnum}{0} + \setcounter{untitledpoemnum}{0} + \setcounter{titledpoemnum}{0} + \setcounter{annotationnum}{0} + \beforepoemgroup + \vspace*{\pregroupvspace} + \renewcommand*{\ptgroup}{#1} + \pagestyle{\grouppagestyle} + \begin{\ptdefaultgroupenv} + \@ifstar{% + \@ptpoemgroupStar{#1} + }{% + \@ptpoemgroupNoStar{#1} + } + \end{\ptdefaultgroupenv} + \vspace*{\postgroupvspace} + \afterpoemgroup +} +\newcommand*{\@ptpoemgroupStar}[1]{% + \section*{#1} +} +\newcommand*{\@ptpoemgroupNoStar}[1]{% + \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} +% +% \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 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{\textbackslash +% ptannotationenv}. +% \begin{macrocode} +\newenvironment{annotation}[2][\ptannotationenv]{% + \newcommand*{\@ptwrapenvironment}{#1} + \cleardoublepage + \addtocounter{annotationnum}{1} + \addtocounter{absoluteannotationnum}{1} + \annotationheadings + \begin{\@ptwrapenvironment} + \subsection{#2} + \nopagebreak +}{% + \end{\@ptwrapenvironment}% + \ifx\@ptclearpageafterannotation\@ptundefined% + \relax% + \else% + \clearpage% + \fi% +} +% \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} +\ProcessOptions\relax +% +% \end{macrocode} +% +% \clearpage +% \setcounter{IndexColumns}{2} +% \phantomsection +% \addcontentsline{toc}{part}{Index} +% \PrintIndex +% +% \makeatletter +% \renewenvironment{theglossary}{% +% \glossary@prologue +% \setlength\emergencystretch{5em} +% \GlossaryParms \let\item\@idxitem \ignorespaces}{} +% \makeatother +% \clearpage +% \phantomsection +% \addcontentsline{toc}{part}{Change History} +% \PrintChanges +% \changes{1.1}{2012/07/19}{Added an example table of poems} +% \renewcommand*{\toptocentrytype}{part} +% \renewcommand*{\beforetop}{\hypertarget{POETRYTEX:TOP}{}} +% \maketop +% \Finale +% +% \iffalse +%\fi +\endinput diff --git a/macros/latex/contrib/poetrytex/poetrytex.pdf b/macros/latex/contrib/poetrytex/poetrytex.pdf new file mode 100644 index 0000000000..0954fe6ba4 Binary files /dev/null and b/macros/latex/contrib/poetrytex/poetrytex.pdf differ -- cgit v1.2.3