summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/edmac/edstanza.doc
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/edmac/edstanza.doc')
-rw-r--r--Master/texmf-dist/doc/latex/edmac/edstanza.doc242
1 files changed, 242 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/edmac/edstanza.doc b/Master/texmf-dist/doc/latex/edmac/edstanza.doc
new file mode 100644
index 00000000000..0e743caacad
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/edmac/edstanza.doc
@@ -0,0 +1,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
+
+