Typesetting simple verse with L

(1)

Typesetting simple verse with L

A

_TEX

Author: Peter Wilson, Herries Press

Maintainer: Will Robertson

http://github.com/wspr/herries-press/

v2.4b

2014/05/10

Abstract

The verse package provides some aids for the typesetting of simple verse.

1 Introduction

The typesetting of a poem should be really be dependent on the particular poem. Individual problems do not usually admit of a general solution, so this document and code should be used more as a guide towards some solutions rather than providing a ready made solution for any particular piece of verse.

This manual is typeset according to the conventions of the LA_TEX

doc-strip utility which enables the automatic extraction of the LATEX macro source files [GMS94].

Section 3 describes the usage of the verse package and commented source code is in Section 4. Colour is used to indicate input and output material; a blue background indicates LA_{TEX input source, and a green background shows the}

corresponding output one should expect.

The doggerel used as illustrative material has been taken from [Wil01].

2 Verses in L

A

_{TEX without this package}

LaTeX provides the verse environment which is defined as a particular kind of list. Within the environment you use \\ to end a line and a blank line will end a stanza. For example, here is a single stanza poem:

\newcommand{\garden}{

I used to love my garden \\ But now my love is dead \\

For I found a bachelor’s button \\ In black-eyed Susan’s bed.

}

When this is typeset as a normal LaTeX paragraph (with no paragraph indenta-tion) it looks like:

I used to love my garden But now my love is dead For I found a bachelor’s button In black-eyed Susan’s bed.

(3)

3

The stanza could also be typeset within the alltt environment, defined in the standard alltt package, using a normal font and no \\ line endings.

\begin{alltt}\normalfont I used to love my garden But now my love is dead

For I found a bachelor’s button In black-eyed Susan’s bed. \end{alltt}

which produces:

The alltt environment is like the verbatim environment except that you can use LaTeX macros inside it.

In the verse environment long lines will be wrapped and indented but in the alltt environment there is no indentation.

Some stanzas have certain lines indented, often alternate ones. To typeset stanzas like this you have to add your own spacing. For instance:

\begin{verse}

There was an old party of Lyme \\ Who married three wives at one time. \\ \hspace{2em} When asked: ‘Why the third?’ \\ \hspace{2em} He replied: ‘One’s absurd, \\ And bigamy, sir, is a crime.’

\end{verse}

will be typeset in a verse environment as: There was an old party of Lyme Who married three wives at one time.

When asked: ‘Why the third?’ He replied: ‘One’s absurd, And bigamy, sir, is a crime.’

Using the alltt environment you can put in the spacing via ordinary spaces. That is, this

(4)

Who married three wives at one time. When asked: ‘Why the third?’ He replied: ‘One’s absurd, And bigamy, sir, is a crime.’ \end{alltt}

is typeset as

There was an old party of Lyme Who married three wives at one time.

More exotically you could use the TeX \parshape command: \parshape = 5 0pt \linewidth 0pt \linewidth

2em \linewidth 2em \linewidth 0pt \linewidth \noindent There was an old party of Lyme \\

Who married three wives at one time. \\ When asked: ‘Why the third?’ \\

He replied: ‘One’s absurd, \\ And bigamy, sir, is a crime.’ \par which will be typeset as:

(5)

5

3 The verse package

The code provided by the verse package is meant to help with some aspects of typesetting poetry but does not, and cannot, provide a comprehensive solution to all the requirements that will arise.

A brief introduction is included to get started quickly; see the examples in Section 3.4 for more context.

3.1 Brief introduction

The verse package provides the verse environment for typesetting verses, over-writing LA_{TEX’s original definition. Every line in a verse environment must end}

with \\, and every stanza within a verse should end with \\! (an empty line af-terwards is optional for readability). These requirements allow line numbering to work correctly in all cases. Use the \poemlines{hN i} command to number every hN ith line of a poem.

Use the \poemtitle{htitlei} command (just before the verse environment) to give each poem a title; commands are provided to adjust the formatting and include the poem into the standard table of contents.

Each stanza within a verse may optionally be surrounded by either an altverse or patverse environment to effect specific typesetting; altverse indents every second line of a stanza, and patverse allows arbitrary indentation based on the hpatterni given by \indentpattern{hpatterni}. The command \flagverse, placed at the very beginning of a stanza places a ‘title’; e.g., for numbering and otherwise labelling stanzas.

3.2 Comprehensive documentation

3.2.1 Main verse environments

The verse environment provided by the package is an extension of the usual verse

LaTeX environment. The environment takes one optional parameter, which is a length; for example \begin{verse}[4em]. You may have noticed that the earlier verse examples are all near the left margin, whereas verses usually look better if they are typeset about the center of the page. The length parameter, if given, should be about the length of an average line, and then the entire contents will be typeset with the mid point of the length centered horizontally on the page.

The length \versewidth is provided as a convenience. It may be used, for \versewidth

example, to calculate the length of a line of text for use as the optional argument to the verse environment:

\settowidth{\versewidth}{This is the average line,} \begin{verse}[\versewidth]

Within the verse environment verses are separated by a blank line in the altverse

(6)

Individual verses within the verse environment may be enclosed in the patverse

patverse environment. Within the environment the indentation of each line is specified by an indentation pattern, which consists of an array of digits, d1to dn,

and the nth line is indented by dn times \vgap. However, the first line is not

indented, irrespective of the value of d1.

The patverse* environment is similar to patverse environment, except that patverse*

the pattern will keep on repeating itself.

The indentation pattern for a patverse environment is specified via the \indentpattern

\indentpattern{hdigitsi} command. If the pattern is shorter than the number of lines in a verse, the trailing lines will not be indented.

3.2.2 Other verse commands

Within the verse environment, the macro \\ must be used at the end of each line \\

of a verse, except for the last line in each stanza. If the lines in a poem are to be numbered then \\! must be used at the end of the last line in each stanza (the \\!

\\ macro increments the line numbers).

The starred version, \\*, prohibits a page break after the line. The \\> version \\*

\\> causes a linebreak within a verse line.

The \\ macro in its various forms can also take an optional length argument, like \\[30pt] which will insert 30pt of vertical space; in the case of \\>[30pt] an additional 30pt of horizontal space will be inserted after the linebreak (effectively \\> is shorthand for \verselinebreak).

The allowable forms of the macro are:

\\, \\*. \\!, \\>, \\[...], \\*[...], \\![...], and \\>[...].

The command \vin is shorthand for \hspace{\vgap} for use at the start of \vin

\vgap an indented line of verse. The length \vgap (initially 1.5em) can be changed by \setlength or \addtolength.

When a verse line is too long to fit within the typeblock it is wrapped onto the \vindent

next line with a space, given by the value of the length \vindent.

Using the command \verselinebreak[hlengthi] will cause later text in the \verselinebreak

line of the verse to be typeset indented on the following line. If the optional length argument is not given the indentation is \vgap, otherwise the indentation is given by hlengthi plus \vgap. The broken line will count as a single line as far as the altverse and patverse environments are concerned (see also the \\> macro).

Putting the command \flagverse{hflagi} at the start of a line of verse will \flagverse

\vleftskip typeset hflagi towards the left margin, ending a distance \vleftskip before the verse line.

3.2.3 Generic verse formatting

The length \stanzaskip controls the spacing between stanzas. It may be changed \stanzaskip

like any other length.

(7)

3.2 Comprehensive documentation 7

also applies to any list environment. To change the minimum indent for verses do something along the lines:

\newlength{\saveleftmargini}

\setlength{\saveleftmargini}{\leftmargini}

\setlength{\leftmargini}{-1em}% for example to outdent verse % verses

\setlength{\leftmargini}{\saveleftmargini}% restore original value

3.2.4 Line numbering

The declaration \poemlines{hnthi} will cause every hnthi lines of succeeding \poemlines

verses to be numbered. For example, \poemlines{5} will number every fifth line. The default is \poemlines{0} which prevents any numbering.

The command \setverselinenums{hfirstlinenumi}{hstartnumsat i} can be \setverselinenums

used to set the number of the first verse line to hfirstlinenumi instead of the default ‘1’ and to specify that the first printed line number should be for line number hstartnumsat i. If used the command must be given within the verse environment before the first line of the verses. For example, if you were quoting portions of poems from a source where the lines were numbered, your first line might be the 112th of the original and that line was originally numbered:

\setverselinenums{112}{112}

or if it was line 115 that was first numbered: \setverselinenums{112}{115}

Note that the numbers must be such that the following relationship holds: firstlinenum <= startnumsat < firstlinenum + poemlines

Lines are numbered via \thepoemline which defaults to typesetting arabic \thepoemline

\verselinenumfont numerals via:

\renewcommand*{\thepoemline}{\arabic{poemline}}

The particular font is defined by \verselinenumfont{hfont-speci}, with default: \verselinenumfont{\rmfamily}

By default the numbers are typeset at the distance \vrightskip into the right \vrightskip

\verselinenumbersleft \verselinenumbersright

margin. If you want line numbers set at the left use the \verselinenumbersleft declaration. To revert to the default use \verselinenumbersright.

The standard \label{metakey} command can be used inside the verse envi-\label

\ref ronment, between the end of the text of a line and the line-ending \\, to grab that line number, no matter what the setting of \poemlines. Elsewhere the standard \ref{hkey i} command can be used to refer to the line number.

3.2.5 Titles

\poemtitle[hshort i}{hlong i} typesets the title of a poem and makes an entry \poemtitle

into the ToC. There is a starred version that makes no ToC entry.

The kind of entry made in the ToC by the \poemtitle command is defined by \poemtoc

(8)

for a section-like ToC entry. This can be changed to, say, chapter or subsection or . . . .

This macro specifies the font and positioning of the poem title. Its initial \poemtitlefont

definition is:

\newcommand{\poemtitlefont}{\normalfont\bfseries\large\centering} to give a \large bold centered title. This can of course be renewed if you want something else.

These two lengths are the vertical space before and after the \poemtitle title \beforepoemtitleskip

\afterpoemtitleskip text. They are initially defined to give the same spacing as for a \section title. They can be changed by \setlength or \addtolength for different spacings.

The \poemtitle macro, but not \poemtitle*, calls the \poemtitlemark{htitlei} \poemtitlemark

macro, which is defined to do nothing. This would probably be changed by a pagestyle definition (like \sectionmark or \chaptermark).

3.3 Supports

The package includes some macros for supporting the patverse environment which may be more generally useful. See the code section for examples on how these may be used.

\newarray{harraynamei}{hlow i}{hhighi} defines the harraynamei array, where \newarray

harraynamei is a name like MyArray. The lowest and highest array indices are set to hlow i and hhighi respectively, where both are integer numbers.

\setarrayelement{harraynamei}{hindex i}{htext i} sets the hindex i location \setarrayelement

in the harraynamei array to be htext i. For example: \setarrayelement{MyArray}{23}{$2^{23}$}.

\getarrayelement{harraynamei}{hindex i}{hresult i} sets the parameterless \getarrayelement

macro hresult i to the contents of the hindex i location in the harraynamei array. For example:

\getarrayelement{MyArray}{23}{\result}.

\checkarrayindex{harraynamei}{hindex i} checks if harraynamei is an array \checkarrayindex

and if hindex i is a valid index for the array.

\stringtoarray{harraynamei}{hstring i} puts each character from hstring i \stringtoarray

sequentially into the harraynamei array, starting at index 1. For example: \stringtoarray{MyArray}{Chars}.

The macro \arraytostring{harraynamei}{hresult i} assumes that harraynamei \arraytostring

is an array of characters, and defines the macro hresult i to be that sequence of characters. For example:

\arraytostring{MyArray}{\MyString}.

\checkifinteger{hnumi} checks if hnumi is an integer (not less than zero). \checkifinteger

If it is then \ifinteger is set TRUE, otherwise it is set FALSE.

3.4 Examples

(9)

3.4 Examples 9

\renewcommand{\poemtoc}{subsection} \poemtitle{A Limerick}

\settowidth{\versewidth}{There was an old party of Lyme} \begin{verse}[\versewidth]

There was an old party of Lyme \\ Who married three wives at one time. \\ \vin When asked: ‘Why the third?’ \\ \vin He replied: ‘One’s absurd, \\ And bigamy, sir, is a crime.’ \\ \end{verse}

which gets typeset as below. The default \poemtoc is redefined to subsection so the title is entered into the ToC as an unnumbered \subsection.

A Limerick

Next is the Garden verse within the altverse environment. It is titled and centered.

\settowidth{\versewidth}{But now my love is dead} \poemtitle{Love’s lost} \begin{verse}[\versewidth] \begin{altverse} \garden \end{altverse} \end{verse} which produces:

Love’s lost

I used to love my garden

But now my love is dead For I found a bachelor’s button

In black-eyed Susan’s bed.

It is left up to you how you might want to add information about the author of a poem. Here is one example of a macro for this:

\newcommand{\attrib}[1]{%

(10)

This can be used as in the next bit of doggerel. \poemtitle{Fleas}

\settowidth{\versewidth}{What a funny thing is a flea} \begin{verse}[\versewidth]

What a funny thing is a flea. \\ You can’t tell a he from a she. \\ But he can. And she can. \\ Whoopee! \\

\end{verse} \attrib{Anonymous}

Fleas

What a funny thing is a flea. You can’t tell a he from a she. But he can. And she can. Whoopee!

Anonymous

Here is an example of line wrapping. \poemtitle{In the beginning}

\settowidth{\versewidth}{And objects at rest tended to remain at rest} \begin{verse}[\versewidth]

Then God created Newton, \\

And objects at rest tended to remain at rest, \\ And objects in motion tended to remain in motion, \\ And energy was conserved

and momentum was conserved and matter was conserved \\

And God saw that it was conservative. \\ \end{verse}

\attrib{Possibly from \textit{Analog}, circa 1950}

In the beginning

Then God created Newton,

And objects at rest tended to remain at rest, And objects in motion tended to remain in motion,

And energy was conserved and momentum was conserved and matter was conserved

And God saw that it was conservative.

(11)

3.4 Examples 11

Here is one with a forced line break and a slightly different title style. \renewcommand{\poemtitlefont}{\normalfont\large\itshape\centering} \poemtitle{Mathematics}

\settowidth{\versewidth}{Than Tycho Brahe, or Erra Pater:} \begin{verse}[\versewidth]

In mathematics he was greater \\ Than Tycho Brahe, or Erra Pater: \\ For he, by geometric scale, \\

Could take the size of pots of ale;\\ \settowidth{\versewidth}{Resolve by} Resolve, by sines \\>[\versewidth] and tangents straight, \\

If bread or butter wanted weight; \\ And wisely tell what hour o’ the day \\ The clock does strike, by Algebra. \\ \end{verse}

\attrib{Samuel Butler (1612--1680)}

Mathematics

In mathematics he was greater Than Tycho Brahe, or Erra Pater: For he, by geometric scale, Could take the size of pots of ale; Resolve, by sines

and tangents straight, If bread or butter wanted weight; And wisely tell what hour o’ the day The clock does strike, by Algebra.

Samuel Butler (1612–1680)

Another limerick, but this time taking advantage of the patverse environment and numbering every third line.

\settowidth{\versewidth}{There was a young lady of Ryde} \poemtitle{The Young Lady of Ryde}

\begin{verse}[\versewidth] \poemlines{3}

\indentpattern{00110} \begin{patverse}

There was a young lady of Ryde \\ Who ate some apples and died. \\ The apples fermented \\

Inside the lamented \\

And made cider inside her inside. \\ \end{patverse}

(12)

The Young Lady of Ryde

There was a young lady of Ryde Who ate some apples and died.

The apples fermented 3

Inside the lamented

And made cider inside her inside.

The next example is a song you may have heard of. The ‘forty-niner’ in line 3 refers to the gold rush of 1849.

\settowidth{\versewidth}{In a cavern, in a canyon,} \poemtitle{Clementine}

\begin{verse}[\versewidth] \poemlines{2}

\begin{altverse}

\flagverse{1.} In a cavern, in a canyon, \\ Excavating for a mine, \\

Lived a miner, forty-niner, \label{vs:49} \\ And his daughter, Clementine. \\!

\end{altverse} \begin{altverse}

\flagverse{\textsc{chorus}} Oh my darling, Oh my darling, \\ Oh my darling Clementine. \\

Thou art lost and gone forever, \\ Oh my darling Clementine \\! \end{altverse} \poemlines{0} \end{verse}

Clementine

1. In a cavern, in a canyon,

Excavating for a mine, 2

Lived a miner, forty-niner,

And his daughter, Clementine. 4

chorus Oh my darling, Oh my darling,

Oh my darling Clementine. 6

Thou art lost and gone forever,

Oh my darling Clementine 8

The last example is a much more ambitious use of \indentpattern. In this case it is defined as:

(13)

3.4 Examples 13

Mouse’s Tale

Fury said to

a mouse, That

he met

in the

house,

‘Let us both go to law: I will prosecute you. — Come, I’ll take no denial; We must have a trial: For really this morning I’ve nothing to do.’ Said the mouse to the cur, Such a trial, dear sir, With no jury or judge, would be wasting our breath.’ ‘I’ll be judge, I’ll be jury.’ Said cunning old Fury; ‘I’ll try the whole cause and condemn you to death.’

(14)

4 The package code

To try and avoid name clashes, all the internal commands include the string @vs.

4.1 Preliminaries

Announce the name and version of the package, which requires LA_{TEX 2ε.} 1h∗usci

2\NeedsTeXFormat{LaTeX2e}

3\ProvidesPackage{verse}[2014/05/10 v2.4b verse typesetting]

For reference, here is the original definition of the verse environment from classes.dtx, based on \letting \\ equal \@centercr.

\newenvironment{verse} {\let\\\@centercr \list{}{\itemsep \z@ \itemindent -1.5em% \listparindent\itemindent \rightmargin \leftmargin \advance\leftmargin 1.5em}% \item\relax} {\endlist}

4.2 Verse code

vslineno poemline \c@fvsline modulo@vs verse@envctr \theHpoemlines

We need a counter for verse lines and poem lines, and one for unique hyperref anchors (based on the verse environment). Also one for specifying the start of line numbering. 4\newcounter{vslineno} 5\newcounter{poemline} 6\newcounter{fvsline} 7 \setcounter{fvsline}{0} 8\newcounter{modulo@vs} 9\newcounter{verse@envctr}\setcounter{verse@envctr}{0} 10\newcommand*{\theHpoemline}{\arabic{verse@envctr}.\arabic{poemline}}

\poemlines \poemlines{hnthi} specifies that every hnthi poem line should be numbered. De-fault is not to number any lines.

(15)

4.2 Verse code 15

\verselinenumfont \vlvnumfont

Set the font for line numbers.

19\newcommand*{\verselinenumfont}[1]{\def\vlnumfont{#1}}

20\verselinenumfont{\rmfamily}

\setverselinenums \setverslinenums{hfirstlinenumi}{hstartnumsat i} sets the number of the first verse line to be hfirstlinenumi and the first line to be numbered to be hstartnumsat i. Note that startnumsat < (firstlinenum + poemlines)

21\newcommand*{\setverselinenums}[2]{% Set the poemline counter to #1.

22 \setcounter{poemline}{#1}\addtocounter{poemline}{\m@ne}%

23 \refstepcounter{poemline}%

24 \ifnum\c@modulo@vs>\z@

If line numbers are to be printed, set \c@fvsline to a suitable value so that the first number to be printed will be line #2.

25 \@tempcnta #2\relax 26 \divide\@tempcnta\c@modulo@vs 27 \multiply\@tempcnta\c@modulo@vs 28 \c@fvsline #2\relax 29 \advance\c@fvsline-\@tempcnta 30 \fi 31}

\getmodulo@vs This returns either nothing or a poem line number for printing.

32\newcommand{\getmodulo@vs}{\bgroup

33 \ifnum\c@modulo@vs<\@ne % no line numbers

34 \else

35 \ifnum\c@modulo@vs<\tw@ % every line numbered

36 \vlnumfont\thepoemline 37 \else 38 \@tempcnta\c@poemline 39 \advance\@tempcnta -\c@fvsline 40 \divide\@tempcnta\c@modulo@vs 41 \multiply\@tempcnta\c@modulo@vs 42 \advance\@tempcnta\c@fvsline 43 \ifnum\@tempcnta=\c@poemline\vlnumfont\thepoemline\fi 44 \fi 45 \fi 46\egroup}

\ifaltindent This should be set TRUE for indenting alternate lines.

47\newif\ifaltindent

\ifpattern This should be set TRUE for indenting lines according to a pattern.

48\newif\ifpattern

\ifstarpattern This should be set TRUE for indenting lines according in a patverse* environ-ment.

(16)

\versewidth \versewidth is a convenience length for the user. 50\newlength{\versewidth} \vgap \vin \vindent \stanzaskip

The length \vgap is used as the basis for spacing. \vin makes a horizontal space of \vgap and \vindent is the indentation of wrapped lines in a verse. \stanzaskip controls the space between stanzas.

51\newlength{\vgap} 52\setlength{\vgap}{1.5em} 53\newcommand{\vin}{\hspace*{\vgap}} 54\newlength{\vindent} 55\setlength{\vindent}{2\vgap} 56\newlength{\stanzaskip} 57\setlength{\stanzaskip}{0.75\baselineskip} \vleftskip \vrightskip

Skips to the left and right of a line of verse.

58\newlength{\vleftskip}

59\setlength{\vleftskip}{30pt}

60\newlength{\vrightskip}

61\setlength{\vrightskip}{10pt}

\flagverse \flagverse{hflag i} inserts hflag i at the left (of a line).

62\newcommand{\flagverse}[1]{%

63 \hskip-\vleftskip\llap{#1}\hskip\vleftskip

64 \ignorespaces

65}

\verselinebreak Break a verse line by inserting \newline.1 66\newcommand*{\verselinebreak}[1][\z@]{%

67 \newline\hspace*{#1}%

68 \ignorespaces

69}

\incr@vsline Increment the line counters.

70\newcommand{\incr@vsline}{%

71 \refstepcounter{poemline}%

72 \stepcounter{vslineno}%

73}

\@vsifbang Like the kernel \@ifstar except it looks for an exclamation mark!

74\newcommand{\@vsifbang}[1]{\@ifnextchar !{\@firstoftwo{#1}}}

\@vsifgt Like the kernel \@ifstar except it looks for a > character.

75\newcommand{\@vsifgt}[1]{\@ifnextchar >{\@firstoftwo{#1}}}

(17)

4.2 Verse code 17

\@vstypelinenumright \@vstypelinenumleft \verselinenumbersright \verselinenumbersleft

These control the typesetting of verse line numbers to the right and to the left of the verse. Default is to set them at the right.

76\newcommand*{\@vstypelinenumright}{% 77 \hfill\rlap{\kern\vrightskip\kern\rightmargin\getmodulo@vs}% 78} 79\newcommand*{\@vstypelinenumleft}{% 80 \hfill\rlap{\kern-\textwidth\kern-\vrightskip\getmodulo@vs}% 81} 82\newcommand*{\verselinenumbersright}{\def\@vstypelinenum{\@vstypelinenumright}} 83\newcommand*{\verselinenumbersleft} {\def\@vstypelinenum{\@vstypelinenumleft}} 84\verselinenumbersright

\@vscentercr This puts the poem line number in the margin, increments the line numbers, and then deals with the options. It is based on the kernel \@centercr. This has to handle various forms of the \\ command: \\, \\*, \\!, and \\>, together with an optional length argument.

85\newcommand{\@vscentercr}{%

86 \ifhmode \unskip\else \@nolnerr\fi

87 \@vstypelinenum

88%%%% \hfill\rlap{\kern\vrightskip\kern\rightmargin\getmodulo@vs}% For > call \verselinebreak to process it.

89 \@vsifgt{\verselinebreak}{%

90 \incr@vsline

If the call is \\*... call \@vsxcentercr to handle the *.... If the call is \\!, do nothing. If the call is \\![...], call \@vsicentercr to handle the [...]. Otherwise, call \@vsxcentercr.

91 \par\@ifstar{\nobreak\@vsxcentercr}{%

92 \@vsifbang{\@ifnextchar[ {\@vsicentercr}{}}{\@vsxcentercr}%

93 }%

94 }%

95}

\@vsxcentercr Processes \\*, and either calls \@vsicentercr to handle a [length], or \start@vsline.

96\newcommand{\@vsxcentercr}{%

97 \addvspace{-\parskip}%

98 \@ifnextchar[ {\@vsicentercr}{\start@vsline}%

99}

\@vsicentercr Processes (\\...)[length] and then calls \start@vsline.

100\def\@vsicentercr[#1]{\vskip #1\ignorespaces \start@vsline}

\start@vsline This is called at the start of every verse line except the first.

101\newcommand{\start@vsline}{%

102 \ifaltindent\ifodd\c@vslineno\else\vin\fi\fi%

103 \ifpattern\get@vsindent\fi%

104 \ifstarpattern\getstar@vsindent\fi

(18)

verse The extended verse environment. It sets the verse line counter, then defines the particular list environment adjusting the margins to center according to the length parameter. If the length parameter is at least the \linewidth then the ‘centering’ defaults to the original verse layout.

106\renewenvironment{verse}[1][\linewidth]{% 107 \stepcounter{verse@envctr}% 108 \setcounter{poemline}{0}\refstepcounter{poemline}% 109 \setcounter{vslineno}{1}% 110 \let\\=\@vscentercr 111 \list{}{\itemsep \z@ 112 \itemindent -\vindent% 113 \listparindent\itemindent 114 \parsep \stanzaskip 115 \ifdim #1 < \linewidth 116 \rightmargin \z@ 117 \setlength{\leftmargin}{\linewidth}% 118 \addtolength{\leftmargin}{-#1}% 119 \addtolength{\leftmargin}{-0.5\leftmargin}% 120 \else 121 \rightmargin \leftmargin 122 \fi 123 \addtolength{\leftmargin}{\vindent}}% 124 \item[]% 125} 126{\endlist}

altverse This sets \altindenttrue (afterwards false) and initialises the line counter.

127\newenvironment{altverse}%

128 {\starpatternfalse\patternfalse\altindenttrue\setcounter{vslineno}{1}}%

129 {\altindentfalse}

4.3 Pattern code

The pattern code is based on the idea of converting a string of digits to an array of digits, and then being able to access the digit at a particular position in the array.

\vs@nameedef A shorthand for using \protected@edef.

130\newcommand{\vs@nameedef}[1]{%

131 \expandafter\protected@edef\csname #1\endcsname

132}

\ifbounderror A flag set TRUE if an attempt is made to access an array element outside the array limits.

133\newif\ifbounderror

\ifinteger A flag to indicate if a ‘number’ is an integer (TRUE) or not (FALSE).

(19)

4.3 Pattern code 19

\c@chrsinstr A counter for the number of characters.

135\newcounter{chrsinstr} % CHARactersINSTRing

\newarray \newarray{harraynamei}{hlow i}{hhighi} defines an array called harraynamei (no backslash e.g. MyArray), with low and high limits hlow i and hhighi.

136\newcommand{\newarray}[3]{%

137 \vs@nameedef{#1-low}{#2}%

138 \vs@nameedef{#1-high}{#3}%

139 \ifnum #3<#2

140 \PackageError{verse}{Limits for array #1 are in reverse order}{\@ehc}%

141 \fi

142}

\stringtoarray \stringtoarray{harraynamei}{hstring i} puts each character from hstring i se-quentially into the harraynamei array, starting with hlow i = 1. It checks for an empty hstringi and handles that specially.

143\newcommand{\stringtoarray}[2]{% 144 \def\@vsarrayname{#1}% 145 \protected@edef\the@vsstring{#2}% 146 \newarray{\@vsarrayname}{1}{1}% 147 \@ifmtarg{#2}{% 148 \c@chrsinstr \z@ 149 \@namedef{\@vsarrayname-1}{}% 150 }{% 151 \c@chrsinstr \@ne 152 \expandafter\@vsstringtoarray \the@vsstring\@vsend 153 }% 154}

\@vsstringtoarray Recursively adds characters to the array \@vsarrayname, incrementing the array’s high limit. 155\def\@vsstringtoarray #1#2\@vsend{% 156 \@namedef{\@vsarrayname-\the\c@chrsinstr}{#1}% 157 \vs@nameedef{\@vsarrayname-high}{\the\c@chrsinstr}% 158 \@ifmtarg{#2}{% 159 \def\@vsinext{}% 160 }{% 161 \advance\c@chrsinstr \@ne 162 \def\@vsinext{% 163 \@vsstringtoarray #2\@vsend% 164 }% 165 }% 166 \@vsinext 167}

\setarrayelement \setarrayelement{harraynamei}{hindex i}{hvaluei} sets the harraynamei ar-ray’s element at hindex i to hvaluei.

168\newcommand{\setarrayelement}[3]{%

(20)

170 \vs@nameedef{#1-#2}{#3}%

171}

\getarrayelement \getarrayelement{harraynamei}{hindex i}{hvaluei} defines the parameterless macro hvaluei (e.g., \result) to be the value at hindex i in the harraynamei array.

172\newcommand{\getarrayelement}[3]{%

173 \checkarrayindex{#1}{#2}%

174 \protected@edef#3{\@nameuse{#1-#2}}%

175}

\checkarrayindex \checkarrayindex{harraynamei}{hindex i} checks that the hindex i of the harraynamei array is valid. \ifbounderror is set FALSE if everything is OK, otherwise it is set TRUE.

176\newcommand{\checkarrayindex}[2]{%

177 \bounderrorfalse

178 \expandafter\ifx\csname #1-low\endcsname\relax

179 \ifpattern\else

180 \PackageError{verse}{No array called #1}{\@ehc}%

181 \fi

182 \bounderrortrue

183 \fi

184 \ifnum #2<\@nameuse{#1-low}\relax

185 \ifpattern\else

186 \PackageError{verse}{Index #2 outside limits for array #1}{\@ehc}%

187 \fi

188 \bounderrortrue

189 \fi

190 \ifnum #2>\@nameuse{#1-high}\relax

191 \ifpattern\else

192 \PackageError{verse}{Index #2 outside limits for array #1}{\@ehc}%

193 \fi

194 \bounderrortrue

195 \fi

196}

\@ifmtarg Provides an if-then-else command for an empty macro argument (empty = zero or more spaces only). Use as:

\@ifmtarg{arg1}{Code for arg1 empty}{Code for arg1 not empty} This code is copied from my ifmtarg package.

197\begingroup 198\catcode‘\Q=3 199\long\gdef\@ifmtarg#1{\@xifmtarg#1QQ\@secondoftwo\@firstoftwo\@nil} 200\long\gdef\@xifmtarg#1#2Q#3#4#5\@nil{#4} 201\long\gdef\@ifnotmtarg#1{\@xifmtarg#1QQ\@firstofone\@gobble\@nil} 202\endgroup

\arraytostring \arraytostring{harraynamei}{hstring i} converts the characters in the harraynamei array into the parameterless macro hstringi (e.g., \MyString).

(21)

4.3 Pattern code 21

204 \def#2{}%

205 \c@chrsinstr = \@nameuse{#1-low}%

206 \@vsarraytostring{#1}{#2}%

207}

\@vsarraytostring \@vsarraytostring{harraynamei}{hstring i} recursively adds the (character) el-ements from harraynamei to hstringi.

208\newcommand{\@vsarraytostring}[2]{% 209 \ifnum\c@chrsinstr>\@nameuse{#1-high}\else 210 \protected@edef#2{#2\@nameuse{#1-\thechrsinstr}}% 211 \advance\c@chrsinstr\@ne% 212 \@vsarraytostring{#1}{#2}% 213 \fi% 214}

\checkifinteger \checkifinteger{hnumi} checks if hnumi is an integer. If it is, then \ifinteger is set TRUE, otherwise it is set FALSE. (Code based on Donald Arseneau’s cite package).

215\newcommand{\checkifinteger}[1]{%

216 \protected@edef\@vsa{#1}%

217 \ifcat _\ifnum9<1\gobm{#1} _\else A\fi

218 \integertrue

219 \else

220 \integerfalse

221 \fi

222}

\gobm \gobm{hnumi} is defined as hnumi. It could be defined as:

\newcommand{\gobm}[1]{\ifx-#1\expandafter\gobm\else#1\fi}

which would remove a leading minus sign (hyphen) from its argument (gobm = gobble minus sign). (Code from a posting to CTT by Donald Arseneau on 1997/07/21).

223\newcommand{\gobm}[1]{#1}

\indentpattern \indentpattern{hdigitsi} stores hdigitsi for use as a verse indentation pattern.

224\newcommand{\indentpattern}[1]{%

225 \stringtoarray{Array@vs}{#1}%

226}

\get@vsindent \get@vsindent gets the indent pattern digit for the \thevslineno, then uses this to specify the line indentation as digit*\vgap.

227\newcommand{\get@vsindent}{%

228 \getarrayelement{Array@vs}{\number\value{vslineno}}{\@vspat}%

229 \ifbounderror

230 \arraytostring{Array@vs}{\@vsp@t}%

231 \PackageWarning{verse}{%

232 Index ‘\thevslineno’ for pattern ‘\@vsp@t’ is out of bounds}%

(22)

234 \else

235 \checkifinteger{\@vspat}%

236 \ifinteger\else

237 \arraytostring{Array@vs}{\@vsp@t}%

238 \PackageWarning{verse}{%

239 ‘\@vspat’ at index ‘\thevslineno’ in pattern ‘\@vsp@t’ is not a digit}%

240 \def\@vspat{0}%

241 \fi

242 \fi

243 \ifcase\@vspat\else\hspace*{\@vspat\vgap}\fi

244}

\getstar@vsindent \getstar@vsindent gets the indent pattern digit for the patverse* environment, then uses this to specify the line indentation as digit*\vgap. It lets the pattern repeat by resetting the vslineno counter.

245\newcommand{\getstar@vsindent}{%

246 \expandafter\ifx\csname Array@vs-high\endcsname\relax

247 \PackageError{verse}{A pattern has not been specified}{\@ehc}%

248 \else 249 \ifnum\c@vslineno>\@nameuse{Array@vs-high}% 250 \setcounter{vslineno}{1}% 251 \fi 252 \get@vsindent 253 \fi 254}

patverse The environment for setting verse line indents according to a pattern. It starts by setting \ifpattern TRUE, any other flags to FALSE, and initialises the line number. It ends by setting \ifpattern FALSE.

255\newenvironment{patverse}

256 {\starpatternfalse\patterntrue\altindentfalse\setcounter{vslineno}{1}}

257 {\patternfalse}

patverse* The environment for setting verse line indents according to a repeating pattern. It starts by setting \ifstarpattern TRUE, any other flags to FALSE, and initialises the line number. It ends by setting \ifstarpattern FALSE.

258\newenvironment{patverse*}

259 {\starpatterntrue\patternfalse\altindentfalse\setcounter{vslineno}{1}}

260 {\starpatternfalse}

4.4 Title code

\poemtitle Typeset a poem title (like \section or other). The actual work is done by \@vsptitle (plain) or \@vssptitle (starred).

261\newcommand{\poemtitle}{%

262 \par

263 \secdef\@vsptitle\@vssptitle

(23)

References 23

\poemtoc The kind of entry \poemtitle is to make in the ToC.

265\newcommand{\poemtoc}{section}

\@vsptitle Typeset a poemtitle.

266\def\@vsptitle[#1]#2{% 267 \@nameuse{phantomsection}% 268 \addcontentsline{toc}{\poemtoc}{#1}% 269 \poemtitlemark{#1}% 270 \@vstypeptitle{#2}% 271 \@afterheading 272}

\@vssptitle Typeset a \poemtitle*.

273\def\@vssptitle#1{%

274 \@vstypeptitle{#1}

275 \@afterheading

276}

\@vstypeptitle This really typesets the title.

277\newcommand{\@vstypeptitle}[1]{% 278 \vspace{\beforepoemtitleskip}% 279 {\poemtitlefont #1\par}% 280 \vspace{\afterpoemtitleskip}% 281} \poemtitlefont \poemtitlemark

Sets the appearance to the title of a poem, and something for a header.

282\newcommand{\poemtitlefont}{\normalfont\large\bfseries\centering}

283\newcommand{\poemtitlemark}[1]{}

\beforepoemtitleskip \afterpoemtitleskip

Lengths before and after a poem title, using the \section values.

284\newlength{\beforepoemtitleskip}

285\setlength{\beforepoemtitleskip}{3.5ex \@plus 1ex \@minus .2ex}

286\newlength{\afterpoemtitleskip}

287\setlength{\afterpoemtitleskip}{2.3ex \@plus.2ex}

The end of this package.

288h/usci

References

[GMS94] Michel Goossens, Frank Mittelbach, and Alexander Samarin. The LaTeX Companion. Addison-Wesley Publishing Company, 1994.

(24)

Index

Numbers written in italic refer to the page where the corresponding entry is de-scribed; numbers underlined refer to the code line of the definition; numbers in roman refer to the code lines where the entry is used.

(25)

Typesetting simple verse with L