version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.51"
+@c \version "2.12.0"
-@node Input syntax
-@chapter Input syntax
+@node General input and output
+@chapter General input and output
-This section deals with general LilyPond input syntax issues,
+This section deals with general LilyPond input and output issues,
rather than specific notation.
@menu
block, and inside or outside the single music expression within a
@code{\score} block.
-@seealso
+@seealso
Learning Manual:
-
@rlearning{Working on input files},
@rlearning{Music expressions explained},
@rlearning{Score is a (single) compound musical expression}.
@}
@end example
+@funindex \bookpart
+
+Pieces of music may be grouped into book parts using @code{\bookpart}
+blocks. Book parts are separated by a page break, and can start with a
+title, like the book itself, by specifying a @code{\header} block.
+
+@example
+\bookpart @{
+ \header @{
+ title = "Book title"
+ subtitle = "First part"
+ @}
+ \score @{ @dots{} @}
+ @dots{}
+@}
+\bookpart @{
+ \header @{
+ subtitle = "Second part"
+ @}
+ \score @{ @dots{} @}
+ @dots{}
+@}
+@end example
+
@node File structure
@subsection File structure
@funindex \header
@funindex \score
@funindex \book
+@funindex \bookpart
A @code{.ly} file may contain any number of toplevel expressions, where a
toplevel expression is one of the following:
toplevel. The default handler is defined in the init file
@file{../scm/@/lily@/.scm}.
+@item
+A @code{\bookpart} block. A book may be divided into several parts,
+using @code{\bookpart} blocks, in order to ease the page breaking,
+or to use different @code{\paper} settings in different parts.
+
@item
A compound music expression, such as
@example
@end example
This can be used later on in the file by entering @code{\foo}. The
-name of an variable should have alphabetic characters only; no
+name of a variable should have alphabetic characters only; no
numbers, underscores or dashes.
@end itemize
@end itemize
-@seealso
+@seealso
Learning Manual:
@rlearning{How LilyPond input files work}.
+
@node Titles and headers
@section Titles and headers
@subsection Creating titles
Titles are created for each @code{\score} block, as well as for the full
-input file (or @code{\book} block).
+input file (or @code{\book} block) and book parts (created by
+@code{\bookpart} blocks).
The contents of the titles are taken from the @code{\header} blocks.
The header block for a book supports the following
@funindex poet
@item poet
-Name of the poet, flush-left below the subtitle.
+Name of the poet, flush-left below the subsubtitle.
+
+@funindex instrument
+@item instrument
+Name of the instrument, centered below the subsubtitle. Also
+centered at the top of pages (other than the first page).
@funindex composer
@item composer
-Name of the composer, flush-right below the subtitle.
+Name of the composer, flush-right below the subsubtitle.
@funindex meter
@item meter
Meter string, flush-left below the poet.
-@funindex opus
-@item opus
-Name of the opus, flush-right below the composer.
-
@funindex arranger
@item arranger
-Name of the arranger, flush-right below the opus.
-
-@funindex instrument
-@item instrument
-Name of the instrument, centered below the arranger. Also
-centered at the top of pages (other than the first page).
+Name of the arranger, flush-right below the composer.
@funindex piece
@item piece
-Name of the piece, flush-left below the instrument.
+Name of the piece, flush-left below the meter.
+
+@funindex opus
+@item opus
+Name of the opus, flush-right below the arranger.
@cindex page breaks, forcing
@funindex breakbefore
\book {
\header {
dedication = "dedicated to me"
- title = \markup \center-align { "Title first line" "Title second line,
+ title = \markup \center-column { "Title first line" "Title second line,
longer" }
subtitle = "the subtitle,"
subsubtitle = #(string-append "subsubtitle LilyPond version "
(lilypond-version))
poet = "Poet"
- composer = \markup \center-align { "composer" \small "(1847-1973)" }
+ composer = \markup \center-column { "composer" \small "(1847-1973)" }
texttranslator = "Text Translator"
meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
"r" }
}
@end lilypond
-@funindex printallheaders
+@funindex print-all-headers
@noindent
You may change this behavior (and print all the headers when defining
@code{\header} inside @code{\score}) by using
@example
\paper@{
- printallheaders=##t
+ print-all-headers = ##t
@}
@end example
dimensions. If the book has between 10 and 99 pages, it may be "00",
ie. a two digit number.
-@predefined
+@predefined
@funindex \label
-@code{\label}
+@code{\label},
@funindex \page-ref
-@code{\page-ref}
+@code{\page-ref}.
+@endpredefined
+
@node Table of contents
@subsection Table of contents
}
@end lilypond
-@seealso
+@seealso
Init files: @file{../ly/@/toc@/-init@/.ly}.
-@predefined
+@predefined
@funindex \table-of-contents
-@code{\table-of-contents}
+@code{\table-of-contents},
@funindex \tocItem
-@code{\tocItem}
+@code{\tocItem}.
+@endpredefined
@node Working with input files
@end example
Files which are to be included can also contain @code{\include}
-statements of their own. These second-level
+statements of their own. By default, 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.
+not the directory containing the included file. However,
+this behavior can be changed by passing the option
+@code{-drelative-includes} option at the command line
+(or by adding @code{#(ly:set-option 'relative-includes #t)}
+at the top of the main input file). With @code{relative-includes}
+set, the path for each @code{\include} command will be taken
+relative to the file containing that command. This behavior is
+recommended and it will become the default behavior in a future
+version of lilypond.
Files can also be included from a directory in a search path
specified as an option when invoking LilyPond from the command
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.
+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.
+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
the first filter will remove all tagged sections except the one
named, and the second filter will remove even that tagged section.
-@seealso
+@seealso
Learning Manual:
@rlearning{Organizing pieces with variables}.
@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.
@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
+is known but which is not available in the editor being used, use
+@code{\char ##xhhhh} within a @code{\markup} block, where
+@code{hhhh} is the hexadecimal code for the character required.
+For example, @code{\char ##x03BE} enters 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. Of course, a font containing all
+such encoded characters must be installed and available to LilyPond.
+
+The following example shows UTF-8 coded characters being used in
+four places -- in a rehearsal mark, as articulation text, in lyrics
+and as stand-alone text below the score:
-@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.
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ c1 \mark \markup { \char ##x03EE }
+ c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
+ }
+ \addlyrics { O \markup { \concat{ Ph \char ##x0153 be! } } }
+}
+\markup { "Copyright 2008" \char ##x00A9 }
+@end lilypond
-@knownissues
+To enter the copyright sign in the copyright notice use:
-The @code{ly:export} format may be used in text within @code{\mark} or
-@code{\markup} commands but not in lyrics.
+@example
+\header @{
+ copyright = \markup @{ \char ##x00A9 "2008" @}
+@}
+@end example
@node Displaying LilyPond notation
@subsection Displaying LilyPond notation
@funindex skipTypesetting
+@funindex showFirstLength
@funindex showLastLength
When entering or copying music, usually only the music near the end (where
in your source file. This will render only the last 5 measures
(assuming 4/4 time signature) of every @code{\score} in the input
file. For longer pieces, rendering only a small part is often an order
-of magnitude quicker than rendering it completely
+of magnitude quicker than rendering it completely. When working on the
+beginning of a score you have already typeset (e.g. to add a new part),
+the @code{showFirstLength} property may be useful as well.
Skipping parts of a score can be controlled in a more fine-grained
fashion with the property @code{Score.skipTypesetting}. When it is
* What goes into the MIDI output?::
* Repeats in MIDI::
* Controlling MIDI dynamics::
+* Percussion in MIDI::
@end menu
@node Creating MIDI files
@example
\new Staff @{
- \set Staff.midiInstrument = "glockenspiel"
+ \set Staff.midiInstrument = #"glockenspiel"
@var{...notes...}
@}
@end example
@example
-\new Staff \with @{midiInstrument = "cello"@} @{
+\new Staff \with @{midiInstrument = #"cello"@} @{
@var{...notes...}
@}
@end example
@item Dynamic marks
@item Crescendi, decrescendi over multiple notes
@item Tempo changes entered with a tempo marking
+@item Lyrics
@end itemize
@unnumberedsubsubsec Unsupported in MIDI
@item Crescendi, decrescendi over a single note
@item Tremolos entered with @q{@code{:}[@var{number}]}
@item Figured bass
-@c TODO Check Lyrics
-@item Lyrics
@end itemize
\score {
\new Staff {
- \set Staff.midiInstrument = "cello"
+ \set Staff.midiInstrument = #"cello"
\set Score.dynamicAbsoluteVolumeFunction = #myDynamics
\new Voice {
\relative c'' {
@ignore
@c Delete when satisfied this is adequately covered elsewhere -td
-@node Microtones in MIDI
-@subsection Microtones in MIDI
+@n ode Microtones in MIDI
+@s ubsection Microtones in MIDI
@cindex microtones in MIDI
@end ignore
+@node Percussion in MIDI
+@subsection Percussion in MIDI
+
+Percussion instruments are generally notated in a @code{DrumStaff}
+context and when notated in this way they are outputted correctly
+to MIDI channel@tie{}10, but some pitched percussion instruments,
+like the xylophone, marimba, vibraphone, timpani, etc., are
+treated like @qq{normal} instruments and music for these instruments
+should be entered in a normal @code{Staff} context, not a
+@code{DrumStaff} context, to obtain the correct MIDI output.
+
+Some non-pitched percussion sounds included in the general MIDI
+standard, like melodic tom, taiko drum, synth drum, etc., cannot
+be reached via MIDI channel@tie{}10, so the notation for such
+instruments should also be entered in a normal @code{Staff}
+context, using suitable normal pitches.
+
+Many percussion instruments are not included in the general MIDI
+standard, e.g. castanets. The easiest, although unsatisfactory,
+method of producing some MIDI output when writing for such
+instruments is to substitute the nearest sound from the standard
+set.
+
+@c TODO Expand with examples, and any other issues
+
+@knownissues
+
+Because the general MIDI standard does not contain rim shots, the
+sidestick is used for this purpose instead.
+
projects / lilypond.git / blobdiff