Extending lilyglyphs (Part 1)

As announced in an earlier post lilyglyphs is a package to insert LilyPond’s notational elements in LaTeX documents. While it is already useful in its initial 0.2.1 release there is much left to be covered. While all glyphs from LilyPond’s Emmentaler font are readily available through generic commands like \lilyGlyph{clefs.percussion} having them available as predefined commands like \clefPerc is more convenient, especially since these are already fine-tuned with regard to their scaling and placement.  This is even more of an issue for certain commands that use LilyPond-generated PDF files to display glyphs because they aren’t readily available but have to be created first.
Fortunately it’s rather straightforward to extend the package by adding new predefined commands. I think that all the steps to do this are documented correctly in lilyglyphs’ manual, but the manual contains quite a lot of information, so a walk-through with pictures may be helpful to get acquainted with the process.

Today I will show you how to add the set of Emmentaler’s accordion symbols to lilyglyphs’ predefined commands. Please do not redo this as an exercise because after I have finished this post, I will add them to liylglyphs so it will already have them available ;-). If you want to practice (and I encourage you to do so) please do so with a different group of glyphs and then contribute them.  One of the major tasks in lilyglyphs development will be to increase the coverage of predefined commands, and any help would be appreciated.

I will assume that you have managed to set up the package correctly and can successfully use the provided Python scripts. In other words, you have Python available and have set up your directories according to the manual, depending on where you got the package from.

A Manually Written Command

As explained in Section 4.3 of the lilyglyphs manual you would start the code for the first glyph with something like:

% ”accordion.discant”
\newcommand*{\accordionDiscant}[1][]{%
    \setkeys{lilyDesignOptions}{scale=1,raise=0}%
    \lilyPrint[#1]{\lilyGetGlyph{accordion.discant}}%
}

In a test file we now consider the preliminary result:

Test \accordionDiscant{} with more text \accordionDiscant.

Which results in:
lilyglyphs-test-single-command
We can see that a) the size of the command is already usable, b) it should sit somewhat lower and c) we need considerable horizontal space to the left of the glyph (because the symbol’s reference point is obviously in its center). If only wanted to create this single command we would now tweak the command until we were satisfied with the result. But since we’re going one step further, we’ll only look for a suitable value for raise (which we determine to be -0.3) and postpone the horizontal spacing to a later step.

Generating Many Commands At Once

Section 5.1 of lilyglyphs’ manual explains how to write a number of predefined commands with Emmentaler glyphs. The basic steps are: 1) Write a file with input definitions, 2) process the file with a Python script, 3) fine-tune the results, and 4) store them in a suitable place. I’ll go through these steps now with examples and images.

1) Write the Input File

The script expects a file with one or more definitions of commands. The definition of the above command for this template file would be:

cmd=accordionDiscant
element=accordion.discant
comment=accordion discant
raise=-0.3

The cmd key will be translated into the LaTeX command name, the comment is optional but recommended and will generate the comment before the command definition.
There are two items to be noticed: raise and type. If a template doesn’t specify a type it defaults to glyph, so the command will print the Emmentaler glyph specified by element.
The raise key of course specifies the corresponding design time option in the generated LaTeX command, but it is also kept throughout the subsequent command templates. This is why we already determined the parameter in the previous step of manually testing the command — it is likely that glyphs of the same group share the same scale and raise parameters.
Now we can write the complete input definitions file containing all eight glyphs (accordion-glyphs-definition.txt – the file extension is irrelevant). In the case of Emmentaler based commands this file is completely intermediate so you can save it anywhere on your disk.

2) Generate the LaTeX commands

Running the script lily-glyph-commands.py on this input file:

python lily-glyphs-commands.py accordion-glyphs-definition.txt

will now produce a file accordion-glyphs-definition.tex in the same folder as the input file. (Actually you would have to cd to the script’s location (or have put it into your search path) and provide the full or relative path to your input file).
The resulting file contains

  • command definitions for all eight glyphs in the document preamble (sorted alphabetically),
  • a reference table as found throughout the lilyglyphs manual, and
  • sample text for each command.

You can have a look at the generated file here (accordion-glyphs-definition.tex), and see the out-of-the-box result of this document here (PDF)
The sample text serves two goals.  Initially it shows that the commands work at all, but its main purpose is to provide a context in which you can fine-tune the output.

3) Fine-tune the Commands

I think the size of commands is OK for all commands, but that’s maybe because I’m not used to accordion symbols (suggestions or confirmation welcome). But as we saw earlier all commands need horizontal space before them. I’ll do this by inserting a line \hspace* before actually printing the glyph.
As this example shows, practically all glyphs in this run need a similar amount of space (depending on their own width). And as this will be the case for many more Emmentaler glyph types I will add this as a key for the script with the next update of the package.

Actually some of the accordion symbols even need further tweaking by removing a little bit of trailing space, but fortunately this isn’t hard either. As an example you can have a look at the new definition of the accordion discant:

% accordion discant
% created by lily-glyph-commands.py on 2013-09-23
\newcommand*{\accordionDiscant}[1][]{%
	\setkeys{lilyDesignOptions}{scale=1,raise=-.2}%
	\hspace*{.6ex}%
	\lilyPrint[#1]{\lilyGetGlyph{accordion.discant}%
	\hspace*{-.3ex}}%
}

View the full file with tweaks here (accordion-glyphs-definition-tweaked.tex) and the modified PDF file here.

As you can see from the relevant page in LilyPond’s documentation, the accordion dot isn’t a glyph in its own right but is rather used to create numerous combined symbols. I will discuss this further in part two of this post, but for now I’m simply going to remove the dot from the set of command definitions.

4) Use the Results

Now we have a file with inline definitions of the new commands, so what are we going to do with it? Of course we could simply copy them to the preamble of a document, or we could create a package file from it. But I will show you how to properly incorporate them in the lilyglyphs package so you can contribute them back. For today I assume you are working on a version cloned from the Github repository because that’s the recommended way to use and contribute to lilyglyphs, and it would be too complex to describe all the other options here.

The main package file lilyglyphs.sty in the root directory uses input files from the commands/ subdirectory where the actual command definitions are stored. As the accordion symbols clearly are a new category of commands we will not append to an existing file but create a new file accordion.inp there by copying an existing one and replacing the definitions in it with the new commands we created in the previous step.
To actually make them available we insert

\input{commands/accordion.inp}

in the lilyglyphs.sty package file. Now we can use our new commands by compiling a document like the following with LuaLaTeX or XeLaTeX:

\documentclass{article} % or any other class
\usepackage{fontspec}
\usepackage{lilyglyphs}
\begin{document}
Now \accordionBayanBass{}
we \accordionDiscant{}
can \accordionFreeBass{}
use \accordionOldEE{}
all \accordionPull{} of \accordionPush{} them \accordionStdBass.
\end{document}

accordion-symbols-example

Finishing Off

We’re nearly finished, but in order to have a useful set of additions we have to document them. We’re lucky here because the Python script already did most of the work for us by generating the reference table:

\begin{reftable}{New commands}{newcommands}
\accordionBayanBass & \cmd{accordionBayanBass} & description\\
\accordionDiscant & \cmd{accordionDiscant} & description\\
\accordionFreeBass & \cmd{accordionFreeBass} & description\\
\accordionOldEE & \cmd{accordionOldEE} & description\\
\accordionPull & \cmd{accordionPull} & description\\
\accordionPush & \cmd{accordionPush} & description\\
\accordionStdBass & \cmd{accordionStdBass} & description\\
\end{reftable}

All there is left for us to do is fill in a table name and label, replace the “description” entries with meaningful phrases (this actually proves quite tricky because nobody seems to know what all of them are used for), and find a suitable place in the manual and create a section in it.

If you now commit your modifications to Git you should see one new file (accordion.inp) and two modified files (lilyglyphs.sty and lilyglyphs.tex). If you have made a fork of the original Git repository you can now upload your change with git push origin and use Github’s web interface to create a pull request. If you have done everything right I will merge it and we’re all happy.

To inspect the actual commit that I created when pushing the changes for these accordion symbols you can go to https://github.com/openlilylib/lilyglyphs/commit/ec9aaf7082a55d9cac694b5edcc447a4f777f593.

What Next?

In this post we have seen how to add a complete set of predefined commands to the lilyglyphs package. Despite the length of this walk-through, it is actually a very straight-forward process once you get used to it. Therefore I can only encourage you: If you are working in a field where you need glyphs that aren’t prepared as predefined commands yet, don’t simply create what you need but take this little extra step and submit a complete group as a pull request. By its very nature lilyglyphs is relying on “crowd contribution” ;-).

Of course our adventure of adding accordion notation to lilyglyphs isn’t over yet because we’re lacking all the commands created from overlaying the discant symbol with dots. While it would be possible to draw such symbols within LaTeX we’re surely better off doing this with lilyglyphs commands that use PDF files generated with LilyPond. Fortunately there is a Python script for this too, and that’s what we’ll investigate in part 2.

2 thoughts on “Extending lilyglyphs (Part 1)

Leave a Reply

Your email address will not be published. Required fields are marked *