version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.51"
+@c \version "2.11.61"
-@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
-* Input structure::
-* Titles and headers::
-* Working with input files::
-* Controlling output::
-* MIDI output::
+* Input structure::
+* Titles and headers::
+* Working with input files::
+* Controlling output::
+* MIDI output::
@end menu
these files end with @code{.ly}.
@menu
-* Structure of a score::
-* Multiple scores in a book::
-* File structure::
+* Structure of a score::
+* Multiple scores in a book::
+* File structure::
@end menu
@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
some pieces include a lot more information.
@menu
-* Creating titles::
-* Custom titles::
-* Reference to page numbers::
-* Table of contents::
+* Creating titles::
+* Custom titles::
+* Reference to page numbers::
+* Table of contents::
@end menu
@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
@section Working with input files
@menu
-* Including LilyPond files::
-* Different editions from one source::
-* Text encoding::
-* Displaying LilyPond notation::
+* Including LilyPond files::
+* Different editions from one source::
+* Text encoding::
+* Displaying LilyPond notation::
@end menu
structure while leaving the notation untouched.
@menu
-* Using variables::
-* Using tags::
+* Using variables::
+* Using tags::
@end menu
@node Using variables
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
+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
Here is an example showing Cyrillic, Hebrew and Portuguese
text:
-@lilypond[verbatim,quote]
+@lilypond[quote]
+%c No verbatim here as the code does not display correctly in PDF
% Cyrillic
bulgarian = \lyricmode {
Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
@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
@section Controlling output
@menu
-* Extracting fragments of music::
-* Skipping corrected music::
+* Extracting fragments of music::
+* Skipping corrected music::
@end menu
@node Extracting fragments of music
(or 14 if you do not use drums). Other staves will remain silent.
@menu
-* Creating MIDI files::
-* What goes into the MIDI output?::
-* MIDI block::
-* MIDI instrument names::
-* Repeats in MIDI::
-* Controlling MIDI dynamics::
-* Microtones in MIDI::
+* Creating MIDI files::
+* MIDI block::
+* What goes into the MIDI output?::
+* Repeats in MIDI::
+* Controlling MIDI dynamics::
+* Percussion in MIDI::
@end menu
@node Creating MIDI files
@subsection Creating MIDI files
-To create a MIDI output file from a LilyPond input file, add a @code{\midi} block
-to a score, for example,
+To create a MIDI output file from a LilyPond input file, add a
+@code{\midi} block to a score, for example,
@example
\score @{
of specifying the inital or overall MIDI tempo is described below,
see @ref{MIDI block}.
+@unnumberedsubsubsec Instrument names
+
+@cindex instrument names
+@funindex Staff.midiInstrument
+
+The MIDI instrument to be used is specified by setting the
+@code{Staff.midiInstrument} property to the instrument name.
+The name should be chosen from the list in @ref{MIDI instruments}.
+
+@example
+\new Staff @{
+ \set Staff.midiInstrument = "glockenspiel"
+ @var{...notes...}
+@}
+@end example
+
+@example
+\new Staff \with @{midiInstrument = "cello"@} @{
+ @var{...notes...}
+@}
+@end example
+
+If the selected instrument does not exactly match an instrument from
+the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
+instrument is used.
+
+
@snippets
@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
output. Players that are known to work include MS Windows Media
Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
-@node What goes into the MIDI output?
-@subsection What goes into the MIDI output?
-
-@c TODO Check grace notes - timing is suspect?
-
-@unnumberedsubsubsec Supported in MIDI
-
-The following items of notation are reflected in the MIDI output:
-
-@itemize
-@item Pitches
-@item Microtones
-@item Chords entered as chord names
-@item Rhythms entered as note durations, including tuplets
-@item Tremolos entered without @q{@code{:}[@var{number}]}
-@item Ties
-@item Dynamic marks
-@item Crescendi, decrescendi over multiple notes
-@item Tempo changes entered with a tempo marking
-@end itemize
-
-@unnumberedsubsubsec Unsupported in MIDI
-
-The following items of notation have no effect on the MIDI output:
-
-@itemize
-@item Rhythms entered as annotations, e.g. swing
-@item Tempo changes entered as annotations with no tempo marking
-@item Staccato and other articulations and ornamentations
-@item Slurs and Phrasing slurs
-@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
-
-
@node MIDI block
@subsection MIDI block
@cindex MIDI block
@}
@end example
-@node MIDI instrument names
-@subsection MIDI instrument names
+@node What goes into the MIDI output?
+@subsection What goes into the MIDI output?
-@cindex instrument names
-@funindex Staff.midiInstrument
+@c TODO Check grace notes - timing is suspect?
-The MIDI instrument name is set by the @code{Staff.midiInstrument}
-property. The instrument name should be chosen from the list in
-@ref{MIDI instruments}.
+@unnumberedsubsubsec Supported in MIDI
-@example
-\set Staff.midiInstrument = "glockenspiel"
-@var{...notes...}
-@end example
+@cindex Pitches in MIDI
+@cindex MIDI, Pitches
+@cindex Quarter tones in MIDI
+@cindex MIDI, quarter tones
+@cindex Microtones in MIDI
+@cindex MIDI, microtones
+@cindex Chord names in MIDI
+@cindex MIDI, chord names
+@cindex Rhythms in MIDI
+@cindex MIDI, Rhythms
+@c TODO etc
-If the selected instrument does not exactly match an instrument from
-the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
-instrument is used.
+The following items of notation are reflected in the MIDI output:
+
+@itemize
+@item Pitches
+@item Quarter tones (See @ref{Accidentals}. Rendering needs a
+player that supports pitch bend.)
+@item Chords entered as chord names
+@item Rhythms entered as note durations, including tuplets
+@item Tremolos entered without @q{@code{:}[@var{number}]}
+@item Ties
+@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
+
+@c TODO index as above
+
+The following items of notation have no effect on the MIDI output:
+
+@itemize
+@item Rhythms entered as annotations, e.g. swing
+@item Tempo changes entered as annotations with no tempo marking
+@item Staccato and other articulations and ornamentations
+@item Slurs and Phrasing slurs
+@item Crescendi, decrescendi over a single note
+@item Tremolos entered with @q{@code{:}[@var{number}]}
+@item Figured bass
+@end itemize
@node Repeats in MIDI
required fraction, and setting
@code{Score.dynamicAbsoluteVolumeFunction} to this function.
-For example, if a @notation{rinforzando} dynamic marking, rfz,
-has been defined with @code{make-dynamic-script}, this will not
+For example, if a @notation{rinforzando} dynamic marking,
+@code{\rfz}, is required, this will not by default
have any effect on the MIDI volume, as this dynamic marking is not
-included in the default set. The following example shows how the
-MIDI volume for this new dynamic marking can be added. The Scheme
+included in the default set. Similarly, if a new dynamic marking
+has been defined with @code{make-dynamic-script} that too will not
+be included in the default set. The following example shows how the
+MIDI volume for such dynamic markings might be added. The Scheme
function sets the fraction to 0.9 if a dynamic mark of rfz is
found, or calls the default function otherwise.
0.9
(default-dynamic-absolute-volume dynamic)))
-rfz = #(make-dynamic-script "rfz")
-
\score {
\new Staff {
\set Staff.midiInstrument = "cello"
}
@end lilypond
-@node Microtones in MIDI
-@subsection Microtones in MIDI
+@ignore
+@c Delete when satisfied this is adequately covered elsewhere -td
+
+@n ode Microtones in MIDI
+@s ubsection Microtones in MIDI
@cindex microtones in MIDI
\midi {}
}
@end lilypond
+@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.