Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2022 by Tanguy Ortolo <[email protected]>
4 %
5 % Redistribution and use in source and binary forms, with or without
6 % modification, are permitted provided that the following conditions are met:
7 % 1. Redistributions of source code must retain the above copyright notice,
8 % this list of conditions and the following disclaimer.
9 % 2. Redistributions in binary form must reproduce the above copyright notice,
10 % this list of conditions and the following disclaimer in the documentation
11 % and/or other materials provided with the distribution.
12 % 3. Neither the name of the copyright holder nor the names of its
13 % contributors may be used to endorse or promote products derived from this
14 % software without specific prior written permission.
15 %
16 % THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 % AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 % IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 % ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 % LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 % CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 % SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 % INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 % CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 % ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 % POSSIBILITY OF SUCH DAMAGE.
27 %
28 % \fi
29 %
30 % \iffalse
31 %<*driver>
32 \ProvidesFile{songproj.dtx}
33 %</driver>
34 %<package>\NeedsTeXFormat{LaTeX2e}[2020/10/01]
35 %<package>\ProvidesPackage{songproj}
36 %<*package>
37 [2023/03/29 v1.2.0 Song projection]
38 %</package>
39 %
40 %<*driver>
41 \documentclass{l3doc}
42 \usepackage{fontspec}
43 \usepackage{bookmark}
44 \EnableCrossrefs
45 \CodelineIndex
46 \RecordChanges
47 \begin{document}
48 \DocInput{songproj.dtx}
49 \PrintChanges
50 \PrintIndex
51 \end{document}
52 %</driver>
53 % \fi
54 %
55 % \CheckSum{269}
56 %
57 % \CharacterTable
58 % {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
59 % 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
60 % Digits \0\1\2\3\4\5\6\7\8\9
61 % Exclamation \! Double quote \" Hash (number) \#
62 % Dollar \$ Percent \% Ampersand \&
63 % Acute accent \' Left paren \( Right paren \)
64 % Asterisk \* Plus \+ Comma \,
65 % Minus \- Point \. Solidus \/
66 % Colon \: Semicolon \; Less than \<
67 % Equals \= Greater than \> Question mark \?
68 % Commercial at \@ Left bracket \[ Backslash \\
69 % Right bracket \] Circumflex \^ Underscore \_
70 % Grave accent \` Left brace \{ Vertical bar \|
71 % Right brace \} Tilde \~}
72 %
73 %
74 % \changes{v0.1.0}{2021/09/19}{Initial version}
75 % \changes{v0.3.0}{2021/09/26}{Use \textsf{expl3} naming conventions}
76 % \changes{v1.0.0}{2021/11/07}{First public release}
77 % \changes{v1.0.1}{2021/11/07}{Add the generated extension file to Git}
78 % \changes{v1.1.0}{2023/03/27}{Allow couplet numbering with \cs{numbercouplets}}
79 % \changes{v1.2.0}{2023/03/29}{Allow couplet numbering with \cs{inputsong*}}
80 %
81 % \GetFileInfo{songproj.dtx}
82 %
83 % \DoNotIndex{\newcommand,\newenvironment}
84 % \DoNotIndex{\begin,\end}
85 % \DoNotIndex{\bool,\bool_gset_false:N,\bool_gset_true:N,\bool_if:NTF,\bool_new:N}
86 % \DoNotIndex{\cs_gset:Npn,\cs_new:Npn}
87 % \DoNotIndex{\dim,\dim_compare:nNnTF,\dim_new:N,\dim_zero:N}
88 % \DoNotIndex{\int,\int_compare:nNnTF,\int_gset_eq:NN,\int_new:N,\int_step_function:nN,\int_eval:n,\int_mod:nn,\int_step_inline:nn,\int_use:N}
89 % \DoNotIndex{\seq,\seq_count:N,\seq_gclear:N,\seq_gput_right:Nn,\seq_gset_from_clist:Nn,\seq_if_empty:NTF,\seq_item:Nn,\seq_map_function:NN,\seq_new:N}
90 % \DoNotIndex{\tl,\tl_gclear:N,\tl_gset:Nn,\tl_new:N,\tl_use:N,\tl_if_empty:NTF}
91 % \DoNotIndex{\IfNoValueTF,\NewDocumentCommand,\NewDocumentEnvironment}
92 % \DoNotIndex{\env,\cmd,\textsf,\vfill}
93 %
94 %
95 % \title{The \textsf{songproj} package\thanks{This document
96 % corresponds to \textsf{songproj}~\fileversion, dated \filedate.}}
97 % \author{Tanguy Ortolo \\ \texttt{[email protected]}}
98 %
99 % \maketitle
100 % \section{Introduction}
101 %
102 % This package, together with the \cls{beamer} class, is used to generate
103 % slideshows with song lyrics. This is typically used in religious services in
104 % churches equipped with a projector, for which this package has been written,
105 % but it can be useful for any type of singing assembly\footnote{Indeed, the
106 % song used here as an example is not really a religious one! It was chosen
107 % because it is in the public domain and the author likes it.}. It provides
108 % environments to describe a song in a natural way, and formatting it into
109 % slides with overlays.
110 %
111 % \section{Usage}
112 %
113 % \subsection{The \env{song} environment}
114 %
115 % The main feature of this package is the \env{song}, that allows the user to
116 % describe an entire song that will be formatted into slides.
117 %
118 % \paragraph{}
119 % \DescribeEnv{song}
120 % The \env{song}\marg{stanzas per slide}\oarg{couplet list} environment is used
121 % around an entire song. It takes a mandatory argument, \meta{stanzas per
122 % slide}, to specify whether the user wants to show one or two
123 % stanzas\footnote{including the refrain} on the slide. An optional argument,
124 % \meta{couplet list} is a comma-separated list of couplet (or verse) indexes,
125 % that allows the user to indicate that they want to include only these
126 % couplets of a large song: without this, all couplets will be included.
127 %
128 % Inside of the \env{song} environment, the user will use the \cs{longest}
129 % command and the \env{intro}, \env{refrain}, \env{couplet}\footnote{We
130 % chose to use the French words \emph{refrain} and \emph{couplet} for several
131 % reason: the author is French, these words are understandable in English and
132 % their English equivalents, \emph{chorus} and \emph{verse}, have multiple
133 % meanings that would make them very ambiguous in both usage and implementation
134 % of this package.} and \env{final} environments.
135 %
136 % \paragraph{Warning} Inside a \env{song} environment, it is an error to write
137 % anything that is not an \env{intro}, \env{refrain}, \env{couplet},
138 % \env{final} environment or a \cs{longest} command. Direct text would be
139 % typeset in a way that would disrupt the song formatting.
140 %
141 % \paragraph{}
142 % \begin{function}{\longest}
143 % \begin{syntax}
144 % \cs{longest}\marg{song line}
145 % \end{syntax}
146 % Inside a \env{song} environment, the \cs{longest}\marg{song line} command is
147 % used to declare the longest line of a song, that will be used to properly
148 % center the song stanzas, as allowed by the \pkg{verse} package. That line
149 % is only used to compute and record its length, and will not be typeset.
150 % \end{function}
151 %
152 % \changes{v1.1.0}{2023/03/27}{Document the \cs{numbercouplets} command}
153 % \begin{function}{\numbercouplets}
154 % \label{doc-cs-numbercouplets}
155 % Inside a \env{song} environment, the \cs{numbercouplets} command can be used
156 % to enable couplet numbering. This can be useful when specific couplets have
157 % been selected but the lead singer has a score a lyrics sheet that includes
158 % all of them: indicating the couplet numbers in the projection will allow them
159 % to check which couplet to sing.
160 % \end{function}
161 %
162 % \changes{v0.4.0}{2021/09/29}{Document \env{intro} and \env{final} environments}
163 %
164 % \paragraph{}
165 % \DescribeEnv{intro}
166 % Inside a \env{song} environment, the optional \env{intro} environment
167 % declares a number of lines meant to be sung once, at the beginning of the
168 % song. In a psalm, this may be an antiphon.
169 %
170 % \paragraph{}
171 % \DescribeEnv{refrain}
172 % Inside a \env{song} environment, the optional \env{refrain} environment
173 % declares the song refrain (or chorus). A song may start with its refrain, or
174 % with a first couplet, followed by the refrain. It is not useful to declare
175 % the refrain several time, as the \env{song} environment will take care of
176 % repeating between the couplets.
177 %
178 % \paragraph{}
179 % \DescribeEnv{couplet}
180 % Inside a \env{song} environment, the \env{couplet} environment declares each
181 % couplet (or verse) of the song.
182 %
183 % \paragraph{}
184 % \DescribeEnv{final}
185 % Inside a \env{song} environment, the optional \env{final} environment
186 % declares a number of lines meant to be sung once, at the end of the song. In
187 % an hymn, that may be a doxology.
188 %
189 % \paragraph{Example} \label{example/song}
190 % The following song is defined with three couplets and a refrain. Since its
191 % begins with a couplet, it will be formatted with the first couplet, the
192 % refrain, the second couplet, the refrain, and so on.
193 %
194 % The \env{song} environment is given two arguments, |{2}[1,2]|. The first one
195 % tells it to show two stanzas, that is, both a couplet and the refrain, on the
196 % generated slide. The second argument tells it to include only the first two
197 % couplets in the output.
198 %
199 % \begin{verbatim}
200 % \begin{frame}
201 % \begin{song}{2}[1,2]
202 % \longest{Light she was, and like a fairy,}
203 % \begin{couplet}
204 % In a cavern, in a canyon, \\
205 % Excavating for a mine. \\
206 % Dwelt a miner, forty-niner, \\
207 % And his daughter, Clementine. \\
208 % \end{couplet}
209 % \begin{refrain}
210 % Oh my darling, oh my darling, \\
211 % Oh my darling Clementine, \\
212 % You are lost and gone forever, \\
213 % Dreadful sorry, Clementine. \\
214 % \end{refrain}
215 % \begin{couplet}
216 % Light she was, and like a fairy, \\
217 % And her shoes were number nine, \\
218 % Herring boxes, without topses, \\
219 % Sandals were for Clementine. \\
220 % \end{couplet}
221 % \begin{couplet}
222 % […]
223 % \end{couplet}
224 % \end{song}
225 % \end{frame}
226 % \end{verbatim}
227 %
228 % \subsection{The \cs{inputsong} command}
229 % \changes{v1.0.0}{2021/11/07}{Document the \cs{inputsong} command}
230 % \changes{v1.2.0}{2023/03/29}{Document the \cs{inputsong*} command}
231 %
232 % \begin{function}{\inputsong, \inputsong*}
233 % \begin{syntax}
234 % \cs{inputsong}\marg{file}\marg{stanzas per slide}\oarg{couplet list}
235 % \cs{inputsong*}\marg{file}\marg{stanzas per slide}\oarg{couplet list}
236 % \end{syntax}
237 %
238 % The \cs{inputsong} command environment is used as a shortcut for
239 % typesetting a song written in an external file. That file should contain the
240 % song content, including intro, refrain, couplet or final as needed, but
241 % \emph{without} being wrapped in a \env{song} environment.
242 %
243 % For instance, one could write a file named \file{clementine.tex} containing
244 % the \emph{content} of the \env{song} environment shown in example
245 % page~\pageref{example/song}, and use it in a slideshow:
246 %
247 % \begin{verbatim}
248 % \frame{\inputsong{clementine.tex}{2}[1,2]}
249 % \end{verbatim}
250 % \end{function}
251 %
252 % The starred version \cs{inputsong*} enables couplet numbering, as described
253 % in \ref{doc-cs-numbercouplets}.
254 %
255 % \subsection{The \env{refrain}, \env{couplet}, \env{intro} and \env{final} environments}
256 %
257 % \changes{v0.4.0}{2021/09/29}{Document \env{intro} and \env{final} environments}
258 %
259 % These commands are also usable outside of a \env{song} environment. In that
260 % case, they simply format a refrain or couplet, which can be useful when you
261 % need more manual control.
262 %
263 % \paragraph{}
264 % \DescribeEnv{refrain}
265 % Outside of a \env{song} environment, this environment simply wraps its
266 % content inside a \env{structure} and a \env{verse} environment. It takes an
267 % optional \meta{verse width} argument, that is used to properly center the
268 % refrain, as allowed by the \pkg{verse} package.
269 %
270 % \paragraph{}
271 % \DescribeEnv{couplet}
272 % Outside of a \env{song} environment, this environment simply wraps its
273 % content inside a \env{verse} environment. It takes an optional \meta{verse
274 % width} argument, that is used to properly center the refrain, as allowed by
275 % the \pkg{verse} package.
276 %
277 % \paragraph{}
278 % \DescribeEnv{intro}
279 % \DescribeEnv{final}
280 % Outside of a \env{song} environment, these environments simply wrap their
281 % content inside a \env{em} and a \env{verse} environment. They takes an
282 % optional \meta{verse width} argument, that is used to properly center the
283 % refrain, as allowed by the \pkg{verse} package.
284 %
285 % \subsection{Usage tips}
286 %
287 % For regular offices, there are several suggestions that can ease the creation
288 % and usage of lyric slideshows.
289 %
290 % \subsubsection{Using dedicated song files}
291 %
292 % It is suggested to write song lyrics in dedicated files, each containing a
293 % single the \emph{content} of a \env{song} environment, without the
294 % environment wrapping itself. They can then be used with the \cs{inputsong}
295 % command.
296 %
297 % For instance, one could write a file named \file{clementine.tex} containing
298 % the \emph{content} of the \env{song} environment shown in example
299 % page~\pageref{example/song}. It would then be used in a slideshow such as:
300 %
301 % \begin{verbatim}
302 % \documentclass{beamer}
303 % \usepackage{songproj}
304 %
305 % \begin{document}
306 % \begin{frame}
307 % \inputsong{clementine.tex}{2}[1,2,3]
308 % \end{frame}
309 % \end{document}
310 % \end{verbatim}
311 %
312 % \subsubsection{Importing text lyrics}
313 % \changes{v1.1.0}{2023/03/27}{Derivate output file name from input file name if not specified}
314 %
315 % Song lyrics are often found in text format with basic markup:
316 %
317 % \begin{verbatim}
318 % 1. In a cavern, in a canon,
319 % Excavating for a mine.
320 % Dwelt a miner, forty-niner,
321 % And his daughter, Clementine.
322 %
323 % C. Oh my darling, oh my darling,
324 % Oh my darling Clementine
325 % You are lost and gone forever,
326 % Dreadful sorry Clementine.
327 %
328 % 2. Light she was, and like a fairy,
329 % And her shoes were number nine,
330 % Herring boxes, without topses,
331 % Sandals were for Clementine.
332 %
333 % […]
334 % \end{verbatim}
335 %
336 % To avoid the tedious task of manually removing text and adding \LaTeX{}
337 % markup, we provide the \file{song2tex.py} helper. Please refer to its
338 % embedded help for detailed instructions about its usage:
339 %
340 % \begin{verbatim}
341 % $ ./song2tex.py --help
342 % $ ./song2tex.py clementine.txt clementine.tex
343 % \end{verbatim}
344 %
345 % \subsubsection{Projection layout advice}
346 % \changes{v1.0.0}{2021/11/07}{Add projection layout advice}
347 %
348 % During a religious service, a song lyrics projection is only a support, and
349 % should not draw their attention away from the main feature, which is the
350 % common prayer.
351 %
352 % I therefore suggest using a very simple Beamer theme, such as its default one
353 % with the \href{https://github.com/rchurchley/beamercolortheme-owl}{owl} color
354 % theme, and removing the navigation symbols. I also suggest not showing song
355 % titles (or anything else that is not actually sung by the assembly) unless
356 % there is a good reason to do so, such as getting used to a song or set of
357 % songs you intend to reuse often.
358 %
359 % \begin{verbatim}
360 % \documentclass{beamer}
361 % \usecolortheme{owl}
362 % \setbeamertemplate{navigation symbols}{}
363 % \usepackage{songproj}
364 % \begin{document}
365 % […]
366 % \end{document}
367 % \end{verbatim}
368 %
369 % \subsubsection{Projection advice}
370 % \changes{v1.0.0}{2021/11/07}{Add projection advice}
371 %
372 % For projecting song lyrics, you can take advantage of using a PDF
373 % presentation software able to show a presenter console on your laptop screen,
374 % and the current slide on the projector. Software like as
375 % \href{https://pdfpc.github.io/}{pdfpc} or
376 % \href{https://github.com/Cimbali/pympress/}{Pympress} can also understand and
377 % adapt their display to the concept of Beamer overlay.
378 %
379 % \StopEventually{}
380 %
381 % \section{Implementation}
382 %
383 % \subsection{Dependencies}
384 %
385 % This module is written using \LaTeX3 programming interfaces and command
386 % definitions:
387 %
388 % \begin{macrocode}
389 \RequirePackage{expl3}
390 \RequirePackage{xparse}
391 % \end{macrocode}
392 %
393 % The implementation of the \env{song} environment and its friends is mainly
394 % based on the \textsf{verse} package:
395 %
396 % \begin{macrocode}
397 \RequirePackage{verse}
398 % \end{macrocode}
399 %
400 % \subsection{Internal definitions}
401 %
402 % Almost all definitions use the \textsf{expl3} syntax:
403 %
404 % \begin{macrocode}
405 \ExplSyntaxOn
406 % \end{macrocode}
407 %
408 % \subsubsection{Internal variables}
409 %
410 % \changes{v0.2.0}{2021/09/23}{Use \texttt{sp} prefix for functions and
411 % variables}
412 % \changes{v1.1.0}{2023/03/27}{Add the \cs{g__sp_show_numbers_bool} variable to
413 % number or not couplets}
414 %
415 % We define a number of internal variables, that are used when reading and
416 % formatting a song. All of these variables are meant to be set globally: since
417 % there is no notion of a song within a song, we are certain that we will
418 % always be either outside of a song or inside a single song.
419 %
420 % \begin{macrocode}
421 \bool_new:N \g__sp_song_bool % are we in a song?
422 \bool_new:N \g__sp_song_start_bool % are we at the start of a song?
423 \bool_new:N \g__sp_refrain_first_bool % does current song start with the
424 % refrain?
425 \bool_new:N \g__sp_show_numbers_bool % should we show the couplet numbers?
426 \int_new:N \g__sp_stanzas_per_slide_int % number of stanzas to show on each
427 % slide (1 or 2)
428 \dim_new:N \g__sp_linewidth_dim % length of the longest line in current
429 % song
430 \tl_new:N \g__sp_intro_tl % current song intro
431 \tl_new:N \g__sp_refrain_tl % current song refrain
432 \seq_new:N \g__sp_couplets_seq % current song couplets
433 \tl_new:N \g__sp_final_tl % current song final
434 \seq_new:N \g__sp_couplet_indexes_seq % indexes of couplets to include
435 % \end{macrocode}
436 %
437 % \subsubsection{Internal environments}
438 %
439 % These are high-level internal environments, that are used in the
440 % implementation of user interface environments.
441 %
442 % \begin{environment}{__sp_refrain}
443 % This environment simply formats a song refrain. It is used in the user interface
444 % \env{refrain} environment.
445 %
446 % \begin{macrocode}
447 \NewDocumentEnvironment {__sp_refrain} {}
448 % The environment opening may be followed by a [length], in fact part of its
449 % body, and will appear just after the opening of the verse environment and
450 % constitute its optional argument.
451 {
452 \begin{structureenv}
453 \begin{verse}
454 }
455 {
456 \end{verse}
457 \end{structureenv}
458 }
459 % \end{macrocode}
460 % \end{environment}
461 %
462 % \begin{environment}{__sp_couplet}
463 % This environment simply formats a song couplet. It is used in the user interface
464 % \env{couplet} environment.
465 %
466 % \begin{macrocode}
467 \NewDocumentEnvironment {__sp_couplet} {}
468 % The environment opening may be followed by a [length], in fact part of its
469 % body, and will appear just after the opening of the verse environment and
470 % constitute its optional argument.
471 { \begin{verse} }
472 { \end{verse} }
473 % \end{macrocode}
474 % \end{environment}
475 %
476 % \begin{environment}{__sp_special} {}
477 %
478 % \changes{v0.4.0}{2021/09/29}{Add an environment to format intro and final}
479 %
480 % This environments simply formats a song intro of final. It is used in the
481 % user interface \env{intro} and \env{final} environments.
482 %
483 % \begin{macrocode}
484 \NewDocumentEnvironment {__sp_special} {}
485 % The environment opening may be followed by a [length], in fact part of its
486 % body, and will appear just after the opening of the verse environment and
487 % constitute its optional argument.
488 {
489 \begin{em}
490 \begin{verse}
491 }
492 {
493 \end{verse}
494 \end{em}
495 }
496 % \end{macrocode}
497 % \end{environment}
498 %
499 % \subsubsection{Internal macros}
500 % \changes{v0.3.0}{2021/09/26}{Define aux functions at top-level}
501 %
502 % These are macros that are used in the implementation of the \env{song}
503 % environment.
504 %
505 % \begin{macro}{\__sp_song_refrain}
506 %
507 % This macro uses the \env{__sp_refrain} environment to format the current song
508 % refrain.
509 %
510 % \begin{macrocode}
511 \tl_gset:Nn \__sp_song_refrain
512 {
513 % Do we know the width of the longest song line?
514 \dim_compare:nNnTF \g__sp_linewidth_dim {=} {0pt}
515 { \begin{__sp_refrain} }
516 { \begin{__sp_refrain} [\g__sp_linewidth_dim] }
517 \tl_use:N \g__sp_refrain_tl
518 \end{__sp_refrain}
519 }
520 % \end{macrocode}
521 % \end{macro}
522 %
523 % \begin{macro}{\__sp_song_couplet:n}
524 % \changes{v1.1.0}{2023/03/27}{Print the couplet number when requested}
525 %
526 % This macro uses the \env{__sp_couplet} environment to format a specified couplet of
527 % the current song. It takes a single argument:
528 %
529 % \begin{arguments}
530 % \item index of the couplet to format.
531 % \end{arguments}
532 %
533 % \begin{macrocode}
534 \cs_gset:Npn \__sp_song_couplet:n #1
535 {
536 % Do we know the width of the longest song line?
537 \dim_compare:nNnTF \g__sp_linewidth_dim {=} {0pt}
538 { \begin{__sp_couplet} }
539 { \begin{__sp_couplet} [\g__sp_linewidth_dim] }
540 \bool_if:NTF \g__sp_show_numbers_bool
541 { \flagverse{#1.} }
542 {}
543 \seq_item:Nn \g__sp_couplets_seq {#1}
544 \end{__sp_couplet}
545 }
546 % \end{macrocode}
547 % \end{macro}
548 %
549 % \begin{macro}{\__sp_song_couplets:n}
550 %
551 % This macro inserts an containing all couplets of the current song in an
552 % \env{overprint} environment, in groups separated with \cs{onslide}
553 % commands. It takes a single argument:
554 %
555 % \begin{arguments}
556 % \item number of couplets to show together on each slide.
557 % \end{arguments}
558 %
559 % \begin{macrocode}
560 \cs_gset:Npn \__sp_song_couplets:n #1
561 {
562 \begin{overprint}
563 % Loop on all specified couplets
564 \int_step_inline:nn
565 { \seq_count:N \g__sp_couplet_indexes_seq }
566 {
567 % Before every #1 lines, i.e. when (##1 - 1) mod #1 == 0),
568 % insert an \onslide
569 \int_compare:nNnTF
570 { \int_mod:nn { \int_eval:n{##1 - 1} } {#1} } { = } { 0 }
571 { \onslide<+> }
572 { \vskip \stanzaskip }
573 \__sp_song_couplet:n { \seq_item:Nn \g__sp_couplet_indexes_seq {##1} }
574 }
575 \end{overprint}
576 }
577 % \end{macrocode}
578 % \end{macro}
579 %
580 % \begin{macro}{\__sp_song_intro}
581 %
582 % \changes{v0.4.0}{2021/09/29}{Add an environment to format current song intro}
583 %
584 % This macro uses the \env{__sp_special} environment to format the current song
585 % intro.
586 %
587 % \begin{macrocode}
588 \tl_gset:Nn \__sp_song_intro
589 {
590 % Do we know the width of the longest song line?
591 \dim_compare:nNnTF \g__sp_linewidth_dim {=} {0pt}
592 { \begin{__sp_special} }
593 { \begin{__sp_special} [\g__sp_linewidth_dim] }
594 \tl_use:N \g__sp_intro_tl
595 \end{__sp_special}
596 }
597 % \end{macrocode}
598 % \end{macro}
599 %
600 % \begin{macro}{\__sp_song_final}
601 %
602 % \changes{v0.4.0}{2021/09/29}{Add an environment to format current song final}
603 %
604 % This macro uses the \env{__sp_refrain} environment to format the current song
605 % final.
606 %
607 % \begin{macrocode}
608 \tl_gset:Nn \__sp_song_final
609 {
610 % Do we know the width of the longest song line?
611 \dim_compare:nNnTF \g__sp_linewidth_dim {=} {0pt}
612 { \begin{__sp_special} }
613 { \begin{__sp_special} [\g__sp_linewidth_dim] }
614 \tl_use:N \g__sp_final_tl
615 \end{__sp_special}
616 }
617 % \end{macrocode}
618 % \end{macro}
619 %
620 % \begin{macro}{\__sp_song}
621 %
622 % \changes{v0.4.0}{2021/09/29}{Include intro and final in complete song}
623 %
624 % This macro inserts the entire song, alternating refrain and couplets in an
625 % \env{overprint} environment.
626 %
627 % \begin{macrocode}
628 \tl_gset:Nn \__sp_song
629 {
630 % Is there a song intro?
631 \tl_if_empty:NTF \g__sp_intro_tl
632 {}
633 {
634 \visible<1> {\__sp_song_intro}
635 % The combination of overprint with verse that comes next somehow adds
636 % extra vertical space that needs to be removed.
637 \vskip -\stanzaskip
638 }
639
640 \begin{overprint}
641
642 % Does the song begin with the refrain?
643 \bool_if:NTF \g__sp_refrain_first_bool
644 {
645 % If so, print an initial refrain
646 \onslide<+>
647 \__sp_song_refrain
648 }
649 {}
650
651 % Is there a refrain?
652 \tl_if_empty:NTF \g__sp_refrain_tl
653 {
654 % No refrain, loop on all specified couplets and insert them
655 \seq_map_inline:Nn
656 \g__sp_couplet_indexes_seq
657 {
658 \onslide<+>
659 \__sp_song_couplet:n {#1}
660 }
661 }
662 {
663 % There is a refrain, loop on all specified couplets and, each time,
664 % insert both a couplet and the refrain
665 \seq_map_inline:Nn
666 \g__sp_couplet_indexes_seq
667 {
668 \onslide<+>
669 \__sp_song_couplet:n {#1}
670 \onslide<+>
671 \__sp_song_refrain
672 }
673 }
674 \end{overprint}
675
676 % Is there a song final?
677 \tl_if_empty:NTF \g__sp_final_tl
678 {}
679 {
680 % Add extra spacing
681 \vskip \stanzaskip
682 \visible<.> {\__sp_song_final}
683 }
684 }
685 % \end{macrocode}
686 % \end{macro}
687 %
688 % \subsection{User interface}
689 %
690 % These environments constitute our user interface. They allow the user to
691 % define songs, refrains and couplets.
692 %
693 % \begin{environment}{refrain}
694 % This environment handles a refrain :
695 % \begin{itemize}
696 % \item outside of a song, it uses the \env{__sp_refrain} environment to
697 % directly format it ;
698 % \item inside a song, it stores it into \cs{g__sp_retrain_tl}, so it can
699 % be formatted by the end of the \env{song} environment.
700 % \end{itemize}
701 %
702 % \begin{macrocode}
703 \NewDocumentEnvironment {refrain} { +b }
704 % The environment opening may be followed by a [length], in fact part of its
705 % body, and will appear just after the opening of the __sp_refrain
706 % environment and constitute its optional argument.
707 {
708 % Are we in a song?
709 \bool_if:NTF \g__sp_song_bool
710 {
711 % We are in a song, are we at its start?
712 \bool_if:NTF \g__sp_song_start_bool
713 {
714 % Indicate that we are no longer at the start of the song
715 \bool_gset_false:N\g__sp_song_start_bool
716 % and that the refrain comes first
717 \bool_gset_true:N\g__sp_refrain_first_bool
718 }
719 {}
720 % Anyway, store the refrain
721 \tl_gset:Nn \g__sp_refrain_tl {#1}
722 }
723 {
724 % We are not in a song, use __sp_refrain to format the refrain
725 \begin{__sp_refrain}
726 #1
727 \end{__sp_refrain}
728 }
729 }
730 {}
731 % \end{macrocode}
732 % \end{environment}
733 %
734 % \begin{environment}{couplet}
735 % This environment handles a couplet, in a similar way:
736 % \begin{itemize}
737 % \item outside of a song, it uses the \env{__sp_couplet} environment to
738 % directly format it ;
739 % \item inside a song, it stores it by appending it to to
740 % \cs{g__sp_couplets_seq}, so it can be formatted by the end of the
741 % \env{song} environment.
742 % \end{itemize}
743 %
744 % \begin{macrocode}
745 \NewDocumentEnvironment {couplet} { +b }
746 % The environment opening may be followed by a [length], in fact part of its
747 % body, and will appear just after the opening of the __sp_couplet
748 % environment and constitute its optional argument.
749 {
750 % Are we in a song?
751 \bool_if:NTF \g__sp_song_bool
752 {
753 % Are we at in a song, are we at its start?
754 \bool_if:NTF \g__sp_song_start_bool
755 {
756 % Indicate that we are no longer at the start of the song
757 \bool_gset_false:N \g__sp_song_start_bool
758 % and that the refrain does not come first
759 \bool_gset_false:N \g__sp_refrain_first_bool
760 }
761 {}
762 % Anyway, store this couplet
763 \seq_gput_right:Nn \g__sp_couplets_seq { {#1} }
764 }
765 {
766 % We are not in a song, use __sp_couplet to format this couplet
767 \begin{__sp_couplet}
768 #1
769 \end{__sp_couplet}
770 }
771 }
772 {}
773 % \end{macrocode}
774 % \end{environment}
775 %
776 % \begin{environment}{intro}
777 %
778 % \changes{v0.4.0}{2021/09/29}{Add an \env{intro} environment}
779 %
780 % This environment handles a song intro, in a similar way:
781 % \begin{itemize}
782 % \item outside of a song, it uses the \env{__sp_special} environment to
783 % directly format it;
784 % \item inside a song, it stores it into \cs{g__sp_intro_tl} so it can be
785 % formatted by the end of the \env{song} environment.
786 % \end{itemize}
787 %
788 % \begin{macrocode}
789 \NewDocumentEnvironment {intro} { +b }
790 % The environment opening may be followed by a [length], in fact part of its
791 % body, and will appear just after the opening of the __sp_special
792 % environment and constitute its optional argument.
793 {
794 % Are we in a song?
795 \bool_if:NTF \g__sp_song_bool
796 {
797 % We are in a song, store its intro
798 \tl_gset:Nn \g__sp_intro_tl {#1}
799 }
800 {
801 % We are not in a song, use __sp_special to format the intro
802 \begin{__sp_special}
803 #1
804 \end{__sp_special}
805 }
806 }
807 {}
808 % \end{macrocode}
809 % \end{environment}
810 %
811 % \begin{environment}{final}
812 %
813 % \changes{v0.4.0}{2021/09/29}{Add a \env{final} environment}
814 %
815 % This environment handles a song final, in a similar way:
816 % \begin{itemize}
817 % \item outside of a song, it uses the \env{__sp_special} environment to
818 % directly format it;
819 % \item inside a song, it stores it into \cs{g__sp_final_tl} so it can be
820 % formatted by the end of the \env{song} environment.
821 % \end{itemize}
822 %
823 % \begin{macrocode}
824 \NewDocumentEnvironment {final} { +b }
825 % The environment opening may be followed by a [length], in fact part of its
826 % body, and will appear just after the opening of the __sp_special
827 % environment and constitute its optional argument.
828 {
829 % Are we in a song?
830 \bool_if:NTF \g__sp_song_bool
831 {
832 % We are in a song, store its intro
833 \tl_gset:Nn \g__sp_final_tl {#1}
834 }
835 {
836 % We are not in a song, use __sp_special to format the intro
837 \begin{__sp_special}
838 #1
839 \end{__sp_special}
840 }
841 }
842 {}
843 % \end{macrocode}
844 % \end{environment}
845 %
846 % \begin{macro}{\longest}
847 % This macro measures the length of a song line and stores it, so it can be
848 % used by the \env{song} environment to properly center refrain and couplets.
849 % It takes a single argument:
850 %
851 % \begin{arguments}
852 % \item a song line to measure.
853 % \end{arguments}
854 %
855 % \begin{macrocode}
856 \NewDocumentCommand {\longest} { m } { \settowidth {\g__sp_linewidth_dim} {#1} }
857 % \end{macrocode}
858 % \end{macro}
859 %
860 % \begin{macro}{\numbercouplets}
861 % \changes{v1.1.0}{2023/03/27}{New command to enable couplet numbering}
862 %
863 % This macro can be used within a song to indicate that its couplets should be
864 % numbered.
865 %
866 % \begin{macrocode}
867 \NewDocumentCommand {\numbercouplets}{}
868 { \bool_gset_true:N \g__sp_show_numbers_bool }
869 % \end{macrocode}
870 % \end{macro}
871 %
872 % \begin{environment}{song}
873 % \changes{v1.1.0}{2023/03/27}{Do not number couplets by default}
874 %
875 % This environment is used as a container for entire songs. On opening, it does several things:
876 % \begin{enumerate}
877 % \item its stores its arguments into variables with a descriptive name;
878 % \item it clears out any previously stored refrain, couplet, intro, final
879 % and longest song line;
880 % \item it sets the \cs{g__sp_song_bool} variable to indicate that we
881 % are inside a song, which will alter the behaviour of the
882 % \env{refrain} and \env{couplet} environments so they record their
883 % content rather than directly formatting it into the document;
884 % \item it sets the \cs{g__sp_song_start_bool} variable to indicate that
885 % we are at the start of the song, which will allow the next
886 % \env{refrain} or \env{couplet} to tell if the song starts with the
887 % refrain or with a couplet;
888 % \item it sets the \cs{g__sp_show_numbers_bool} variable to false, to
889 % indicate that the couplets should not be numbered by default (the user
890 % will be able to override this with the \cs{numbercouplets} command).
891 % \end{enumerate}
892 %
893 % This environment takes two arguments:
894 %
895 % \begin{arguments}
896 % \item number of stanzas (counting couplets and refrain, when there is one) per slide;
897 % \item list of couplets to include (defaults to all), for instance |1,3,4|.
898 % \end{arguments}
899 %
900 % \begin{macrocode}
901 \NewDocumentEnvironment {song} { m o }
902 % {number of stanzas per slide (1 or 2)}
903 % [list of couplets to include (defaults to all)]
904 {
905 % Put arguments into variables with understandable names
906 \int_gset_eq:NN {\g__sp_stanzas_per_slide_int} {#1}
907 \IfNoValueTF {#2}
908 { \seq_gclear:N \g__sp_couplet_indexes_seq }
909 { \seq_gset_from_clist:Nn \g__sp_couplet_indexes_seq {#2} }
910
911 % Clear out intro, refrain, couplet, final and longest song line
912 \tl_gclear:N \g__sp_intro_tl
913 \tl_gclear:N \g__sp_refrain_tl
914 \seq_gclear:N \g__sp_couplets_seq
915 \tl_gclear:N \g__sp_final_tl
916 \dim_zero:N {\g__sp_linewidth_dim}
917
918 % Indicate that we are in a song, and at its start
919 \bool_gset_true:N \g__sp_song_bool
920 \bool_gset_true:N \g__sp_song_start_bool
921
922 % Couplets should not be numbered by default
923 \bool_gset_false:N \g__sp_show_numbers_bool
924 }
925 % \end{macrocode}
926 %
927 % And on closing:
928 % \begin{itemize}
929 % \item if no list of couplet indexes to use have been given, it generates one
930 % covering all couplets in order;
931 % \item it uses internal functions to insert the intro, refrain, couplets and
932 % final into the document, in the right order according to the song
933 % structure (refrain or couplet first) and to the formatting instructions
934 % (one or two stanzas per slide).
935 % \end{itemize}
936 %
937 % \changes{v0.4.0}{2021/09/29}{Include intro and final in formatted song}
938 %
939 % \begin{macrocode}
940 {
941 % Have we been given indexes of specific couplets to use?
942 \seq_if_empty:NTF \g__sp_couplet_indexes_seq
943 {
944 % If not, generate it from the list of couplets
945 \int_step_inline:nn
946 { \seq_count:N \g__sp_couplets_seq }
947 { \seq_gput_right:Nn \g__sp_couplet_indexes_seq {##1} }
948 }
949 {}
950
951 % Now we actually start inserting things into the document.
952 % How many stanzas per side did the user request?
953 \int_compare:nNnTF \g__sp_stanzas_per_slide_int {>} {1}
954 {
955 % More than one stanza per slide
956 %
957 % Is there an intro?
958 \tl_if_empty:NTF \g__sp_intro_tl
959 {}
960 {
961 \visible<1> {\__sp_song_intro}
962 % Adjust vertical spacing depending on whether the refrain or the
963 % couplets follow.
964 \bool_if:NTF\g__sp_refrain_first_bool
965 {
966 % Refrain comes next, add extra space
967 \vskip \parsep
968 }
969 {
970 % Couplets come next, the combination of their overprint and
971 % verse environment somehow adds extra vertical space that
972 % needs to be removed.
973 \vskip -\stanzaskip
974 }
975 }
976
977 % Is there a refrain?
978 \tl_if_empty:NTF \g__sp_refrain_tl
979 {
980 % If there is no refrain, we use \__sp_song_couplets:n to write the
981 % couplets, \g__sp_stanzas_per_slide_int at a time.
982 \__sp_song_couplets:n { \int_use:N \g__sp_stanzas_per_slide_int }
983 }
984 {
985 % If there is a refrain, we use \__sp_song_refrain to write the
986 % refrain and \__sp_song_couplets:n to write overprint with all
987 % couplets.
988
989 % Does the song begin with the refrain?
990 \bool_if:NTF\g__sp_refrain_first_bool
991 {
992 \__sp_song_refrain
993 \vskip -\stanzaskip
994 \__sp_song_couplets:n 1
995 }
996 {
997 \__sp_song_couplets:n 1
998 \vskip \stanzaskip
999 \__sp_song_refrain
1000 }
1001 }
1002
1003 % Is there a final?
1004 \tl_if_empty:NTF \g__sp_final_tl
1005 {}
1006 {
1007 % Adjust vertical spacing depending on whether we follow the
1008 % refrain or the couplets.
1009 \tl_if_empty:NTF \g__sp_refrain_tl
1010 {
1011 % No refrain, we follow the couplets, add extra space
1012 \vskip \stanzaskip
1013 }
1014 {
1015 % There was a refrain, did it come first?
1016 \bool_if:NTF \g__sp_refrain_first_bool
1017 {
1018 % Refrain came first, we follow the couplets, add extra space
1019 \vskip \stanzaskip
1020 }
1021 {
1022 % Refrain came last, we follow it, add extra space
1023 \vskip \parsep
1024 }
1025 }
1026 \visible<.> {\__sp_song_final}
1027 }
1028 }
1029 {
1030 % If the user requested one stanza per slide, we use \__sp_song to
1031 % write the entire song in a single overprint environment.
1032 \__sp_song
1033 }
1034 % Indicate that we are no longer in a song
1035 \bool_gset_false:N\g__sp_song_bool
1036 }
1037 % \end{macrocode}
1038 % \end{environment}
1039 %
1040 % \begin{macro}{\inputsong}
1041 % \changes{v1.0.0}{2021/11/07}{Add an \cs{inputsong} command}
1042 % \changes{v1.2.0}{2023/03/29}{Add an \cs{inputsong*} command}
1043 %
1044 % This macro starts a \env{song} environment and \cs{input}s the song content
1045 % from an external file.
1046 %
1047 % \begin{macrocode}
1048 \NewDocumentCommand {\inputsong} { s m m o }
1049 {
1050 \IfNoValueTF {#4}
1051 { \begin{song} {#3} }
1052 { \begin{song} {#3} [#4] }
1053 \IfBooleanT {#1}
1054 { \numbercouplets }
1055 \input{#2}
1056 \end{song}
1057 }
1058 % \end{macrocode}
1059 % \end{macro}
1060 %
1061 % \subsection{Wrapping up}
1062 %
1063 % Now that we have defined everything we need, we can leave the \textsf{expl3}
1064 % syntax and return to normal \TeX{} syntax:
1065 %
1066 % \begin{macrocode}
1067 \ExplSyntaxOff
1068 % \end{macrocode}
1069 %
1070 % \Finale
1071 \endinput