LilyPond code: best practices for new submissions

#Introduction

Throughout the Mutopia Project archive you will find many different LilyPond styles. What is the best style? The question came up on mutopia-discuss recently and I decided to review those emails and put some of the comments in here. There are probably no set of style rules that define a perfect lilyPond document and it may be that this article makes recommendations which aren't your style. The goal is readability and maintainability.

##The basics

###One measure per line Part of the reasoning is that it makes it easier for maintainers to find measures, but it also makes it easier to visualize the measure. If you are working on polyphonic music where one voice is absent for many measures, consider breaking this rule with the help of a \barNumberCheck:

c4 f g c |
s1*4 |
\barNumberCheck #6
c2 c2 |

###Bar and bar number checks Bar checks (|) are simply good practice. You can argue that they aren't needed in the 4-bar silent passage above but in general it keeps accidents from happening.

Bar number checks are a little more contentious. Having had the experience of updating a score that had inaccurate bar numbers in comments, I would argue that at least the \barNumberCheck performs an actual check.

###The mbreak variable This simple definition can be very useful when transcribing. Insert it where the measures break on the source from which you are transcribing. Later you can redefine it to empty (mbreak={}) to allow LilyPond to decide where to insert staff and page breaks.

mbreak = {\break}
upper = \relative c' {
  c2 c2 |
  c4 g g c |
  % ...
  \mbreak
  f4 f g g |
  % ...

Sometimes LilyPond ignore manual line or page breaks. Put this \override commands in the \layout of the score block and comment it when you've finished entering the notes from the manuscript:

\score {
  ...
  \layout {
    \context {
      \Score
      \override NonMusicalPaperColumn.line-break-permission = ##f
      \override NonMusicalPaperColumn.page-break-permission = ##f
    }
  }
}

###Separate structure from content Think of structure as how your sheet music looks and content as the music itself. The idea here is that you can make the LilyPond music entry more readable if all it contains is music.

upperVoice = \relative c {
  \set Score.markFormatter = #format-mark-box-alphabet
  \mark \default
  a8 e'16-2 a-3 c8-1^\markup{\smaller\italic "dolce"} e d,16 a'-2 d-4 f-1 |
  a8 e'16-2 a-3 c8-1 e d,16 a'-2 d-4 f-1 |
  ...

Might be coded better as,

\layout {
  \context {
    \Score
    markFormatter = #format-mark-box-alphabet
  }
}
dolce = {\markup{\smaller\italic "dolce"}}

upperVoice = \relative c {
  \mark \default
  a8 e'16-2 a-3 c8-1^\dolce e d,16 a'-2 d-4 f-1 |
  ...

If you change your mind later, you are not editing music to change the rehearsal mark format or the font size for the dolce markup.

##The Mutopia Header If you are like me you have only the necessary information in your header --- title, composer, opus number, and maybe a subtitle. Some contributors will use just about all of the header tags supported by LilyPond. The Mutopia publishing process is designed so that the contributor's header information is respected in the published work and, at the same time, provide consistent and clear titling and searching on the web-site.

Mutopia provides concise information on what tags are needed for publication on its How to Contribute page. This section will provide some practical examples to give you an idea of how Mutopia uses the header.

###For the Minimalist The first example shows the type of header I usually start with --- all I care about is describing the piece and I worry about submission details later.

\header {
  title = "Adelita"
  subtitle = "Mazurka para Guitarra"
  composer = "Francisco Tárrega"
}

Once the piece has been completed and you decide to contribute it to Mutopia, you have a little more work to do to make it acceptable to Mutopia. Here is the completed header,

\header {
  title = "Adelita"
  subtitle = "Mazurka para Guitarra"
  composer = "Francisco Tárrega"
  date = "1880"
  mutopiacomposer = "TarregaF"
  mutopiainstrument = "Guitar"
  style = "Romantic"
  license = "Creative Commons Attribution-ShareAlike 4.0"
  source = "Valencia: Antich y Tena (a.y.t. 361)"
  % From Boije 828
  maintainer = "John Q. Public"
  maintainerEmail = "johnqpublic at example.com"
}

Even though lots of stuff has been added to the header, if you were to compile this it would look exactly the same as it did before. When it is processed through Mutopia, several things will happen:

1. The piece will be assigned an ID number
2. The header will be modified with a footer tag to identify the piece with its official Mutopia ID
3. A copyright will be added that will appear at the bottom of first page of the published piece

Here are a few notes on what was added to the header:

• The date tag is optional but it is usually on the front page and I personally like knowing it.
• A mutopiatitle tag is not added so the title tag will be used.
• The mutopiacomposer was added by finding TarregaF in Mutopia's list of composers. If you don't find the name and you believe the composer meets the licensing qualifications then add the name using the proscribed format (capitalized surname followed by an uppercase first initial) and the name can be added to the list.
• The mutopiainstrument is used with a name from the list of instruments. Alternatively, the instrument tag could have been used but apparently the transcriber doesn't like how LilyPond process that particular tag for a solo instrument.
• It is very important that the value for the license tag match the Mutopia list.
• The source tag should be verbatim from the publisher's page of the source you are using. At a minimum, include the publisher and, were available, the year of publication.

n.b. Article in progress, please feel free to help