-@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
+@node Output formats
+@chapter Output formats
This is a placeholder until I can write a nice intro for this chapter.
@menu
-* Global layout::
-* File structure::
-* Sound::
+* Paper output::
+* Sound output::
@end menu
-@node Global layout
-@section Global layout
+@node Paper output
+@section Paper output
-The global layout is determined by three factors: the page layout, the
+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
@menu
* Setting global staff size::
+* Selecting notation font size::
* Paper size::
-* Page layout::
+* Page formatting::
+* Score layout::
* Vertical spacing::
* Vertical spacing of piano staves::
* Horizontal spacing::
@seealso
-This manual: @ref{Selecting font sizes}.
+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 Paper size
@cindex page size
@cindex @code{papersize}
-To change the paper size, there are two equal commands,
+To change the paper size, there are two commands,
@example
#(set-default-paper-size "a4")
\paper @{
The first command sets the size of all pages. The second command sets the size
of the pages that the @code{\paper} block applies to -- if the @code{\paper}
block is at the top of the file, then it will apply to all pages. If the
-@code{\paper} block is inside a @code{\score}, then the paper size will only
-apply to that score.
+@code{\paper} block is inside a @code{\book}, then the paper size will only
+apply to that book.
+
+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).
-The following paper sizes are supported: @code{a6}, @code{a5}, @code{a4},
-@code{a3}, @code{legal}, @code{letter}, @code{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
@end example
-@node Page layout
-@subsection Page layout
+@node Page formatting
+@subsection Page formatting
-@cindex page layout
+@cindex page formatting
@cindex margins
@cindex header, page
@cindex footer, page
The default layout responds to the following settings in the
@code{\paper} block.
-@cindex \paper
+@cindex @code{\paper}
@quotation
@table @code
+@cindex @code{firstpagenumber}
@item firstpagenumber
The value of the page number of the first page. Default is@tie{}1.
+@cindex @code{printfirstpagenumber}
@item printfirstpagenumber
If set to true, will print the page number in the first page. Default is
false.
+@cindex @code{printpagenumber}
+@item printpagenumber
+If set to false, page numbers will not be printed.
+
+@cindex @code{hsize}
@item hsize
The width of the page.
+@cindex @code{vsize}
@item vsize
The height of the page.
+@cindex @code{topmargin}
@item topmargin
Margin between header and top of the page.
+@cindex @code{bottommargin}
@item bottommargin
Margin between footer and bottom of the page.
+@cindex @code{leftmargin}
@item leftmargin
Margin between the left side of the page and the beginning of the music.
+@cindex @code{linewidth}
@item linewidth
The length of the systems.
+@cindex @code{headsep}
@item headsep
Distance between the top-most music system and the page header.
+@cindex @code{footsep}
@item footsep
Distance between the bottom-most music system and the page footer.
+@cindex @code{pagetopspace}
+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{raggedbottom}
@item raggedbottom
If set to true, systems will not be spread across the page.
This should be set false for pieces that have only two or three
systems per page, for example orchestral scores.
+@cindex @code{raggedlastbottom}
@item raggedlastbottom
If set to false, systems will be spread to fill the last page.
Pieces that amply fill two pages or more should have this set to
true.
+@cindex @code{betweensystemspace}
@item betweensystemspace
This dimensions determines the distance between systems. It is the
ideal distance between the center of the bottom staff of one system
Increasing this will provide a more even appearance of the page at the
cost of using more vertical space.
+@cindex @code{betweensystempadding}
@item betweensystempadding
This dimension is the minimum amount of white space that will always
be present between the bottom-most symbol of one system, and the
Increasing this will put systems whose bounding boxes almost touch
farther apart.
+
+@cindex @code{horizontalshift}
+@item horizontalshift
+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{aftertitlespace}
@item aftertitlespace
Amount of space between the title and the first system.
+@cindex @code{aftertitlespace}
@item beforetitlespace
Amount of space between the last system of the previous piece and the
title of the next.
+@cindex @code{betweentitlespace}
@item betweentitlespace
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 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 ``Engraved by LilyPond (@var{version})''.@footnote{Nicely
+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.}
and @code{make-header}, defined in @code{\paper}. The default
implementations are in @file{scm/@/page@/-layout@/.scm}.
-The following settings influence the header and footer layout.
-
-@quotation
-@table @code
-@item printpagenumber
- this boolean controls whether a pagenumber is printed.
-@end table
-@end quotation
-
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
field from the @code{\header} block on a line.
+@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
+ minimumVerticalExtent = #'(-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
will be much more useful than changing @code{minimumVerticalExtent}.
@example
-\layout @{
+\paper @{
betweensystemspace = 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 @{
+ betweensystempadding = #1
+ raggedbottom=##f
+ raggedlastbottom=##f
+@}
+@end example
+
+
+@c let's wait for a some comments before writing more.
+
+The vertical spacing on a page can also be changed for each system individually.
+Some examples are found in the example file
+@inputfileref{input/regression/,page-spacing.ly}.
+
+When setting @code{annotatespacing} in the @code{\paper} block LilyPond
+will graphically indicate the dimensions of properties that may be set
+for page spacing,
+
+@lilypond[verbatim]
+#(set-default-paper-size "a6")
+\paper { annotatespacing = ##t }
+{ c4 }
+@end lilypond
+
+
@seealso
Internals: Vertical alignment of staves is handled by the
-@internalsref{VerticalAlignment} object.
+@internalsref{VerticalAlignment} object. The context parameters
+specifying the vertical extent are described in connection with
+the @internalsref{Axis_group_engraver}.
+
+Example files: @inputfileref{input/regression/,page-spacing.ly}.
+
@refbugs
@code{forced-distance} cannot be changed per system.
-
@node Horizontal spacing
@subsection Horizontal Spacing
-The spacing engine translates differences in durations into
-stretchable distances (``springs'') of differring lengths. Longer
-durations get more space, shorter durations get less. The shortest
-durations get a fixed amount of space (which is controlled by
-@code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
-The longer the duration, the more space it gets: doubling a
+The spacing engine translates differences in durations into stretchable
+distances (``springs'') of differring lengths. Longer durations get
+more space, shorter durations get less. The shortest durations get a
+fixed amount of space (which is controlled by
+@code{shortest-duration-space} in the @internalsref{SpacingSpanner}
+object). The longer the duration, the more space it gets: doubling a
duration adds a fixed amount (this amount is controlled by
@code{spacing-increment}) of space to the note.
No work-around exists for decreasing the amount of space.
+
@node Line length
@subsection Line length
@cindex @code{indent}
@cindex @code{linewidth}
+@cindex @code{raggedright}
@c Although linewidth can be set in \layout, it should be set in paper
@c block, to get page layout right.
@c stretch as the previous line. eTeX uses \lastlinefit to
@c interpolate between both these solutions.
+
@node Line breaking
@subsection Line breaking
Page breaks are computed by the @code{page-breaking} function in the
@code{\paper} block.
+To force a new page for a new piece (in a collection of pieces or a
+piece in several movements), use @code{breakbefore} in the header.
+
+@example
+\header@{
+ breakbefore = ##t
+@}
+@end example
+
@refcommands
@cindex @code{\pageBreak}
@cindex bibliographic information
@cindex titles
@cindex composer
-@cindex Engraved by LilyPond
+@cindex Music engraving by LilyPond
-A document may contain multiple pieces of music. Examples of these
-are an etude book, or an orchestral part with multiple movements.
-Each movement is entered with a @code{\score} block,
+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 @{
@}
@end example
-The movements are combined together in a @code{\book} block, like
+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{..}
@}
@dots{}
\header @{ piece = "Romanze" @}
@}
+ \markup @{
+ ..text of second verse..
+ @}
+ \markup @{
+ ..text of third verse..
+ @}
\score @{
@dots{}
\header @{ piece = "Menuetto" @}
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 on top of the first page.
+The title of the music, centered just below the dedication.
@item subtitle
Subtitle, centered below the title.
Name of the arranger, flush-right below the opus.
@item instrument
-Name of the instrument, centered below the arranger.
-
-@item dedication
-To whom the piece is dedicated.
+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.
+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,
+Here is a demonstration of the fields available. Note that you
+may use any @ref{Text markup} commands in the header.
@lilypond[quote,verbatim,linewidth=11.0\cm]
\paper {
\book {
\header {
- title = "Title,"
+ dedication = "dedicated to me"
+ title = \markup \center-align { "Title first line" "Title second line, longer" }
subtitle = "the subtitle,"
- subsubtitle = "and the sub sub title"
+ subsubtitle = #(string-append "subsubtitle LilyPond version " (lilypond-version))
poet = "Poet"
- composer = "Composer"
+ composer = \markup \center-align { "composer" \small "(1847-1973)" }
texttranslator = "Text Translator"
- meter = "Meter"
- arranger = "Arranger"
- instrument = "Instrument"
+ 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"
}
- { c'1 }
+ }
+ \markup {
+ and now...
}
\score {
+ { c'1 }
\header {
piece = "piece2"
opus = "opus2"
}
- { c'1 }
}
}
@end lilypond
-Different fonts may be selected for each element by using
-@code{\markup}, e.g.,
+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
+@example
\header @{
- title = \markup @{ \italic @{ The italic title @} @}
+ composer = "Composer"
+@}
+\header @{
+ title = "Title"
+@}
+\score @{
+ \new Staff @{ c'4 @}
+ \header @{
+ title = "New title" % 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.
+
+@lilypond[quote,verbatim,linewidth=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
+
+
+@commonprop
+
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.
- @item evenHeaderMarkup
+@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.
@verbatim
\paper {
bookTitleMarkup = \markup {
- \fill-line @{
+ \fill-line {
\fromproperty #'header:title
\fromproperty #'header:composer
- @}
+ }
}
}
@end verbatim
-@node File structure
-@section File structure
-
-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. This section enumerates
-them all.
-
-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 @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}.
-
-@item
-A @code{\book} block logically combines multiple movements
-(i.e., multiple @code{\score} blocks) in one document. A number of
-@code{\scores} creates a single output file, where all movement are
-concatenated.
-
-This behavior can be changed by setting the variable
-@code{toplevel-book-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
-
-@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.
-
-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 An indentifier, such as
-@example
-foo = @{ c4 d e d @}
-@end example
-
-This can be used later on in the file by entering @code{\foo}.
+@node Sound output
+@section Sound output
-@end itemize
-
-The following example shows three things that may be entered at
-toplevel
-
-@example
-\layout @{
- % movements are non-justified by default
- raggedright = ##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 Sound
-@section Sound
@cindex Sound
-
@cindex MIDI
MIDI (Musical Instrument Digital Interface) is a standard for
@end menu
@node Creating MIDI files
-@section 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 MIDI block
-@section MIDI block
+@subsection MIDI block
@cindex MIDI block
@node MIDI instrument names
-@section MIDI instrument names
+@subsection MIDI instrument names
@cindex instrument names
@cindex @code{Staff.midiInstrument}
the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
instrument is used.
-
projects / lilypond.git / blobdiff