summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/edmac/edstanza.doc
blob: 0e743caacad404efe8ed6c99ca753c2d4d273a11 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242

\def\fileversion{0.01}
\def\filedate{92/6/25}
\def\docdate {92/6/25}

%% \CheckSum{191}
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%%
%
%
%\iffalse   % This is a META comment
%
% File `edstanza.doc'.
% Copyright (C) 1992 Wayne G. Sullivan, all rights reserved.
%
% Copying of this file is authorized only if either
% (1) you make absolutely no changes to your copy, or
% (2) you use a different name for your modified file.
%
%
% Error reports (unmodified files only):
%                          Department of Mathematics
%                          University College
%                          Dublin 4, Ireland
%                 Bitnet:  <WSULIVAN@IRLEARN>
%
%
%\fi
%
%
% \title{The file {\tt edstanza.doc}\thanks{This file has version
%        number \fileversion, dated \filedate.  The documentation was
%        last updated on \docdate.}.}
%
% \author{Wayne G. Sullivan}
%
% \maketitle
%
% \StopEventually{}
% \section{Stanzas using EDMAC}
% The {\sc edmac} macro package of John Lavagnino and Dominik Wujastyk
% provides a framework for preparing critical editions using \TeX\null.
% This document contains some additional macros specifically for
% handling poetry stanzas which use indentation to indicate rhyme or
% metre. The macros are designed to handle the case in which a line of
% verse requires more than one print line.
% The macros are an adjunct to {\sc edmac}, so
% we check to see if it is loaded.
%    \begin{macrocode}
   \ifx\edmacloaded\relax\else
     \errmessage{EDSTANZA requires EDMAC.}\endinput\fi
%    \end{macrocode}
%
% \begin{macro}{\stanza@count}
% \begin{macro}{\stanzaindentbase}
% Before we can define the main macros we need to save and reset
% some category codes. To save the current values we use
% \verb+\next+ and \verb+\body+ from the \verb+\loop+ macro.
%    \begin{macrocode}
  \chardef\body=\catcode`\@
  \catcode`\@=11
  \chardef\next=\catcode`\&
  \catcode`\&=\active
%    \end{macrocode}
% A count register is allocated for counting lines in a stanza; also allocated
% is a dimension register which is used to specify the base value for
% line indentation; all stanza indentations are multiples of this
% value. The default value of \verb+\stanzaindentbase+ is 20pt.
%    \begin{macrocode}
  \newcount\stanza@count
  \newdimen\stanzaindentbase
  \stanzaindentbase=20pt
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\strip@szacnt}
% \begin{macro}{\setstanzavalues}
% The indentations of stanza lines are non-negative integer multiples of the
% unit called
% \verb+\stanzaindentbase+. To make it easier for the user to specify these
% numbers, some list macros are defined. These take numerical values
% in a list separated by commas and assign the values to special control
% sequences using \verb+\mathchardef+. Though this does limit the range
% from 0 to  32767, it should suffice for most applications,
% including {\em penalties}, which will be discussed below.
%    \begin{macrocode}
\def\strip@szacnt#1,#2|{\def\@tempb{#1}\def\@tempa{#2|}}
\def\setstanzavalues#1#2{\def\@tempa{#2,,|}%
        \stanza@count\z@
     \def\next{\expandafter\strip@szacnt\@tempa
            \ifx\@tempb\empty\let\next\relax\else
            \expandafter\mathchardef\csname #1@\number\stanza@count
            @\endcsname\@tempb\relax
            \advance\stanza@count\@ne\fi\next}%
      \next}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\stanza@line}
% \begin{macro}{\stanza@hang}
% \begin{macro}{\sza@penalty}
% Now we arrive at the main works. \verb+\stanza@line+ sets the
% indentation for the line and starts a numbered paragraph---each
% line is treated as a paragraph. \verb+\stanza@hang+ sets the
% hanging indentation to be used if the stanza line requires
% more than one print line. If it is known that each stanza line
% will fit on one print line, it is advisable to set the
% hanging indentation to zero. \verb+\sza@penalty+ places the
% specified penalty following each stanza line. By default, this
% facility is turned off so that no penalty is included. However,
% the user may initiate these penalties to indicate good and bad
% places in the stanza for page breaking.
%    \begin{macrocode}
\def\stanza@line{\parindent=\csname sza@\number\stanza@count
                 @\endcsname\stanzaindentbase
            \pstart\stanza@hang\ignorespaces}
\xdef\stanza@hang{\noexpand\leavevmode\noexpand\startlock
            \hangindent\expandafter
            \noexpand\csname sza@0@\endcsname\stanzaindentbase
            \hangafter\@ne}
\def\sza@penalty{\count@\csname szp@\number\stanza@count @\endcsname
          \ifnum\count@>\@M\advance\count@-\@M\penalty-\else
          \penalty\fi\count@}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{\stanza}
% \begin{macro}{\endstanzaextra}
% Now we have the components of the \verb+\stanza+ macro,
% which appears at the start of a group of lines. This macro
% initializes the count and checks to see if hanging indentation
% and penalties are to be included. Hanging indentation suspends
% the line count, so that the enumeration is by verse line
% rather than by print line. If the print line count is desired,
% invoke \verb+\let\startlock=\relax+ and do the same for
% \verb+\endlock+. Here and above we have used \verb+\xdef+ to
% make the stored macros take up a bit less space, but it also
% makes them more obscure to the reader. Lines of the stanza are
% delimited by ampersands \&. The last line of the stanza must
% end with \verb+\&+. For convenience the macro
% \verb+\endstanzaextra+ is incuded. The user may use this to add
% vertical space or penalties between stanzas.
%    \begin{macrocode}
\let\endstanzaextra\relax
\xdef\stanza{\begingroup\catcode`\&\active\global\stanza@count\@ne
         \noexpand\ifnum\expandafter\noexpand
         \csname sza@0@\endcsname=\z@\let\noexpand\stanza@hang\relax
         \let\noexpand\endlock\relax\noexpand\else\interlinepenalty
         \@M\rightskip\z@ plus 1fil\relax\noexpand\fi\noexpand\ifnum
         \expandafter\noexpand\csname szp@0@\endcsname=\z@
         \let\noexpand\sza@penalty\relax\noexpand\fi \def\noexpand&{%
         \noexpand\endlock\noexpand\pend\noexpand\sza@penalty\global
         \advance\stanza@count\@ne\noexpand\stanza@line}\def\noexpand
         \&{\noexpand\endlock\noexpand\pend\endgroup\endstanzaextra}%
         \noexpand\stanza@line}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\ampersand}
% The ampersand \& is used to mark the end of each stanza line, except the
% last, which is marked with \verb+\&+. This means that \verb+\halign+ may
% not be used directly within a stanza line. This does not affect macros
% involving alignments defined outside \verb+\stanza  \&+. Since these
% macros usurp the control sequence \verb+\&+, the replacement
% \verb+\ampersand+ is defined to be used if this symbol is needed in a
% stanza. Also we reset the modified category codes and initialize the
% penalty default.
%    \begin{macrocode}
  \catcode`\&=\next
  \catcode`\@=\body
  \let\ampersand=\&
  \setstanzavalues{szp}{0}
    \endinput
%    \end{macrocode}
% \end{macro}
% \section{Indentations in Stanzas}
% In order to use the stanza macros, one must set the indentation values.
% First the value of \verb+\stanzaindentbase+ should be set,
% unless the default value 20pt is desired.
% Every stanza line indentation is a multiple of this. To specify these
% multiples one invokes, {\it e.g.,} \verb+\setstanzavalues{sza}{3,1,2,1,2}+.
% The numerical entries must be whole numbers, 0 or greater, separated by
% commas without embedded spaces. There
% must be one more entry than there are lines in the stanza. The first entry
% gives the hanging indentation to be used if the stanza line requires more
% than one print line. If it is known that each stanza line will fit on
% a single print line, then this first entry should be 0; \TeX\ does less
% work in this case, but no harm ensues if the hanging indentation is not
% 0 but is never used. Enumeration is by stanza lines, not by print lines.
% In the above example the lines are indented one unit, two units, one unit,
% two units, with 3 units of hanging indentation in case a stanza line is too
% long to fit on one print line. Make sure you have at least one more numerical
% entry in \verb+\setstanzavalues+ than the number of lines in the stanza.
% The macros make no restriction on the number of lines in a stanza.
% Stanza indentation values (and penalty values) obey \TeX's grouping
% conventions, so if one stanza among several has a different structure,
% its indentations (penalties) may be set within a group; the prior values
% will be restored when the group ends.
%
% \section{Penalties in Stanzas}
% When the stanzas run over several pages, often it is
% desirable that page breaks should arise between certain lines in the
% stanza, so a facility for including penalties after stanza lines is
% provided. If you are satisfied with the page breaks, you need not set the
% penalty values. The command
% \verb+\setstanzavalues{szp}{1,5000,10100,5000,0}+ results in a penalty of
% 5000  being placed after the first and third lines of the stanza, and a
% penalty of ${-100}$ after the second. The first entry ``1'' is a control
% value. If it is zero, then no penalties are passed on to \TeX\null,
% which is the default. Values between 0 and 10000 are penalty
% values; values between 10001 and 20000 have 10000 subtracted and the result
% is given as a negative penalty. The mechanism used for indentations and
% penalties requires unsigned values less than 32768. No penalty is placed
% after the last line, so the final \verb+,0+ in then example above could
% be omitted. The control sequence \verb+\endstanzaextra+ can be defined to
% include a penalty. A penalty of 10000 will prevent a page break; such a
% penalty is included automatically where there is stanza hanging indentation.
% A penalty of ${-10000}$ (corresponding to the entry value 20000 in this
% context) forces a page break. Values in between act as suggestions as to the
% desirability of a page break at a given line. There is a subtle interaction
% between penalties and {\it glue}, so it may take some adjustment of skips
% and penalties to achieve the best results.
%
% \Finale
\endinput