+
+@node Including LilyPond files
+@subsection Including LilyPond files
+
+@funindex \include
+@cindex including files
+
+A large project may be split up into separate files. To refer to
+another file, use
+
+@example
+\include "otherfile.ly"
+@end example
+
+The line @code{\include "otherfile.ly"} is equivalent to pasting the
+contents of @file{otherfile.ly} into the current file at the place
+where the @code{\include} appears. For example, in a large
+project you might write separate files for each instrument part
+and create a @qq{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 @ref{Different editions from
+one source}.
+
+Files in the current working directory may be referenced by
+specifying just the file name after the @code{\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 @file{stuff.ly} is located
+one directory higher than the current working directory, use
+
+@example
+\include "../stuff.ly"
+@end example
+
+@noindent
+or if the included orchestral parts files are all located in a
+subdirectory called @file{parts} within the current directory, use
+
+@example
+\include "parts/VI.ly"
+\include "parts/VII.ly"
+... etc
+@end example
+
+Files which are to be included can also contain @code{\include}
+statements of their own. These second-level
+@code{\include} statements are not interpreted until they have
+been brought into the main file, so the file names they specify
+must all be relative to the directory containing the main file,
+not the directory containing the included file.
+
+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 @file{main.ly} which includes
+files located in a subdirectory called @file{parts} by this method,
+cd to the directory containing @file{main.ly} and enter
+
+@example
+lilypond --include=parts main.ly
+@end example
+
+and in main.ly write
+
+@example
+\include "VI.ly"
+\include "VII.ly"
+... etc
+@end example
+
+Files which are to be included in many scores may be placed in
+the LilyPond directory @file{../ly}. (The location of this
+directory is installation-dependent - see @rlearning{Other sources
+of information}). These files can then be included simply by
+naming them on an @code{\include} statement. This is how the
+language-dependent files like @file{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 @code{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 @rlearning{Other
+sources of information}. These files may be edited, but changes to
+them will be lost on installing a new version of LilyPond.
+
+Some simple examples of using @code{\include} are shown in
+@rlearning{Scores and parts}.
+
+@seealso
+Learning Manual:
+@rlearning{Other sources of information},
+@rlearning{Scores and parts}.
+
+@knownissues
+
+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.
+
+
+
+@node Different editions from one source
+@subsection Different editions from one source
+
+Several mechanisms are available to facilitate the generation
+of different versions of a score from the same music source.
+Variables are perhaps most useful for combining lengthy sections
+of music and/or annotation in various ways, while tags are more
+useful for selecting one from several alternative shorter sections
+of music. 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.
+
+@menu
+* Using variables::
+* Using tags::
+@end menu
+
+@node Using variables
+@unnumberedsubsubsec Using variables
+
+@cindex variables, use of
+
+If sections of the music are defined in variables they can be
+reused in different parts of the score, see @rlearning{Organizing
+pieces with variables}. For example, an @notation{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 @ref{Automatic part combining}.
+Here is an example:
+
+@lilypond[verbatim,quote]
+sopranoMusic = \relative c'' { a4 b c b8( a)}
+altoMusic = \relative g' { e4 e e f }
+tenorMusic = \relative c' { c4 b e d8( c) }
+bassMusic = \relative c' { 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" {
+ \set Staff.printPartCombineTexts = ##f
+ \partcombine
+ \sopranoMusic
+ \altoMusic
+ }
+ \new Staff = "LH" {
+ \set Staff.printPartCombineTexts = ##f
+ \clef "bass"
+ \partcombine
+ \tenorMusic
+ \bassMusic
+ }
+ >>
+>>
+@end lilypond
+
+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 @ref{Including
+LilyPond files}.
+
+@node Using tags
+@unnumberedsubsubsec Using tags
+
+@funindex \tag
+@funindex \keepWithTag
+@funindex \removeWithTag
+@cindex tag
+@cindex keep tagged music
+@cindex remove tagged music
+
+The @code{\tag #'@var{partA}} command marks a music expression
+with the name @var{partA}.
+Expressions tagged in this way can be selected or filtered out by
+name later, using either @code{\keepWithTag #'@var{name}} or
+@code{\removeWithTag #'@var{name}}. The result of applying these filters
+to tagged music is as follows:
+@multitable @columnfractions .5 .5
+@headitem Filter
+ @tab Result
+@item
+Tagged music preceded by @code{\keepWithTag #'@var{name}}
+ @tab Untagged music and music tagged with @var{name} is included;
+ music tagged with any other tag name is excluded.
+@item
+Tagged music preceded by @code{\removeWithTag #'@var{name}}
+@tab Untagged music and music tagged with any tag name other than
+ @var{name} is included; music tagged with @var{name} is
+ excluded.
+@item
+Tagged music not preceded by either @code{\keepWithTag} or
+@code{\removeWithTag}
+@tab All tagged and untagged music is included.
+@end multitable
+
+The arguments of the @code{\tag}, @code{\keepWithTag} and
+@code{\removeWithTag} commands should be a symbol
+(such as @code{#'score} or @code{#'part}), followed
+by a music expression.
+
+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:
+
+@lilypond[verbatim,quote]
+music = \relative g' {
+ g8. c32 d
+ \tag #'trills {d8.\trill }
+ \tag #'expand {\repeat unfold 3 {e32 d} }
+ c32 d
+ }
+
+\score {
+ \keepWithTag #'trills \music
+}
+\score {
+ \keepWithTag #'expand \music
+}
+@end lilypond
+
+@noindent
+Alternatively, it is sometimes easier to exclude sections of music:
+
+@lilypond[verbatim,quote]
+music = \relative g' {
+ g8. c32 d
+ \tag #'trills {d8.\trill }
+ \tag #'expand {\repeat unfold 3 {e32 d} }
+ c32 d
+ }
+
+\score {
+ \removeWithTag #'expand
+ \music
+}
+\score {
+ \removeWithTag #'trills
+ \music
+}
+@end lilypond
+
+Tagged filtering can be applied to articulations, texts, etc. by
+prepending
+
+@example
+-\tag #'@var{your-tag}
+@end example
+
+to an articulation. For example, this would define a note with a
+conditional fingering indication and a note with a conditional
+annotation:
+
+@example
+c1-\tag #'finger ^4
+c1-\tag #'warn ^"Watch!"
+@end example
+
+Multiple tags may be placed on expressions with multiple
+@code{\tag} entries:
+
+@lilypond[quote,verbatim]
+music = \relative c'' {
+ \tag #'a \tag #'both { a a a a }
+ \tag #'b \tag #'both { b b b b }
+}
+<<
+\keepWithTag #'a \music
+\keepWithTag #'b \music
+\keepWithTag #'both \music
+>>
+@end lilypond
+
+Multiple @code{\removeWithTag} filters may be applied to a single
+music expression to remove several differently named tagged sections:
+
+@lilypond[verbatim,quote]
+music = \relative c'' {
+\tag #'A { a a a a }
+\tag #'B { b b b b }
+\tag #'C { c c c c }
+\tag #'D { d d d d }
+}
+{
+\removeWithTag #'B
+\removeWithTag #'C
+\music
+}
+@end lilypond
+
+Two or more @code{\keepWithTag} filters applied to a single music
+expression will cause @emph{all} tagged sections to be removed, as
+the first filter will remove all tagged sections except the one
+named, and the second filter will remove even that tagged section.
+
+@seealso
+
+Learning Manual:
+@rlearning{Organizing pieces with variables}.
+
+Notation Reference:
+@ref{Automatic part combining},
+@ref{Including LilyPond files}.
+
+@ignore
+@c This warning is more general than this placement implies.
+@c Rests are not merged whether or not they come from tagged sections.
+@c Should be deleted? -td
+
+@knownissues
+
+Multiple rests are not merged if you create a score with more
+than one tagged section at the same place.
+
+@end ignore
+
+@node Text encoding
+@subsection 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
+
+@example
+FT_Get_Glyph_Name () error: invalid argument
+@end example
+
+will be generated.
+
+Here is an example showing Cyrillic, Hebrew and Portuguese
+text:
+
+@lilypond[quote]
+%c No verbatim here as the code does not display correctly in PDF
+% Cyrillic
+bulgarian = \lyricmode {
+ Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
+}
+
+% Hebrew
+hebrew = \lyricmode {
+ זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
+}
+
+% Portuguese
+portuguese = \lyricmode {
+ à vo -- cê uma can -- ção legal
+}
+
+\relative {
+ c2 d e f g f e
+}
+\addlyrics { \bulgarian }
+\addlyrics { \hebrew }
+\addlyrics { \portuguese }
+@end lilypond
+
+To enter a single character for which the Unicode escape sequence
+is known but which is not available in the editor being used, enter
+
+@example
+#(ly:export (ly:wide-char->utf-8 #x03BE))
+@end example
+
+where in this example @code{x03BE} is the hexadecimal code for the
+Unicode U+03BE character, which has the Unicode name @qq{Greek Small
+Letter Xi}. Any Unicode hexadecimal code may be substituted, and
+if all special characters are entered in this format it is not
+necessary to save the input file in UTF-8 format.
+
+@knownissues
+
+The @code{ly:export} format may be used in text within @code{\mark} or
+@code{\markup} commands but not in lyrics.
+