summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/thalie/thalie.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-12-29 23:21:20 +0000
committerKarl Berry <karl@freefriends.org>2015-12-29 23:21:20 +0000
commitee249cd54ebe341b124574c6d7b6d6f08c659a84 (patch)
tree267c7f988e12504628f06f7e4c09a4d12b8a6e4b /Master/texmf-dist/source/latex/thalie/thalie.dtx
parentf281e35ba5b0fdd1bacb0f9736ba138aa42ce189 (diff)
thalie (29dec15)
git-svn-id: svn://tug.org/texlive/trunk@39232 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/thalie/thalie.dtx')
-rw-r--r--Master/texmf-dist/source/latex/thalie/thalie.dtx256
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},