| 1 |
% \iffalse meta-comment |
| 2 |
% |
| 3 |
% This is sharedline.dtx, a documented TeX source file. |
| 4 |
% |
| 5 |
% To get the user documentation, run this file through LaTeX: |
| 6 |
% > pdflatex sharedline.dtx |
| 7 |
% > makeindex -s gind.ist sharedline.idx |
| 8 |
% > pdflatex sharedline.dtx |
| 9 |
% |
| 10 |
% To extract the package file sharedline.sty: |
| 11 |
% > tex sharedline.ins |
| 12 |
% |
| 13 |
% Copyright 2025 by Jacob Smullyan |
| 14 |
% |
| 15 |
% This work may be distributed and/or modified under the |
| 16 |
% conditions of the LaTeX Project Public License, either version 1.3c |
| 17 |
% of this license or (at your option) any later version. |
| 18 |
% The latest version of this license is in |
| 19 |
% http://www.latex-project.org/lppl.txt |
| 20 |
% and version 1.3 or later is part of all distributions of LaTeX |
| 21 |
% version 2005/12/01 or later. |
| 22 |
% |
| 23 |
% \fi |
| 24 |
% |
| 25 |
% \iffalse |
| 26 |
%<*driver> |
| 27 |
\ProvidesFile{sharedline.dtx} |
| 28 |
[2025/06/26 v1.0 A package for typesetting shared lines in verse] |
| 29 |
\documentclass{ltxdoc} |
| 30 |
\usepackage{parskip} |
| 31 |
\usepackage[T1]{fontenc} |
| 32 |
\usepackage{verse} |
| 33 |
\GetFileInfo{sharedline.dtx} |
| 34 |
\EnableCrossrefs |
| 35 |
\CodelineIndex |
| 36 |
\RecordChanges |
| 37 |
\title{The \textsf{sharedline} package\thanks{This package is licensed under the LPPL v1.3c or later.}} |
| 38 |
\author{Jacob Smullyan} |
| 39 |
\date{\fileversion, \filedate} |
| 40 |
\begin{document} |
| 41 |
\DocInput{sharedline.dtx} |
| 42 |
\end{document} |
| 43 |
%</driver> |
| 44 |
% \fi |
| 45 |
% |
| 46 |
% \changes{v1.0}{2025/06/26}{Initial release} |
| 47 |
% |
| 48 |
% \maketitle |
| 49 |
% \begin{abstract} |
| 50 |
% The \textsf{sharedline} package provides a robust and flexible solution for |
| 51 |
% typesetting shared lines in dramatic verse, such as in the plays of |
| 52 |
% Shakespeare. It allows a single line of verse to be split across multiple |
| 53 |
% speakers while maintaining perfect horizontal alignment, creating the |
| 54 |
% visual effect of a single, continuous line of iambic pentameter. |
| 55 |
% \end{abstract} |
| 56 |
% |
| 57 |
% \tableofcontents |
| 58 |
% |
| 59 |
% \section{Introduction} |
| 60 |
% Typesetting dramatic verse presents a unique challenge: a single metrical |
| 61 |
% line is often shared between two or more characters. Standard use of the |
| 62 |
% \texttt{verse} environment breaks the visual continuity of the line. This |
| 63 |
% package introduces two simple commands, \cs{shareline} and \cs{linefeed}, |
| 64 |
% that work together to solve this problem elegantly. |
| 65 |
% |
| 66 |
% The ``starter'' command, \cs{shareline}, typesets the first part of a |
| 67 |
% shared line and saves its width. The ``continuation'' command, |
| 68 |
% \cs{linefeed}, is then used for all subsequent parts. It typesets an |
| 69 |
% optional introductory text (such as a speaker prompt) at the left margin, |
| 70 |
% then indents the verse text so that it begins at the horizontal position |
| 71 |
% where the previous segment ended. It then adds its own verse width to the |
| 72 |
% running total, so a line can be split any number of times. |
| 73 |
% |
| 74 |
% The package works naturally within the \texttt{verse} environment but does |
| 75 |
% not depend on it. The user retains full control over line breaks, using |
| 76 |
% \texttt{\textbackslash\textbackslash}, \texttt{\textbackslash\textbackslash!}, |
| 77 |
% or other standard mechanisms. |
| 78 |
% |
| 79 |
% \section{Installation} |
| 80 |
% To install the package, place the \texttt{sharedline.sty} file in a |
| 81 |
% location where your \TeX\ distribution can find it. For a local |
| 82 |
% installation, this is typically in your \texttt{texmf} tree (e.g., |
| 83 |
% \texttt{TEXMFHOME/tex/latex/sharedline/}). After moving the file, you may |
| 84 |
% need to refresh your distribution's file database. |
| 85 |
% |
| 86 |
% If you are using this \texttt{.dtx} file, you can extract the package by |
| 87 |
% running the command: \texttt{tex sharedline.ins} |
| 88 |
% |
| 89 |
% \section{Usage} |
| 90 |
% The package provides two commands. They work naturally within the |
| 91 |
% \texttt{verse} environment but do not depend on it. |
| 92 |
% |
| 93 |
% \DescribeMacro{\shareline} |
| 94 |
% \cs{shareline}\marg{full text} \\ |
| 95 |
% Starts a shared line. The mandatory argument contains the entire first |
| 96 |
% segment, including any speaker prompt. The command typesets its argument |
| 97 |
% and saves its total horizontal width as the baseline for subsequent |
| 98 |
% indentation. It does not add a line break; you must add one manually |
| 99 |
% (e.g., with \texttt{\textbackslash\textbackslash}). |
| 100 |
% |
| 101 |
% \DescribeMacro{\linefeed} |
| 102 |
% \cs{linefeed}\oarg{intro}\marg{verse} \\ |
| 103 |
% Continues a shared line. Used for all subsequent parts (second, third, etc.). |
| 104 |
% \begin{itemize} |
| 105 |
% \item \oarg{intro}: Optional introductory text (e.g., a speaker prompt), |
| 106 |
% typeset at the left margin. |
| 107 |
% \item \marg{verse}: The verse text for this segment, indented so that it |
| 108 |
% begins at the horizontal position where the previous segment ended. |
| 109 |
% \end{itemize} |
| 110 |
% After typesetting, the width of the verse text (not the intro) is added to |
| 111 |
% the running total, so that subsequent \cs{linefeed} calls indent further. |
| 112 |
% Like \cs{shareline}, this command does not add a line break. |
| 113 |
% |
| 114 |
% \subsection{Example: A Two-Way Split} |
| 115 |
% \begin{verbatim} |
| 116 |
% \begin{verse} |
| 117 |
% \shareline{ANNE: I would I knew thy heart.}\\ |
| 118 |
% \linefeed[GLOUCESTER: ]{'Tis figured in my tongue.}\\ |
| 119 |
% \end{verse} |
| 120 |
% \end{verbatim} |
| 121 |
% |
| 122 |
% \subsection{Example: A Three-Way Split} |
| 123 |
% Notice that \cs{linefeed} is used for both the second and third parts. A |
| 124 |
% manual line break is required after each segment except the last. |
| 125 |
% \begin{verbatim} |
| 126 |
% \begin{verse} |
| 127 |
% \shareline{GUARD 1: Who goes there?}\\ |
| 128 |
% \linefeed[GUARD 2: ]{Speak now, or I swear}\\ |
| 129 |
% \linefeed[GUARD 1: ]{I'll shoot!}\\ |
| 130 |
% \end{verse} |
| 131 |
% \end{verbatim} |
| 132 |
% |
| 133 |
% \subsection{Example: Without Speaker Prompts} |
| 134 |
% The syntax remains clean when no prompts are needed. Simply omit the |
| 135 |
% optional argument for \cs{linefeed}. |
| 136 |
% \begin{verbatim} |
| 137 |
% \begin{verse} |
| 138 |
% \shareline{A path of dust and dreams beneath the sun,}\\ |
| 139 |
% \linefeed{a journey to a star.}\\ |
| 140 |
% \end{verse} |
| 141 |
% \end{verbatim} |
| 142 |
% |
| 143 |
% \StopEventually{\PrintChanges\PrintIndex} |
| 144 |
% |
| 145 |
% \section{Implementation} |
| 146 |
% We begin by identifying the package and its dependencies. |
| 147 |
% |
| 148 |
% \begin{macrocode} |
| 149 |
%<*package> |
| 150 |
\ProvidesPackage{sharedline}[2025/06/26 v1.0] |
| 151 |
|
| 152 |
\RequirePackage{xparse} |
| 153 |
% \end{macrocode} |
| 154 |
% |
| 155 |
% We use a number of internal lengths and saveboxes. To prevent clashes |
| 156 |
% with user-defined macros or other packages, we use the \verb|@| symbol |
| 157 |
% in their names and wrap the definitions in \cs{makeatletter} and |
| 158 |
% \cs{makeatother}. The prefix \texttt{sl@} is used for ``sharedline''. |
| 159 |
% |
| 160 |
% \begin{macrocode} |
| 161 |
\makeatletter |
| 162 |
|
| 163 |
\newsavebox{\sl@linebox} |
| 164 |
\newlength{\sl@linelength} |
| 165 |
\newsavebox{\sl@subtractbox} |
| 166 |
\newsavebox{\sl@addbox} |
| 167 |
% \end{macrocode} |
| 168 |
% |
| 169 |
% \begin{macro}{\shareline} |
| 170 |
% The starter command. It takes a single mandatory argument |
| 171 |
% containing the full text of the first segment, including any speaker prompt. |
| 172 |
% It places the argument into a box to measure its width, saves this width |
| 173 |
% globally into \cs{sl@linelength}, and typesets the argument. |
| 174 |
% \begin{macrocode} |
| 175 |
\NewDocumentCommand{\shareline}{m}{% |
| 176 |
\sbox{\sl@linebox}{#1}% |
| 177 |
\global\settowidth{\sl@linelength}{\usebox{\sl@linebox}}% |
| 178 |
#1% |
| 179 |
} |
| 180 |
% \end{macrocode} |
| 181 |
% \end{macro} |
| 182 |
% |
| 183 |
% \begin{macro}{\linefeed} |
| 184 |
% The continuation command, used for all subsequent parts of a |
| 185 |
% shared line. It takes an optional intro and a mandatory verse segment. |
| 186 |
% It measures the intro width, typesets the intro, inserts a horizontal space |
| 187 |
% equal to the accumulated length minus the intro width, typesets the verse, |
| 188 |
% and adds the verse width to the running total. |
| 189 |
% \begin{macrocode} |
| 190 |
\NewDocumentCommand{\linefeed}{O{} m}{% |
| 191 |
\sbox{\sl@subtractbox}{#1}% |
| 192 |
#1% |
| 193 |
\hspace*{\dimexpr\sl@linelength - \wd\sl@subtractbox\relax}% |
| 194 |
#2% |
| 195 |
\sbox{\sl@addbox}{#2}% |
| 196 |
\global\addtolength{\sl@linelength}{\wd\sl@addbox}% |
| 197 |
} |
| 198 |
|
| 199 |
\makeatother |
| 200 |
|
| 201 |
\endinput |
| 202 |
% \end{macrocode} |
| 203 |
% \end{macro} |
| 204 |
% |
| 205 |
%</package> |
| 206 |
% \Finale |