version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.61"
+@c \version "2.12.0"
@node General input and output
@chapter General input and output
@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.
+or to use different @code{\paper} settings in different parts.
@item
A compound music expression, such as
@end itemize
+@cindex whitespace
+
+Whitespace between items in the input stream is generally ignored,
+and may be freely omitted or extended to enhance readability.
+However, whitespace should always be used in the following
+circumstances to avoid errors:
+
+@itemize
+@item Around every opening and closing curly bracket.
+@item After every command or variable, i.e. every item that
+begins with a @code{\} sign.
+@item After every item that is to be interpreted as a Scheme
+expression, i.e. every item that begins with a @code{#} sign.
+@item To separate all elements of a Scheme expression.
+@item In @code{lyricmode} to separate all the terms in both
+@code{\override} and @code{\set} commands. In particular, spaces
+must be used around the dot and the equals sign in commands like
+@code{\override Score . LyricText #'font-size = #5} and before and
+after the entire command.
+
+@end itemize
@seealso
Learning Manual:
@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}.
@node Text encoding
@subsection Text encoding
+@cindex Unicode
+@cindex UTF-8
+@cindex non-ASCII characters
+
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
LilyPond uses the Pango library to layout and render multi-lingual
texts.
-Lilypond does not perform any input-encoding conversions. This
+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
\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, 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
+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 @code{\char ##xhhhh} or @code{\char #dddd} within a
+@code{\markup} block, where @code{hhhh} is the hexadecimal code for
+the character required and @code{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 @emph{not} be used
+after @code{\char}, as UTF-8 encodings contain extra bits indicating
+the number of octets.)
+
+For example, @code{\char ##x03BE} and @code{\char #958} would both
+enter the Unicode U+03BE character, which has the Unicode name
+@qq{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 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:
+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:
@lilypond[quote,verbatim]
\score {
}
\addlyrics { O \markup { \concat{ Ph \char ##x0153 be! } } }
}
-\markup { "Copyright 2008" \char ##x00A9 }
+\markup { "Copyright 2008--2009" \char ##x00A9 }
@end lilypond
+@cindex copyright sign
+
To enter the copyright sign in the copyright notice use:
@example
of specifying the inital or overall MIDI tempo is described below,
see @ref{MIDI block}.
+Due to some limitations on Windows, the default extension for
+MIDI files on Windows is @code{.mid}. Other operating systems still
+use the extension @code{.midi}. If a different extension is preferred,
+insert the following line at the top-level of the input file,
+before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
+
+@example
+#(ly:set-option 'midi-extension "midi")
+@end example
+
+The line above will set the default extension for MIDI files to
+@code{.midi}.
+
+Alternatively, this option can also be supplied on the command line:
+
+@example
+lilypond … -dmidi-extension=midi lilyFile.ly
+@end example
+
+
@unnumberedsubsubsec Instrument names
@cindex instrument names
@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
@itemize
@item Pitches
-@item Quarter tones (See @ref{Accidentals}. Rendering needs a
+@item Microtones (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 Crescendi, decrescendi over a single note
@item Tremolos entered with @q{@code{:}[@var{number}]}
@item Figured bass
+@item Microtonal chords
@end itemize
\score {
\new Staff {
- \set Staff.midiInstrument = "cello"
+ \set Staff.midiInstrument = #"cello"
\set Score.dynamicAbsoluteVolumeFunction = #myDynamics
\new Voice {
\relative c'' {
projects / lilypond.git / blobdiff