2.2.3 Working on input files (LilyPond Learning Manual)

#### 2.2.3 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 whitespace 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 are now going to 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.26.0"

  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 prints a warning during the compilation of the file.

- Case sensitive: It matters whether you enter a letter in lowercase (e.g., ‘`a`’, ‘`b`’, ‘`s`’, ‘`t`’) or uppercase (e.g., ‘`A`’, ‘`B`’, ‘`S`’, ‘`T`’). Notes are lowercase: ‘`{ c d e }`’ is valid input; ‘`{ C D E }`’ produces 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 }

  or

      { 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 { … }`’) 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 next line with the two 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
      %}

#### LilyPond Learning Manual v2.26.0 (stable-branch).

- 1 Installing
  - 1.1 Graphical setup
  - 1.2 Command line setup
- 2 Tutorial
  - 2.1 Compiling a file
  - 2.2 How to write input files
    - 2.2.1 Input characters
    - 2.2.2 Simple notation
      - Pitches
      - Durations (rhythms)
      - Rests
      - Time signature
      - Tempo marks
      - Clef
      - All together
    - 2.2.3 Working on input files
  - 2.3 Dealing with errors
  - 2.4 How to read the manuals
    - 2.4.1 Omitted material
    - 2.4.2 Clickable examples
    - 2.4.3 Overview of manuals
- 3 Common notation
  - 3.1 Single-staff notation
    - 3.1.1 Bar lines and bar checks
      - Bar lines
      - Bar checks
    - 3.1.2 Pitches and key signatures
      - Pitch alterations
      - Key signatures
      - Warning: key signatures and pitches
    - 3.1.3 Ties and slurs
      - Ties
      - Slurs
      - Phrasing slurs
      - Warnings: slurs vs. ties
    - 3.1.4 Articulations and dynamics
      - Articulations
      - Fingerings
      - Dynamics
    - 3.1.5 Adding text
    - 3.1.6 Automatic and manual beams
    - 3.1.7 Advanced rhythmic commands
      - Partial measure
      - Tuplets
      - Grace notes
  - 3.2 Multiple notes at once
    - 3.2.1 Music expressions explained
      - Analogy: mathematical expressions
      - Simultaneous music expressions: multiple staves
      - Simultaneous music expressions: single-staff
    - 3.2.2 Multiple staves
    - 3.2.3 Staff groups
    - 3.2.4 Combining notes into chords
    - 3.2.5 Single-staff polyphony
  - 3.3 Songs
    - 3.3.1 Setting simple songs
    - 3.3.2 Aligning lyrics to a melody
    - 3.3.3 Lyrics to multiple staves
  - 3.4 Final touches
    - 3.4.1 Organizing pieces with variables
    - 3.4.2 Adding titles
    - 3.4.3 Absolute note names
    - 3.4.4 After the tutorial
- 4 Fundamental concepts
  - 4.1 How LilyPond input files work
    - 4.1.1 Introduction to the LilyPond file structure
    - 4.1.2 A score is a (single) compound musical expression
    - 4.1.3 Nesting music expressions
    - 4.1.4 Structure of a note entry
    - 4.1.5 On the un-nestedness of brackets and ties
  - 4.2 Voices contain music
    - 4.2.1 I’m hearing voices
    - 4.2.2 Explicitly instantiating voices
    - 4.2.3 Voices and vocals
  - 4.3 Contexts and engravers
    - 4.3.1 Contexts explained
    - 4.3.2 Creating contexts
    - 4.3.3 Engravers explained
    - 4.3.4 Modifying context properties
    - 4.3.5 Adding and removing engravers
  - 4.4 Extending the templates
    - 4.4.1 Soprano and cello
    - 4.4.2 Four-part SATB vocal score
    - 4.4.3 Building a score from scratch
    - 4.4.4 Saving typing with variables and functions
    - 4.4.5 Scores and parts
- 5 Tweaking output
  - 5.1 Tweaking basics
    - 5.1.1 Objects and interfaces
    - 5.1.2 Naming conventions of objects and properties
    - 5.1.3 Tweaking methods
      - The `\override` command
      - The `\revert` command
      - The `\once` prefix
      - The `\tweak` and `\offset` commands
      - The `\single` prefix
  - 5.2 The Internals Reference manual
    - 5.2.1 Properties of layout objects
    - 5.2.2 Properties found in interfaces
    - 5.2.3 Types of properties
  - 5.3 Appearance of objects
    - 5.3.1 Visibility and color of objects
      - The `stencil` property
      - The `break-visibility` property
      - The `transparent` property
      - The `color` property
    - 5.3.2 Size of objects
    - 5.3.3 Length and thickness of objects
  - 5.4 Offsets and alignments
  - 5.5 Placement of objects
    - 5.5.1 Automatic behavior
    - 5.5.2 Within-staff objects
      - The `direction` property
      - Fingering
    - 5.5.3 Outside-staff objects
      - The `outside-staff-priority` property
      - The `\textLengthOn` command
      - Dynamics placement
      - Grob sizing
  - 5.6 Vertical spacing
  - 5.7 Collisions of objects
    - 5.7.1 Moving objects
    - 5.7.2 Fixing overlapping notation
      - The `padding` property
      - The `right-padding` property
      - The `staff-padding` property
      - The `self-alignment-X` property
      - The `staff-position` property
      - The `extra-offset` property
      - The `positions` property
      - The `force-hshift` property
    - 5.7.3 Real music example
  - 5.8 Further tweaking
    - 5.8.1 Other uses for tweaks
      - Tying notes across voices
      - Simulating a fermata in MIDI
    - 5.8.2 Using variables for layout adjustments
    - 5.8.3 Style sheets
    - 5.8.4 Other sources of information
    - 5.8.5 Advanced tweaks with Scheme
- Appendix A Templates
  - A.1 Built-in templates
    - A.1.1 SATB template
    - A.1.2 SSAATTBB template
  - A.2 Single staff templates
    - A.2.1 Notes only
    - A.2.2 Notes and lyrics
    - A.2.3 Notes and chords
    - A.2.4 Notes, lyrics, and chords
  - A.3 Piano templates
    - A.3.1 Solo piano
    - A.3.2 Piano and melody with lyrics
    - A.3.3 Piano-centered lyrics
  - A.4 String quartet templates
    - A.4.1 String quartet
    - A.4.2 String quartet parts
  - A.5 Vocal ensembles templates
    - A.5.1 SATB vocal score
    - A.5.2 SATB vocal score and automatic piano reduction
    - A.5.3 SATB with aligned contexts
    - A.5.4 SATB on four staves
    - A.5.5 Solo verse and two-part refrain
    - A.5.6 Hymn tunes
    - A.5.7 Psalms
  - A.6 Orchestral templates
    - A.6.1 Orchestra, choir and piano
  - A.7 Ancient notation templates
    - A.7.1 Transcription of mensural music
    - A.7.2 Gregorian transcription template
  - A.8 Other templates
    - A.8.1 Jazz combo
- Appendix B GNU Free Documentation License
- Appendix C Index