summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/recorder-fingering
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/recorder-fingering')
-rw-r--r--macros/latex/contrib/recorder-fingering/README.md9
-rw-r--r--macros/latex/contrib/recorder-fingering/RecorderInCchart.pngbin0 -> 65144 bytes
-rw-r--r--macros/latex/contrib/recorder-fingering/recorder-fingering.pdfbin0 -> 68489 bytes
-rw-r--r--macros/latex/contrib/recorder-fingering/recorder-fingering.sty355
-rw-r--r--macros/latex/contrib/recorder-fingering/recorder-fingering.tex276
5 files changed, 640 insertions, 0 deletions
diff --git a/macros/latex/contrib/recorder-fingering/README.md b/macros/latex/contrib/recorder-fingering/README.md
new file mode 100644
index 0000000000..d0d5179023
--- /dev/null
+++ b/macros/latex/contrib/recorder-fingering/README.md
@@ -0,0 +1,9 @@
+# recorder-fingering
+
+Version 1.0 February 17, 2023
+
+LaTeX package for recorder fingering diagrams. Support for all standard F and C recorder fingerings, with the ability to add new fingerings as needed.
+
+# Sample of what you can do with it:
+
+![Fingering chart](RecorderInCchart.png)
diff --git a/macros/latex/contrib/recorder-fingering/RecorderInCchart.png b/macros/latex/contrib/recorder-fingering/RecorderInCchart.png
new file mode 100644
index 0000000000..2dc30ed9f3
--- /dev/null
+++ b/macros/latex/contrib/recorder-fingering/RecorderInCchart.png
Binary files differ
diff --git a/macros/latex/contrib/recorder-fingering/recorder-fingering.pdf b/macros/latex/contrib/recorder-fingering/recorder-fingering.pdf
new file mode 100644
index 0000000000..a513c2c860
--- /dev/null
+++ b/macros/latex/contrib/recorder-fingering/recorder-fingering.pdf
Binary files differ
diff --git a/macros/latex/contrib/recorder-fingering/recorder-fingering.sty b/macros/latex/contrib/recorder-fingering/recorder-fingering.sty
new file mode 100644
index 0000000000..6c5f447f72
--- /dev/null
+++ b/macros/latex/contrib/recorder-fingering/recorder-fingering.sty
@@ -0,0 +1,355 @@
+%%
+%% This is file `recorder-fingerings.sty'
+% Copyright 2023 by Alan Munn
+%
+% This package provides a single command to produce a fingering
+% diagram for any not in the playable range of the recorder.
+%
+% This package may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This package has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this package is Alan Munn.
+%
+% This package consists of the file
+%
+% recorder-fingering.sty
+%
+% and documentation files:
+%
+% recorder-fingering.tex, recorder-fingering.pdf
+%
+% Version 1.0 2023/02/17
+\NeedsTeXFormat{LaTeX2e}[2022/11/01]
+\ProvidesPackage{recorder-fingering}[2023/02/17 v1.0 Recorder fingering diagrams]
+\RequirePackage{tikz}
+\usetikzlibrary{calc}
+\RequirePackage{graphicx}
+% Split node code from
+% https://tex.stackexchange.com/a/657282/2693
+% These styles are local to the package
+\pgfkeys{/fingering/.style={
+ node split radius/.initial=1,
+ node split color 1/.initial=white,
+ node split color 2/.initial=black,
+ node split color 3/.initial=blue,
+ node split half/.style={node split={##1,##1+180}},
+ node split/.style args={##1,##2}{
+ path picture={
+ \tikzset{
+ x=($(path picture bounding box.east)-(path picture bounding box.center)$),
+ y=($(path picture bounding box.north)-(path picture bounding box.center)$),
+ radius=\pgfkeysvalueof{/tikz/node split radius}}
+ \foreach \ang[count=\iAng, remember=\ang as \prevAng (initially ##1)] in {##2,360+##1}
+ \fill[line join=round, draw, fill=\pgfkeysvalueof{/tikz/node split color \iAng}]
+ (path picture bounding box.center)
+ --++(\prevAng:\pgfkeysvalueof{/tikz/node split radius})
+ arc[start angle=\prevAng, end angle=\ang] --cycle;
+} },
+hole/.style={circle,draw,##1},
+1/.style={fill=black}, % closed hole
+0/.style={fill=none}, % open hole
+t/.style={node split half=0}, % thumb half hole
+h/.style={node split half=-90}, % finger half hole
+top double/.style={circle,minimum size=7pt,inner sep=0pt,draw,##1},
+bottom double/.style={circle,minimum size=6pt,inner sep=0pt,draw,##1},
+}}
+\ExplSyntaxOn
+
+
+% Error messages
+\msg_new:nnnn {recorder-fingering}{too-few}{\\You\ haven't\ provided\ enough\ holes!}{Fingerings\ must\ specify\ all\ 8\ holes\ (thumb\ +\ all\ 7\ fingers)}
+\msg_new:nnnn {recorder-fingering}{key-exists}{\\This\ fingering\ is\ already\ defined!}{Use\ the\ starred\ version\ of\ the\ command\ or\ \token_to_str:N \AddFingerings\ instead\ to\ override\ existing\ fingerings.}
+\msg_new:nnnn {recorder-fingering}{wrong-instrument}{\\This\ command\ only\ permits\ F\ and\ C\ fingerings!}{}
+\msg_new:nnnn {recorder-fingering}{deprecated}{\\This\ command\ is\ deprecated.\ Please\ use\ \token_to_str:N \alto\ or\ \token_to_str:N \soprano\ instead.}{}
+
+% Command parameters
+\keys_define:nn {fingering}{
+ thumboffset.bool_set:N = \g_fingering_thumboffset_bool,
+ width.dim_set:N = \g_fingering_size_dim,
+ thumboffset.initial:n = {true},
+ width.initial:n = {20pt}
+}
+\keys_define:nn {fingering / command}{
+ thumboffset.bool_set:N = \g_fingering_command_thumboffset_bool,
+ width.dim_set:N = \l_fingering_command_size_dim,
+}
+\NewDocumentCommand{\fingeringSetup}{m}{
+ \keys_set:nn {fingering} {#1}
+}
+
+% Manage the thumb offset parameters
+\tl_set:Nn \g_fingering_thumboffset_x {-.5}
+\tl_set:Nn \g_fingering_thumboffset_y {-.25}
+\cs_new:Nn \fingering_offset_reset:
+{\tl_gset:Nn \g_fingering_thumboffset_x {-.5}
+\tl_gset:Nn \g_fingering_thumboffset_y {-.25}
+}
+\cs_new:Nn \fingering_offset_zero:
+{\tl_gset:Nn \g_fingering_thumboffset_x {0}
+\tl_gset:Nn \g_fingering_thumboffset_y {0}
+}
+\cs_new:Nn \fingering_set_thumboffset: {
+\bool_if:nTF {\g_fingering_command_thumboffset_bool}
+ {\fingering_offset_reset:}
+ {\fingering_offset_zero:}
+}
+
+% Set up the property lists for F and C fingerings
+\prop_new:N \l_fingering_F_prop
+\prop_new:N \l_fingering_C_prop
+% Set up transposition tables for later
+\prop_new:N \l_fingering_C_to_F_prop
+\prop_new:N \l_fingering_F_to_C_prop
+
+% Set up the clists for the fingering vectors themselves
+\clist_new:N \l_fingering_fing_clist
+\clist_new:N \l_fingering_topholes_clist
+
+
+% Generic fingering generator: takes a clist, splits it between top holes and bottom holes
+% and produces the corresponding diagram
+% basic idea for splitting the clist using step_inline and pop from Jonathan P. Spratte (Skillmon)
+
+\cs_new_protected:Nn \fingering_generate_fingering:n
+{
+\clist_set:Nn \l_fingering_holes_clist {#1}
+ \clist_clear:N \l_fingering_topholes_clist
+ \int_step_inline:nn { 6 } {
+ \clist_pop:NNF \l_fingering_holes_clist \l_tmpa_tl { \msg_error:nn { recorder-fingering } { too-few }}
+ \clist_put_right:NV \l_fingering_topholes_clist \l_tmpa_tl }
+ \resizebox{\l_fingering_command_size_dim}{!}{
+ \begin{tikzpicture}[/fingering]
+% display the topholes
+ \fingering_set_thumboffset:
+ \foreach[expand~list]~\x~[count=\xi]~in~\l_fingering_topholes_clist {
+ \node[hole=\x]~at~(0+\g_fingering_thumboffset_x,-\xi/2+\g_fingering_thumboffset_y)~{};
+ \fingering_offset_zero:}
+% display the bottom two paired holes
+ \clist_pop:NN \l_fingering_holes_clist \l_tmpa_tl
+ \int_case:nnTF {\l_tmpa_tl}{
+ {0} {\node[top~double=0]~at~(.15,-7/2)~{};
+ \node[bottom~double=0]~at~(-.15,-7.15/2)~{};}
+ {2} {\node[top~double=1,]~at~(.15,-7/2)~{};
+ \node[bottom~double=1]~at~(-.15,-7.15/2)~{};}
+ {1} {\node[top~double=1]~at~(.15,-7/2)~{};
+ \node[bottom~double=0]~at~(-.15,-7.15/2)~{};}
+ }
+ {}
+ {}
+ \clist_pop:NN \l_fingering_holes_clist \l_tmpa_tl
+ \int_case:nnTF {\l_tmpa_tl}{
+ {0} {\node[top~double=0,]~at~(.15,-8/2)~{};
+ \node[bottom~double=0]~at~(-.15,-8.15/2)~{};}
+ {2} {\node[top~double=1,]~at~(.15,-8/2)~{};
+ \node[bottom~double=1]~at~(-.15,-8.15/2)~{};}
+ {1} {\node[top~double=1,]~at~(.15,-8/2)~{};
+ \node[bottom~double=0]~at~(-.15,-8.15/2)~{};}
+ }
+ {}
+ {}
+% display the bell hole if present
+ \clist_if_empty:NTF \l_fingering_holes_clist
+ {}
+ {\clist_pop:NN \l_fingering_holes_clist \l_tmpa_tl
+ \node[hole=\l_tmpa_tl]~at~(0,-9/2)~{};}
+ \end{tikzpicture}}
+ }
+
+% create variable version of the command
+\cs_generate_variant:Nn \fingering_generate_fingering:n { V }
+
+
+% Main user commands and synonyms
+% First basic commands to display the fingering for any note
+\NewDocumentCommand{\Alto}{om}{
+\IfNoValueTF{#1}
+ {\keys_set:nn {fingering / command} {width = \g_fingering_size_dim}
+ \bool_set_eq:NN {\g_fingering_command_thumboffset_bool}{\g_fingering_thumboffset_bool}}
+ {\bool_set_eq:NN {\g_fingering_command_thumboffset_bool}{\g_fingering_thumboffset_bool}
+ \keys_set:nn {fingering /command } {#1}}
+ \prop_get:NnN \l_fingering_F_prop {#2} \l_tmpa_tl
+ \fingering_generate_fingering:V \l_tmpa_tl
+}
+\cs_set_eq:NN \Sopranino \Alto
+\cs_set_eq:NN \Bass \Alto
+
+\NewDocumentCommand{\Soprano}{om}{
+\IfNoValueTF{#1}
+ {\keys_set:nn {fingering / command} {width = \g_fingering_size_dim}
+ \bool_set_eq:NN {\g_fingering_command_thumboffset_bool}{\g_fingering_thumboffset_bool}}
+ {\bool_set_eq:NN {\g_fingering_command_thumboffset_bool}{\g_fingering_thumboffset_bool}
+ \keys_set:nn {fingering /command } {#1}}
+ \prop_get:NnN \l_fingering_C_prop {#2} \l_tmpa_tl
+ \fingering_generate_fingering:V \l_tmpa_tl
+}
+\cs_set_eq:NN \Tenor \Soprano
+
+% Now commands to add new fingerings:
+% First, a note = { } version for multiple fingerings
+% This command will override existing fingerings
+\NewDocumentCommand{\AddFingerings}{mm}{
+ \str_case:nnTF {#1}{
+ {F} {\prop_put_from_keyval:Nn \l_fingering_F_prop {#2}}
+ {C}{\prop_put_from_keyval:Nn \l_fingering_C_prop {#2}}
+ }
+ {}
+ {\msg_error:nn { recorder-fingering }{ wrong-instrument}}
+}
+
+% Second individual fingerings for alto and soprano
+% These commands will throw an error if the note is already defined
+\NewDocumentCommand{\NewFfingering}{smm}{
+\IfBooleanTF{#1}
+ {\prop_put:Nnn \l_fingering_F_prop {#2} {#3}}
+ {\prop_get:NnNTF \l_fingering_F_prop {#2} \tl_tmpa_tl
+ {\msg_error:nn { recorder-fingering } { key-exists }}
+ {\prop_put:Nnn \l_fingering_F_prop {#2} {#3}}
+ }}
+
+\NewDocumentCommand{\NewCfingering}{smm}{
+\IfBooleanTF{#1}
+ {\prop_put:Nnn \l_fingering_C_prop {#2} {#3}}
+ {\prop_get:NnNTF \l_fingering_C_prop {#2} \tl_tmpa_tl
+ {\msg_error:nn { recorder-fingering } { key-exists }}
+ {\prop_put:Nnn \l_fingering_C_prop {#2} {#3}}
+ }}
+
+% Now add all of the basic fingerings
+\AddFingerings{F}{
+ F = {1,1,1,1,1,1,2,2},
+ Gb = {1,1,1,1,1,1,2,1},
+ G = {1,1,1,1,1,1,2,0},
+ Ab = {1,1,1,1,1,1,0,0},
+ A = {1,1,1,1,1,1,0,0},
+ Bb = {1,1,1,1,1,0,2,2},
+ B = {1,1,1,1,0,1,2,0},
+ C = {1,1,1,1,0,0,0,0},
+ Db = {1,1,1,0,1,1,1,0},
+ D = {1,1,1,0,0,0,0,0},
+ Eb = {1,1,0,1,1,0,0,0},
+ E = {1,1,0,0,0,0,0,0},
+ f = {1,0,1,0,0,0,0,0},
+ gb = {0,1,1,0,0,0,0,0},
+ g = {0,0,1,0,0,0,0,0},
+ ab = {0,0,1,1,1,1,2,0},
+ a = {t,1,1,1,1,1,0,0},
+ bb = {t,1,1,1,1,0,2,0},
+ b = {t,1,1,1,0,1,0,0},
+ c = {t,1,1,1,0,0,0,0},
+ db = {t,1,1,0,1,0,0,0},
+ d = {t,1,1,0,0,0,0,0},
+ eb = {t,1,1,0,0,1,2,1},
+ e = {t,1,1,0,1,1,0,0},
+ f' = {t,1,0,0,1,1,0,0},
+ gb' = {t,1,0,1,1,0,2,2,1},
+ g' = {t,1,0,1,1,0,2,2},
+ ab' = {t,0,1,1,0,1,2,0}
+ }
+\AddFingerings{C}{
+ C = {1,1,1,1,1,1,2,2},
+ Db = {1,1,1,1,1,1,2,1},
+ D = {1,1,1,1,1,1,2,0},
+ Eb = {1,1,1,1,1,1,1,0},
+ E = {1,1,1,1,1,1,0,0},
+ F = {1,1,1,1,1,0,2,2},
+ Gb = {1,1,1,1,0,1,1,0},
+ G = {1,1,1,1,0,0,0,0},
+ Ab = {1,1,1,0,1,1,0,0},
+ A = {1,1,1,0,0,0,0,0},
+ Bb = {1,1,0,1,1,0,0,0},
+ B = {1,1,0,0,0,0,0,0},
+ c = {1,0,1,0,0,0,0,0},
+ db = {0,1,1,0,0,0,0,0},
+ d = {0,0,1,0,0,0,0,0},
+ eb = {0,0,1,1,1,1,2,0},
+ e = {t,1,1,1,1,1,0,0},
+ f = {t,1,1,1,1,0,2,0},
+ gb = {t,1,1,1,0,1,0,0},
+ g = {t,1,1,1,0,0,0,0},
+ ab = {t,1,1,0,1,0,0,0},
+ a = {t,1,1,0,0,0,0,0},
+ bb = {t,1,1,0,0,1,2,1},
+ b = {t,1,1,0,1,1,0,0},
+ c' = {t,1,0,0,1,1,0,0},
+ db' = {t,1,0,1,1,0,2,2,1},
+ d' = {t,1,0,1,1,0,2,2},
+ eb' = {t,0,1,1,0,1,2,0}
+}
+
+% Transposition tables (may be useful; currently not used)
+\prop_set_from_keyval:Nn \l_fingering_F_to_C_prop {
+ F = {C},
+ Gb = {Db},
+ G = {D},
+ Ab = {Eb},
+ A = {E},
+ Bb = {F},
+ B = {Gb},
+ C = {G},
+ Db = {Ab},
+ D = {A},
+ Eb = {Bb},
+ E = {B},
+ f = {c},
+ gb = {db},
+ g = {d},
+ ab = {eb},
+ a = {e},
+ bb = {f},
+ b = {gb},
+ c = {g},
+ db = {ab},
+ d = {a},
+ eb = {bb},
+ e = {b},
+ f' = {c'},
+ gb' = {db'},
+ g' = {d'},
+ ab' = {eb'}
+ }
+
+\prop_set_from_keyval:Nn \l_fingering_C_to_F_prop {
+ C = {F},
+ Db = {Gb},
+ D = {G},
+ Eb = {Ab},
+ E = {A},
+ F = {Bb},
+ Gb = {B},
+ G = {C},
+ Ab = {Db},
+ A = {D},
+ Bb = {Eb},
+ B = {E},
+ c = {f},
+ db = {gb},
+ d = {g},
+ eb = {ab},
+ e = {a},
+ f = {bb},
+ gb = {b},
+ g = {c},
+ ab = {db},
+ a = {d},
+ bb = {eb},
+ b = {e},
+ c' = {f'},
+ db' = {gb'},
+ d' = {g'},
+ eb' = {ab'}
+ }
+
+
+% Backwards (in)compatibility with the initial version of the package
+
+\NewDocumentCommand{\fingering}{}{
+ \msg_error:nn {recorder-fingering}{deprecated}}
+\ExplSyntaxOff
+\endinput
diff --git a/macros/latex/contrib/recorder-fingering/recorder-fingering.tex b/macros/latex/contrib/recorder-fingering/recorder-fingering.tex
new file mode 100644
index 0000000000..c2cfbe9cae
--- /dev/null
+++ b/macros/latex/contrib/recorder-fingering/recorder-fingering.tex
@@ -0,0 +1,276 @@
+% !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.0\\February 17, 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}{>{\ttfamily}r}
+\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}{tX}
+\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.
+\subsection{Display parameters}
+Each display command allows two display parameters to be set.
+
+\begin{table}[htpb]
+\centering
+\begin{tabularx}{.9\textwidth}{tX}
+\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\\
+\bottomrule
+\end{tabularx}
+\caption{Display parameters}
+\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|.
+
+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}{TT}
+\pkg{\bs Alto\{c\}} & \pkg{\bs Soprano[width=10pt,thumboffset=false]\{f\}}\\
+\\
+\Alto{c} & \Soprano[width=10pt,thumboffset=false]{f}
+\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}{tX}
+\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{ABbtrill}{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}
+}
+\begin{lstlisting}
+\NewFfingering{ABbtrill}{0,1,1,1,1,1,0,0}
+\Alto{ABbtrill}
+\end{lstlisting}
+\Alto{ABbtrill}
+
+\begin{lstlisting}
+\AddFingerings{C}{
+ EFtrill = {0,1,1,1,1,1,0,0},
+ altd = {0,1,1,1,1,1,2,2}
+}
+\Soprano{EFtrill}
+\Soprano{altd}
+\end{lstlisting}
+
+\Soprano{EFtrill}
+\Soprano{altd}
+
+\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. 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 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.
+
+\section*{Recorder in C soprano chart}
+\begin{tabular}{cccccccccccc}
+\toprule
+C & Db & D & Eb & E & F & Gb & 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}
+
+\bigskip
+\begin{tabular}{cccccccccccc}
+\toprule
+c & db & d & eb & e & f & gb & 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' & db' & 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}