Debian Codegraph @

texmf-dist/source/latex/sharedline/sharedline.dtx

raw
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