X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fglobal.itely;h=052c075a18e7f573678db3f1fb7d25e7a2db6dbd;hb=ddca9dc5c3d3a6cee3ecb3fc6f12d7cf96c62ae5;hp=6e6100256f18cb0eece80302aa9287199b08c43a;hpb=623ba211d607b134c2749a3fa8368d3b3b149e8c;p=lilypond.git diff --git a/Documentation/user/global.itely b/Documentation/user/global.itely index 6e6100256f..052c075a18 100644 --- a/Documentation/user/global.itely +++ b/Documentation/user/global.itely @@ -1,6 +1,1815 @@ -@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 +@c M-x texinfo-all-menus-update +@c to automatically fill in these menus before saving changes + @node Global issues @chapter Global issues -This is a placeholder for very-near future reorganization of the manual. +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:: +@end menu + + +@node Input files +@section Input files + +The main format of input for LilyPond are text files. By convention, +these files end with ``@code{.ly}''. + +@menu +* File structure (introduction):: +* File structure:: +* Including LilyPond files:: +* Text encoding:: +@end menu + + +@node File structure (introduction) +@subsection File structure (introduction) + +A basic example of a lilypond input file is + +@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 +c'4 +@end example + +@noindent +will result in a parsing error. Instead, music should be inside other +expressions, which may be put in a file by themselves. Such +expressions are called toplevel expressions. The next section enumerates +them all. + + +@node File structure +@subsection File structure + +A @code{.ly} file contains any number of toplevel expressions, where a +toplevel expression is one of the following + +@itemize @bullet +@item +An output definition, such as @code{\paper}, @code{\midi}, and +@code{\layout}. Such a definition at the toplevel changes the default +settings for the block entered. + +@item +A direct scheme expression, such as +@code{#(set-default-paper-size "a7" 'landscape)} or +@code{#(ly:set-option 'point-and-click #f)}. + +@item +A @code{\header} block. This sets the global header block. This +is the block containing the definitions for book-wide settings, like +composer, title, etc. + +@item +An @code{\addquote} statement. See @ref{Quoting other voices} +for more information. + +@item +A @code{\score} block. This score will be collected with other +toplevel scores, and combined as a single @code{\book}. + +This behavior can be changed by setting the variable +@code{toplevel-score-handler} at toplevel. The default handler is +defined in the init file @file{scm/@/lily@/.scm}. + +The @code{\score} must begin with a music expression, and may +contain only one music expression. + +@item +A @code{\book} block logically combines multiple movements +(i.e., multiple @code{\score} blocks) in one document. If there are +a number of @code{\scores}, a single output file will be created +in which all movements are concatenated. + +This behavior can be changed by setting the variable +@code{toplevel-book-handler} at toplevel. The default handler is +defined in the init file @file{scm/@/lily@/.scm}. + +@item +A compound music expression, such as +@example +@{ c'4 d' e'2 @} +@end example + +This will add the piece in a @code{\score} and format it in a +single book together with all other toplevel @code{\score}s and music +expressions. In other words, a file containing only the above +music expression will be translated into + +@example +\book @{ + \score @{ + \new Staff @{ + \new Voice @{ + @{ c'4 d' e'2 @} + @} + @} + @} + \layout @{ @} + \header @{ @} +@} +@end example + +This behavior can be changed by setting the variable +@code{toplevel-music-handler} at toplevel. The default handler is +defined in the init file @file{scm/@/lily@/.scm}. + +@item +A markup text, a verse for example +@example +\markup @{ + 2. The first line verse two. +@} +@end example + +Markup texts are rendered above, between or below the scores or music +expressions, wherever they appear. + +@item +An identifier, such as +@example +foo = @{ c4 d e d @} +@end example + +This can be used later on in the file by entering @code{\foo}. The +name of an identifier should have alphabetic characters only; no +numbers, underscores or dashes. + +@end itemize + +The following example shows three things that may be entered at +toplevel + +@example +\layout @{ + % movements are non-justified by default + ragged-right = ##t +@} + +\header @{ + title = "Do-re-mi" +@} + +@{ c'4 d' e2 @} +@end example + + +At any point in a file, any of the following lexical instructions can +be entered: + +@itemize @bullet +@item @code{\version} +@item @code{\include} +@item @code{\renameinput} +@end itemize + + +@node Including LilyPond files +@subsection Including LilyPond files + +@cindex @code{\include} +@cindex including files + +A large project may be split up into separate files. To refer to another +file, use + +@example +\include "otherfile.ly" +@end example + +The line @code{\include "file.ly"} is equivalent to pasting the contents +of file.ly into the current file at the place where you have the +\include. For example, for a large project you might write separate files +for each instrument part and create a ``full score'' file which brings +together the individual instrument files. + +The initialization of LilyPond is done in a number of files that are +included by default when you start the program, normally transparent to the +user. Run lilypond --verbose to see a list of paths and files that Lily +finds. + +Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where +VERSION is in the form ``2.6.1'') are on the path and available to +@code{\include}. Files in the +current working directory are available to \include, but a file of the same +name in LilyPond's installation takes precedence. Files are +available to \include from directories in the search path specified as an +option when invoking @code{lilypond --include=DIR} which adds DIR to the search +path. + +The @code{\include} statement can use full path information, but with the Unix +convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example, +if @file{stuff.ly} is located one directory higher than the current working +directory, use + +@example +\include "../stuff.ly" +@end example + + +@node Text encoding +@subsection Text encoding + +LilyPond uses the Pango library to format multi-lingual texts, and +does not perform any input-encoding conversions. This means that any +text, be it title, lyric text, or musical instruction containing +non-ASCII characters, must be utf-8. The easiest way to enter such text is +by using a Unicode-aware editor and saving the file with utf-8 encoding. Most +popular modern editors have utf-8 support, for example, vim, Emacs, +jEdit, and GEdit do. + +Depending on the fonts installed, the following fragment shows Hebrew +and Cyrillic lyrics, + +@cindex Cyrillic +@cindex Hebrew +@cindex ASCII, non + +@lilypondfile[fontload]{utf-8.ly} + +The @TeX{} backend does not handle encoding specially at all. Strings +in the input are put in the output as-is. Extents of text items in the +@TeX{} backend, are determined by reading a file created via the +@file{texstr} backend, + +@example +lilypond -b texstr input/les-nereides.ly +latex les-nereides.texstr +@end example + +The last command produces @file{les-nereides.textmetrics}, which is +read when you execute + +@example +lilypond -b tex input/les-nereides.ly +@end example + +Both @file{les-nereides.texstr} and @file{les-nereides.tex} need +suitable LaTeX wrappers to load appropriate La@TeX{} packages for +interpreting non-ASCII strings. + +To use a Unicode escape sequence, use + +@example +#(ly:export (ly:wide-char->utf-8 #x2014)) +@end example + + +@seealso + +@inputfileref{input/regression,utf-8.ly} + + + +@node A single music expression +@section A single music expression + +A @code{\score} must contain a single music expression. However, +this music expression may be of any size. Recall that music +expressions may be included inside other expressions to form +larger expressions. All of these examples are single music +expressions; note the curly braces @{ @} or angle brackets << +>> at the beginning and ending of the music. + +@example +@{ c'4 c' c' c' @} +@end example + +@lilypond[ragged-right,verbatim,quote] +{ + { c'4 c' c' c'} + { d'4 d' d' d'} +} +@end lilypond + +@lilypond[ragged-right,verbatim,quote] +<< + \new Staff { c'4 c' c' c' } + \new Staff { d'4 d' d' d' } +>> +@end lilypond + +@example +@{ + \new GrandStaff << + \new StaffGroup << + \new Staff @{ \flute @} + \new Staff @{ \oboe @} + >> + \new StaffGroup << + \new Staff @{ \violinI @} + \new Staff @{ \violinII @} + >> + >> +@} +@end example + + +@node Titles and headers +@section Titles and headers + +Almost all printed music includes a title and the composer's name; +some pieces include a lot more information. + +@menu +* 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. + +@cindex @code{annotate-spacing} +@cindex Spacing, display of properties + +To graphically display the dimensions of properties that may +be altered for page formatting, use + +@example +\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. + +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. + + +@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. + +@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. + +@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[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 +@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 + +@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}. + +@cindex @code{common-shortest-duration} +@cindex @code{base-shortest-duration} +@cindex @code{stem-spacing-correction} +@cindex @code{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 + +@cindex @code{indent} +@cindex @code{line-width} +@cindex @code{ragged-right} +@cindex @code{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}. +@cindex @code{\break} +@cindex @code{\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 + +@cindex @code{\pageBreak} +@code{\pageBreak} +@cindex @code{\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 + +@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 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 +@{ 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 +@subsection MIDI block +@cindex MIDI block + + +The MIDI block is analogous to the layout block, but it is somewhat +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 + +Context definitions follow precisely the same syntax as within the +\layout block. Translation modules for sound are called performers. +The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}. + + +@node MIDI instrument names +@subsection MIDI instrument names + +@cindex instrument names +@cindex @code{Staff.midiInstrument} + +The MIDI instrument name is set by the @code{Staff.midiInstrument} +property. The instrument name should be chosen from the list in +@ref{MIDI instruments}. + +@example +\set Staff.midiInstrument = "glockenspiel" +@var{...notes...} +@end example + +If the selected instrument does not exactly match an instrument from +the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"}) +instrument is used.