-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely
@c A menu is needed before every deeper *section nesting of @node's; run
@node Global issues
@chapter Global issues
-This is a placeholder until I can write a nice intro for this chapter.
+This section deals with general lilypond issues, rather than
+specific notation.
@menu
-* Global layout::
+* Input files::
+* A single music expression::
+* Titles and headers::
+* Paper and pages::
+* Music layout::
+* Multiple movements::
+* MIDI output::
+@end menu
+
+
+@node Input files
+@section Input files
+
+The main format of input for LilyPond are text files. By convention,
+these files end with ``@code{.ly}''.
+
+@menu
+* File structure (introduction)::
* File structure::
-* Sound::
+* Including LilyPond files::
+* Text encoding::
@end menu
-@node Global layout
-@section Global layout
+@node File structure (introduction)
+@subsection File structure (introduction)
-The global layout is determined by three factors: the page layout, the
-line breaks, and the spacing. These all influence each other. The
-choice of spacing determines how densely each system of music is set.
-This influences where line breaks are chosen, and thus ultimately, how
-many pages a piece of music takes.
+A basic example of a lilypond input file is
-Globally spoken, this procedure happens in three steps: first,
-flexible distances (``springs'') are chosen, based on durations. All
-possible line breaking combinations are tried, and the one with the
-best results -- a layout that has uniform density and requires as
-little stretching or cramping as possible -- is chosen.
+@example
+\version "2.8.0"
+\score @{
+ @{ @} % this is a single music expression;
+ % all the music goes in here.
+ \header @{ @}
+ \layout @{ @}
+ \midi @{ @}
+@}
+@end example
-After spacing and linebreaking, the systems are distributed across
-pages, taking into account the size of the page, and the size of the
-titles.
+@noindent
+There are many variations of this basic pattern, but this
+example serves as a useful starting place.
+
+The major part of this manual is concerned with entering various
+forms of music in LilyPond. However, many music expressions are not
+valid input on their own, for example, a @code{.ly} file containing
+only a note
+@example
+c'4
+@end example
+
+@noindent
+will result in a parsing error. Instead, music should be inside other
+expressions, which may be put in a file by themselves. Such
+expressions are called toplevel expressions. The next section enumerates
+them all.
+
+
+@node File structure
+@subsection File structure
+
+A @code{.ly} file contains any number of toplevel expressions, where a
+toplevel expression is one of the following
+
+@itemize @bullet
+@item
+An output definition, such as @code{\paper}, @code{\midi}, and
+@code{\layout}. Such a definition at the toplevel changes the default
+settings for the block entered.
+
+@item
+A direct scheme expression, such as
+@code{#(set-default-paper-size "a7" 'landscape)} or
+@code{#(ly:set-option 'point-and-click #f)}.
+
+@item
+A @code{\header} block. This sets the global header block. This
+is the block containing the definitions for book-wide settings, like
+composer, title, etc.
+
+@item
+An @code{\addquote} statement. See @ref{Quoting other voices}
+for more information.
+
+@item
+A @code{\score} block. This score will be collected with other
+toplevel scores, and combined as a single @code{\book}.
+
+This behavior can be changed by setting the variable
+@code{toplevel-score-handler} at toplevel. The default handler is
+defined in the init file @file{scm/@/lily@/.scm}.
+
+The @code{\score} must begin with a music expression, and may
+contain only one music expression.
+
+@item
+A @code{\book} block logically combines multiple movements
+(i.e., multiple @code{\score} blocks) in one document. If there are
+a number of @code{\scores}, a single output file will be created
+in which all movements are concatenated.
+
+This behavior can be changed by setting the variable
+@code{toplevel-book-handler} at toplevel. The default handler is
+defined in the init file @file{scm/@/lily@/.scm}.
+
+@item
+A compound music expression, such as
+@example
+@{ c'4 d' e'2 @}
+@end example
+
+This will add the piece in a @code{\score} and format it in a
+single book together with all other toplevel @code{\score}s and music
+expressions. In other words, a file containing only the above
+music expression will be translated into
+
+@example
+\book @{
+ \score @{
+ \new Staff @{
+ \new Voice @{
+ @{ c'4 d' e'2 @}
+ @}
+ @}
+ @}
+ \layout @{ @}
+ \header @{ @}
+@}
+@end example
+
+This behavior can be changed by setting the variable
+@code{toplevel-music-handler} at toplevel. The default handler is
+defined in the init file @file{scm/@/lily@/.scm}.
+
+@item
+A markup text, a verse for example
+@example
+\markup @{
+ 2. The first line verse two.
+@}
+@end example
+
+Markup texts are rendered above, between or below the scores or music
+expressions, wherever they appear.
+
+@item
+An identifier, such as
+@example
+foo = @{ c4 d e d @}
+@end example
+
+This can be used later on in the file by entering @code{\foo}. The
+name of an identifier should have alphabetic characters only; no
+numbers, underscores or dashes.
+
+@end itemize
+
+The following example shows three things that may be entered at
+toplevel
+
+@example
+\layout @{
+ % movements are non-justified by default
+ ragged-right = ##t
+@}
+
+\header @{
+ title = "Do-re-mi"
+@}
+
+@{ c'4 d' e2 @}
+@end example
+
+
+At any point in a file, any of the following lexical instructions can
+be entered:
+
+@itemize @bullet
+@item @code{\version}
+@item @code{\include}
+@item @code{\renameinput}
+@end itemize
+
+
+@node Including LilyPond files
+@subsection Including LilyPond files
+
+@cindex @code{\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 "file.ly"} is equivalent to pasting the contents
+of file.ly into the current file at the place where you have the
+\include. For example, for 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.
+
+The initialization of LilyPond is done in a number of files that are
+included by default when you start the program, normally transparent to the
+user. Run lilypond --verbose to see a list of paths and files that Lily
+finds.
+
+Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
+VERSION is in the form ``2.6.1'') are on the path and available to
+@code{\include}. Files in the
+current working directory are available to \include, but a file of the same
+name in LilyPond's installation takes precedence. Files are
+available to \include from directories in the search path specified as an
+option when invoking @code{lilypond --include=DIR} which adds DIR to the search
+path.
+
+The @code{\include} statement can use full path information, but with the Unix
+convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
+if @file{stuff.ly} is located one directory higher than the current working
+directory, use
+
+@example
+\include "../stuff.ly"
+@end example
+
+
+@node Text encoding
+@subsection Text encoding
+
+LilyPond uses the Pango library to format multi-lingual texts, and
+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 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.
+
+Depending on the fonts installed, the following fragment shows Hebrew
+and Cyrillic lyrics,
+
+@cindex Cyrillic
+@cindex Hebrew
+@cindex ASCII, non
+
+@lilypondfile[fontload]{utf-8.ly}
+
+The @TeX{} backend does not handle encoding specially at all. Strings
+in the input are put in the output as-is. Extents of text items in the
+@TeX{} backend, are determined by reading a file created via the
+@file{texstr} backend,
+
+@example
+lilypond -b texstr input/les-nereides.ly
+latex les-nereides.texstr
+@end example
+
+The last command produces @file{les-nereides.textmetrics}, which is
+read when you execute
+
+@example
+lilypond -b tex input/les-nereides.ly
+@end example
+Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
+suitable LaTeX wrappers to load appropriate La@TeX{} packages for
+interpreting non-ASCII strings.
+
+To use a Unicode escape sequence, use
+
+@example
+#(ly:export (ly:wide-char->utf-8 #x2014))
+@end example
+
+
+@seealso
+
+@inputfileref{input/regression,utf-8.ly}
+
+
+
+@node A single music expression
+@section A single music expression
+
+A @code{\score} must contain a single music expression. However,
+this music expression may be of any size. Recall that music
+expressions may be included inside other expressions to form
+larger expressions. All of these examples are single music
+expressions; note the curly braces @{ @} or angle brackets <<
+>> at the beginning and ending of the music.
+
+@example
+@{ c'4 c' c' c' @}
+@end example
+
+@lilypond[ragged-right,verbatim,quote]
+{
+ { c'4 c' c' c'}
+ { d'4 d' d' d'}
+}
+@end lilypond
+
+@lilypond[ragged-right,verbatim,quote]
+<<
+ \new Staff { c'4 c' c' c' }
+ \new Staff { d'4 d' d' d' }
+>>
+@end lilypond
+
+@example
+@{
+ \new GrandStaff <<
+ \new StaffGroup <<
+ \new Staff @{ \flute @}
+ \new Staff @{ \oboe @}
+ >>
+ \new StaffGroup <<
+ \new Staff @{ \violinI @}
+ \new Staff @{ \violinII @}
+ >>
+ >>
+@}
+@end example
+
+
+@node Titles and headers
+@section Titles and headers
+
+Almost all printed music includes a title and the composer's name;
+some pieces include a lot more information.
@menu
-* Setting global staff size::
-* Paper size::
-* Page layout::
-* Vertical spacing::
-* Vertical spacing of piano staves::
-* Horizontal spacing::
-* Line length::
-* Line breaking::
-* Page breaking::
-* Multiple movements::
* Creating titles::
+* Custom titles::
@end menu
-@node Setting global staff size
-@subsection Setting global staff size
+@node Creating titles
+@subsection Creating titles
-@cindex font size, setting
-@cindex staff size, setting
-@cindex @code{layout} file
+Titles are created for each @code{\score} block, and over a
+@code{\book}.
-To set the global staff size, use @code{set-global-staff-size}.
+The contents of the titles are taken from the @code{\header} blocks.
+The header block for a book supports the following
+@table @code
+@item dedication
+The dedicatee of the music, centered at the top of the first page.
-@example
-#(set-global-staff-size 14)
+@item title
+The title of the music, centered just below the dedication.
+
+@item subtitle
+Subtitle, centered below the title.
+
+@item subsubtitle
+Subsubtitle, centered below the subtitle.
+
+@item poet
+Name of the poet, flush-left below the subtitle.
+
+@item composer
+Name of the composer, flush-right below the subtitle.
+
+@item meter
+Meter string, flush-left below the poet.
+
+@item opus
+Name of the opus, flush-right below the composer.
+
+@item arranger
+Name of the arranger, flush-right below the opus.
+
+@item instrument
+Name of the instrument, centered below the arranger. Also
+centered at the top of pages (other than the first page).
+
+@item piece
+Name of the piece, flush-left below the instrument.
+
+@cindex page breaks, forcing
+@item breakbefore
+This forces the title to start on a new page (set to ##t or ##f).
+
+@item copyright
+Copyright notice, centered at the bottom of the first page. To
+insert the copyright symbol, see @ref{Text encoding}.
+
+@item tagline
+Centered at the bottom of the last page.
+
+@end table
+
+Here is a demonstration of the fields available. Note that you
+may use any @ref{Text markup} commands in the header.
+
+@lilypond[quote,verbatim,line-width=11.0\cm]
+\paper {
+ line-width = 9.0\cm
+ paper-height = 10.0\cm
+}
+
+\book {
+ \header {
+ dedication = "dedicated to me"
+ title = \markup \center-align { "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)" }
+ texttranslator = "Text Translator"
+ meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge "r" }
+ arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
+ instrument = \markup \bold \italic "instrument"
+ piece = "Piece"
+ }
+
+ \score {
+ { c'1 }
+ \header {
+ piece = "piece1"
+ opus = "opus1"
+ }
+ }
+ \markup {
+ and now...
+ }
+ \score {
+ { c'1 }
+ \header {
+ piece = "piece2"
+ opus = "opus2"
+ }
+ }
+}
+@end lilypond
+
+As demonstrated before, you can use multiple @code{\header} blocks.
+When same fields appear in different blocks, the latter is used.
+Here is a short example.
+
+@example
+\header @{
+ composer = "Composer"
+@}
+\header @{
+ piece = "Piece"
+@}
+\score @{
+ \new Staff @{ c'4 @}
+ \header @{
+ piece = "New piece" % overwrite previous one
+ @}
+@}
@end example
+If you define the @code{\header} inside the @code{\score} block, then
+normally only the @code{piece} and @code{opus} headers will be printed.
+Note that the music expression must come before the @code{\header}.
+
+@lilypond[quote,verbatim,line-width=11.0\cm]
+\score {
+ { c'4 }
+ \header {
+ title = "title" % not printed
+ piece = "piece"
+ opus = "opus"
+ }
+}
+@end lilypond
+
+@cindex @code{printallheaders}
@noindent
-This sets the global default size to 14pt staff height and scales all
-fonts accordingly.
+You may change this behavior (and print all the headers when defining
+@code{\header} inside @code{\score}) by using
-The Feta font provides musical symbols at eight different
-sizes. Each font is tuned for a different staff size: at a smaller size
-the font becomes heavier, to match the relatively heavier staff lines.
-The recommended font sizes are listed in the following table:
+@example
+\paper@{
+ printallheaders=##t
+@}
+@end example
+
+
+@node Custom titles
+@subsection Custom titles
+
+A more advanced option is to change the definitions of the following
+variables in the @code{\paper} block. The init file
+@file{ly/titling-init.ly} lists the default layout.
+
+@table @code
+@cindex @code{bookTitleMarkup}
+@item bookTitleMarkup
+ This is the title put over an entire @code{\book} block. Typically,
+ it has the composer and the title of the piece
+
+@cindex @code{scoreTitleMarkup}
+@item scoreTitleMarkup
+ This is the title put over a @code{\score} block within a
+@code{\book}. Typically, it has the name of the movement (@code{piece}
+field).
+
+@cindex @code{oddHeaderMarkup}
+@item oddHeaderMarkup
+ This is the page header for odd-numbered pages.
+
+@cindex @code{evenHeaderMarkup}
+@item evenHeaderMarkup
+ This is the page header for even-numbered pages. If unspecified,
+ the odd header is used instead.
-@quotation
-@multitable @columnfractions .15 .2 .22 .2
+ By default, headers are defined such that the page number is on the
+ outside edge, and the instrument is centered.
-@item @b{font name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
+@cindex @code{oddFooterMarkup}
+@item oddFooterMarkup
+ This is the page footer for odd-numbered pages.
+
+@cindex @code{evenFotterMarkup}
+@item evenFooterMarkup
+ This is the page footer for even-numbered pages. If unspecified,
+ the odd header is used instead.
-@item feta11
-@tab 11.22
-@tab 3.9
-@tab pocket scores
+ By default, the footer has the copyright notice on the first, and
+ the tagline on the last page.
+@end table
-@item feta13
-@tab 12.60
-@tab 4.4
-@tab
-
-@item feta14
-@tab 14.14
-@tab 5.0
-@tab
-@item feta16
-@tab 15.87
-@tab 5.6
-@tab
+@cindex \paper
+@cindex header
+@cindex footer
+@cindex page layout
+@cindex titles
-@item feta18
-@tab 17.82
-@tab 6.3
-@tab song books
+The following definition will put the title flush left, and the
+composer flush right on a single line.
-@item feta20
-@tab 20
-@tab 7.0
-@tab standard parts
+@verbatim
+\paper {
+ bookTitleMarkup = \markup {
+ \fill-line {
+ \fromproperty #'header:title
+ \fromproperty #'header:composer
+ }
+ }
+}
+@end verbatim
-@item feta23
-@tab 22.45
-@tab 7.9
-@tab
-@item feta26
-@tab 25.2
-@tab 8.9
-@tab
-@c modern rental material?
+@refbugs
-@end multitable
-@end quotation
+The @code{breakbefore=##t} header requires that there is a @code{piece} header as well. It may be used as a normal header, or left blank (@code{=""}) as in the example above, but it must be present.
-These fonts are available in any sizes. The context property
-@code{fontSize} and the layout property @code{staff-space} (in
-@internalsref{StaffSymbol}) can be used to tune the size for individual
-staves. The sizes of individual staves are relative to the global size.
-@example
-@end example
+@node Paper and pages
+@section Paper and pages
-@seealso
+This section deals with the display of music on physical paper.
-This manual: @ref{Selecting font sizes}.
+@menu
+* Paper size::
+* Page formatting::
+@end menu
@node Paper size
@cindex page size
@cindex @code{papersize}
-To change the paper size, there are two equal commands,
+To change the paper size, there are two commands,
@example
#(set-default-paper-size "a4")
\paper @{
The first command sets the size of all pages. The second command sets the size
of the pages that the @code{\paper} block applies to -- if the @code{\paper}
block is at the top of the file, then it will apply to all pages. If the
-@code{\paper} block is inside a @code{\score}, then the paper size will only
-apply to that score.
+@code{\paper} block is inside a @code{\book}, then the paper size will only
+apply to that book.
-The following paper sizes are supported: @code{a6}, @code{a5}, @code{a4},
-@code{a3}, @code{legal}, @code{letter}, @code{tabloid}.
+Support for the following paper sizes are included by default,
+@code{a6}, @code{a5}, @code{a4}, @code{a3}, @code{legal}, @code{letter},
+@code{11x17} (also known as tabloid).
+
+Extra sizes may be added by editing the definition for
+@code{paper-alist} in the initialization file @file{scm/paper.scm}.
@cindex orientation
@cindex landscape
#(set-default-paper-size "a6" 'landscape)
@end example
+Setting the paper size will adjust a number of @code{\paper} variables
+(such as margins). To use a particular paper size with altered
+@code{\paper} variables, set the paper size before setting the variables.
-@node Page layout
-@subsection Page layout
-@cindex page layout
+@node Page formatting
+@subsection Page formatting
+
+@cindex page formatting
@cindex margins
@cindex header, page
@cindex footer, page
The default layout responds to the following settings in the
@code{\paper} block.
-@cindex \paper
+@cindex @code{\paper}
@quotation
@table @code
-@item firstpagenumber
+@cindex @code{first-page-number}
+@item first-page-number
The value of the page number of the first page. Default is@tie{}1.
-@item printfirstpagenumber
+@cindex @code{printfirst-page-number}
+@item printfirst-page-number
If set to true, will print the page number in the first page. Default is
false.
-@item hsize
+@cindex @code{print-page-number}
+@item print-page-number
+If set to false, page numbers will not be printed.
+
+@cindex @code{paper-width}
+@item paper-width
The width of the page.
-@item vsize
+@cindex @code{paper-height}
+@item paper-height
The height of the page.
-@item topmargin
+@cindex @code{top-margin}
+@item top-margin
Margin between header and top of the page.
-@item bottommargin
+@cindex @code{bottom-margin}
+@item bottom-margin
Margin between footer and bottom of the page.
-@item leftmargin
+@cindex @code{left-margin}
+@item left-margin
Margin between the left side of the page and the beginning of the music.
-@item linewidth
+@cindex @code{line-width}
+@item line-width
The length of the systems.
-@item headsep
+@cindex @code{head-separation}
+@item head-separation
Distance between the top-most music system and the page header.
-@item footsep
+@cindex @code{foot-separation}
+@item foot-separation
Distance between the bottom-most music system and the page footer.
-@item raggedbottom
-If set to true, systems will not be spread across the page.
+@cindex @code{page-top-space}
+Distance from the top of the printable area to the center of the first
+staff. This only works for staves which are vertically small. Big staves
+are set with the top of their bounding box aligned to the top of the
+printable area.
+
+@cindex @code{ragged-bottom}
+@item ragged-bottom
+If set to true, systems will not be spread vertically across the page. This
+does not affect the last page.
-This should be set false for pieces that have only two or three
+This should be set to true for pieces that have only two or three
systems per page, for example orchestral scores.
-@item raggedlastbottom
-If set to false, systems will be spread to fill the last page.
+@cindex @code{ragged-last-bottom}
+@item ragged-last-bottom
+If set to false, systems will be spread vertically to fill the last page.
Pieces that amply fill two pages or more should have this set to
true.
-@item betweensystemspace
+@cindex @code{system-count}
+@item system-count
+This variable, if set, specifies into how many lines a score should be
+broken.
+
+@cindex @code{between-system-space}
+@item between-system-space
This dimensions determines the distance between systems. It is the
ideal distance between the center of the bottom staff of one system
and the center of the top staff of the next system.
Increasing this will provide a more even appearance of the page at the
cost of using more vertical space.
-@item betweensystempadding
+@cindex @code{between-system-padding}
+@item between-system-padding
This dimension is the minimum amount of white space that will always
be present between the bottom-most symbol of one system, and the
top-most of the next system.
Increasing this will put systems whose bounding boxes almost touch
farther apart.
-@item aftertitlespace
+
+@cindex @code{horizontal-shift}
+@item horizontal-shift
+All systems (including titles and system separators) are shifted by
+this amount to the right. Page markup, such as headers and footers are
+not affected by this. The purpose of this variable is to make space
+for instrument names at the left.
+
+@cindex @code{after-title-space}
+@item after-title-space
Amount of space between the title and the first system.
-@item beforetitlespace
+@cindex @code{after-title-space}
+@item before-title-space
Amount of space between the last system of the previous piece and the
title of the next.
-@item betweentitlespace
+@cindex @code{between-title-space}
+@item between-title-space
Amount of space between consecutive titles (e.g., the title of the
book and the title of a piece).
+@cindex @code{printallheaders}
+@item printallheaders
+Setting this to #t will print all headers for each \score in a
+\book. Normally only the piece and opus \headers are printed.
+
+@cindex @code{systemSeparatorMarkup}
@item systemSeparatorMarkup
This contains a markup object, which will be inserted between
systems. This is often used for orchestral scores.
The markup command @code{\slashSeparator} is provided as a sensible
default, for example
-@lilypond[raggedright]
-\paper {
- systemSeparatorMarkup = \slashSeparator
+@lilypond[ragged-right]
+\book {
+ \score {
+ \relative { c1 \break c1 }
+ }
+ \paper {
+ systemSeparatorMarkup = \slashSeparator
+ }
}
-
-\relative { c1 \break c1 }
@end lilypond
@example
\paper@{
- hsize = 2\cm
- topmargin = 3\cm
- bottommargin = 3\cm
- raggedlastbottom = ##t
+ paper-width = 2\cm
+ top-margin = 3\cm
+ bottom-margin = 3\cm
+ ragged-last-bottom = ##t
@}
@end example
@example
\paper @{
- #(define bottommargin (* 2 cm))
+ #(define bottom-margin (* 2 cm))
@}
@end example
@refbugs
-The option rightmargin is defined but doesn't set the right margin
+The option right-margin is defined but doesn't set the right margin
yet. The value for the right margin has to be defined adjusting the
-values of the leftmargin and linewidth.
+values of @code{left-margin} and @code{line-width}.
The default page header puts the page number and the @code{instrument}
field from the @code{\header} block on a line.
+
+@node Music layout
+@section Music layout
+
+This section deals with the manner in which the music is printed
+within the boundaries defined by the @code{\paper} block.
+
+The global paper layout is determined by three factors: the page layout, the
+line breaks, and the spacing. These all influence each other. The
+choice of spacing determines how densely each system of music is set.
+This influences where line breaks are chosen, and thus ultimately, how
+many pages a piece of music takes.
+
+Globally spoken, this procedure happens in three steps: first,
+flexible distances (``springs'') are chosen, based on durations. All
+possible line breaking combinations are tried, and the one with the
+best results -- a layout that has uniform density and requires as
+little stretching or cramping as possible -- is chosen.
+
+After spacing and linebreaking, the systems are distributed across
+pages, taking into account the size of the page, and the size of the
+titles.
+
+@menu
+* Setting global staff size::
+* Selecting notation font size::
+* Score layout::
+* Vertical spacing::
+* Vertical spacing of piano staves::
+* Horizontal spacing::
+* Line length::
+* Line breaking::
+* Page breaking::
+@end menu
+
+
+@node Setting global staff size
+@subsection Setting global staff size
+
+@cindex font size, setting
+@cindex staff size, setting
+@cindex @code{layout} file
+
+To set the global staff size, use @code{set-global-staff-size}.
+
+@example
+#(set-global-staff-size 14)
+@end example
+
+@noindent
+This sets the global default size to 14pt staff height and scales all
+fonts accordingly.
+
+The Feta font provides musical symbols at eight different
+sizes. Each font is tuned for a different staff size: at a smaller size
+the font becomes heavier, to match the relatively heavier staff lines.
+The recommended font sizes are listed in the following table:
+
+@quotation
+@multitable @columnfractions .15 .2 .22 .2
+
+@item @b{font name}
+@tab @b{staff height (pt)}
+@tab @b{staff height (mm)}
+@tab @b{use}
+
+@item feta11
+@tab 11.22
+@tab 3.9
+@tab pocket scores
+
+@item feta13
+@tab 12.60
+@tab 4.4
+@tab
+
+@item feta14
+@tab 14.14
+@tab 5.0
+@tab
+
+@item feta16
+@tab 15.87
+@tab 5.6
+@tab
+
+@item feta18
+@tab 17.82
+@tab 6.3
+@tab song books
+
+@item feta20
+@tab 20
+@tab 7.0
+@tab standard parts
+
+@item feta23
+@tab 22.45
+@tab 7.9
+@tab
+
+@item feta26
+@tab 25.2
+@tab 8.9
+@tab
+@c modern rental material?
+
+@end multitable
+@end quotation
+
+These fonts are available in any sizes. The context property
+@code{fontSize} and the layout property @code{staff-space} (in
+@internalsref{StaffSymbol}) can be used to tune the size for individual
+staves. The sizes of individual staves are relative to the global size.
+
+@example
+
+@end example
+
+@seealso
+
+This manual: @ref{Selecting notation font size}.
+
+
+@node Selecting notation font size
+@subsection Selecting notation font size
+
+The easiest method of setting the font size of any context, is by
+setting the @code{fontSize} property.
+
+@lilypond[quote,fragment,relative=1,verbatim]
+c8
+\set fontSize = #-4
+c f
+\set fontSize = #3
+g
+@end lilypond
+
+@noindent
+It does not change the size of variable symbols, such as beams or
+slurs.
+
+Internally, the @code{fontSize} context property will cause the
+@code{font-size} property to be set in all layout objects. The value
+of @code{font-size} is a number indicating the size relative to the
+standard size for the current staff height. Each step up is an
+increase of approximately 12% of the font size. Six steps is exactly a
+factor two. The Scheme function @code{magstep} converts a
+@code{font-size} number to a scaling factor.
+
+@lilypond[quote,fragment,relative=1,verbatim]
+c8
+\override NoteHead #'font-size = #-4
+c f
+\override NoteHead #'font-size = #3
+g
+@end lilypond
+
+LilyPond has fonts in different design sizes. The music fonts for
+smaller sizes are chubbier, while the text fonts are relatively wider.
+Font size changes are achieved by scaling the design size that is
+closest to the desired size. The standard font size (for
+@code{font-size} equals 0), depends on the standard staff height. For
+a 20pt staff, a 10pt font is selected.
+
+The @code{font-size} property can only be set on layout objects that
+use fonts. These are the ones supporting the
+@internalsref{font-interface} layout interface.
+
+@refcommands
+
+The following commands set @code{fontSize} for the current voice:
+
+@cindex @code{\tiny}
+@code{\tiny},
+@cindex @code{\small}
+@code{\small},
+@cindex @code{\normalsize}
+@code{\normalsize}.
+
+
+@node Score layout
+@subsection Score layout
+
+@cindex @code{\layout}
+
+While @code{\paper} contains settings that relate to the page formatting
+of the whole document, @code{\layout} contains settings for score-specific
+layout.
+
+@example
+\layout @{
+ indent = 2.0\cm
+ \context @{ \Staff
+ \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6)
+ @}
+ \context @{ \Voice
+ \override TextScript #'padding = #1.0
+ \override Glissando #'thickness = #3
+ @}
+@}
+@end example
+
+
+@seealso
+
+This manual: @ref{Changing context default settings}
+
+
@node Vertical spacing
@subsection Vertical spacing
Normally staves are stacked vertically. To make staves maintain a
distance, their vertical size is padded. This is done with the
-property @code{minimumVerticalExtent}. It takes a pair of numbers, so
-if you want to make it smaller than its default @code{#'(-4 . 4)},
+property @code{minimum-Y-extent}. When applied to a
+@internalsref{VerticalAxisGroup}, it controls the size of a horizontal
+line, such as a staff or a line of lyrics. @code{minimum-Y-extent}
+takes a pair of numbers, so
+if you want to make it smaller than its default @code{#'(-4 . 4)}
then you could set
@example
-\set Staff.minimumVerticalExtent = #'(-3 . 3)
+\override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
@end example
@noindent
This sets the vertical size of the current staff to 3 staff spaces on
-either side of the center staff line. The argument of
-@code{minimumVerticalExtent} is interpreted as an interval, where the
-center line is the 0, so the first number is generally negative. The
-staff can be made larger at the bottom by setting it to @code{(-6 . 4)}.
+either side of the center staff line. The value @code{(-3 . 3)} is
+interpreted as an interval, where the center line is the 0, so the
+first number is generally negative. The staff can be made larger at
+the bottom by setting it to @code{(-6 . 4)}.
+
+The spacing of staves in a system may also be tuned per system. This is
+done with the command
+
+@example
+\overrideProperty
+#"Score.NonMusicalPaperColumn"
+#'line-break-system-details
+#'((alignment-extra-space . 15))
+@end example
+
+@noindent
+at the line break before the system to be changed. The distance
+@code{15} is distributed over all staves that have a fixed distance
+alignment. For example,
+
+@lilypond[ragged-right, fragment, relative=2, staffsize=13]
+\new StaffGroup <<
+ \new Staff {
+ c1\break
+
+ \overrideProperty
+ #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details
+ #'((fixed-alignment-extra-space . 15))
+
+ c\break
+ }
+ \new Staff { c c }
+>>
+@end lilypond
+
+The distance for @code{alignment-extra-space} may also be negative.
+
+
+To change the amount of space between systems, use
+@code{between-system-space}. A score with only one staff is still
+considered to have systems, so setting @code{between-system-space} will
+be much more useful than changing @code{minimum-Y-extent} of a Staff
+context.
+
+@example
+\paper @{
+ between-system-space = 10\mm
+@}
+@end example
-To change the amount of space between systems, use
-@code{betweensystemspace}. A score with only one staff is still
-considered to have systems, so setting @code{betweensystemspace}
-will be much more useful than changing @code{minimumVerticalExtent}.
+If you simply want to tell LilyPond ``fit as much as possible onto
+these pages, then expand to fill any available space on the pages,''
+then use the following
@example
-\layout @{
- betweensystemspace = 10\mm
+\paper @{
+ between-system-padding = #1
+ ragged-bottom=##f
+ ragged-last-bottom=##f
@}
@end example
+@c let's wait for a some comments before writing more.
+
+The vertical spacing on a page can also be changed for each system individually.
+Some examples are found in the example file
+@inputfileref{input/regression/,page-spacing.ly}.
+
+When setting @code{annotatespacing} in the @code{\paper} block LilyPond
+will graphically indicate the dimensions of properties that may be set
+for page spacing,
+
+@lilypond[verbatim]
+#(set-default-paper-size "a7" 'landscape)
+\paper { annotatespacing = ##t }
+{ c4 }
+@end lilypond
+
+@noindent
+All units dimensions are measured in staff spaces. The pairs
+(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
+@var{b} the upper edge of the interval.
+
@seealso
Internals: Vertical alignment of staves is handled by the
-@internalsref{VerticalAlignment} object.
+@internalsref{VerticalAlignment} object. The context parameters
+specifying the vertical extent are described in connection with
+the @internalsref{Axis_group_engraver}.
-@refbugs
-
-@code{minimumVerticalExtent} is syntactic sugar for setting
-@code{minimum-Y-extent} of the @internalsref{VerticalAxisGroup} of the
-current context. It can only be changed score wide.
+Example files: @inputfileref{input/regression/,page-spacing.ly},
+@inputfileref{input/regression/,alignment-vertical-spacing.ly}.
The difference is demonstrated in the following example,
@lilypond[quote,verbatim]
-\relative <<
+\relative c'' <<
\new PianoStaff \with {
\override VerticalAlignment #'forced-distance = #7
} <<
@end lilypond
+It is also possible to change the distance between for each system
+individually. This is done by including the command
-@refbugs
+@example
+\overrideProperty
+#"Score.NonMusicalPaperColumn"
+#'line-break-system-details
+#'((fixed-alignment-extra-space . 15))
+@end example
+
+@noindent
+at the line break before the system to be changed. The distance
+@code{15} is distributed over all staves that have a fixed distance
+alignment. For example,
+
+@lilypond[ragged-right, fragment, relative=2, staffsize=13]
+\new PianoStaff <<
+ \new Staff {
+ c1\break
+
+ \overrideProperty
+ #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details
+ #'((fixed-alignment-extra-space . 15))
+
+ c\break
+ }
+ \new Staff { c c }
+>>
+@end lilypond
+
+The distance for @code{fixed-alignment-extra-space} may also be
+negative.
-@code{forced-distance} cannot be changed per system.
+@seealso
+Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}.
@node Horizontal spacing
@subsection Horizontal Spacing
-The spacing engine translates differences in durations into
-stretchable distances (``springs'') of differring lengths. Longer
-durations get more space, shorter durations get less. The shortest
-durations get a fixed amount of space (which is controlled by
-@code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
-The longer the duration, the more space it gets: doubling a
+The spacing engine translates differences in durations into stretchable
+distances (``springs'') of differring lengths. Longer durations get
+more space, shorter durations get less. The shortest durations get a
+fixed amount of space (which is controlled by
+@code{shortest-duration-space} in the @internalsref{SpacingSpanner}
+object). The longer the duration, the more space it gets: doubling a
duration adds a fixed amount (this amount is controlled by
@code{spacing-increment}) of space to the note.
these corrections, once with default settings, and once with
exaggerated corrections:
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
{
c'4 e''4 e'4 b'4 |
b'4 e''4 b'4 e''4|
}
@end lilypond
+Proportional notation is supported; see @ref{Proportional notation}.
+
+By default, spacing in tuplets depends on various non-duration
+factors (such as accidentals, clef changes, etc). To disregard
+such symbols and force uniform equal-duration spacing, use
+@code{Score.SpacingSpanner #'uniform-stretching}. This
+property can only be changed at the beginning of a score,
+
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+\new Score \with {
+ \override SpacingSpanner #'uniform-stretching = ##t
+} <<
+ \new Staff{
+ \times 4/5 {
+ c8 c8 c8 c8 c8
+ }
+ c8 c8 c8 c8
+ }
+ \new Staff{
+ c8 c8 c8 c8
+ \times 4/5 {
+ c8 c8 c8 c8 c8
+ }
+ }
+>>
+@end lilypond
+
+
+When @code{strict-note-spacing} is set, notes are spaced without
+regard for clefs, bar lines, and grace notes,
+
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+\override Score.SpacingSpanner #'strict-note-spacing = ##t
+\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] }
+@end lilypond
+
@seealso
No work-around exists for decreasing the amount of space.
+
@node Line length
@subsection Line length
@cindex breaking pages
@cindex @code{indent}
-@cindex @code{linewidth}
+@cindex @code{line-width}
+@cindex @code{ragged-right}
+@cindex @code{ragged-last}
-@c Although linewidth can be set in \layout, it should be set in paper
+@c Although line-width can be set in \layout, it should be set in paper
@c block, to get page layout right.
@c Setting indent in \paper block makes not much sense, but it works.
@c Bit verbose and vague, use examples?
The most basic settings influencing the spacing are @code{indent} and
-@code{linewidth}. They are set in the @code{\layout} block. They
+@code{line-width}. They are set in the @code{\layout} block. They
control the indentation of the first line of music, and the lengths of
the lines.
-If @code{raggedright} is set to true in the @code{\layout} block, then
-the lines are justified at their natural length. This is useful for
+If @code{ragged-right} is set to true in the @code{\layout} block, then
+systems ends at their natural horizontal length, instead of being spread
+horizontally to fill the whole line. This is useful for
short fragments, and for checking how tight the natural spacing is.
@cindex page layout
@cindex vertical spacing
-The option @code{raggedlast} is similar to @code{raggedright}, but
+The option @code{ragged-last} is similar to @code{ragged-right}, but
only affects the last line of the piece. No restrictions are put on
that line. The result is similar to formatting text paragraphs. In a
-paragraph, the last line simply takes its natural length.
+paragraph, the last line simply takes its natural horizontal length.
@c Note that for text there are several options for the last line.
@c While Knuth TeX uses natural length, lead typesetters use the same
@c stretch as the previous line. eTeX uses \lastlinefit to
@c interpolate between both these solutions.
-@node Line breaking
-@subsection Line breaking
-
-@cindex line breaks
-@cindex breaking lines
-
-Line breaks are normally computed automatically. They are chosen so
-that lines look neither cramped nor loose, and that consecutive lines
-have similar density.
-
-Occasionally you might want to override the automatic breaks; you can
-do this by specifying @code{\break}. This will force a line break at
-this point. Line breaks can only occur at places where there are bar
-lines. If you want to have a line break where there is no bar line,
-you can force an invisible bar line by entering @code{\bar
-""}. Similarly, @code{\noBreak} forbids a line break at a
-point.
-
-
-@cindex regular line breaks
-@cindex four bar music.
-
-For line breaks at regular intervals use @code{\break} separated by
-skips and repeated with @code{\repeat}:
-@example
-<< \repeat unfold 7 @{
- s1 \noBreak s1 \noBreak
- s1 \noBreak s1 \break @}
- @emph{the real music}
->>
-@end example
-
-@noindent
-This makes the following 28 measures (assuming 4/4 time) be broken every
-4 measures, and only there.
-
-@refcommands
-
-@code{\break}, and @code{\noBreak}.
-@cindex @code{\break}
-@cindex @code{\noBreak}
-
-@seealso
-
-Internals: @internalsref{BreakEvent}.
-
-
-@node Page breaking
-@subsection Page breaking
-
-The default page breaking may be overriden by inserting
-@code{\pageBreak} or @code{\noPageBreak} commands. These commands are
-analogous to @code{\break} and @code{\noBreak}. They should be
-inserted at a bar line. These commands force and forbid a page-break
-from happening. Of course, the @code{\pageBreak} command also forces
-a line break.
-
-Page breaks are computed by the @code{page-breaking} function in the
-@code{\paper} block.
-
-To force a new page for a new piece (in a collection of pieces or a
-piece in several movements), use @code{breakbefore} in the header.
-
-@example
-\header@{
- breakbefore = ##t
-@}
-@end example
-
-@refcommands
-
-@cindex @code{\pageBreak}
-@code{\pageBreak}
-@cindex @code{\noPageBreak}
-@code{\noPageBreak}
-
-
-@node Multiple movements
-@subsection Multiple movements
-
-@cindex bibliographic information
-@cindex titles
-@cindex composer
-@cindex Music engraiving by LilyPond
-
-A document may contain multiple pieces of music and texts. Examples
-of these are an etude book, or an orchestral part with multiple
-movements. Each movement is entered with a @code{\score} block,
-
-@example
-\score @{
- @var{..music..}
-@}
-@end example
-
-and texts are entered with a @code{\markup} block,
-
-@example
-\markup @{
- @var{..text..}
-@}
-@end example
-
-The movements and texts are combined together in a @code{\book} block,
-like
-
@example
-\book @{
- \score @{
- @var{..}
- @}
- \markup @{
- @var{..}
- @}
- \score @{
- @var{..}
- @}
-@}
-@end example
-
-
-The header for each piece of music can be put inside the @code{\score}
-block. The @code{piece} name from the header will be printed before
-each movement. The title for the entire book can be put inside the
-@code{\book}, but if it is not present, the @code{\header} which is at
-the top of the file is inserted.
-
-@cindex Engraved by LilyPond
-@cindex signature line
-
-@example
-\book @{
- \header @{
- title = "Eight miniatures"
- composer = "Igor Stravinsky"
- @}
- \score @{
- @dots{}
- \header @{ piece = "Romanze" @}
- @}
- \markup @{
- ..text of second verse..
- @}
- \markup @{
- ..text of third verse..
- @}
- \score @{
- @dots{}
- \header @{ piece = "Menuetto" @}
- @}
+\layout @{
+ indent = #0
+ line-width = #150
+ ragged-last = ##t
@}
@end example
-@node Creating titles
-@subsection Creating titles
-
-Titles are created for each @code{\score} block, and over a
-@code{\book}.
-
-The contents of the titles are taken from the @code{\header} blocks.
-The header block for a book supports the following
-@table @code
-@item title
-The title of the music. Centered on top of the first page.
-
-@item subtitle
-Subtitle, centered below the title.
-
-@item subsubtitle
-Subsubtitle, centered below the subtitle.
-
-@item poet
-Name of the poet, flush-left below the subtitle.
-
-@item composer
-Name of the composer, flush-right below the subtitle.
-
-@item meter
-Meter string, flush-left below the poet.
-
-@item opus
-Name of the opus, flush-right below the composer.
-
-@item arranger
-Name of the arranger, flush-right below the opus.
-
-@item instrument
-Name of the instrument, centered below the arranger.
-
-@item dedication
-To whom the piece is dedicated.
-
-@item piece
-Name of the piece, flush-left below the instrument.
-
-@cindex page breaks, forcing
-@item breakbefore
- This forces the title to start on a new page (set to ##t or ##f).
-@end table
-
-Here is a demonstration of the fields available,
-
-@lilypond[quote,verbatim,linewidth=11.0\cm]
-\paper {
- linewidth = 9.0\cm
- vsize = 10.0\cm
-}
-
-\book {
- \header {
- title = "Title,"
- subtitle = "the subtitle,"
- subsubtitle = "and the sub sub title"
- poet = "Poet"
- composer = "Composer"
- texttranslator = "Text Translator"
- meter = "Meter"
- arranger = "Arranger"
- instrument = "Instrument"
- piece = "Piece"
- }
-
- \score {
- \header {
- piece = "piece1"
- opus = "opus1"
- }
- { c'1 }
- }
- \markup {
- and now...
- }
- \score {
- \header {
- piece = "piece2"
- opus = "opus2"
- }
- { c'1 }
- }
-}
-@end lilypond
+@node Line breaking
+@subsection Line breaking
+
+@cindex line breaks
+@cindex breaking lines
+
+Line breaks are normally computed automatically. They are chosen so
+that lines look neither cramped nor loose, and that consecutive lines
+have similar density.
+
+Occasionally you might want to override the automatic breaks; you can
+do this by specifying @code{\break}. This will force a line break at
+this point. Line breaks can only occur at places where there are bar
+lines. If you want to have a line break where there is no bar line,
+you can force an invisible bar line by entering @code{\bar
+""}. Similarly, @code{\noBreak} forbids a line break at a
+point.
-Different fonts may be selected for each element by using
-@code{\markup}, e.g.,
+@cindex regular line breaks
+@cindex four bar music.
+
+For line breaks at regular intervals use @code{\break} separated by
+skips and repeated with @code{\repeat}:
@example
-\header @{
- title = \markup @{ \italic @{ The italic title @} @}
-@}
+<< \repeat unfold 7 @{
+ s1 \noBreak s1 \noBreak
+ s1 \noBreak s1 \break @}
+ @emph{the real music}
+>>
@end example
-A more advanced option is to change the definitions of the following
-variables in the @code{\paper} block. The init file
-@file{ly/titling-init.ly} lists the default layout.
+@noindent
+This makes the following 28 measures (assuming 4/4 time) be broken every
+4 measures, and only there.
-@table @code
-@item bookTitleMarkup
- This is the title put over an entire @code{\book} block. Typically,
- it has the composer and the title of the piece
-
-@item scoreTitleMarkup
- This is the title put over a @code{\score} block within a
-@code{\book}. Typically, it has the name of the movement (@code{piece}
-field).
+@refcommands
-@item oddHeaderMarkup
- This is the page header for odd-numbered pages.
+@code{\break}, and @code{\noBreak}.
+@cindex @code{\break}
+@cindex @code{\noBreak}
- @item evenHeaderMarkup
- This is the page header for even-numbered pages. If unspecified,
- the odd header is used instead.
+@seealso
- By default, headers are defined such that the page number is on the
- outside edge, and the instrument is centered.
+Internals: @internalsref{BreakEvent}.
-@item oddFooterMarkup
- This is the page footer for odd-numbered pages.
-
-@item evenFooterMarkup
- This is the page footer for even-numbered pages. If unspecified,
- the odd header is used instead.
+A linebreaking configuration can now be saved as a @code{.ly} file
+automatically. This allows vertical alignments to be stretched to
+fit pages in a second formatting run. This is fairly new and
+complicated; see @inputfileref{input/regression/,page-layout-twopass.ly}
+for details.
- By default, the footer has the copyright notice on the first, and
- the tagline on the last page.
-@end table
+@refbugs
+Line breaks can only occur if there is a ``proper'' bar line. A note
+which is hanging over a bar line is not proper, such as
-@cindex \paper
-@cindex header
-@cindex footer
-@cindex page layout
-@cindex titles
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+c4 c2 c2 \break % this does nothing
+c2 c4 | % a break here would work
+c4 c2 c4 ~ \break % as does this break
+c4 c2 c4
+@end lilypond
-The following definition will put the title flush left, and the
-composer flush right on a single line.
-@verbatim
-\paper {
- bookTitleMarkup = \markup {
- \fill-line @{
- \fromproperty #'header:title
- \fromproperty #'header:composer
- @}
- }
-}
-@end verbatim
+@node Page breaking
+@subsection Page breaking
+The default page breaking may be overriden by inserting
+@code{\pageBreak} or @code{\noPageBreak} commands. These commands are
+analogous to @code{\break} and @code{\noBreak}. They should be
+inserted at a bar line. These commands force and forbid a page-break
+from happening. Of course, the @code{\pageBreak} command also forces
+a line break.
+Page breaks are computed by the @code{page-breaking} function in the
+@code{\paper} block.
-@node File structure
-@section File structure
+To force a new page for a new piece (in a collection of pieces or a
+piece in several movements), use @code{breakbefore} in the header.
-The major part of this manual is concerned with entering various
-forms of music in LilyPond. However, many music expressions are not
-valid input on their own, for example, a @code{.ly} file containing
-only a note
@example
-c'4
+\header@{
+ breakbefore = ##t
+ piece = ""
+@}
@end example
-@noindent
-will result in a parsing error. Instead, music should be inside other
-expressions, which may be put in a file by themselves. Such
-expressions are called toplevel expressions. This section enumerates
-them all.
+@refcommands
-A @code{.ly} file contains any number of toplevel expressions, where a
-toplevel expression is one of the following
+@cindex @code{\pageBreak}
+@code{\pageBreak}
+@cindex @code{\noPageBreak}
+@code{\noPageBreak}
-@itemize @bullet
-@item
-An output definition, such as @code{\paper}, @code{\midi}, and
-@code{\layout}. Such a definition at the toplevel changes the default
-settings for the block entered.
-@item
-A @code{\header} block. This sets the global header block. This
-is the block containing the definitions for book-wide settings, like
-composer, title, etc.
+@refbugs
-@item
-An @code{\addquote} statement. See @ref{Quoting other voices}
-for more information.
+The @code{breakbefore=##t} header requires that there is a @code{piece} header as well. It may be used as a normal header, or left blank (@code{=""}) as in the example above, but it must be present.
-@item
-A @code{\score} block. This score will be collected with other
-toplevel scores, and combined as a single @code{\book}.
-This behavior can be changed by setting the variable
-@code{toplevel-score-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
-@item
-A @code{\book} block logically combines multiple movements
-(i.e., multiple @code{\score} blocks) in one document. A number of
-@code{\scores} creates a single output file, where all movement are
-concatenated.
+@node Multiple movements
+@section Multiple movements
-This behavior can be changed by setting the variable
-@code{toplevel-book-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
+@cindex bibliographic information
+@cindex titles
+@cindex composer
+@cindex Music engraving by LilyPond
+
+A document may contain multiple pieces of music and texts. Examples
+of these are an etude book, or an orchestral part with multiple
+movements. Each movement is entered with a @code{\score} block,
-@item
-A compound music expression, such as
@example
-@{ c'4 d' e'2 @}
+\score @{
+ @var{..music..}
+@}
@end example
-This will add the piece in a @code{\score} and format it in a
-single book together with all other toplevel @code{\score}s and music
-expressions.
-
-This behavior can be changed by setting the variable
-@code{toplevel-music-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
+and texts are entered with a @code{\markup} block,
-@item
-A markup text, a verse for example
@example
\markup @{
- 2. The first line verse two.
+ @var{..text..}
@}
@end example
-Markup texts are rendered above, between or below the scores or music
-expressions, wherever they appear.
+@cindex @code{\book}
+
+The movements and texts are combined together in a @code{\book} block,
+like
-@item
-An indentifier, such as
@example
-foo = @{ c4 d e d @}
+\book @{
+ \score @{
+ @var{..}
+ @}
+ \markup @{
+ @var{..}
+ @}
+ \score @{
+ @var{..}
+ @}
+@}
@end example
-This can be used later on in the file by entering @code{\foo}. The
-name of an identifier should have alphabetic characters only; no
-numbers, underscores or dashes.
-
-@end itemize
-The following example shows three things that may be entered at
-toplevel
+The header for each piece of music can be put inside the @code{\score}
+block. The @code{piece} name from the header will be printed before
+each movement. The title for the entire book can be put inside the
+@code{\book}, but if it is not present, the @code{\header} which is at
+the top of the file is inserted.
-@example
-\layout @{
- % movements are non-justified by default
- raggedright = ##t
-@}
+@cindex Engraved by LilyPond
+@cindex signature line
-\header @{
- title = "Do-re-mi"
+@example
+\book @{
+ \header @{
+ title = "Eight miniatures"
+ composer = "Igor Stravinsky"
+ @}
+ \score @{
+ @dots{}
+ \header @{ piece = "Romanze" @}
+ @}
+ \markup @{
+ ..text of second verse..
+ @}
+ \markup @{
+ ..text of third verse..
+ @}
+ \score @{
+ @dots{}
+ \header @{ piece = "Menuetto" @}
+ @}
@}
-
-@{ c'4 d' e2 @}
@end example
-At any point in a file, any of the following lexical instructions can
-be entered:
-
-@itemize @bullet
-@item @code{\version}
-@item @code{\include}
-@item @code{\renameinput}
-@end itemize
+@node MIDI output
+@section MIDI output
-@node Sound
-@section Sound
@cindex Sound
-
@cindex MIDI
MIDI (Musical Instrument Digital Interface) is a standard for
For each type of MIDI instrument, a volume range can be defined. This
gives a basic equalizer control, which can enhance the quality of
the MIDI output remarkably. The equalizer can be controlled by
-setting @code{instrumentEqualizer}.
+setting @code{instrumentEqualizer}, or by setting
+
+@example
+\set Staff.midiMinimumVolume = #0.2
+\set Staff.midiMaximumVolume = #0.8
+@end example
+
+To remove dynamics from the MIDI output, insert the following lines
+in the @code{\midi@{@}} section.
+
+@example
+\midi @{
+ ...
+ \context @{
+ \Voice
+ \remove "Dynamic_performer"
+ \remove "Span_dynamic_performer"
+ @}
+@}
+@end example
+
+
+@refbugs
+
+Unterminated (de)crescendos will not render properly in the midi file,
+resulting in silent passages of music. The workaround is to explicitly
+terminate the (de)crescendo. For example,
+
+@example
+@{ a\< b c d\f @}
+@end example
+
+@noindent
+will not work properly but
+
+@example
+@{ a\< b c d\!\f @}
+@end example
+
+@noindent
+will.
@node MIDI block
the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
instrument is used.
-
projects / lilypond.git / blobdiff