3.3 Working with input files

3.3.1 Including LilyPond files

A large project may be split up into separate files. To refer to another file, use

\include "otherfile.ly"

The line \include "otherfile.ly" is equivalent to pasting the contents of ‘otherfile.ly’ into the current file at the place where the \include appears. For example, in a large project you might write separate files for each instrument part and create a “full score” file which brings together the individual instrument files. Normally the included file will define a number of variables which then become available for use in the full score file. Tagged sections can be marked in included files to assist in making them usable in different places in a score, see Different editions from one source.

Files in the current working directory may be referenced by specifying just the file name after the \include command. Files in other locations may be included by giving either a full path reference or a relative path reference (but use the UNIX forward slash, /, rather than the DOS/Windows back slash, \, as the directory separator.) For example, if ‘stuff.ly’ is located one directory higher than the current working directory, use

\include "../stuff.ly"

or if the included orchestral parts files are all located in a subdirectory called ‘parts’ within the current directory, use

\include "parts/VI.ly"
\include "parts/VII.ly"
… etc

Files which are to be included can also contain \include statements of their own. These second-level \include statements are then interpreted relatively to the path of the file containing that command, which is convenient for multiple files located in the same subdirectory. For example, a general library, libA, may itself use sub-files which are \included by the entry file of that library, like this:

libA/
  libA.ly
  A1.ly
  A2.ly
  …

then the entry file, libA.ly, will contain

\include "A1.ly"
\include "A2.ly"
…

Any ‘.ly’ file can then include the entire library simply with

\include "~/libA/libA.ly"

However, that behavior can be changed globally by passing the option ‘-drelative-includes=#f’ option at the command line (or by adding #(ly:set-option 'relative-includes #f) at the top of the main input file). In that case, each file will be included relatively to the location of the main file, regardless of where its \include statement is located. Complex file structures, that require to \include both files relative to the main directory and files relative to some other directory, may even be devised by setting relative-includes to #f or #t at appropriate places in the files.

Files can also be included from a directory in a search path specified as an option when invoking LilyPond from the command line. The included files are then specified using just their file name. For example, to compile ‘main.ly’ which includes files located in a subdirectory called ‘parts’ by this method, cd to the directory containing ‘main.ly’ and enter

lilypond --include=parts main.ly

and in main.ly write

\include "VI.ly"
\include "VII.ly"
… etc

Files which are to be included in many scores may be placed in the LilyPond directory ‘../ly’. (The location of this directory is installation-dependent - see (learning)Other sources of information section ‘Other sources of information’ in Learning Manual). These files can then be included simply by naming them on an \include statement. This is how the language-dependent files like ‘english.ly’ are included.

LilyPond includes a number of files by default when you start the program. These includes are not apparent to the user, but the files may be identified by running lilypond --verbose from the command line. This will display a list of paths and files that LilyPond uses, along with much other information. Alternatively, the more important of these files are discussed in (learning)Other sources of information section ‘Other sources of information’ in Learning Manual. These files may be edited, but changes to them will be lost on installing a new version of LilyPond.

Some simple examples of using \include are shown in (learning)Scores and parts section ‘Scores and parts’ in Learning Manual.

See also

Learning Manual: (learning)Other sources of information section ‘Other sources of information’ in Learning Manual, (learning)Scores and parts section ‘Scores and parts’ in Learning Manual.

Known issues and warnings

If an included file is given a name which is the same as one in LilyPond’s installation files, LilyPond’s file from the installation files takes precedence.

3.3.2 Different editions from one source

Several methods can be used to generate different versions of a score from the same music source. Variables are perhaps the most useful for combining lengthy sections of music and/or annotation. Tags are more useful for selecting one section from several alternative shorter sections of music, and can also be used for splicing pieces of music together at different points.

Whichever method is used, separating the notation from the structure of the score will make it easier to change the structure while leaving the notation untouched.

Using variables

If sections of the music are defined in variables they can be reused in different parts of the score, see pieces with variables (learning)Organizing pieces with variables section ‘Organizing pieces with variables’ in Learning Manual. For example, an a cappella vocal score frequently includes a piano reduction of the parts for rehearsal purposes which is identical to the vocal music, so the music need be entered only once. Music from two variables may be combined on one staff, see Automatic part combining. Here is an example:

sopranoMusic = \relative { a'4 b c b8( a) } altoMusic = \relative { e'4 e e f } tenorMusic = \relative { c'4 b e d8( c) } bassMusic = \relative { a4 gis a d, } allLyrics = \lyricmode { King of glo -- ry } << \new Staff = "Soprano" \sopranoMusic \new Lyrics \allLyrics \new Staff = "Alto" \altoMusic \new Lyrics \allLyrics \new Staff = "Tenor" { \clef "treble_8" \tenorMusic } \new Lyrics \allLyrics \new Staff = "Bass" { \clef "bass" \bassMusic } \new Lyrics \allLyrics \new PianoStaff << \new Staff = "RH" { \partCombine \sopranoMusic \altoMusic } \new Staff = "LH" { \clef "bass" \partCombine \tenorMusic \bassMusic } >> >>

Separate scores showing just the vocal parts or just the piano part can be produced by changing just the structural statements, leaving the musical notation unchanged.

For lengthy scores, the variable definitions may be placed in separate files which are then included, see Including LilyPond files.

Using tags

The \tag #'partA command marks a music expression with the name partA. Expressions tagged in this way can be selected or filtered out by name later, using either \keepWithTag #'name or \removeWithTag #'name. The result of applying these filters to tagged music is as follows:

The arguments of the \tag, \keepWithTag and \removeWithTag commands should be a symbol or list of symbols (such as #'score or #'(violinI violinII), followed by a music expression. If and only if the symbols are valid LilyPond identifiers (alphabetic characters only, no numbers, underscores, or dashes) which cannot be confused with notes, the #' may be omitted and, as a shorthand, a list of symbols can use the dot separator: i.e., \tag #'(violinI violinII) can be written \tag violinI.violinII. The same applies to \keepWithTag and \removeWithTag. Tagging commands are music functions, thus they cannot be used to filter items that are not music expressions, such as \book or \score blocks.

In the following example, we see two versions of a piece of music, one showing trills with the usual notation, and one with trills explicitly expanded:

music = \relative { g'8. c32 d \tag #'trills { d8.\trill } \tag #'expand { \repeat unfold 3 { e32 d } } c32 d } \score { \keepWithTag #'trills \music } \score { \keepWithTag #'expand \music }

Alternatively, it is sometimes easier to exclude sections of music:

music = \relative { g'8. c32 d \tag #'trills { d8.\trill } \tag #'expand {\repeat unfold 3 { e32 d } } c32 d } \score { \removeWithTag #'expand \music } \score { \removeWithTag #'trills \music }

Tagged filtering can be applied to articulations, texts, etc., by prepending

-\tag #'your-tag

to an articulation. For example, this would define a note with a conditional fingering indication and a note with a conditional annotation:

c1-\tag #'finger ^4
c1-\tag #'warn ^"Watch!"

Multiple tags may be placed on expressions with multiple \tag entries, or by combining multiple tags into one symbol list:

music = \relative c'' { \tag #'a \tag #'both { a4 a a a } \tag #'(b both) { b4 b b b } } << \keepWithTag #'a \music \keepWithTag #'b \music \keepWithTag #'both \music >>

Multiple \removeWithTag filters may be applied to a single music expression to remove several differently named tagged sections. Alternatively, you can use a single \removeWithTag with a list of tags.

music = \relative c'' { \tag #'A { a4 a a a } \tag #'B { b4 b b b } \tag #'C { c4 c c c } \tag #'D { d4 d d d } } \new Voice { \removeWithTag #'B \removeWithTag #'C \music \removeWithTag #'(B C) \music }

Using two or more \keepWithTag filters on a single music expression will cause all of the tagged sections to be removed. The first filter will remove all except the one named and any subsequent filters will remove the rest. Using one \keepWithTag command with a list of multiple tags will only remove tagged sections that are not specified in that list.

music = \relative c'' { \tag #'violinI { a4 a a a } \tag #'violinII { b4 b b b } \tag #'viola { c4 c c c } \tag #'cello { d4 d d d } } \new Staff { \keepWithTag #'(violinI violinII) \music }

will print \tags violinI and violinII but not viola or cello.

While \keepWithTag is convenient when dealing with one set of alternatives, the removal of music tagged with unrelated tags is problematic when using them for more than one purpose. In that case ‘groups’ of tags can be declared:

\tagGroup #'(violinI violinII viola cello)

Now all the different tags belong to a single ‘tag group’. Note that individual tags cannot be members of more than one tag group.

\keepWithTag #'violinI …

will now only show music tagged from violinI’s tag group and any music tagged with one of the other tags will removed.

music = \relative { \tagGroup #'(violinI violinII viola cello) \tag #'violinI { c''4^"violinI" c c c } \tag #'violinII { a2 a } \tag #'viola { e8 e e2. } \tag #'cello { d'2 d4 d } R1^"untagged" } \new Voice { \keepWithTag #'violinI \music }

When using the \keepWithTag command, only tags from the tag groups of the tags given in the command are visible.

Sometimes you want to splice some music at a particular place in an existing music expression. You can use \pushToTag and \appendToTag for adding material at the front or end of the elements of an existing music construct. Not every music construct has elements, but sequential and simultaneous music are safe bets:

music = { \tag #'here { \tag #'here <<c''>> } } { \pushToTag #'here c' \pushToTag #'here e' \pushToTag #'here g' \music \appendToTag #'here c' \appendToTag #'here e' \appendToTag #'here g' \music }

Both commands get a tag, the material to splice in at every occurence of the tag, and the tagged expression.

See also

Learning Manual: (learning)Organizing pieces with variables section ‘Organizing pieces with variables’ in Learning Manual.

Notation Reference: Automatic part combining, Including LilyPond files.

Known issues and warnings

Calling \relative on a music expression obtained by filtering music through \keepWithTag or \removeWithTag might cause the octave relations to change, as only the pitches actually remaining in the filtered expression will be considered. Applying \relative first, before \keepWithTag or \removeWithTag, avoids this danger as \relative then acts on all the pitches as-input.

Using global settings

Global settings can be included from a separate file:

lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly

Groups of settings such as page size, font or type face can be stored in separate files. This allows different editions from the same score as well as standard settings to be applied to many scores, simply by specifying the proper settings file.

This technique also works well with the use of style sheets, as discussed in (learning)Style sheets section ‘Style sheets’ in Learning Manual.

See also

Learning Manual: (learning)Organizing pieces with variables section ‘Organizing pieces with variables’ in Learning Manual, (learning)Style sheets section ‘Style sheets’ in Learning Manual.

Notation Reference: Including LilyPond files.

3.3.3 Special characters

Text encoding

LilyPond uses the character repertoire defined by the Unicode consortium and ISO/IEC 10646. This defines a unique name and code point for the character sets used in virtually all modern languages and many others too. Unicode can be implemented using several different encodings. LilyPond uses the UTF-8 encoding (UTF stands for Unicode Transformation Format) which represents all common Latin characters in one byte, and represents other characters using a variable length format of up to four bytes.

The actual appearance of the characters is determined by the glyphs defined in the particular fonts available - a font defines the mapping of a subset of the Unicode code points to glyphs. LilyPond uses the Pango library to layout and render multi-lingual texts.

LilyPond does not perform any input-encoding conversions. This means that any text, be it title, lyric text, or musical instruction containing non-ASCII characters, must be encoded in UTF-8. The easiest way to enter such text is by using a Unicode-aware editor and saving the file with UTF-8 encoding. Most popular modern editors have UTF-8 support, for example, vim, Emacs, jEdit, and Gedit do. All MS Windows systems later than NT use Unicode as their native character encoding, so even Notepad can edit and save a file in UTF-8 format. A more functional alternative for Windows is BabelPad.

If a LilyPond input file containing a non-ASCII character is not saved in UTF-8 format the error message

FT_Get_Glyph_Name () error: invalid argument

will be generated.

Here is an example showing Cyrillic, Hebrew and Portuguese text:

Unicode

To enter a single character for which the Unicode code point is known but which is not available in the editor being used, use either \char ##xhhhh or \char #dddd within a \markup block, where hhhh is the hexadecimal code for the character required and dddd is the corresponding decimal value. Leading zeroes may be omitted, but it is usual to specify all four characters in the hexadecimal representation. (Note that the UTF-8 encoding of the code point should not be used after \char, as UTF-8 encodings contain extra bits indicating the number of octets.) Unicode code charts and a character name index giving the code point in hexadecimal for any character can be found on the Unicode Consortium website, http://www.unicode.org/.

For example, \char ##x03BE and \char #958 would both enter the Unicode U+03BE character, which has the Unicode name “Greek Small Letter Xi”.

Any Unicode code point may be entered in this way and if all special characters are entered in this format it is not necessary to save the input file in UTF-8 format. Of course, a font containing all such encoded characters must be installed and available to LilyPond.

The following example shows Unicode hexadecimal values being entered in four places – in a rehearsal mark, as articulation text, in lyrics and as stand-alone text below the score:

\score { \relative { c''1 \mark \markup { \char ##x03EE } c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } } } \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } } } \markup { "Copyright 2008--2020" \char ##x00A9 }

To enter the copyright sign in the copyright notice use:

\header {
  copyright = \markup { \char ##x00A9 "2008" }
}

ASCII aliases

A list of ASCII aliases for special characters can be included:

\paper { #(include-special-characters) } \markup "&flqq; – &OE;uvre incomplète… &frqq;" \score { \new Staff { \repeat unfold 9 a'4 } \addlyrics { This is al -- so wor -- kin'~in ly -- rics: –_&OE;… } } \markup \column { "The replacement can be disabled:" "– &OE; …" \override #'(replacement-alist . ()) "– &OE; …" }

You can also make your own aliases, either globally:

\paper { #(add-text-replacements! '(("100" . "hundred") ("dpi" . "dots per inch"))) } \markup "A 100 dpi."

or locally:

\markup \replace #'(("100" . "hundred") ("dpi" . "dots per inch")) "A 100 dpi."

See also

Notation Reference: List of special characters.

Installed Files: ‘ly/text-replacements.ly’.

This document was generated by gub on July 13, 2020 using texi2html 1.82.

Más nyelvek: català, deutsch, español, français, italiano, 日本語.
Az automatikus nyelvválasztásról.