path: root/macros/latex/contrib/play/play.dtx

% \iffalse meta-comment
%% play - Typesetting Drama with LaTeX2e
%
% Copyright (c) 1999 James Kilfiger
%
% The play package
% This program can redistributed and/or modified under the terms
% of the LaTeX Project Public License Distributed from CTAN
% archives in directory macros/latex/base/lppl.txt; either
% version 1 of the License, or (at your option) any later
% version.
% \fi
%% \CheckSum{159}
%% \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
%<*driver>
\documentclass{ltxdoc}
\begin{document}
\DocInput{play.dtx}
\end{document}
%</driver>
%\fi
%\title{Typesetting Drama with \LaTeX}
%\author{James Kilfiger |mapdn@csv.warwick.ac.uk|}
%\date{26th March 1999}
%\maketitle
%
%\begin{abstract}
%  A package and a class for typesetting plays and versed plays. 
%  It is especially
%  designed for typesetting short extracts of plays.
%\end{abstract}
% 
% \section{Usage}
% This is a small package for typesetting plays. It provides two new 
% environments: |play| and |verseplay|. The first is for prose dramas, and 
% second for plays in verse.  The environments are implemented as
% lists, and the 
% character's names are introduced by |\item| with an optional argument.
%
%   The verseplay environment takes an optional argument for the width of 
% the box for the names of the characters, it defaults to 8em.
%
%   In addition there are three commands: |\shortdirection|, which typesets its 
% argument emphasized and in brackets, |\longdirection| which typesets its 
% argument emphasized and displayed, and |\phantomline| which is intended for 
% making long indentations when one character finishes the line of verse 
% started by another. 
%
% If the class form is used then |\act|, |\scene| and |\setting|
% commands are defined, to introduce acts and scenes (these commands
% take no argument) And to describe a setting
%
% If the |lineno| option is given to the package or class then
% verseplays will be numbered, every five lines.  This may be adjusted
% by the |linemodulo| counter. Setting |linemodulo| to zero turns off
% line numbering.  Line numbering the play environment is beyond the
% scope of this package, but may be achieved with the |lineno| package
%
%   When quoting from a play the entire environment should be embedded
% in a quote environment.
%
%   The typesetting in this file is based on the recommendations in the the
% \emph{MHRA Style Book}~\cite{MRHA}.
%
% I have adapted a number of ideas from  Antti-Juhani Kaijanaho's |plari|
% class~\cite{plari}. Particularly the |\act|, |\scene|, and |\setting| commands.
% However the implementation of these commands is my own.
% \section{Changes}
% I've included a |\speaker| command, for better markup. See the
% examples below.  I've provided a |thesetting| environment, which is
% how it should have been done from the start.  The |\setting| command
% is preseverved.  I've added started forms of the act and scene
% commands. These started forms take 1 argument, the title of the
% scene or act.  They format of the character's names is now more
% flexible the commands |\speakerfont| and |\speakerdelim| may be set,
% with |\renewcommand|. Similarly there are |\shortdirectionopen| and
% |shortdirectionclosed| which are the delimiters of short directions
% (normally `(' and `)') and |\directionfont| normally |\em|
% 
% \begin{thebibliography}{2}
% \bibitem{MRHA}\emph{MRHA Style book}, Glanville Price, et.~al., fifth
% edition (London: MRHA, 1996)
% \bibitem{plari} The |plari| class, Available from\\
% |CTAN:macros/latex/contrib/supported/plari|
% \end{thebibliography}
%  \section{A sample}
%   \begin{verbatim}
%   \begin{play}
%   \speaker{Brassbound}It will teach other scoundrels to respect widows and 
%   orphans. Do you forget there is such a thing as justice?
%   \speaker{Lady Cicely}\shortdirection{gaily shaking out the finished coat}
%   Oh, if you are going to dress yourself in ermine and call yourself
%   Justice, I give you up. You are just your uncle over again; only he
%   gets \pounds5000 a year for it, and you do it for nothing.
%   \longdirection{She holds up the coat to see whether any further repairs
%   are needed but, seeing none, folds it carefully away.}
%   \speaker{Brassbound \shortdirection{sulkily}} You twist my words very
%   cleverly. [taken from \emph{Captain Brassbound's Conversion \textsc{ii}]
%   \end{play}
%   
%   \begin{verseplay}[9em]
%   \speaker{Macbeth}Prithee, peace!\\
%      I dare do all that may become a man;\\
%      Who dares do more is none.
%   \speaker{Lady Macbeth}\phantomline{Who dares do more is none.}What beast 
%   was't then\\
%      That made you break this enterprise to me?\\
%      When you durst do it, then you were a man;\\
%      And to be more tha what you were, you would\\
%      Be so much more the man. Nor time nor place\\
%      Did then adhere, and you would make both;\\
%      They have made themselves, and that their fitness now\\
%      Does unmake you.
%   \end{verseplay}
% \end{verbatim}
%\StopEventually{\relax}
%\section{Implementation}
% We start by declaring ourself. We generate the correct header
% for a package or class.
%    \begin{macrocode}
%<*package>
\NeedsTeXFormat{LaTeX2e}
%<*justpackage>
\ProvidesPackage{play}[1999/03/26 A LaTeX package for typesetting plays]
%</justpackage>
%<*class>
\ProvidesClass{play}[1999/03/26 A LaTeX class for typesetting plays]
%</class>
%    \end{macrocode}
%
% The definitions for line numbering are taken in part from the lineno
% package. 
% The line numbering
% commands are, by default, set to |\relax|.
%
%    \begin{macrocode}
\DeclareOption{lineno}{
  \newcommand{\PLthemoduloline}{\@tempcnta=\c@line
    \divide\@tempcnta\c@linemodulo
    \multiply\@tempcnta\c@linemodulo
    \ifnum\@tempcnta=\c@line\arabic{line}\fi}
  \newcommand{\@PLtypemodline}{%
    \ifnum\value{linemodulo}=0%
    \else
      \marginpar{\scriptsize\PLthemoduloline}%
    \fi}
  \newcommand{\@PLputline}{%
    \@PLtypemodline
    \refstepcounter{line}}%
}
%    \end{macrocode}
%
% If we are generating a class then we load the book class, with all the
% remaining options. 
%    \begin{macrocode}
%<*class>
\DeclareOption*{%
  \PassOptionsToClass{\CurrentOption}{book}}
%</class>
\ProcessOptions\relax
%<*class>
\LoadClass{book}
%    \end{macrocode}
%
% For the class we define Act, scene and setting macros.  These are not
% required for the package (which is intended for typesetting quotes
% from plays), and so are omitted.  The Act and scene macros use Chapter
% and section. Another reason for not defining them in the package is
% that we cannot be sure that |\chapter| will be defined. One can
% redefine |\actname| and |\scenename| if `Act' and `Scene' are not what
% is required. The |\setting| command should come before the
% |\begin{play}| command. 
% An environment is a much more sencible way of doing the setting. So
% I've included that also. 
% The starred forms of act and scene take an argument, the title of
% the act or scene.
% This whole section is a mess and need total revision
%    \begin{macrocode}
\newcounter{act}
\newcounter{scene}[act]
\renewcommand{\theact}{\Roman{act}}
\renewcommand{\thescene}{\theact.\arabic{scene}}
\newcommand{\actname}{Act}
\newcommand{\scenename}{Scene}

\DeclareRobustCommand\act{\@ifstar{\@sact}{\@act}}

\newcommand{\@act}{%
  \refstepcounter{act}
  \chapter*{\actname~\theact}
  \addcontentsline{toc}{chapter}{\actname~\theact}}

\newcommand{\@sact}[1]{%
  \refstepcounter{act}
  \chapter*{#1}
  \addcontentsline{toc}{chapter}{#1}}

\DeclareRobustCommand{\scene}{\@ifstar{\@sscene}{\@scene}}

\newcommand{\@scene}{%
  \refstepcounter{scene}
  \section*{\scenename~\arabic{scene}}
   \addcontentsline{toc}{section}{\scenename~\arabic{scene}}}

\newcommand{\@sscene}[1]{%
  \refstepcounter{scene}
  \section*{#1}
  \addcontentsline{toc}{section}{\scenename~\arabic{scene}}}

\DeclareRobustCommand{\setting}[1]{\thesetting #1\endthesetting}
\newenvironment{thesetting}{\em\quotation}{\endquotation}
%</class>
%    \end{macrocode}
%
% Here is the stuff for linenumbering. Providecommands are used to stop
% errors caused if these macros weren't defined by the lineno option. 
% The |\typeline| command can be used to put a line number on arbitrary
% lines. 
%    \begin{macrocode}
\newcounter{line}
\newcounter{linemodulo}\setcounter{linemodulo}{5}
\providecommand{\@PLtypemodline}{\relax}
\providecommand\@PLthemoduloline{\relax}
\providecommand{\typeline}{\marginpar{\scriptsize\theline}}
\providecommand{\@PLputline}{\relax}
%    \end{macrocode}
%
% The commands |\shortdirection| and |\longdirection| are for
% instructions to the actors (or whoever). They are formated
% differently. A short direction after a character's name is best put in
% the argument to |\item|. Long directions before the first line of
% dialogue should be put before the |\begin{play}| line, to avoid
% missing |\item| errors.
%    \begin{macrocode}
\newcommand\shortdirectionopen{(}
\newcommand\shortdirectionclose{)}
\newcommand\directionfont{\em}
\DeclareRobustCommand*{\speaker}[1]{\item[#1]}
\DeclareRobustCommand*{\shortdirection}[1]{\shortdirectionopen
                                           {\directionfont#1\/}%
                                           \shortdirectionclose}
\DeclareRobustCommand{\longdirection}[1]%
           {{\list{}{\setlength{\topsep}{0pt}}\item\directionfont#1\endlist}}
%    \end{macrocode}
% The phantom line is a phantom of it's argument.
% This causes problems if the character's name is longer than the 8em
% (or whatever) used to typeset their name in.
%    \begin{macrocode}
\DeclareRobustCommand*{\phantomline}[1]{\leavevmode\phantom{#1}}
%    \end{macrocode}
%
% The playlabel is the format for the character's name. I've just kept
% it as a name is small caps. Should I add a colon?
%    \begin{macrocode}
\newcommand*\speakerfont{\scshape}
\newcommand*\speakerdelim{}
\newcommand*{\@PLplaylabel}[1]{{\speakerfont#1\speakerdelim\hfil}}
%    \end{macrocode}
%
% The |verseplay| environment is modeled on the verse environment. It takes
% an optional argument for the width of the box the names are typeset
% in. The character names are set flush to the left margin. Note that it
% is the |\\| command which generates the lineno. Understanding this is
% the key to good linenumbering.
%    \begin{macrocode}
\newenvironment{verseplay}[1][8em]{%
  \list{}{%
    \setcounter{line}{0}
    \refstepcounter{line}
    \def\\{\@PLputline\@centercr}
    \setlength\labelwidth{#1}
    \setlength\itemindent{-3em}
    \setlength\leftmargin{\labelwidth}
    \setlength{\itemsep}{0pt}
    \setlength{\parsep}{0pt}
    \addtolength\leftmargin{-\itemindent}
    \addtolength\leftmargin{\labelsep}
    \setlength\listparindent{\itemindent}
    \let\makelabel=\@PLplaylabel
  }
}
{\endlist}
%    \end{macrocode}
%
% The |play| environment is modeled on the description environment. (In
% fact apart from the typesetting of the label as \textsc{sc} instead of
% \textbf{bold} it is the description environment)
%    \begin{macrocode}
\newenvironment{play}{%
  \list{}{%
    \setlength{\labelwidth}{0pt}
    \setlength{\labelsep}{1em}
    \setlength{\leftmargin}{1em}
    \setlength{\itemsep}{0pt}
    \setlength{\parsep}{0pt}
    \let\makelabel=\@PLplaylabel
  }
}
{\endlist}
% </package>
%    \end{macrocode}
% \Finale