@c M-x texinfo-all-menus-update
@c to automatically fill in these menus before saving changes
-@node Non-musical notation
-@chapter Non-musical notation
+@node Global issues
+@chapter Global issues
This section deals with general lilypond issues, rather than
specific notation.
@menu
* Input files::
+* A single music expression::
* Titles and headers::
+* Paper and pages::
+* Music layout::
+* Multiple movements::
* MIDI output::
* Displaying LilyPond notation::
-* Skipping corrected music::
+* Other::
@end menu
@menu
* File structure (introduction)::
-* Multiple scores in a book::
* File structure::
-* A single music expression::
* Including LilyPond files::
* Text encoding::
@end menu
A basic example of a lilypond input file is
@example
-\version "2.9.13"
+\version "2.8.0"
\score @{
@{ @} % this is a single music expression;
% all the music goes in here.
them all.
-@node Multiple scores in a book
-@subsection Multiple scores in a book
-
-@funindex \book
-@cindex movements, multiple
-
-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
-
-@funindex \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.
-
-@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 File structure
@subsection File structure
@end itemize
-@node A single music expression
-@subsection 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 Including LilyPond files
@subsection Including LilyPond files
-@funindex \include
+@findex \include
@cindex including files
A large project may be split up into separate files. To refer to another
+@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
The contents of the titles are taken from the @code{\header} blocks.
The header block for a book supports the following
-
-
@table @code
-@funindex dedication
@item dedication
The dedicatee of the music, centered at the top of the first page.
-@funindex title
@item title
The title of the music, centered just below the dedication.
-@funindex subtitle
@item subtitle
Subtitle, centered below the title.
-@funindex subsubtitle
@item subsubtitle
Subsubtitle, centered below the subtitle.
-@funindex poet
@item poet
Name of the poet, flush-left below the subtitle.
-@funindex composer
@item composer
Name of the composer, flush-right below the subtitle.
-@funindex meter
@item meter
Meter string, flush-left below the poet.
-@funindex opus
@item opus
Name of the opus, flush-right below the composer.
-@funindex arranger
@item arranger
Name of the arranger, flush-right below the opus.
-@funindex instrument
@item instrument
Name of the instrument, centered below the arranger. Also
centered at the top of pages (other than the first page).
-@funindex piece
@item piece
Name of the piece, flush-left below the instrument.
@cindex page breaks, forcing
-@funindex breakbefore
@item breakbefore
This forces the title to start on a new page (set to ##t or ##f).
-@funindex copyright
@item copyright
Copyright notice, centered at the bottom of the first page. To
insert the copyright symbol, see @ref{Text encoding}.
-@funindex tagline
@item tagline
Centered at the bottom of the last page.
}
@end lilypond
-@funindex printallheaders
+@findex printallheaders
@noindent
You may change this behavior (and print all the headers when defining
@code{\header} inside @code{\score}) by using
@}
@end example
-@cindex copyright
-@cindex tagline
-
-The default footer is empty, except for the first page, where the
-@code{copyright} field from @code{\header} is inserted, and the last
-page, where @code{tagline} from @code{\header} is added. The default
-tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
-printed parts are good PR for us, so please leave the tagline if you
-can.}
-
-Headers may be completely removed by setting them to false.
-
-@example
-\header @{
- tagline = ##f
- composer = ##f
-@}
-@end example
-
@node Custom titles
@subsection Custom titles
@file{ly/titling-init.ly} lists the default layout.
@table @code
-@funindex bookTitleMarkup
+@findex 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
-@funindex scoreTitleMarkup
+@findex 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).
-@funindex oddHeaderMarkup
+@findex oddHeaderMarkup
@item oddHeaderMarkup
This is the page header for odd-numbered pages.
-@funindex evenHeaderMarkup
+@findex 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.
-@funindex oddFooterMarkup
+@findex oddFooterMarkup
@item oddFooterMarkup
This is the page footer for odd-numbered pages.
-@funindex evenFotterMarkup
+@findex evenFotterMarkup
@item evenFooterMarkup
This is the page footer for even-numbered pages. If unspecified,
the odd header is used instead.
-@node MIDI output
-@section MIDI output
-
-@cindex Sound
-@cindex MIDI
-
-MIDI (Musical Instrument Digital Interface) is a standard for
-connecting and controlling digital instruments. A MIDI file is a
-series of notes in a number of tracks. It is not an actual
-sound file; you need special software to translate between the
-series of notes and actual sounds.
-
-Pieces of music can be converted to MIDI files, so you can listen to
-what was entered. This is convenient for checking the music; octaves
-that are off or accidentals that were mistyped stand out very much
-when listening to the MIDI output.
-
-@refbugs
-
-Many musically interesting effects, such as swing, articulation,
-slurring, etc., are not translated to midi.
-
-The midi output allocates a channel for each staff, and one for global
-settings. Therefore the midi file should not have more than 15 staves
-(or 14 if you do not use drums). Other staves will remain silent.
+@node Paper and pages
+@section Paper and pages
-Not all midi players correctly handle tempo changes in the midi
-output. Players that are known to work include
-@uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
+This section deals with the display of music on physical paper.
@menu
-* Creating MIDI files::
-* MIDI block::
-* MIDI instrument names::
+* Paper size::
+* Page formatting::
@end menu
-@node Creating MIDI files
-@subsection Creating MIDI files
-To create a MIDI from a music piece of music, add a @code{\midi} block
-to a score, for example,
+@node Paper size
+@subsection Paper size
+@cindex paper size
+@cindex page size
+@findex papersize
+
+To change the paper size, there are two commands,
@example
-\score @{
- @var{...music...}
- \midi @{ @}
+#(set-default-paper-size "a4")
+\paper @{
+ #(set-paper-size "a4")
@}
@end example
-FIXME
+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.
-The tempo is specified using the @code{\tempo} command. In this
-example the tempo of quarter notes is set to 72 beats per minute.
+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}.
-If there is a @code{\midi} command in a @code{\score}, only MIDI will
-be produced. When notation is needed too, a @code{\layout} block must
-be added
+@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
-\score @{
- @var{...music...}
- \midi @{ @}
- \layout @{ @}
-@}
+#(set-default-paper-size "a6" 'landscape)
@end example
-@cindex layout block
+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.
-Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
-crescendi and decrescendi translate into MIDI volume levels. Dynamic
-marks translate to a fixed fraction of the available MIDI volume
-range, crescendi and decrescendi make the volume vary linearly between
-their two extremes. The fractions can be adjusted by
-@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
-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}, or by setting
+@node Page formatting
+@subsection Page formatting
-@example
-\set Staff.midiMinimumVolume = #0.2
-\set Staff.midiMaximumVolume = #0.8
-@end example
+@cindex page formatting
+@cindex margins
+@cindex header, page
+@cindex footer, page
-To remove dynamics from the MIDI output, insert the following lines
-in the @code{\midi@{@}} section.
+LilyPond will do page layout, set margins, and add headers and
+footers to each page.
+
+@findex annotate-spacing
+@cindex Spacing, display of properties
+
+To graphically display the dimensions of properties that may
+be altered for page formatting, use
@example
-\midi @{
- ...
- \context @{
- \Voice
- \remove "Dynamic_performer"
- \remove "Span_dynamic_performer"
- @}
+\paper @{
+ annotate-spacing = ##t
@}
@end example
+@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.
-@refbugs
+The default layout responds to the following settings in the
+@code{\paper} block.
-Unterminated (de)crescendos will not render properly in the midi file,
-resulting in silent passages of music. The workaround is to explicitly
+@findex \paper
+
+@quotation
+@table @code
+@findex first-page-number
+@item first-page-number
+The value of the page number of the first page. Default is@tie{}1.
+
+@findex printfirst-page-number
+@item printfirst-page-number
+If set to true, will print the page number in the first page. Default is
+false.
+
+@findex print-page-number
+@item print-page-number
+If set to false, page numbers will not be printed.
+
+@findex paper-width
+@item paper-width
+The width of the page.
+
+@findex paper-height
+@item paper-height
+The height of the page.
+
+@findex top-margin
+@item top-margin
+Margin between header and top of the page.
+
+@findex bottom-margin
+@item bottom-margin
+Margin between footer and bottom of the page.
+
+@findex left-margin
+@item left-margin
+Margin between the left side of the page and the beginning of the music.
+
+@findex line-width
+@item line-width
+The length of the systems.
+
+@findex head-separation
+@item head-separation
+Distance between the top-most music system and the page header.
+
+@findex foot-separation
+@item foot-separation
+Distance between the bottom-most music system and the page footer.
+
+@findex 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.
+
+@findex 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.
+
+@findex 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.
+
+@findex system-count
+@item system-count
+This variable, if set, specifies into how many lines a score should be
+broken.
+
+@findex 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.
+
+@findex 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.
+
+
+@findex 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.
+
+@findex after-title-space
+@item after-title-space
+Amount of space between the title and the first system.
+
+@findex after-title-space
+@item before-title-space
+Amount of space between the last system of the previous piece and the
+title of the next.
+
+@findex 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).
+
+@findex 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.
+
+@findex 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[ragged-right]
+\book {
+ \score {
+ \relative { c1 \break c1 }
+ }
+ \paper {
+ systemSeparatorMarkup = \slashSeparator
+ }
+}
+@end lilypond
+
+
+@end table
+@end quotation
+
+Example:
+
+@example
+\paper@{
+ paper-width = 2\cm
+ top-margin = 3\cm
+ bottom-margin = 3\cm
+ ragged-last-bottom = ##t
+@}
+@end example
+
+You can also define these values in Scheme. In that case @code{mm},
+@code{in}, @code{pt}, and @code{cm} are variables defined in
+@file{paper-defaults.ly} with values in millimeters. That's why the
+value has to be multiplied in the example
+
+@example
+\paper @{
+ #(define bottom-margin (* 2 cm))
+@}
+@end example
+
+@cindex copyright
+@cindex tagline
+
+The default footer is empty, except for the first page, where the
+@code{copyright} field from @code{\header} is inserted, and the last
+page, where @code{tagline} from @code{\header} is added. The default
+tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
+printed parts are good PR for us, so please leave the tagline if you
+can.}
+
+The header and footer are created by the functions @code{make-footer}
+and @code{make-header}, defined in @code{\paper}. The default
+implementations are in @file{ly/@/paper@/-defaults@/.ly} and
+@file{ly/@/titling@/-init@/.ly}.
+
+The page layout itself is done by two functions in the
+@code{\paper} block, @code{page-music-height} and
+@code{page-make-stencil}. The former tells the line-breaking algorithm
+how much space can be spent on a page, the latter creates the actual
+page given the system to put on it.
+
+
+@refbugs
+
+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 @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.
+
+The titles (from the @code{\header@{@}} section) are treated as a
+system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
+add space between the titles and the first system of the score.
+
+
+@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
+@findex 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:
+
+@findex \tiny
+@code{\tiny},
+@findex \small
+@code{\small},
+@findex \normalsize
+@code{\normalsize}.
+
+
+@node Score layout
+@subsection Score layout
+
+@findex \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
+
+@cindex vertical spacing
+@cindex distance between staves
+@cindex staff distance
+@cindex between staves, distance
+@cindex staves per page
+@cindex space between staves
+
+The height of each system is determined automatically. To prevent
+systems from bumping into each other, some minimum distances are set.
+By changing these, you can put staves closer together, and thus put
+more systems onto one page.
+
+Normally staves are stacked vertically. To make staves maintain a
+distance, their vertical size is padded. This is done with the
+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
+\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 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
+
+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{annotate-spacing} 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 { annotate-spacing = ##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. The context parameters
+specifying the vertical extent are described in connection with
+the @internalsref{Axis_group_engraver}.
+
+Example files: @inputfileref{input/regression/,page-spacing.ly},
+@inputfileref{input/regression/,alignment-vertical-spacing.ly}.
+
+
+
+
+@node Vertical spacing of piano staves
+@subsection Vertical spacing of piano staves
+
+The distance between staves of a @internalsref{PianoStaff} cannot be
+computed during formatting. Rather, to make cross-staff beaming work
+correctly, that distance has to be fixed beforehand.
+
+The distance of staves in a @code{PianoStaff} is set with the
+@code{forced-distance} property of the
+@internalsref{VerticalAlignment} object, created in
+@internalsref{PianoStaff}.
+
+It can be adjusted as follows
+@example
+\new PianoStaff \with @{
+ \override VerticalAlignment #'forced-distance = #7
+@} @{
+ ...
+@}
+@end example
+
+@noindent
+This would bring the staves together at a distance of 7 staff spaces,
+measured from the center line of each staff.
+
+The difference is demonstrated in the following example,
+@lilypond[quote,verbatim]
+\relative c'' <<
+ \new PianoStaff \with {
+ \override VerticalAlignment #'forced-distance = #7
+ } <<
+ \new Staff { c1 }
+ \new Staff { c }
+ >>
+ \new PianoStaff <<
+ \new Staff { c }
+ \new Staff { c }
+ >>
+>>
+@end lilypond
+
+
+It is also possible to change the distance between for each system
+individually. This is done by including the command
+
+@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.
+
+@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
+duration adds a fixed amount (this amount is controlled by
+@code{spacing-increment}) of space to the note.
+
+For example, the following piece contains lots of half, quarter, and
+8th notes; the eighth note is followed by 1 note head width (NHW).
+The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
+
+@lilypond[quote,fragment,verbatim,relative=1]
+c2 c4. c8 c4. c8 c4. c8 c8
+c8 c4 c4 c4
+@end lilypond
+
+Normally, @code{spacing-increment} is set to 1.2 staff space, which is
+approximately the width of a note head, and
+@code{shortest-duration-space} is set to 2.0, meaning that the
+shortest note gets 2.4 staff space (2.0 times the
+@code{spacing-increment}) of horizontal space. This space is counted
+from the left edge of the symbol, so the shortest notes are generally
+followed by one NHW of space.
+
+If one would follow the above procedure exactly, then adding a single
+32nd note to a score that uses 8th and 16th notes, would widen up the
+entire score a lot. The shortest note is no longer a 16th, but a 32nd,
+thus adding 1 NHW to every note. To prevent this, the shortest
+duration for spacing is not the shortest note in the score, but rather
+the one which occurs most frequently.
+
+
+The most common shortest duration is determined as follows: in every
+measure, the shortest duration is determined. The most common shortest
+duration is taken as the basis for the spacing, with the stipulation
+that this shortest duration should always be equal to or shorter than
+an 8th note. The shortest duration is printed when you run
+@code{lilypond} with the @code{--verbose} option.
+
+These durations may also be customized. If you set the
+@code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
+this sets the base duration for spacing. The maximum duration for this
+base (normally an 8th), is set through @code{base-shortest-duration}.
+
+@findex common-shortest-duration
+@findex base-shortest-duration
+@findex stem-spacing-correction
+@findex spacing
+
+Notes that are even shorter than the common shortest note are
+followed by a space that is proportional to their duration relative to
+the common shortest note. So if we were to add only a few 16th notes
+to the example above, they would be followed by half a NHW:
+
+@lilypond[quote,fragment,verbatim,relative=2]
+c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
+@end lilypond
+
+
+In the introduction (see @ref{Engraving}), it was explained that stem
+directions influence spacing. This is controlled with the
+@code{stem-spacing-correction} property in the
+@internalsref{NoteSpacing}, object. These are generated for every
+@internalsref{Voice} context. The @code{StaffSpacing} object
+(generated in @internalsref{Staff} context) contains the same property
+for controlling the stem/bar line spacing. The following example shows
+these corrections, once with default settings, and once with
+exaggerated corrections:
+
+@lilypond[quote,ragged-right]
+{
+ c'4 e''4 e'4 b'4 |
+ b'4 e''4 b'4 e''4|
+ \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
+ \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
+ 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
+
+Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
+@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
+@internalsref{SeparatingGroupSpanner}.
+
+@refbugs
+
+Spacing is determined on a score wide basis. If you have a score that
+changes its character (measured in durations) halfway during the
+score, the part containing the longer durations will be spaced too
+widely.
+
+There is no convenient mechanism to manually override spacing. The
+following work-around may be used to insert extra space into a score.
+@example
+ \once \override Score.SeparationItem #'padding = #1
+@end example
+
+No work-around exists for decreasing the amount of space.
+
+
+@node Line length
+@subsection Line length
+
+@cindex page breaks
+@cindex breaking pages
+
+@findex indent
+@findex line-width
+@findex ragged-right
+@findex ragged-last
+
+@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{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{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{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 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
+
+@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}.
+@findex \break
+@findex \noBreak
+
+@seealso
+
+Internals: @internalsref{BreakEvent}.
+
+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
+
+@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
+
+
+@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
+ piece = ""
+@}
+@end example
+
+@refcommands
+
+@findex \pageBreak
+@code{\pageBreak}
+@findex \noPageBreak
+@code{\noPageBreak}
+
+
+@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 Multiple movements
+@section Multiple movements
+
+@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,
+
+@example
+\score @{
+ @var{..music..}
+@}
+@end example
+
+and texts are entered with a @code{\markup} block,
+
+@example
+\markup @{
+ @var{..text..}
+@}
+@end example
+
+@findex \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 MIDI output
+@section MIDI output
+
+@cindex Sound
+@cindex MIDI
+
+MIDI (Musical Instrument Digital Interface) is a standard for
+connecting and controlling digital instruments. A MIDI file is a
+series of notes in a number of tracks. It is not an actual
+sound file; you need special software to translate between the
+series of notes and actual sounds.
+
+Pieces of music can be converted to MIDI files, so you can listen to
+what was entered. This is convenient for checking the music; octaves
+that are off or accidentals that were mistyped stand out very much
+when listening to the MIDI output.
+
+@refbugs
+
+Many musically interesting effects, such as swing, articulation,
+slurring, etc., are not translated to midi.
+
+The midi output allocates a channel for each staff, and one for global
+settings. Therefore the midi file should not have more than 15 staves
+(or 14 if you do not use drums). Other staves will remain silent.
+
+Not all midi players correctly handle tempo changes in the midi
+output. Players that are known to work include
+@uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
+
+@menu
+* Creating MIDI files::
+* MIDI block::
+* MIDI instrument names::
+@end menu
+
+@node Creating MIDI files
+@subsection Creating MIDI files
+
+To create a MIDI from a music piece of music, add a @code{\midi} block
+to a score, for example,
+
+@example
+\score @{
+ @var{...music...}
+ \midi @{ \tempo 4=72 @}
+@}
+@end example
+
+The tempo is specified using the @code{\tempo} command. In this
+example the tempo of quarter notes is set to 72 beats per minute.
+
+
+If there is a @code{\midi} command in a @code{\score}, only MIDI will
+be produced. When notation is needed too, a @code{\layout} block must
+be added
+
+@example
+\score @{
+ @var{...music...}
+ \midi @{ \tempo 4=72 @}
+ \layout @{ @}
+@}
+@end example
+@cindex layout block
+
+
+
+Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
+crescendi and decrescendi translate into MIDI volume levels. Dynamic
+marks translate to a fixed fraction of the available MIDI volume
+range, crescendi and decrescendi make the volume vary linearly between
+their two extremes. The fractions can be adjusted by
+@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
+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}, 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
The MIDI block is analogous to the layout block, but it is somewhat
-simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
-context definitions.
+simpler. The @code{\midi} block can contain
+@cindex MIDI block
+
+@itemize @bullet
+ @item a @code{\tempo} definition, and
+ @item context definitions.
+@end itemize
+
+A number followed by a period is interpreted as a real number, so
+for setting the tempo for dotted notes, an extra space should be
+inserted, for example
+
+@example
+\midi @{ \tempo 4 . = 120 @}
+@end example
@cindex context definition
@subsection MIDI instrument names
@cindex instrument names
-@funindex Staff.midiInstrument
+@findex Staff.midiInstrument
The MIDI instrument name is set by the @code{Staff.midiInstrument}
property. The instrument name should be chosen from the list in
@node Displaying LilyPond notation
@section Displaying LilyPond notation
-@funindex \displayLilyMusc
+@findex \displayLilyMusc
Displaying a music expression in LilyPond notation can be
done using the music function @code{\displayLilyMusic}. For example,
@end example
+@node Other
+@section Other
+
+@c FIXME: yeah, it really needs to be moved soon. -gp
+@menu
+* Skipping corrected music::
+* Writing music in parallel::
+@end menu
+
@node Skipping corrected music
-@section Skipping corrected music
+@subsection Skipping corrected music
-@funindex skipTypesetting
-@funindex showLastLength
+@findex skipTypesetting
+@findex showLastLength
When entering or copying music, usually only the music near the end (where
you
voices and staves, saving even more time.
+@node Writing music in parallel
+@subsection Writing music in parallel
+@cindex Writing music in parallel
+@cindex Interleaved music
+
+Music for multiple parts can be interleaved
+
+@lilypond[quote,fragment,verbatim]
+\parallelMusic #'(voiceA voiceB) {
+ r8 g'16[ c''] e''[ g' c'' e''] r8 g'16[ c''] e''[ g' c'' e''] |
+ c'2 c'2 |
+ r8 a'16[ d''] f''[ a' d'' f''] r8 a'16[ d''] f''[ a' d'' f''] |
+ c'2 c'2 |
+}
+\new StaffGroup <<
+ \new Staff \new Voice \voiceA
+ \new Staff \new Voice \voiceB
+>>
+@end lilypond
+
projects / lilypond.git / blobdiff