thalie (29dec15)

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

1 files changed, 164 insertions, 92 deletions

diff --git a/Master/texmf-dist/source/latex/thalie/thalie.dtx b/Master/texmf-dist/source/latex/thalie/thalie.dtx
index 7744193e082..077d0e2986c 100644
--- a/Master/texmf-dist/source/latex/thalie/thalie.dtx
+++ b/Master/texmf-dist/source/latex/thalie/thalie.dtx
@@ -1,5 +1,5 @@
 % \iffalse meta-comment
-% Copyright 2010-2014 Louis Paternault
+% Copyright 2010-2015 Louis Paternault
 %
 % This work may be distributed and/or modified under the
 % conditions of the LaTeX Project Public License, either version 1.3
@@ -110,9 +110,12 @@
 % \DoNotIndex{\WithSuffix}
 % \DoNotIndex{\xappto, \xspace}
 %
-% \title{The \textsf{thalie} package\thanks{This document
-% corresponds to \textsf{thalie}~\fileversion,
-% dated \filedate.}\\A package to typeset drama plays}
+% \newcommand{\bbackslash}{\symbol{92}}
+%
+% \title{The \textsf{thalie} package\thanks{
+%   This document corresponds to \textsf{thalie}~\fileversion, dated \filedate.
+%   Home page, bug requests, etc. at \url{http://git.framasoft.org/spalax/thalie}
+%   }\\A package to typeset drama plays}
 % \author{Louis Paternault\\ \texttt{spalax(at)gresille(dot)org}}
 %
 % \maketitle
@@ -152,10 +155,8 @@
 % are more options when building the dramatis person\ae{}; headers and footers
 % are taken into account, etc. But these improvements are small; it might have
 % been smarter to contribute to |dramatist| instead of starting my own package.
-% The good part is that I have a package that exactly\footnote{Well, not
-% exactly: see the wish list page \pageref{sec:wishlist}. But I do not think
-% |dramatist| can do this either.} fits my needs, and I learned how to write a
-% \LaTeX{} package.
+% The good part is that I have a package that fits my needs, and I learned how
+% to write a \LaTeX{} package.
 %
 % Oh, yes! I know why I started this: I am a geek\ldots
 %
@@ -184,9 +185,10 @@
 % \subsection{Examples}
 %
 % All the examples are taken from Edmond Rostand's \emph{Cyrano de Bergerac}
-% \cite{cyrano}. The snippets are from the original (French) version of this
-% play, roughly translated by myself (which means that they must be of poor
-% quality).
+% \cite{cyrano} or from William Shakespeare's \emph{A Midsummer Night's Dream}
+% \cite{midsummer}. The snippets of \emph{Cyrano de Bergerac} are from the
+% original (French) version of this play, roughly translated by myself (which
+% means that they must be of poor quality).
 %
 % A part of this play (now in public domain), is
 % \textattachfile[mimetype=text/plain,color=0 0 1]{cyrano.tex}{attached to this
@@ -250,8 +252,6 @@
 % \subsection{Package options}
 % \label{sec:options}
 %
-% \subsubsection{Summary}
-%
 % Package options are summed up in table \ref{table:packageoptions}.
 %
 % \begin{table}
@@ -272,11 +272,34 @@
 % |scenelevel| &  & |subsection| \tabularnewline
 % \hline
 % |interludelevel| & |play| |act| |scene| & |act| \tabularnewline
+% \hline
+% |xspace| & |true| |false| & |true|\tabularnewline
 % \end{tabular}
 % \caption{Package options summary}
 % \label{table:packageoptions}
 % \end{table}
 %
+% \subsubsection{Space following character commands}
+% \changes{v0.7}{2015/12/28}{New package option \texttt{xspace}.}
+% As commands introducing characters' lines and displaying characters' names
+% may be frequently used, it might be tempting to omit the following |{}|. For
+% instance, one might prefer to write:
+% \begin{quote}
+% |\cyrano Indeed, \cyranoname is my name!|
+% \end{quote}
+% instead of:
+% \begin{quote}
+% |\cyrano{} Indeed, \cyranoname{} is my name!|
+% \end{quote}
+%
+% If package option |xspace| is set (e.g. |xspace=true|), space is automatically
+% added after those commands if necessary\footnote{This is easily done with
+% the |$\backslash$xspace| command (from the |xspace| package), hence the name.};
+% otherwise, it is not.
+%
+% For historical reasons, the option |xspace| default is |true|, but this might
+% change in some later non-backward compatible version.
+%
 % \subsubsection{Style}
 % The way characters' lines are displayed, as well as play, act and scene
 % titles, can be set when loading the options.
@@ -446,9 +469,9 @@
 % Definition of characters is done inside the |dramatis| environment. If the
 % |hidden| option is given, the dramatis person\ae{} is not printed (its
 % only purpose is then to define the character commands).
-% \begin{center}
+% \begin{quote}
 % |\begin{dramatis}|\oarg{hidden}
-% \end{center}
+% \end{quote}
 % Then, several commands are available to define characters, and organize
 % character definitions.
 %
@@ -489,9 +512,9 @@ Wait for the crowd to leave.  \did{To \bellerosename} Can I stay?
 %
 % \DescribeMacro{\character}
 % To define a character, use command |\character|.
-% \begin{center}%
+% \begin{quote}%
 % |\character|\oarg{\emph{cmd=}command,\emph{drama=}dramatis,\emph{desc=}description}\marg{name}%
-% \end{center}
+% \end{quote}
 % The mandatory argument is the name of the character, as it will appear in each of this character's line. It is later possible to redefine it using command |\setcharactername| (see part \ref{setcharactername}). Optional arguments are:
 % \begin{description}
 % \item[desc] is a description of your character, appearing in the dramatis person\ae{};
@@ -591,7 +614,7 @@ Wait for the crowd to leave.  \did{To \bellerosename} Can I stay?
 % \DescribeMacro{\disposablecharacter}
 % One can need to define characters that are used only once (or a few times).
 % Command |\disposablecharacter| is here to help.
-% \begin{center}|\disposablecharacter|\oarg{directions}\marg{name}\end{center}
+% \begin{quote}|\disposablecharacter|\oarg{directions}\marg{name}\end{quote}
 % This command, used in the body, introduces a line for character |name|, with optional stage
 % directions. It is rendered the same way regular characters are rendered, but
 % nothing is added to the dramatis person\ae{}. It is used in figure
@@ -636,10 +659,10 @@ Wait for the crowd to leave.  \did{To \bellerosename} Can I stay?
 %
 % It is possible to change the name that appears to introduce character's lines
 % within the text. This can be used, for example, when a character is first
-% refered to as \emph{A sailor}, until we learn his real identity, which is
-% \emph{Liz's father}. An example is given in figure
+% refered to as \emph{A voice}, until we learn his real identity, which is
+% \emph{Cyrano}. An example is given in figure
 % \ref{fig:setcharactername_example}.
-% \begin{center}|\setcharactername|\marg{command}\marg{name}\end{center}
+% \begin{quote}|\setcharactername|\marg{command}\marg{name}\end{quote}
 %
 % This command takes two mandatory arguments. The first one, |command|, is the
 % command used to introduce this character's line. The second one is the name
@@ -652,7 +675,7 @@ Wait for the crowd to leave.  \did{To \bellerosename} Can I stay?
 % \ref{fig:character_example}).
 %
 % \paragraph{Choose style}
-% \changes{v0.6}{2014/06/25}{Added character styles \texttt{imprimerie-verse}, \texttt{imprimerie-prose} and \texttt{arden}.}
+% \changes{v0.6}{2014/06/25}{New character styles \texttt{imprimerie-verse}, \texttt{imprimerie-prose} and \texttt{arden}.}
 % Several styles are available, to typeset character's name and lines in
 % different ways. Change the style by loading package using option
 % |characterstyle=|\marg{style} (available styles are |bold|, |center|,
@@ -705,6 +728,66 @@ Wait for the crowd to leave.  \did{To \bellerosename} Can I stay?
 % As we often need to mark pauses in theater, we created the command |\pause|,
 % which is a shortcut for |\did{\pausename}|.
 %
+% \subsection{Splitting verses}
+% \DescribeMacro{\pauseverse}
+% \DescribeMacro{\resumeverse}
+% \DescribeMacro{\adjustverse}
+%
+% When writing verses, it is sometimes useful to split a verse between two
+% characters: the first character starts it in its line, and the second one
+% finishes it in a second line. Visually, the start of the second line is
+% vertically aligned to the end of the first line.
+%
+% \begin{figure}[p]
+% \centering
+% \iffalse
+%<*example>
+% \fi
+% \begin{dramatis}[hidden]
+%   \character[cmd={hermia}]{Hermia}
+%   \character[cmd={theseus}]{Theseus}
+% \end{dramatis}
+% \begin{LTXexample}[pos=b]
+\adjustverse{-7em}
+
+\hermia
+So is Lysander.\pauseverse
+
+\theseus
+\resumeverse In himself he is.
+% \end{LTXexample}
+% \iffalse
+%</example>
+% \fi
+% \caption{Example of commands to split verse}
+% \label{fig:splitverse}
+% \end{figure}
+%
+% Command |\pauseverse|  is used at the end of the verse to be continued,
+% while command |\resumeverse| is used at the beginning of the continuing
+% verse.
+% Let us face it: these commands are kind of a hack, and sometimes, the lines
+% are not aligned the way one would expect them to. To correct this, command
+% |\adjustverse|\marg{length} can be used to add an extra (possibly negative)
+% space when calling |\resumeverse|, to get a correct alignment.
+% See figure \ref{fig:splitverse}, page \pageref{fig:splitverse}, for an
+% example of those three commands.
+%
+% When writing a play in verse, one can use a lot of those commands, which can
+% be tedious because of their long names. So, defining ``shortcuts'' of those
+% commands can be handy, as in the following example.
+%
+% \begin{quote}
+% \begin{verbatim}
+% \newcommand{\pv}{\pauseverse}
+% \newcommand{\rv}{\resumeverse}
+% \end{verbatim}
+% \end{quote}
+%
+% This is not done by default, because short command names is a scare ressource
+% in \LaTeX, so, defining these commands by default might conflict with other
+% packages, while most of |thalie| users will not use them.
+%
 % \section{Implementation}
 % \label{sec:implementation}
 %
@@ -718,7 +801,7 @@ Wait for the crowd to leave.  \did{To \bellerosename} Can I stay?
 % Dramatis person\ae{} is written using a table. Package "longtable" is used to be
 % able to write it on several pages.
 \RequirePackage{longtable}
-% Handling spaces after having introduces characters' lines.
+% Handling spaces after having introduced characters' lines.
 \RequirePackage{xspace}
 %    \end{macrocode}
 %
@@ -815,6 +898,15 @@ Wait for the crowd to leave.  \did{To \bellerosename} Can I stay?
   interludelevel/scene/.code=\def\@interludelevel{scene},
   interludelevel,
 }
+\newif\if@xspace
+\pgfkeys{
+  % xspace option
+  /THALIE/.cd,
+  xspace/.value required,
+  xspace/.is if=@xspace,
+  xspace/.default=true,
+  xspace,
+}
 
 \ProcessPgfPackageOptions{/THALIE}
 %    \end{macrocode}
@@ -1124,8 +1216,18 @@ Wait for the crowd to leave.  \did{To \bellerosename} Can I stay?
 %
 % \subsection{Characters}
 %
-% \subsubsection{Characters' line}
+% \subsubsection{Spacing}
+% Add (or not) an |$\backslash$xspace| command at the end of character names,
+% depending on the |xspace| package option.
+%    \begin{macrocode}
+\newcommand{\@maybexspace}{%
+  \if@xspace%
+    \xspace%
+  \fi%
+}
+%    \end{macrocode}
 %
+% \subsubsection{Characters' line}
 % Define the command |\@speaks|, wich introduce a character's line. It
 % is not meant to be used by user, but will be used by further commands.  It
 % takes two arguments: the character's name, and optionally, a stage direction.
@@ -1135,7 +1237,7 @@ Wait for the crowd to leave.  \did{To \bellerosename} Can I stay?
     \speakswithoutdirection{#2}%
   }{%
     \speakswithdirection{#2}{#1}%
-  }\xspace%
+  }\@maybexspace%
 }
 %    \end{macrocode}
 % 
@@ -1310,7 +1412,7 @@ Wait for the crowd to leave.  \did{To \bellerosename} Can I stay?
 % The tough part of this code is to deal with optional argument.
 \newcommand{\setcharactername}[2]{%
     \expandafter\gdef\csname#1name\endcsname{%
-      #2\xspace%
+      #2\@maybexspace%
     }%
     \expandafter\gdef\csname#1\endcsname{%
       \@ifnextchar[{%
@@ -1454,78 +1556,44 @@ Wait for the crowd to leave.  \did{To \bellerosename} Can I stay?
 \newcommand\pause{\did{\pausename}}
 %    \end{macrocode}
 % \end{macro}
+
+% \subsection{Splitting verses}
+% \begin{macro}{\pauseverse}
+% \changes{v0.7}{2015/12/28}{New commands \texttt{\bbackslash{}pauseverse}, \texttt{\bbackslash{}resumeverse}, \texttt{\bbackslash{}adjustverse}.}
+% \begin{macro}{\resumeverse}
+% \begin{macro}{\adjustverse}
+% Commands to split a verse between several characters.
+%    \begin{macrocode}
+% Thanks to Timothy Li for his question, and David Carlisle for his answer:
+% https://tex.stackexchange.com/questions/107726/107727#107727
+
+\newlength{\@verseadjust}
+\setlength{\@verseadjust}{0pt}
+
+\newcommand{\adjustverse}[1]{\setlength{\@verseadjust}{#1}}
+
+\newcommand{\pauseverse}{{\abovedisplayshortskip\z@\abovedisplayskip\z@
+      \belowdisplayshortskip\z@\belowdisplayskip\z@
+  $$\global\dimen\@ne\predisplaysize
+   \xdef\tmp{%
+        \predisplaysize\the\predisplaysize
+        \prevgraf\the\prevgraf\relax}%
+  $$\vskip\dimexpr-\parskip-\baselineskip\relax}\tmp
+}
+
+\newcommand{\resumeverse}{%
+  \hspace{\@verseadjust}\hspace{\the\dimen\@ne}
+}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \changes{v0.5}{2013/06/08}{First published version.}
 %
 % \addcontentsline{toc}{section}{Change History}
 % \PrintChanges
 %
-% \section*{Wish list}
-% \label{sec:wishlist}
-% \addcontentsline{toc}{section}{Wish list}
-% 
-% \subsubsection*{Verse}
-% I would like to be able to render drama plays in verse, where a verse can be
-% continued on the next line if relevant (as shown on figure \ref{fig:verse}).
-% But I could not find a way to do this, which would not be too complicated for
-% the user, and which I am able to implement.
-% 
-% \begin{figure}
-% \centering
-% \fbox{\begin{minipage}{1\linewidth}
-% \small
-% \begin{otherlanguage}{francais}
-% \begin{dramatis}[hidden]
-% \character[cmd=cyrano]{Cyrano}
-% \character[cmd=vicomte]{Le vicomte}
-% \end{dramatis}
-% \renewcommand{\speakswithoutdirection}[1]{
-%    \begin{center}%
-%    \textsc{#1}%
-%    \end{center}%
-% }
-% \renewcommand{\speakswithdirection}[2]{
-%   \begin{center}%
-%   \textsc{#1},\\\emph{#2}%
-%   \end{center}%
-% }
-% \newlength{\currentverselength}
-% \begin{verse}
-% \vicomte
-% Vous\ldots vous avez un nez\ldots heu\ldots un nez\ldots tr\`es grand.
-% \settowidth{\currentverselength}{Vous\ldots vous avez un nez\ldots heu\ldots un nez\ldots tr\`es grand.}
-% 
-% \cyrano[gravement]
-% \hspace{\currentverselength} Tr\`es.
-% 
-% \vicomte[riant]
-% Ha !
-% \settowidth{\currentverselength}{Ha !}
-% 
-% \cyrano[imperturbable]
-% \hspace{\currentverselength} C'est tout ? \ldots
-% \settowidth{\currentverselength}{\hspace{\currentverselength} C'est tout ? \ldots}
-% 
-% \vicomte
-% \hspace{\currentverselength} Mais\ldots
-% \settowidth{\currentverselength}{\hspace{\currentverselength} Mais\ldots}
-% 
-% \cyrano
-% \hspace{\currentverselength} Ah ! non ! c'est un peu court, jeune homme !\\
-% On pouvait dire\ldots Oh ! Dieu ! \ldots bien des choses en somme\ldots\\
-% En variant le ton, --- par exemple, tenez :\\
-% Agressif : \og Moi, monsieur, si j'avais un tel nez,\\
-%  Il faudrait sur-le-champ que je me l'amputasse ! \fg
-% \end{verse}
-% \end{otherlanguage}
-% \end{minipage}}
-% 
-% \medskip
-% From \emph{Cyrano de Bergerac}, by Edmond Rostand (act I, scene 4).
-% \caption{Wished verse rendering}
-% \label{fig:verse}
-% \end{figure}
-% 
 % \begin{thebibliography}{9}
 %   \addcontentsline{toc}{section}{References}
 %   \bibitem{imprimerienationale}
@@ -1537,6 +1605,10 @@ Wait for the crowd to leave.  \did{To \bellerosename} Can I stay?
 %     {Edmond Rostand},
 %     \emph{Cyrano de Bergerac},
 %     1897
+%   \bibitem{midsummer}
+%     {William Shakespeare},
+%     \emph{A Midsummer Night's Dream},
+%     1600
 %   \bibitem{dtxtut}
 %     {Scott Pakin},
 %     \emph{How to Package Your \LaTeX{} Package --- Tutorial on writing .dtx and .ins files},