summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/recorder-fingering/recorder-fingering.tex
blob: 066369408dd93492cee56db3e1e49678753537eb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
% !TEX TS-program = LuaLaTeXmk

\documentclass[11pt]{article} 
\usepackage{calc}
\usepackage{fontspec}
\usepackage[lmargin=.75in,rmargin=.75in,tmargin=1in,bmargin=1in]{geometry}
\usepackage{titling}
\usepackage{array, booktabs,tabularx}
\usepackage{enumitem}
\usepackage{fancyvrb}
\usepackage{listings}
\usepackage{url}
\usepackage[sf,small]{titlesec}
\usepackage[section]{placeins}
\usepackage[colorlinks=true]{hyperref}
\setmonofont{Inconsolatazi4}
\usepackage{recorder-fingering}
\usepackage{parskip}
\usepackage{musixtex}
\input musixlyr
\usetikzlibrary{tikzmark}
\usetikzlibrary{positioning}
\NewDocumentCommand{\addf}{m}{\tikz[remember picture]{\node[overlay,above=of pic cs:#1]{\Soprano{#1}};}}
\DefineShortVerb{\|}
\title{The \texttt{recorder-fingering} package}
\author{Alan Munn\\amunn@msu.edu}
\date{Version 1.1\\February 20, 2023}
  
\lstset{%
    basicstyle=\ttfamily\small,
    commentstyle=\itshape\ttfamily\small,
    showspaces=false,
    showstringspaces=false,
    breaklines=true,
    breakautoindent=true,
    frame=single
    captionpos=t
    language=TeX
}
  
\newcommand*{\pkg}[1]{\texttt{#1}}
\newcolumntype{t}[1]{>{\ttfamily}#1}
\newcolumntype{T}{>{\ttfamily}c}
\newcommand*{\bs}{\textbackslash}
\setlength{\droptitle}{-1in}
\renewcommand{\abstractname}{\sffamily Abstract}



\begin{document}
\maketitle
\thispagestyle{empty}
\begin{abstract}{\noindent
The |recorder-fingering| package provides support for generating fingering diagrams for baroque fingering recorders. Standard fingerings are provided for recorders in both C and F, along with methods to create and display alternate fingerings for trills, etc. 
}
\end{abstract}


\section{Display commands}
This package provides five commands (|\Sopranino|, |\Soprano|, |\Alto|, |\Tenor|, and |\Bass|)\footnote{Because \pkg{musixtex} defines commands \pkg{\bs alto} and \pkg{\bs bass} the fingering display commands are capitalized.}  which will produce a fingering diagram for any note in the playable range of that recorder. At present, there are no differences between the three F recorders (sopranino, alto, and bass) and the two C recorders (soprano and tenor), so the different command names are simply there for convenience. 


\begin{table}[htpb]
\centering
\begin{tabularx}{.8\textwidth}{t{r}X}
\toprule
\bs Sopranino [<parameters>]\{<note>\} & Display a fingering diagram for note in F\\
\bs Soprano [<parameters>]\{<note>\} & Display a fingering diagram for note in C\\
\bs Alto [<parameters>]\{<note>\} & Display a fingering diagram for note in F\\
\bs Tenor [<parameters>]\{<note>\} & Display a fingering diagram for note in C\\
\bs Bass [<parameters>]\{<note>\} & Display a fingering diagram for note in F\\
\bottomrule
\end{tabularx}
\caption{Display commands}
\end{table}
\subsection{Note ranges and notation\label{Notes}}
The notes range from C–Eb for recorders in C (|\Soprano| and |\Tenor|) or F–Ab for recorders in F (|\Sopranino| and |\Alto|).

Notes are noted as C-B (first octave) c-b (second octave) and c'–eb' (third octave) with an equivalent scheme starting at F for the recorders in F.

Enharmonic notes are available for any of the flat/sharp notes (i.e., Db and C\#, etc. are both defined by default.)
\subsection{Display parameters}
Fingering diagrams are customizable either globally using |\fingeringSetup{}| or locally as an optional argument passed to any individual command.  

\begin{table}[htpb]
\centering
\begin{tabularx}{.9\textwidth}{t{l}X}
\toprule
thumboffset = <true/false> & Display the thumb hole offset or not (default = \pkg{true})\\
width = <length> & Width of the diagram (default = \pkg{20pt}). Height adjusts proportionally\\
LHRHdivider = <true/false> & Display a line separating the left and right hand holes (default = \pkg{true})\\
LHRHspace = <length> & Space between the left hand and right hand holds (default = \pkg{10pt})\\
trilldir = <L/R/LR> & trill arrows uniformly to the Left or Right, or top 3 holes L, bottom 4 holes R\\
Lpointer = <left trill pointer> & changes the left pointer for trills\\
Rpointer = <right trill pointer> & changes the right pointer for trills\\
trill = \{<list of holes>\} & add a trill marker at each hole position in the list (local use only)\\
\bottomrule
\end{tabularx}
\caption{Display options}
\end{table}

The |width| parameter sets the width of the diagram; it defaults to |20pt| for the default thumb offset diagrams. If you set |thumboffset=false| you will probably want to choose a smaller value e.g. |10pt|.

The |trill| parameter sets an arrow pointing to a hole (numbered 1-7 from the top hole). This parameter is only in effect when using the display commands. It will place an arrow on the side specified by |trilldir| at a single hole or comma separated list of holes. e.g. |trill=3| sets an arrow at hole 3, |trill={6,7}| sets arrows at holes 6 and 7.

The trill arrow direction can be specified using the |trilldir| parameter. Setting it to |L| places all arrows on the left, setting it to |R| places all arrows on the right. Setting it to |LR| places arrows to the left on holes 1-3 and on the right on holes 4-7.

The |Lpointer| and |Rpointer| parameters set the left and right trill pointers. The default values are |Lpointer={$\rightarrow$}| and |Rpointer={$\leftarrow$}|.

You can set the parameters individually for any particular display command, but most likely you'll want global settings. To set the parameters globally use the command |\fingeringSetup|

e.g. |\fingeringSetup{width=12pt,thumboffset=false}| makes all diagrams use an inline thumb hole and 12pt width.
\begin{table}[htpb]
\centering
\begin{tabular}{TTT}
\bs Alto\{c\} & \bs Soprano[width=10pt,thumboffset=false]\{f\} & \bs Alto[trill=3]\{C\}\\
\\
\Alto{c} & \Soprano[width=10pt,thumboffset=false]{f} & \Alto[trill=3]{C}
\end{tabular}
\caption{Example fingering commands}
\end{table}
\section{Producing new fingerings}

There are three commands to add new fingerings to the predefined list, or in fact, to change the existing defaults.
\subsection{Note names}
Although the basic predefined fingerings use the note naming schema outlined in section \ref{Notes}, the note names themselves are arbitrary. This allows you to add trill fingerings or alternate fingerings with meaningful names, e.g. |ftrill| or |altF| are possible names for new fingerings.
\subsection{Fingering vectors}
Fingerings are specified using an 8 (and possibly 9) element comma separated list. Each position in the list denotes a hole starting from the thumb (position 0) to the bell (position 8). Each hole position is indicated by a hole state according to the following scheme:

\begin{table}[htpb]
\centering
\begin{tabularx}{.8\textwidth}{t{r}X}
\toprule
0 &  open hole\\
1 &  closed hole (positions 0-5); single closed hole (positions 6,7)\\
2 &  double closed hole (positions 6,7 only)\\
t &  half hole (thumb)\\
h &  half hole (positions 1-5)\\
\bottomrule
\end{tabularx}
\caption{Hole states}
\end{table}
\subsection{New fingering commands}

Two commands |\NewFfingering| and |\NewCfingering| are designed to add a single fingering. They check whether the name for the fingering is already used and produce an error if so. To overwrite an existing fingering, use |\NewFfingering*| and |\NewCfingering*|.

The third command is designed to enter a set of new fingerings at once. It will override any existing note names. It takes two arguments, a key, and a key value list consisting of note names plus fingering vectors. 

\begin{table}[htpb]
\centering
\begin{tabularx}{.8\textwidth}{X}
\toprule
\texttt{\bs NewFfingering\{<notename>\}\{<fingering vector>\}} \\\rule{3em}{0pt}Add a new note and fingering to the F recorder set\\
\texttt{\bs NewCfingering\{<notename>\}\{<fingering vector>\}} \\\rule{3em}{0pt} Add a new note and fingering to the C recorder set\\
\texttt{\bs AddFingerings\{<key>\}\{<note = \{<fingering vector>\}\}} \\\rule{3em}{0pt} Add a set of new fingerings to the F or C recorder set\\
\bottomrule
\end{tabularx}
\caption{Commands for adding new fingerings}
\end{table}
%\clearpage
\subsection{New fingering examples}
\NewFfingering{BbAtrill}{0,1,1,1,1,1,0,0}
\AddFingerings{C}{
	EFtrill = {0,1,1,1,1,1,0,0},
	altd = {0,1,1,1,1,1,2,2}
}
\AddFingerings{F}{
	agtrill = {0,0,1,1,1,1,0,0}}
\begin{lstlisting}
\NewFfingering{BbAtrill}{0,1,1,1,1,1,0,0}
\Alto[trill=5]{BbAtrill}
\end{lstlisting}
\Alto[trill=5]{BbAtrill}
\clearpage
\begin{lstlisting}
\AddFingerings{C}{
	EFtrill = {0,1,1,1,1,1,0,0},
	altd = {0,1,1,1,1,1,2,2}
\AddFingerings{F}{
	agtrill = {0,0,1,1,1,1,0,0}
}
\Soprano{EFtrill}
\Soprano{altd}\hfil
\Alto{agtrill}\hfil
\end{lstlisting}

\Soprano{EFtrill}\hfil
\Soprano{altd}\hfil
\Alto{agtrill}

\section{Version History}
Version 0.5 of this package (the initial version) was in response to a \href{https://tex.stackexchange.com/q/674847/2693}{TeX.se question} and used a substantially different set of user commands. The current version (1.0) is more flexible and has a more useable user interface. Version 1.1 added support for trill annotation, and added a separation between the left and right hand holes. Bug reports and feature requests are welcome at the \href{https://github.com/amunn/recorder-fingering/issues}{GitHub bug tracker}. 
\section{Acknowledgements}
This is my first attempt to write a package using |expl3|. Thanks to Jonathan P. Spratte for suggesting how to split fingering vectors and the various LaTeX development team members (David Carlisle, Ulrike Fischer, Phelype Olenik and Joseph Wright) who have answered random |expl3| questions in the TeX.se chat. Thanks to Bob Tennent, whose suggestions resulted in version 1.1.  Thanks also to all the TeX.se users who have both asked and answered questions on the site. Your questions encourage new packages like this one and your answers help make the code better.
\clearpage
\section{Samples} The chart below shows all of the possible fingerings.\footnote{Since the top row of the table represents the input name, \pkg{b} and  \pkg{\#} are used instead the proper symbols \flat\ and \sharp.}

\section*{Recorder in C soprano chart}
\begin{tabular}{cccccccccccc}
\toprule
C & C\# & D & Eb & E & F & F\# & G & Ab & A & Bb & B\\ 
\midrule
\Soprano{C} & 
\Soprano{C#} & 
\Soprano{D} & 
\Soprano{Eb} & 
\Soprano{E} &
\Soprano{F} &
\Soprano{F#} &
\Soprano{G} &
\Soprano{Ab} &
\Soprano{A} &
\Soprano{Bb} &
\Soprano{B}\\
\bottomrule
\end{tabular}

\bigskip
\begin{tabular}{cccccccccccc}
\toprule
c & c\# & d & eb & e & f & f\# & g & ab & a & bb & b\\ 
\midrule
\Soprano{c} &
\Soprano{db} &
\Soprano{d} &
\Soprano{eb} &
\Soprano{e} &
\Soprano{f} &
\Soprano{gb} &
\Soprano{g} &
\Soprano{ab} &
\Soprano{a} &
\Soprano{bb} &
\Soprano{b}\\
\bottomrule
\end{tabular}

\fingeringSetup{width=10pt,thumboffset=false}
\bigskip

Here's what the fingering diagrams look like with |thumboffset=false|:


\begin{tabular}{cccc}
\toprule
c' & c\#' & d' & eb'\\
\midrule
\Soprano{c'} &
\Soprano{db'} &
\Soprano{d'} &
\Soprano{eb'}\\
\bottomrule
\end{tabular}
\clearpage
\section{Using in conjunction with \texttt{musixtex}}
\fingeringSetup{thumboffset=true,width=12pt}
It's simple to add fingerings on top of musical excerpts created with |musixtex| using the |tikzmark| library to place the fingerings.  Here's a sample of what you can do, with the code below.

\subsection*{C Maj scale Soprano/Tenor recorder fingerings}
\vspace{\heightof{\Soprano{C}}+\baselineskip}
\begin{music}
\setlyrics{scale}{C D E F G A B C}
\lyrraise{1}{b-2ex}
\assignlyrics{1}{scale}
\startextract
\NOTEs
\tikzmark{C}\wh{c}\tikzmark{D}\wh{d}\tikzmark{E}\wh{e}\tikzmark{F}\wh{f}
\tikzmark{G}\wh{g}\tikzmark{A}\wh{h}\tikzmark{B}\wh{i}\tikzmark{c}\wh{j}
\en
\zendextract
\end{music}
\addf{C}\addf{D}\addf{E}\addf{E}\addf{F}\addf{G}\addf{A}\addf{B}\addf{c}
\begin{lstlisting}
%\usetikzlibrary{tikzmark} % in document premable
%\usetikzlibrary{positioning} % in document preamble
%\usepackage{calc} % in document preamble
% Helper command to place each fingering
\NewDocumentCommand{\addf}{m}{\tikz[remember picture]{\node[overlay,above=of pic cs:#1]{\Soprano{#1}};}}
% add vertical space for the height of the diagram 
\vspace{\heightof{\Soprano{C}}+\baselineskip}
\begin{music}
\setlyrics{scale}{C D E F G A B C}
\lyrraise{1}{b-2ex}
\assignlyrics{1}{scale}
\startextract
\NOTEs
% add \tikzmark for before each note
\tikzmark{C}\wh{c}\tikzmark{D}\wh{d}\tikzmark{E}\wh{e}\tikzmark{F}\wh{f}
\tikzmark{G}\wh{g}\tikzmark{A}\wh{h}\tikzmark{B}\wh{i}\tikzmark{c}\wh{j}
\en
\zendextract
\end{music}
% use the helper function to add the fingerings (requires two compilations)
\addf{C}\addf{D}\addf{E}\addf{E}\addf{F}\addf{G}\addf{A}\addf{B}\addf{c}
\end{lstlisting}
\end{document}