\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{musicography}[2023/09/08
  Symbols for music writing with pdflatex]

% Copyright 2023 Andrew A. Cashner, andrewacashner@gmail.com

% This work may be distributed and/or modified under the 
% conditions of the LaTeX Project Public License, either
% version 1.3 of this license or (at your option) 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 work has the LPPL maintenance status `maintained'.
% The Current Maintainer of this work is Andrew A. Cashner.
% This work consists of the package file musicography.sty
% and the documentation file musicography.tex.

% CHANGE LOG
% 2023-09-08 - Improved time signatures, figured bass, documentation
%               + Documentation reorganized, clarified, corrected
%               + Customizable font commands used throughout:
%                 \musAccidentalFont, \musNumFont, \musFigSize, and
%                 \musFigFont 
%               + \musStack now takes an optional last argument to specify
%                 alignment
%               + \musMeter now takes an optional font argument, and has a
%                 smaller vertical gap between numerals. It is now scaled
%                 to fit within the line.
%               + Spacing commands in \musSymbolMeter are simplified
%               + \meterThreeTwo now uses \musMeter for the numbers, shifted
%                 slightly to align with the meter symbol
%               + \meterCZ now pulls in a cursive Z symbol from the EB
%                 Garamond font (installed by default in TeXLive)
%               + \musFig now includes configurable \musFigSize and
%                 \musFigFont switches, and a first optional argument with
%                 alignment specifier
%               + New commands for scale degress (\musDegree) and pitches with
%                 Helmholtz octave (\musPitch)
%               + For testing or extension, add command to display a list of
%                 symbols by number in a given font
%
% 2020-01-29 - Reduced stack gap for \musFig
% 2019-11-24 - Fix problem with \MeterCThreeTwo where numerals were being
%               printed next to each other instead of stacked.
% 2019-05-28 - Fix issue #1:
%               + Correct notehead symbol for values < quarter note
%                 (was hollow, should be filled)
%               + Add 32nd and 64th notes regular and dotted
%               + \musSymbol now inside an \mbox to fix alignment problems
%            - New features (some requested in issue #1)
%               + Add medieval perfect meter
%               + Add aliases for fusa (= corchea = eighth note)
%               + Replace musStack implementation with stackengine:
%                 Now takes any number of space-separated arguments to stack
%                 numerals, allowing for full figured-bass notation
% 2018-05-21 Override semantic-markup's \fl, \sh, \na commands if it is loaded
% 2017-10-31 Corrected glyph for \musHalf and documented
%              \musMeter and \musFigures
% 2017-08-29 First version on CTAN
% 2017-04-12 Created

% FONT SIZES

% Package option 'bigger'
%
% The package uses three sizes of music fonts;  the 'bigger' option increases
%  all three.
\newif\ifLargeFont
\LargeFontfalse
\DeclareOption{bigger}{\LargeFonttrue}
\ProcessOptions\relax

\ifLargeFont
    \newfont{\musFont}{musix13}
    \newfont{\musFontBig}{musix16}
    \newfont{\musFontLarge}{musix20}
\else
    \newfont{\musFont}{musix11}
    \newfont{\musFontBig}{musix13}
    \newfont{\musFontLarge}{musix16}
\fi

% BASIC COMMANDS

% Print a music symbol from the \musFont, specifying space before, after, and
% baseline adjustment
%  #1 optional font command (default: \musFont)
%  #2 kern before    
%  #3 raisebox value 
%  #4 kern after     
%  #5 symbol code (e.g., \symbol{4}) 
\NewDocumentCommand{\musSymbol}{ O{\musFont} m m m m }{%
    \mbox{#1\kern#2\raisebox{#3}{#5}\kern#4}%
}

% ACCIDENTALS

% Larger relative font for accidentals (can be modified)
\NewDocumentCommand{\musAccidentalFont}{}{\musFontLarge}

% Any accidental
%  #1 symbol command for accidental
\NewDocumentCommand{\musAccidental}{ m }{%
    \musSymbol[\musAccidentalFont]{0.1em}{0.5ex}{-0.1pt}{#1}%
}

% Specific accidentals
\NewDocumentCommand{\musFlat}       {}{\musAccidental{\symbol{90}}}
\NewDocumentCommand{\musDoubleFlat} {}{\musAccidental{\symbol{91}}}
\NewDocumentCommand{\musSharp}      {}{\musAccidental{\symbol{92}}}
\NewDocumentCommand{\musDoubleSharp}{}{\musAccidental{\symbol{93}}}
\NewDocumentCommand{\musNatural}    {}{\musAccidental{\symbol{94}}}

% Shorthand accidental commands
%
% These commands are defined differently in the semantic-markup package,
% so LaTeX will use musicography commands instead
\@ifpackageloaded{semantic-markup}{%
    \RenewDocumentCommand{\fl}{}{\musFlat}
    \RenewDocumentCommand{\sh}{}{\musSharp}
    \RenewDocumentCommand{\na}{}{\musNatural}
}{%
    \NewDocumentCommand{\fl}{}{\musFlat}
    \NewDocumentCommand{\sh}{}{\musSharp}
    \NewDocumentCommand{\na}{}{\musNatural}
}

% MUSIC NOTES

% Just the stem
\NewDocumentCommand{\musStem}{}{%
    \musSymbol{0.955em}{0.55ex}{0pt}{\symbol{16}}%
}

% Just the (augmentation) dot 
\NewDocumentCommand{\musDot}{}{%
    \musSymbol{-0.2em}{-0.5ex}{0.7em}{\symbol{24}}%
}

% Notehead plus stem (composite music symbol)
%  #1 Symbol musSymbol command for notehead
\NewDocumentCommand{\musStemmedNote}{ m }{%
    \musSymbol{0.05em}{0.5ex}{0.2em}{#1\musStem}%
}

% Stemmed note plus flag
%  #1 symbol command for base note
%  #2 symbol command for flag
\NewDocumentCommand{\musFlaggedNote}{ m m }{%
    \musSymbol{0.05em}{0.5ex}{0pt}{#1\musStem}%
    \musSymbol{0pt}{0pt}{0.9em}{#2}%
}

% Dotted note
%  #1 \musSymbol command for note to be dotted
\NewDocumentCommand{\musDottedNote}{ m }{#1\musDot}


% Notes of different rhythmic values
\NewDocumentCommand{\musBreve}{}{%
    \musSymbol{0.05em}{0.5ex}{1.35em}{\symbol{32}}%
}
\NewDocumentCommand{\musWhole}{}{%
    \musSymbol{0.05em}{0.5ex}{1.35em}{\symbol{9}}%
}
\NewDocumentCommand{\musHalf}{}{%
    \musStemmedNote{\symbol{8}}%
}
\NewDocumentCommand{\musQuarter}{}{%
    \musStemmedNote{\symbol{7}}%
}
\NewDocumentCommand{\musEighth}{}{%
    \musFlaggedNote{\symbol{7}}{\symbol{40}}%
}
\NewDocumentCommand{\musSixteenth}{}{%
    \musFlaggedNote{\symbol{7}}{\symbol{41}}%
}
\NewDocumentCommand{\musThirtySecond}{}{%
    \musFlaggedNote{\symbol{7}}{\symbol{42}}%
}
\NewDocumentCommand{\musSixtyFourth}{}{%
    \musFlaggedNote{\symbol{7}}{\symbol{43}}%
}

% Dotted rhythmic values
\NewDocumentCommand{\musWholeDotted}{}{%
    \musDottedNote{\musWhole}%
}
\NewDocumentCommand{\musHalfDotted}{}{%
    \musDottedNote{\musHalf}%
}
\NewDocumentCommand{\musQuarterDotted}{}{%
    \musDottedNote{\musQuarter}%
}
\NewDocumentCommand{\musEighthDotted}{}{%
    \musDottedNote{\musEighth}%
}
\NewDocumentCommand{\musSixteenthDotted}{}{%
    \musDottedNote{\musSixteenth}%
}
\NewDocumentCommand{\musThirtySecondDotted}{}{%
    \musDottedNote{\musThirtySecond}%
}
\NewDocumentCommand{\musSixtyFourthDotted}{}{%
    \musDottedNote{\musSixtyFourth}%
}

% Aliases for older note names
\NewDocumentCommand{\musSemibreve}         {}{\musWhole}
\NewDocumentCommand{\musMinim}             {}{\musHalf}
\NewDocumentCommand{\musSemiminim}         {}{\musQuarter}
\NewDocumentCommand{\musCorchea}           {}{\musEighth}
\NewDocumentCommand{\musFusa}              {}{\musEighth}
\NewDocumentCommand{\musSemibreveDotted}   {}{\musWholeDotted}
\NewDocumentCommand{\musMinimDotted}       {}{\musHalfDotted}
\NewDocumentCommand{\musSeminiminimDotted} {}{\musQuarterDotted}
\NewDocumentCommand{\musCorcheaDotted}     {}{\musEighthDotted}
\NewDocumentCommand{\musFusaDotted}        {}{\musEighthDotted}


% STACKED NUMERALS (for figured bass, time signatures)

\RequirePackage{stackengine}

% Only a minimal vertical gap between stacked elements
\setstackgap{S}{1pt}

% Specify the font for numbers in \musStack. For time signatures I think bold
% numbers look better in most fonts, but you could redefine it, for example,
% to use lining figures, math mode, sans-serif, etc.
%
% Example: To get lining figures when using the ebgaramond package:
% \renewcommand{\musNumFont}{\liningnums}
%
% The command is employed in a way that both font switches and commands with
% arguments will work (e.g., {\bfseries\liningnums}), but take care when
% combining multiple elements.
\NewDocumentCommand{\musNumFont}{}{\bfseries}

% Command to stack numerals for metrical symbols or figured bass
% Takes any number of space-separated arguments and stacks them vertically
% 
% #1 (optional) Font command (\musNumFont by default)
% #2 Series of space-separated arguments to be stacked, e.g., {\fl6 5}
% #3 (optional) Alignment specifier for \Shortstack (l, c, or r); default is c
%    for centering
\NewDocumentCommand{\musStack}{ O{\musNumFont} m O{c} }{%
    {#1{\Shortstack[#3]{#2}}}%
}

% METER and TIME SIGNATURES

\RequirePackage{graphicx} % for resizebox

% Numeric meter signatures (e.g., 3/4)
%  #1 (optional) font command (\musNumFont by default)
%  #1 number on top
%  #2 number on bottom
%
% In a pinch you can issue a font command directly in the optional first
% argument, but it would be better to redefine \musNumFont.
%
% These are now scaled to the current line height and centered.
\NewDocumentCommand{\musMeter}{ O{\musNumFont} m m }{%
    \resizebox{!}{\ht\strutbox}{%
        \musStack[#1]{#2 #3}%
    }\kern0.05em
}

% Meter symbols
%  #1 symbol code for meter sign
\NewDocumentCommand{\musSymbolMeter}{ m }{%
    \smash{\kern-1pt\musFontBig\raisebox{1.1ex}{#1}\kern0.3em}%
}

% Meter symbol plus numerals
\NewDocumentCommand{\meterPlus}{ m m }{#1\kern-0.7pt#2}

% Meter signatures with a C or cut C symbol
% Just the symbols
\NewDocumentCommand{\meterC}{}{%
    \musSymbolMeter{\symbol{83}}%
}
\NewDocumentCommand{\meterCutC}{}{%
    \musSymbolMeter{\symbol{82}}%
}

% Ternary meters used in 16th--18th c. music
% Just the numbers: 3
\NewDocumentCommand{\meterThree}{}{%
    {\musNumFont{3}}%
}

% 3/2
\NewDocumentCommand{\meterThreeTwo}{}{%
    \raisebox{-0.26ex}{\musMeter{3}{2}}%
}

% Combining symbols and numbers
% Meter that combines \meterC with numerals (e.g., C3 C3/2)
\NewDocumentCommand{\meterCplus}{ m }{\meterPlus{\meterC}{#1}}

% Meter that combines \meterCutC with numerals (e.g., C3 C3/2)
\NewDocumentCommand{\meterCutCplus}{ m }{\meterPlus{\meterCutC}{#1}}

% Proportions of cut C
\NewDocumentCommand{\meterCutCThree}{}{%
    \meterCutCplus{\meterThree}%
}
\NewDocumentCommand{\meterCutCThreeTwo}{}{%
    \meterCutCplus{\meterThreeTwo}%
}

% Proportions of C
\NewDocumentCommand{\meterCThree}{}{%
    \meterCplus{\meterThree}%
}
\NewDocumentCommand{\meterCThreeTwo}{}{%
    \meterCplus{\meterThreeTwo}%
}

% CZ meter: Ternary meter used in 17th-century Spanish music
%
% A cursive Z to match the C meter symbol, as notated in Spanish manuscripts
%
% Pull in symbol from EB Garamond font; could be redefined
\NewDocumentCommand{\meterZfont}{}{%
    \fontfamily{EBGaramond-LF}\selectfont
}

% The symbol
\NewDocumentCommand{\meterZsymbol}{}{%
    {\meterZfont\Large\itshape z}%
}

% CZ meter
\NewDocumentCommand{\meterCZ}{}{%
    \meterCplus{\meterZsymbol}%
}

% Perfect meter in medieval music
\NewDocumentCommand{\meterO}{}{%
    $\bigcirc$
}


% FIGURED BASS

% Definable font command to be used with figured bass; consider matching
% \musNumFont (e.g., with lining numerals)
\NewDocumentCommand{\musFigFont}{}{}

% Size adjustment for figured bass: smaller font for numerals, reduce sizes of
% music symbols (\tiny might make it fit better within the line height)
\NewDocumentCommand{\musFigSize}{}{%
    \scriptsize
    \RenewDocumentCommand{\musAccidentalFont}{}{\musFont}%
}

% Figured bass is typeset a \musStack using \musFigFont, right-aligned to
% allow for accidentals preceding numerals
%  #1 (optional) Alignment specifier: l, c, r (default: r)
%  #2 space-delimited list of arguments to stack, in top-down order
% 
% Example: \musFig{\fl6 4} or \musFig{\sh5 4 2}
%
% Note that the command applies first \musFigSize, then \musFigFont inside the
% stack.
\NewDocumentCommand{\musFig}{ O{r} m }{%
    {\musFigSize\musStack[\musFigFont]{#2}[#1]}%
}

% Placeholder for no figure, to maintain alignment
%  #1 (optional) width of blank space (Default: numeral 5)
%
% Example: \musFig{6 4}--\musFig{5 \noFig}
\NewDocumentCommand{\noFig}{ O{5} }{%
    \hphantom{#1}%
}

% MISCELLANEOUS SYMBOLS and NOTATIONS

% Segno (repeat marker)
\NewDocumentCommand{\musSegno}{}{%
    \musSymbol{0.55em}{-0.4ex}{1.5em}{\symbol{86}}%
}

% Scale degrees
% #1 Numeral (offset from tonic)
\NewDocumentCommand{\musDegree}{ m }{$\hat{#1}$}

% Pitch with Helmholtz octave number (e.g., A4 = A440Hz)
% #1 Pitch-class name (A-G)
% #2 Octave number
\NewDocumentCommand{\musPitch}{ m m }{#1\textsubscript{#2}}

% Recommended: Use my 'octave' package for more options, including
% traditional, non-Helmholtz notation

% AUXILIARY COMMANDS

% Print a list of symbols for documentation, debugging, or extension
% E.g., \symbolList{\musFont}{256} to see all useable symbols in MusiXTeX font

\RequirePackage{setspace} % for symbol list spacing

\ExplSyntaxOn
% Single entry in the symbol list: Number + corresponding symbol
%  #1 font command
%  #2 symbol number
\cs_new:Nn \aac_symbolEntry:nn
{
    \makebox[4em]{#2\quad{#1\symbol{#2}}}\ %
}

% Loop through all the symbols in given font up to given max
%  #1 font command
%  #2 max symbol number
\cs_new:Nn \aac_symbolLoop:nn
{
    \int_step_inline:nnn {0} {#2 - 1}
    {
        \aac_symbolEntry:nn {#1} {##1}
    }
}


% The whole symbol list up to a given max, typeset in a big double-spaced
% block
%  #1 font command
%  #2 max symbol number
\NewDocumentCommand{\symbolList}{ m m }{\par
    \begin{doublespace}
        \noindent\aac_symbolLoop:nn {#1} {#2}
    \end{doublespace}
}
\ExplSyntaxOff

% Print a list of symbols in the MusiXTeX font
\NewDocumentCommand{\musixSymbolList}{}{\symbolList{\musFont}{128}}

\endinput