-@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::
-* LilyPond files::
-* Sound::
+* Input files::
+* A single music expression::
+* Titles and headers::
+* Paper and pages::
+* Music layout::
+* Multiple movements::
+* MIDI output::
@end menu
-@node Global layout
-@section Global layout
-
-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.
-
-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.
-
+@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
-* 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::
+* File structure (introduction)::
+* File structure::
+* Including LilyPond files::
+* Text encoding::
@end menu
-@node Setting global staff size
-@subsection Setting global staff size
+@node File structure (introduction)
+@subsection File structure (introduction)
-@cindex font size, setting
-@cindex staff size, setting
-@cindex @code{layout} file
+A basic example of a lilypond input file is
-To set the global staff size, use @code{set-global-staff-size}.
+@example
+\version "2.8.0"
+\score @{
+ @{ @} % this is a single music expression;
+ % all the music goes in here.
+ \header @{ @}
+ \layout @{ @}
+ \midi @{ @}
+@}
+@end example
+@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
-#(set-global-staff-size 14)
+c'4
@end example
@noindent
-This sets the global default size to 14pt staff height and scales all
-fonts accordingly.
+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.
-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
+@node File structure
+@subsection File structure
-@item @b{font name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
+A @code{.ly} file contains any number of toplevel expressions, where a
+toplevel expression is one of the following
-@item feta11
-@tab 11.22
-@tab 3.9
-@tab pocket scores
+@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 feta13
-@tab 12.60
-@tab 4.4
-@tab
-
-@item feta14
-@tab 14.14
-@tab 5.0
-@tab
+@item
+A direct scheme expression, such as
+@code{#(set-default-paper-size "a7" 'landscape)} or
+@code{#(ly:set-option 'point-and-click #f)}.
-@item feta16
-@tab 15.87
-@tab 5.6
-@tab
+@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 feta18
-@tab 17.82
-@tab 6.3
-@tab song books
+@item
+An @code{\addquote} statement. See @ref{Quoting other voices}
+for more information.
-@item feta20
-@tab 20
-@tab 7.0
-@tab standard parts
+@item
+A @code{\score} block. This score will be collected with other
+toplevel scores, and combined as a single @code{\book}.
-@item feta23
-@tab 22.45
-@tab 7.9
-@tab
+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 feta26
-@tab 25.2
-@tab 8.9
-@tab
-@c modern rental material?
+The @code{\score} must begin with a music expression, and may
+contain only one music expression.
-@end multitable
-@end quotation
+@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.
-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.
+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
-@seealso
+Markup texts are rendered above, between or below the scores or music
+expressions, wherever they appear.
-This manual: @ref{Selecting font sizes}.
+@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.
-@node Paper size
-@subsection Paper size
+@end itemize
-@cindex paper size
-@cindex page size
-@cindex @code{papersize}
+The following example shows three things that may be entered at
+toplevel
-To change the paper size, there are two commands,
@example
-#(set-default-paper-size "a4")
-\paper @{
- #(set-paper-size "a4")
+\layout @{
+ % movements are non-justified by default
+ ragged-right = ##t
+@}
+
+\header @{
+ title = "Do-re-mi"
@}
+
+@{ c'4 d' e2 @}
@end example
-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.
-The following paper sizes are supported: @code{a6}, @code{a5}, @code{a4},
-@code{a3}, @code{legal}, @code{letter}, @code{tabloid}.
+At any point in a file, any of the following lexical instructions can
+be entered:
-@cindex orientation
-@cindex landscape
+@itemize @bullet
+@item @code{\version}
+@item @code{\include}
+@item @code{\renameinput}
+@end itemize
-If the symbol @code{landscape} is supplied as an argument to
-@code{set-default-paper-size}, the pages will be rotated by 90 degrees,
-and wider line widths will be set correspondingly.
+
+@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
-#(set-default-paper-size "a6" 'landscape)
-@end 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
-@node Page layout
-@subsection Page layout
+@example
+\include "../stuff.ly"
+@end example
-@cindex page layout
-@cindex margins
-@cindex header, page
-@cindex footer, page
-LilyPond will do page layout, set margins, and add headers and
-footers to each page.
+@node Text encoding
+@subsection Text encoding
-The default layout responds to the following settings in the
-@code{\paper} block.
+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.
-@cindex \paper
+Depending on the fonts installed, the following fragment shows Hebrew
+and Cyrillic lyrics,
-@quotation
-@table @code
-@item firstpagenumber
-The value of the page number of the first page. Default is@tie{}1.
+@cindex Cyrillic
+@cindex Hebrew
+@cindex ASCII, non
-@item printfirstpagenumber
-If set to true, will print the page number in the first page. Default is
-false.
+@lilypondfile[fontload]{utf-8.ly}
-@item hsize
-The width of the page.
+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,
-@item vsize
-The height of the page.
+@example
+lilypond -b texstr input/les-nereides.ly
+latex les-nereides.texstr
+@end example
-@item topmargin
-Margin between header and top of the page.
+The last command produces @file{les-nereides.textmetrics}, which is
+read when you execute
-@item bottommargin
-Margin between footer and bottom of the page.
+@example
+lilypond -b tex input/les-nereides.ly
+@end example
-@item leftmargin
-Margin between the left side of the page and the beginning of the music.
+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.
-@item linewidth
-The length of the systems.
+To use a Unicode escape sequence, use
-@item headsep
-Distance between the top-most music system and the page header.
+@example
+#(ly:export (ly:wide-char->utf-8 #x2014))
+@end example
-@item footsep
-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.
+@seealso
-This should be set false 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.
+@inputfileref{input/regression,utf-8.ly}
-Pieces that amply fill two pages or more should have this set to
-true.
-@item betweensystemspace
-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.
+@node A single music expression
+@section A single music expression
-@item betweensystempadding
-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.
+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
+* Creating titles::
+* Custom titles::
+@end menu
+
+
+@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 dedication
+The dedicatee of the music, centered at the top of the first page.
+
+@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
+You may change this behavior (and print all the headers when defining
+@code{\header} inside @code{\score}) by using
+
+@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.
+
+ By default, headers are defined such that the page number is on the
+ outside edge, and the instrument is centered.
+
+@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.
+
+ By default, the footer has the copyright notice on the first, and
+ the tagline on the last page.
+@end table
+
+
+@cindex \paper
+@cindex header
+@cindex footer
+@cindex page layout
+@cindex titles
+
+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
+
+
+@refbugs
+
+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.
+
+
+
+@node Paper and pages
+@section Paper and pages
+
+This section deals with the display of music on physical paper.
+
+@menu
+* Paper size::
+* Page formatting::
+@end menu
+
+
+@node Paper size
+@subsection Paper size
+
+@cindex paper size
+@cindex page size
+@cindex @code{papersize}
+
+To change the paper size, there are two commands,
+@example
+#(set-default-paper-size "a4")
+\paper @{
+ #(set-paper-size "a4")
+@}
+@end example
+
+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{\book}, then the paper size will only
+apply to that book.
+
+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
+
+If the symbol @code{landscape} is supplied as an argument to
+@code{set-default-paper-size}, the pages will be rotated by 90 degrees,
+and wider line widths will be set correspondingly.
+
+@example
+#(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 formatting
+@subsection Page formatting
+
+@cindex page formatting
+@cindex margins
+@cindex header, page
+@cindex footer, page
+
+LilyPond will do page layout, set margins, and add headers and
+footers to each page.
+
+The default layout responds to the following settings in the
+@code{\paper} block.
+
+@cindex @code{\paper}
+
+@quotation
+@table @code
+@cindex @code{first-page-number}
+@item first-page-number
+The value of the page number of the first page. Default is@tie{}1.
+
+@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.
+
+@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.
+
+@cindex @code{paper-height}
+@item paper-height
+The height of the page.
+
+@cindex @code{top-margin}
+@item top-margin
+Margin between header and top of the page.
+
+@cindex @code{bottom-margin}
+@item bottom-margin
+Margin between footer and bottom of the page.
+
+@cindex @code{left-margin}
+@item left-margin
+Margin between the left side of the page and the beginning of the music.
+
+@cindex @code{line-width}
+@item line-width
+The length of the systems.
+
+@cindex @code{head-separation}
+@item head-separation
+Distance between the top-most music system and the page header.
+
+@cindex @code{foot-separation}
+@item foot-separation
+Distance between the bottom-most music system and the page footer.
+
+@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 to true for pieces that have only two or three
+systems per page, for example orchestral scores.
+
+@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.
+
+@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.
+
+@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{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}.
+@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
-\layout @{
- betweensystemspace = 10\mm
+\paper @{
+ between-system-space = 10\mm
@}
@end example
+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
+\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.
-
-@refbugs
+@internalsref{VerticalAlignment} object. The context parameters
+specifying the vertical extent are described in connection with
+the @internalsref{Axis_group_engraver}.
-@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
-@code{forced-distance} cannot be changed per system.
+@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.
+
+@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.
+@example
+\layout @{
+ indent = #0
+ line-width = #150
+ ragged-last = ##t
+@}
+@end example
+
+
@node Line breaking
@subsection Line breaking
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
-
-@cindex @code{\book}
-
-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" @}
- @}
-@}
-@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 dedication
-The dedicatee of the music, centered at the top of the first page.
-
-@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.
-
-@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. Note that you
-may use any @ref{Text markup} commands in the header.
-
-@lilypond[quote,verbatim,linewidth=11.0\cm]
-\paper {
- linewidth = 9.0\cm
- vsize = 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 = "Arranger"
- opus = \markup { \fontsize #8.5 "o" \fontsize #2.5 "p" \fontsize #-2.5 "u" \fontsize #-5.3 "s" \fontsize #7.5 " " }
- instrument = \markup \bold \italic "instrument"
- piece = "Piece"
- }
-
- \score {
- \header {
- piece = "piece1"
- opus = "opus1"
- }
- { c'1 }
- }
- \markup {
- and now...
- }
- \score {
- \header {
- piece = "piece2"
- opus = "opus2"
- }
- { c'1 }
- }
-}
-@end lilypond
-
-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
-@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).
+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.
-@item oddHeaderMarkup
- This is the page header for odd-numbered pages.
- @item evenHeaderMarkup
- This is the page header for even-numbered pages. If unspecified,
- the odd header is used instead.
+@cindex regular line breaks
+@cindex four bar music.
- By default, headers are defined such that the page number is on the
- outside edge, and the instrument is centered.
+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
-@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.
+@noindent
+This makes the following 28 measures (assuming 4/4 time) be broken every
+4 measures, and only there.
- By default, the footer has the copyright notice on the first, and
- the tagline on the last page.
-@end table
+@refcommands
+@code{\break}, and @code{\noBreak}.
+@cindex @code{\break}
+@cindex @code{\noBreak}
-@cindex \paper
-@cindex header
-@cindex footer
-@cindex page layout
-@cindex titles
+@seealso
-The following definition will put the title flush left, and the
-composer flush right on a single line.
+Internals: @internalsref{BreakEvent}.
-@verbatim
-\paper {
- bookTitleMarkup = \markup {
- \fill-line @{
- \fromproperty #'header:title
- \fromproperty #'header:composer
- @}
- }
-}
-@end verbatim
+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.
+@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
-@node LilyPond files
-@section LilyPond files
+@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
-@menu
-* File structure::
-* Including LilyPond files::
-@end menu
+@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.
-@node File structure
-@subsection File structure
+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.
-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.
-
-A @code{.ly} file contains any number of toplevel expressions, where a
-toplevel expression is one of the following
+@refcommands
-@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.
+@cindex @code{\pageBreak}
+@code{\pageBreak}
+@cindex @code{\noPageBreak}
+@code{\noPageBreak}
-@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.
+@refbugs
-@item
-A @code{\score} block. This score will be collected with other
-toplevel scores, and combined as a single @code{\book}.
+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.
-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.
-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}.
+@node Multiple movements
+@section Multiple movements
-@item
-A compound music expression, such as
-@example
-@{ c'4 d' e'2 @}
-@end example
+@cindex bibliographic information
+@cindex titles
+@cindex composer
+@cindex Music engraving by LilyPond
-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}.
+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 markup text, a verse for example
@example
-\markup @{
- 2. The first line verse two.
+\score @{
+ @var{..music..}
@}
@end example
-Markup texts are rendered above, between or below the scores or music
-expressions, wherever they appear.
+and texts are entered with a @code{\markup} block,
-@item
-An indentifier, such as
@example
-foo = @{ c4 d e d @}
+\markup @{
+ @var{..text..}
+@}
@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
+@cindex @code{\book}
-The following example shows three things that may be entered at
-toplevel
+The movements and texts are combined together in a @code{\book} block,
+like
@example
-\layout @{
- % movements are non-justified by default
- raggedright = ##t
-@}
-
-\header @{
- title = "Do-re-mi"
+\book @{
+ \score @{
+ @var{..}
+ @}
+ \markup @{
+ @var{..}
+ @}
+ \score @{
+ @var{..}
+ @}
@}
-
-@{ 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
+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.
-A large project may be split up into separate files. To refer to another
-file, use
+@cindex Engraved by LilyPond
+@cindex signature line
-@example
-\include "otherfile.ly"
+@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" @}
+ @}
+@}
@end example
-For example, you may write separate files for each instrument part and
-create a ``full score'' file which brings together the individual
-instrument files.
-@node Sound
-@section Sound
-@cindex Sound
+@node MIDI output
+@section MIDI output
+@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.
-