Engraving Statistics: other functions and shorthands

This post is part of a series analyzing LilyPond’s performance during the preparation of a new edition of Oskar Fried’s songs.

As I’ve shown you in the previous post, \shape was definitely the most prominent tool I had used for adjustments in the scores of Oskar Fried’s songs. But it wasn’t the only one. There are 520 explicit \overrides and \tweaks in the scores; other than that, I have used numerous special commands and functions – some of them were taken from the LilyPond Snippet Repository, some were written by me or Urs.

Probably the most used and most helpful one was David Nalesnik’s \offset (some time ago it was added to official LilyPond commands). It is interesting to note that \shape is basically a special version of \offset – both commands alter the default values calculated by LilyPond.

Apart from \offset, we have also used:

  • \alterBroken (also by David Nalesnik, available in LilyPond since version 2.15.42)
  • a function correcting the placement of TupletNumbers on kneed beams (again by David Nalesnik),
  • some other, more specific functions, contributed by Thomas Morley, David Nalesnik, David Kastrup and others.

It will be probably interesting to note that we have created 13 special commands for marking objects as “editorial additions”. These commands ranged from trivial (e.g. decreasing font-size by 2) to fairly complex (e.g. drawing a sophisticated dashed stem). In total, they were used 78 times.


In every big project there are some tasks that appear so frequently that it makes sense to devise special commands to make dealing with them simpler. Sometimes the common tasks aren’t really complicated, but it’s still worth to make some shorthands just to save typing. Here are the most frequent issues we encountered, sorted by the number of occurrences:

  • 977 staff changes (10 per page of music). Changing staff in LilyPond is simple – you just write \change Staff = "staffname" (sometimes you also have to use \voiceOne or \voiceTwo to make sure the stems point in desired direction). However, typing this command a thousand times is… well, a waste of time? So, Urs defined the following:
    SUp = \change Staff = "up"
    SDn = \change Staff = "down"
    SSUp = { \SUp \voiceTwo }
    SSDn = { \SDn \voiceOne }
    While it may seem that there is not much gain in defining such commands, they saved us a lot of typing: without these four, our source code would be 23387 characters longer – that’s an equivalent of 8 full pages of conntinuous text, and it’s almost 3% of the whole codebase!
  • 295 beams to adjust – we defined \beampos as a shorthand for \offset Beam #'positions; it was very handy.
  • 244 objects to move around using X-, Y- or extra-offset properties. We defined \xoff, \yoff and \extraoff shorthands respectively.
  • 121 lyric syllables to align differently.
  • 97 stems to shorten.

In total, the shorthands we defined reduced the source code volume by about 5%. Some people may not like such “syntactic sugar”, but I really believe that it makes working with LilyPond easier.

This almost concludes our statistics – in the next post I’ll show you the last, and most interesting one: the amount of time I spent during beautification.

Leave a Reply

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