doc/latex

git-svn-id: svn://tug.org/texlive/trunk@84 c570f23f-e606-0410-a88d-b1316a301751

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

+

+