summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/songproj/songproj.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/songproj/songproj.dtx')
-rw-r--r--macros/latex/contrib/songproj/songproj.dtx67
1 files changed, 57 insertions, 10 deletions
diff --git a/macros/latex/contrib/songproj/songproj.dtx b/macros/latex/contrib/songproj/songproj.dtx
index 7c1783fe15..6ed09318c0 100644
--- a/macros/latex/contrib/songproj/songproj.dtx
+++ b/macros/latex/contrib/songproj/songproj.dtx
@@ -34,7 +34,7 @@
%<package>\NeedsTeXFormat{LaTeX2e}[2020/10/01]
%<package>\ProvidesPackage{songproj}
%<*package>
- [2022/11/07 v1.0.1 Song projection]
+ [2023/03/29 v1.2.0 Song projection]
%</package>
%
%<*driver>
@@ -52,7 +52,7 @@
%</driver>
% \fi
%
-% \CheckSum{256}
+% \CheckSum{269}
%
% \CharacterTable
% {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
@@ -75,6 +75,8 @@
% \changes{v0.3.0}{2021/09/26}{Use \textsf{expl3} naming conventions}
% \changes{v1.0.0}{2021/11/07}{First public release}
% \changes{v1.0.1}{2021/11/07}{Add the generated extension file to Git}
+% \changes{v1.1.0}{2023/03/27}{Allow couplet numbering with \cs{numbercouplets}}
+% \changes{v1.2.0}{2023/03/29}{Allow couplet numbering with \cs{inputsong*}}
%
% \GetFileInfo{songproj.dtx}
%
@@ -147,6 +149,16 @@
% is only used to compute and record its length, and will not be typeset.
% \end{function}
%
+% \changes{v1.1.0}{2023/03/27}{Document the \cs{numbercouplets} command}
+% \begin{function}{\numbercouplets}
+% \label{doc-cs-numbercouplets}
+% Inside a \env{song} environment, the \cs{numbercouplets} command can be used
+% to enable couplet numbering. This can be useful when specific couplets have
+% been selected but the lead singer has a score a lyrics sheet that includes
+% all of them: indicating the couplet numbers in the projection will allow them
+% to check which couplet to sing.
+% \end{function}
+%
% \changes{v0.4.0}{2021/09/29}{Document \env{intro} and \env{final} environments}
%
% \paragraph{}
@@ -215,10 +227,12 @@
%
% \subsection{The \cs{inputsong} command}
% \changes{v1.0.0}{2021/11/07}{Document the \cs{inputsong} command}
+% \changes{v1.2.0}{2023/03/29}{Document the \cs{inputsong*} command}
%
-% \begin{function}{\inputsong}
+% \begin{function}{\inputsong, \inputsong*}
% \begin{syntax}
% \cs{inputsong}\marg{file}\marg{stanzas per slide}\oarg{couplet list}
+% \cs{inputsong*}\marg{file}\marg{stanzas per slide}\oarg{couplet list}
% \end{syntax}
%
% The \cs{inputsong} command environment is used as a shortcut for
@@ -235,6 +249,9 @@
% \end{verbatim}
% \end{function}
%
+% The starred version \cs{inputsong*} enables couplet numbering, as described
+% in \ref{doc-cs-numbercouplets}.
+%
% \subsection{The \env{refrain}, \env{couplet}, \env{intro} and \env{final} environments}
%
% \changes{v0.4.0}{2021/09/29}{Document \env{intro} and \env{final} environments}
@@ -293,6 +310,7 @@
% \end{verbatim}
%
% \subsubsection{Importing text lyrics}
+% \changes{v1.1.0}{2023/03/27}{Derivate output file name from input file name if not specified}
%
% Song lyrics are often found in text format with basic markup:
%
@@ -391,6 +409,8 @@
%
% \changes{v0.2.0}{2021/09/23}{Use \texttt{sp} prefix for functions and
% variables}
+% \changes{v1.1.0}{2023/03/27}{Add the \cs{g__sp_show_numbers_bool} variable to
+% number or not couplets}
%
% We define a number of internal variables, that are used when reading and
% formatting a song. All of these variables are meant to be set globally: since
@@ -402,6 +422,7 @@
\bool_new:N \g__sp_song_start_bool % are we at the start of a song?
\bool_new:N \g__sp_refrain_first_bool % does current song start with the
% refrain?
+\bool_new:N \g__sp_show_numbers_bool % should we show the couplet numbers?
\int_new:N \g__sp_stanzas_per_slide_int % number of stanzas to show on each
% slide (1 or 2)
\dim_new:N \g__sp_linewidth_dim % length of the longest line in current
@@ -500,8 +521,9 @@
% \end{macro}
%
% \begin{macro}{\__sp_song_couplet:n}
+% \changes{v1.1.0}{2023/03/27}{Print the couplet number when requested}
%
-% This macro uses the \env{__sp_couplet} environment to a specified couplet of
+% This macro uses the \env{__sp_couplet} environment to format a specified couplet of
% the current song. It takes a single argument:
%
% \begin{arguments}
@@ -515,6 +537,9 @@
\dim_compare:nNnTF \g__sp_linewidth_dim {=} {0pt}
{ \begin{__sp_couplet} }
{ \begin{__sp_couplet} [\g__sp_linewidth_dim] }
+ \bool_if:NTF \g__sp_show_numbers_bool
+ { \flagverse{#1.} }
+ {}
\seq_item:Nn \g__sp_couplets_seq {#1}
\end{__sp_couplet}
}
@@ -832,7 +857,20 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\numbercouplets}
+% \changes{v1.1.0}{2023/03/27}{New command to enable couplet numbering}
+%
+% This macro can be used within a song to indicate that its couplets should be
+% numbered.
+%
+% \begin{macrocode}
+ \NewDocumentCommand {\numbercouplets}{}
+ { \bool_gset_true:N \g__sp_show_numbers_bool }
+% \end{macrocode}
+% \end{macro}
+%
% \begin{environment}{song}
+% \changes{v1.1.0}{2023/03/27}{Do not number couplets by default}
%
% This environment is used as a container for entire songs. On opening, it does several things:
% \begin{enumerate}
@@ -847,6 +885,9 @@
% we are at the start of the song, which will allow the next
% \env{refrain} or \env{couplet} to tell if the song starts with the
% refrain or with a couplet;
+% \item it sets the \cs{g__sp_show_numbers_bool} variable to false, to
+% indicate that the couplets should not be numbered by default (the user
+% will be able to override this with the \cs{numbercouplets} command).
% \end{enumerate}
%
% This environment takes two arguments:
@@ -877,6 +918,9 @@
% Indicate that we are in a song, and at its start
\bool_gset_true:N \g__sp_song_bool
\bool_gset_true:N \g__sp_song_start_bool
+
+ % Couplets should not be numbered by default
+ \bool_gset_false:N \g__sp_show_numbers_bool
}
% \end{macrocode}
%
@@ -994,18 +1038,21 @@
% \end{environment}
%
% \begin{macro}{\inputsong}
-% \changes{v1.0.0}{2021/11/07}{Add a \cs{inputsong} command}
+% \changes{v1.0.0}{2021/11/07}{Add an \cs{inputsong} command}
+% \changes{v1.2.0}{2023/03/29}{Add an \cs{inputsong*} command}
%
% This macro starts a \env{song} environment and \cs{input}s the song content
% from an external file.
%
% \begin{macrocode}
-\NewDocumentCommand {\inputsong} { m m o }
+\NewDocumentCommand {\inputsong} { s m m o }
{
- \IfNoValueTF {#3}
- { \begin{song} {#2} }
- { \begin{song} {#2} [#3] }
- \input{#1}
+ \IfNoValueTF {#4}
+ { \begin{song} {#3} }
+ { \begin{song} {#3} [#4] }
+ \IfBooleanT {#1}
+ { \numbercouplets }
+ \input{#2}
\end{song}
}
% \end{macrocode}