lilypond-learning: Working on input files
1.2.2 Working on input files
----------------------------
LilyPond input files are similar to source files in many common
programming languages. They contain a version statement, are case
sensitive, and white-space is generally ignored. Expressions are formed
with curly braces ‘{ }’, and comments are denoted with ‘%’ or
‘%{ ... %}’ .
If the previous sentences sound like nonsense, don’t worry! We’ll
explain what all these terms mean:
• *Version statement*: Every LilyPond file should contain a version
statement. A version statement is a line that describes the
version of LilyPond for which the file was written, as in the
following example:
\version "2.18.2"
By convention, the version statement is placed at the top of the
LilyPond file.
The version statement is important for at least two reasons.
First, it allows automatic updating of the input file as LilyPond
syntax changes. Second, it describes the version of LilyPond
needed to compile the file.
If the version statement is omitted from an input file, LilyPond
will print a warning during the compilation of the file.
• *Case sensitive*: it matters whether you enter a letter in lower
case (e.g. ‘a, b, s, t’) or upper case (e.g. ‘A, B, S, T’). Notes
are lower case: ‘{ c d e }’ is valid input; ‘{ C D E }’ will
produce an error message.
• *Whitespace insensitive*: it does not matter how many spaces (or
tabs or new lines) you add. ‘{ c4 d e }’ means the same thing as
‘{ c4 d e }’ and:
{ c4 d
e }
Of course, the previous example is hard to read. A good rule of
thumb is to indent code blocks with two spaces:
{
c4 d e
}
However, whitespace _is_ required to separate many syntactical
elements from others. In other words, whitespace can always be
_added_, but not always _eliminated_. Since missing whitespace can
give rise to strange errors, it is advisable to always insert
whitespace before and after every syntactic element, for example,
before and after every curly brace.
• *Expressions*: every piece of LilyPond input needs to have
*{ curly braces }* placed around the input. These braces tell
LilyPond that the input is a single music expression, just like
parentheses ‘()’ in mathematics. The braces should be surrounded
by a space unless they are at the beginning or end of a line to
avoid ambiguities.
A LilyPond command followed by a simple expression in braces (such
as ‘‘\relative c' { ... }’’) also counts as a single music
expression.
• *Comments*: a comment is a remark for the human reader of the music
input; it is ignored while parsing, so it has no effect on the
printed output. There are two types of comments. The percent
symbol ‘%’ introduces a line comment; anything after ‘%’ on that
line is ignored. By convention, a line comment is placed _above_
the code it refers to.
a4 a a a
% this comment refers to the Bs
b2 b
A block comment marks a whole section of music input as a comment.
Anything that is enclosed in ‘%{’ and ‘%}’ is ignored. However,
block comments do not ‘nest’. This means that you cannot place a
block comment inside another block comment. If you try, the first
‘%}’ will terminate _both_ block comments. The following fragment
shows possible uses for comments:
% notes for twinkle twinkle follow
c4 c g' g a a g2
%{
This line, and the notes below are ignored,
since they are in a block comment.
f4 f e e d d c2
%}