certain effect.
The controls available for tuning are described in a separate
-document, the @internalsref{Program reference} manual. This manual
+document, the @internalsref{Program reference} manual. That manual
lists all different variables, functions and options available in
LilyPond. It is written as a HTML document, which is available
@uref{http://lilypond.org/doc/Documentation/user/out-www/lilypond-internals/,on-line},
@menu
* Scheme tutorial::
+* File structure::
* Interpretation contexts::
* Tuning output::
* Fonts::
* Text markup::
* Global layout::
-* Output details::
@end menu
@node Scheme tutorial
#'((1) (2))
@end example
+@node File structure
+@section File structure
+The following items may be present in a @file{.ly} file at toplevel
+
+@itemize @bullet
+@item An output definition, such as @code{\bookpaper}, @code{\midi}
+and @code{\paper}. Such a definition at toplevel changes the default
+settings for the block entered.
+
+@item An @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 formats the block
+
+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 formats it into 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}.
+
+@end itemize
+
+The following example shows three things which may be entered at
+toplevel
+@verbatim
+ \paper {
+ % movements are non-justified by default
+ raggedright = ##t
+ }
+
+ \header {
+ title = "Do-re-mi"
+ }
+
+ { c'4 d' e2 }
+@end verbatim
+
+
+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{\encoding}
+@item @code{\renameinput}
+@end itemize
+
+
+
@node Interpretation contexts
@section Interpretation contexts
input, which is often bare bones. For example, compare the input and
output of the following example:
-@lilypond[verbatim,relative=2]
+@lilypond[verbatim,relative=2,fragment]
cis4 cis2. g4
@end lilypond
@menu
* Creating contexts::
-* Changing context properties on the fly ::
+* Changing context properties on the fly::
* Modifying context plug-ins::
* Layout tunings within contexts::
* Changing context default settings::
create them by hand. There are three commands which do this.
The easiest command is @code{\new}, and it also the quickest to type.
-It is prepended to a music expression, for example
+It is prepended to a music expression, for example
+
+@cindex @code{\new}
+@cindex new contexts
+@cindex Context, creating
@example
\new @var{type} @var{music expression}
staves. Each part that should be on its own staff, is preceded with
@code{\new Staff}.
-@lilypond[verbatim,relative=2,raggedright]
+@lilypond[verbatim,relative=2,raggedright,fragment]
<< \new Staff { c4 c }
\new Staff { d4 d }
>>
@end lilypond
+@cindex @code{\context}
+
Like @code{\new}, the @code{\context} command also directs a music
expression to a context object, but gives the context an extra name. The
syntax is
@verbatim
music = \notes { c4 c4 }
-arts = \notes { s4-. s4-> }
+arts = \notes { s4-. s4-> }
@end verbatim
They are combined by sending both to the same @context{Voice} context,
>>
@end verbatim
@lilypond[raggedright]
-music = \notes { c4 c4 }
+music = \notes { c4 c4 }
arts = \notes { s4-. s4-> }
\score {
- \notes \relative c'' << \new Staff \context Voice = "A" \music
+ \notes \relative c'' << \new Staff \context Voice = "A" \music
\context Voice = "A" \arts
>>
}
@end lilypond
-
+@cindex @code{\context}
+@cindex creating contexts
The third command for creating contexts is
@example
@node Changing context properties on the fly
@subsection Changing context properties on the fly
+@cindex properties
+@cindex @code{\set}
+@cindex changing properties
+
Each context can have different @emph{properties}, variables contained
in that context. They can be changed during the interpretation step.
This is achieved by inserting the @code{\set} command in the music,
@end quotation
For example,
-@lilypond[verbatim,relative=2]
+@lilypond[verbatim,relative=2,fragment]
R1*2
\set Score.skipBars = ##t
R1*2
context (typically @context{ChordNames}, @context{Voice}, or
@context{Lyrics}) is used. In this example,
-@lilypond[verbatim,relative=2]
+@lilypond[verbatim,relative=2,fragment]
c8 c c c
\set autoBeaming = ##f
c8 c c c
`on-the-fly', during the music, so that the setting only affects the
second group of eighth notes.
+@cindex @code{\unset}
+
There is also an @code{\unset} command,
@quotation
@code{\set }@var{context}@code{.}@var{prop}
Settings that should only apply to a single time-step can be entered
easily with @code{\once}, for example in
-@lilypond[verbatim,relative=2]
+@lilypond[verbatim,relative=2,fragment]
c4
\once \set fontSize = #4.7
c4
example which removes @code{Time_signature_engraver} and
@code{Clef_engraver} from a @code{Staff} context,
-@lilypond[relative=1, verbatim]
+@lilypond[relative=1, verbatim,fragment]
<< \new Staff {
f2 g
}
@cindex polymetric scores
-@lilypond[relative=1,raggedright,verbatim]
+@lilypond[relative=1,raggedright,verbatim,fragment]
\new Score \with {
\remove "Timing_engraver"
} <<
applies to the current staff. Other staves will keep their normal
appearance. Here we see the command in action:
-@lilypond[verbatim,relative=2]
+@lilypond[verbatim,relative=2,fragment]
c4
\override Staff.Stem #'thickness = #4.0
c4
causing it to default to @context{Voice}, and adding @code{\once} applies
the change during one timestep only
-@lilypond[verbatim,relative=2]
+@lilypond[fragment,verbatim,relative=2]
c4
\once \override Stem #'thickness = #4.0
c4
the object is created. In this example,
-@lilypond[verbatim,relative=2]
+@lilypond[fragment,verbatim,relative=2]
\override Slur #'thickness = #3.0
c8[( c
\override Beam #'thickness = #0.6
@cindex setting object properties
-@lilypond[relative=1,verbatim]
+@lilypond[fragment,relative=1,verbatim]
\stemUp
f-5
\once \override Fingering
example; a more elaborate explanation is in @ref{Constructing a
tweak}:
-@lilypond[relative=1,verbatim]
+@lilypond[fragment,relative=1,verbatim]
c2\fermata
\override Script #'padding = #3
b2\fermata
Suppose we want to move the fingering indication in the fragment
below:
-@lilypond[relative=2,verbatim]
+@lilypond[fragment,relative=2,verbatim]
c-2
\stemUp
f
are.
We have been talking of `the' @code{Fingering} object, but actually it
-does not amount to much. The initialization file
+does not amount to much. The initialization file
@file{scm/define-grobs.scm} shows the soul of the `object',
@verbatim
Recall that we wanted to change the position of the @b{2} in
-@lilypond[relative=2,verbatim]
+@lilypond[fragment,relative=2,verbatim]
c-2
\stemUp
f
notes. An elaborate example of those is in
@inputfileref{input/test,cue-notes.ly}.
+@cindex cue notes
@cindex @code{font-style}
@refcommands
flexible distances (``springs'') are chosen, based on durations. All
possible line breaking combination 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. When the score
-is processed by @TeX{}, each page is filled with systems, and page breaks
-are chosen whenever the page gets full.
+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.
* Vertical spacing::
* Horizontal spacing::
* Line breaking::
+* Line length and line breaking::
+* Titling::
+* Page breaking::
+* Paper size::
* Page layout::
@end menu
Internals: @internalsref{BreakEvent}.
-
-@node Page layout
-@subsection Page layout
+@node Line length and line breaking
+@subsection Line length and line breaking
@cindex page breaks
@cindex breaking pages
that line. The result is similar to formatting paragraphs. In a
paragraph, the last line simply takes its natural length.
-The page layout process happens outside the LilyPond formatting
-engine: variables controlling page layout are passed to the output,
-and are further interpreted by @code{lilypond} wrapper program. It
-responds to the following variables in the @code{\paper} block. The
-spacing between systems is controlled with @code{interscoreline}, its
-default is 16pt. The distance between the score lines will stretch in
-order to fill the full page @code{interscorelinefill} is set to a
-positive number. In that case @code{interscoreline} specifies the
-minimum spacing.
-
-@cindex @code{textheight}
-@cindex @code{interscoreline}
-@cindex @code{interscorelinefill}
-
-If the variable @code{lastpagefill} is defined,
-@c fixme: this should only be done if lastpagefill= #t
-systems are evenly distributed vertically on the last page. This
-might produce ugly results in case there are not enough systems on the
-last page. The @command{lilypond-book} command ignores
-@code{lastpagefill}. See @ref{lilypond-book manual} for more
-information.
-
-@cindex @code{lastpagefill}
-
-Page breaks are normally computed by @TeX{}, so they are not under
-direct control of LilyPond. However, you can insert commands into
-the @file{.tex} output to instruct @TeX{} where to break pages. This
-is done by setting the @code{between-systems-strings} on the
-@internalsref{NonMusicalPaperColumn} where the system is broken.
-An example is shown in @inputfileref{input/regression,between-systems.ly}.
-The predefined command @code{\newpage} also does this.
+
+@node Titling
+@subsection Titling
+
+Titles are created for each @code{\score} block, and over a
+@code{\book}.
+
+The contents of the titles are taken from the @code{\header} blocks.
+The header block for a book supports the following
+@table @code
+@item title
+ The title of the music. Centered on top of the first page.
+@item subtitle
+ Subtitle, centered below the title.
+@item poet
+ Name of the poet, left flushed below the subtitle.
+@item composer
+ Name of the composer, right flushed below the subtitle.
+@item meter
+ Meter string, left flushed below the poet.
+@item opus
+ Name of the opus, right flushed below the composer.
+@item arranger
+ Name of the arranger, right flushed below the opus.
+@item instrument
+ Name of the instrument, centered below the arranger.
+@item dedication
+ To whom the piece is dedicated.
+@item piece
+ Name of the piece, left flushed below the instrument.
+@end table
+
+This is a demonstration of the fields available,
+
+@lilypond[verbatim]
+\book {
+ \header {
+ title = "Title"
+ subtitle = "(and (the) subtitle)"
+ subsubtitle = "Sub sub title"
+ poet = "Poet"
+ composer = "Composer"
+ texttranslator = "Text Translator"
+ meter = "Meter"
+ arranger = "Arranger"
+ instrument = "Instrument"
+ piece = "Piece"
+ }
+
+ \score {
+ \header {
+ piece = "piece1"
+ opus = "opus1"
+ }
+ { c'1 }
+ }
+ \score {
+ \header {
+ piece = "piece2"
+ opus = "opus2"
+ }
+ { c'1 }
+ }
+}
+@end lilypond
+
+Different fonts may be selected for each element, by using a
+@code{\markup}, e.g.
+
+@verbatim
+ \header {
+ title = \markup { \italic { The italic title } }
+ }
+@end verbatim
+
+A more advanced option is to change the Scheme functions
+@code{make-book-title} and @code{make-score-title} functions, defined
+in the @code{\bookpaper} of the @code{\book} block. These functions
+create a block of titling, given the information in the
+@code{\header}. The init file @file{ly/titling.scm} shows how the
+default format is created, and it may be used as a template for
+different styles.
+
+
+
+@cindex header
+@cindex footer
+@cindex page layout
+@cindex titles
+
+
+
+
+@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 with a bar line. These commands force and forbid a page-break
+from happening.
+
+Page breaks are computed by the @code{page-breaking} function in the
+@code{\bookpaper} block.
+
+@refcommands
+
+@cindex @code{\pageBreak}
+@code{\pageBreak}
+@cindex @code{\noPageBreak}
+@code{\noPageBreak}
+
+@node Paper size
+@subsection Paper size
@cindex paper size
@cindex page size
#(set-paper-size "a4")
@}
@end example
-The second one sets the size of the @code{\paper} block that it's in.
-
-@refcommands
-
-@cindex @code{\newpage}
-@code{\newpage}.
+The second one sets the size of the @code{\paper} block that it is in.
-@seealso
-
-In this manual: @ref{Invoking lilypond}.
+@node Page layout
+@subsection Page layout
-Examples: @inputfileref{input/regression,between-systems.ly}.
+@cindex page layout
+@cindex margins
+@cindex header, page
+@cindex footer, page
-Internals: @internalsref{NonMusicalPaperColumn}.
+LilyPond will do page layout, setting margins and adding headers and
+footers to each page.
-@refbugs
+The default layout responds to the following settings in the
+@code{\bookpaper} block
-LilyPond has no concept of page layout, which makes it difficult to
-reliably choose page breaks in longer pieces.
+@table @code
+@item hsize
+ The width of the page
+@item vsize
+ The height of the page
+@item top-margin
+ Margin between header and top of the page
+@item bottom-margin
+ Margin between footer and bottom of the page
+@item head-sep
+ Distance between top-most music system and the page header
+@item foot-sep
+ Distance between bottom-most music system and the page footer
+@item raggedbottom
+ If set to true, systems will not be spread across the page.
+@item raggedlastbottom
+ If set to true, systems will not be spread to fill the last page.
+@end table
+The default page header puts the page number and the @code{instrument}
+field from the @code{\header} block on a line.
-@node Output details
-@section Output details
-The default output format is La@TeX{}, which should be run
-through La@TeX{}. Using the option @option{-f}
-(or @option{--format}) other output formats can be selected also, but
- none of them work reliably.
+@cindex copyright
+@cindex tagline
-Now the music is output system by system (a `system' is a single line
-from the score, consisting of staves belonging together). From
-@TeX{}'s point of view, a system is an @code{\hbox} which contains a
-lowered @code{\vbox} so that it is centered vertically on the baseline
-of the text. Between systems, @code{\interscoreline} is inserted
-vertically to have stretchable space. The horizontal dimension of the
-@code{\hbox} is given by the @code{linewidth} parameter from
-LilyPond's @code{\paper} block.
+The default footer is empty, except for the first page, where it 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})''.
-After the last system LilyPond emits a stronger variant of
-@code{\interscoreline} only if the macro
-@code{\lilypondpaperlastpagefill} is not defined (flushing the systems
-to the top of the page). You can avoid that by setting the variable
-@code{lastpagefill} in LilyPond's @code{\paper} block.
+The header and footer are created by the functions @code{make-footer}
+and @code{make-header}, defined in @code{\bookpaper}. The default
+implementations are in @file{scm/page-layout.scm}.
-@c FIXME: broken by page layout
-It is possible to fine-tune the vertical offset further by defining the
-macro @code{\lilypondscoreshift}:
+The following settings influence the header and footer layout.
-@example
-\def\lilypondscoreshift@{0.25\baselineskip@}
-@end example
+@table @code
+@item printpagenumber
+ this boolean controls whether a pagenumber is printed.
+@end table
-@noindent
-where @code{\baselineskip} is the distance from one text line to the next.
-Here an example how to embed a small LilyPond file @code{foo.ly} into
-running La@TeX{} text without using the @code{lilypond-book} script
-(@pxref{lilypond-book manual}):
-@example
-\documentclass@{article@}
+The page layout itself is done by two functions:
+@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.
-\def\lilypondpaperlastpagefill@{@}
-\lineskip 5pt
-\def\lilypondscoreshift@{0.25\baselineskip@}
-\begin@{document@}
-This is running text which includes an example music file
-\input@{foo.tex@}
-right here.
-\end@{document@}
-@end example
+@seealso
-The file @file{foo.tex} has been simply produced with
+Examples: @inputfileref{input/test/,page-breaks.ly}
-@example
- lilypond-bin foo.ly
-@end example
-The call to @code{\lineskip} assures that there is enough vertical space
-between the LilyPond box and the surrounding text lines.
projects / lilypond.git / blobdiff