@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
-When music is printed, a lot of things notation elements must be added
-to the input, which is often bare bones. For example, compare the
-input and output of the following example:
+When music is printed, a lot of notation elements must be added to the
+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
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
\paper @{
@dots{}
\context @{
- \StaffContext
+ \Staff
\set fontSize = #-2
\override Stem #'thickness
Here
@example
- \StaffContext
+ \Staff
@end example
@noindent
takes the existing definition @context{Staff} from the identifier
-@code{StaffContext}. This works analogously to other contexts, so that
-the existing definition of @code{Voice} is in @code{\VoiceContext}.
+@code{Staff}. This works analogously to other contexts.
The statements
@example
\override Stem #'transparent = ##t
\alias Voice
}
- \context { \StaffContext
+ \context { \Staff
\accepts "ImproVoice"
}}
\score { \notes \relative c'' {
@verbatim
\context {
- \StaffContext
+ \Staff
\accepts ImproVoice
}
@end verbatim
@dots{}
@}
\context @{
- \StaffContext
+ \Staff
\accepts "ImproVoice"
@}
@}
There are many different properties. Not all of them are listed in
this manual. However, the program reference lists them all in the
-section @internalsref{Context-properties}, and most properties are
-demonstrated in one of the
+section @internalsref{Tunable-context-properties}, and most properties
+are demonstrated in one of the
@ifhtml
-@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
+@uref{../../../../input/test/out-www/collated-files.html,tips-and-tricks}
@end ifhtml
@ifnothtml
tips-and-tricks
The exact tuning possibilities for each type of layout object are
documented in the program reference of the respective
object. However, many layout objects share properties, which can be
-used to apply generic tweaks. We mention a couple of these:
+used to apply generic tweaks. We mention a few of these:
@itemize @bullet
@item The @code{extra-offset} property, which
@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
@end itemize
-More specific overrides are also possible. The following section
+More specific overrides are also possible. The next section
discusses in depth how to figure out these statements for yourself.
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
starts from the output, and ends at the input event.
The program reference can also be browsed like a normal document. It
-contains a chapter on @internalsref{Music definitions}, on
-@internalsref{Translation}, and the @internalsref{Backend}. Every
- chapter lists all the definitions used, and all properties that may
- be tuned.
+contains a chapter on
+@ifhtml
+@internalsref{Music-definitions},
+@end ifhtml
+@ifnothtml
+Music definitions
+@end ifnothtml
+on @internalsref{Translation}, and the @internalsref{Backend}. Every
+chapter lists all the definitions used, and all properties that may be
+tuned.
@node Layout interfaces
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
@tab 7.9
@tab
-@item feta20
+@item feta26
@tab 25.2
@tab 8.9
@tab
@example
\paper @{
\context @{
- \PianoStaffContext
+ \PianoStaff
\override VerticalAlignment #'forced-distance = #9
@}
@dots{}
created before any property commands are interpreted.
@example
\paper @{ \context @{
- \ScoreContext
+ \Score
\override SpacingSpanner #'spacing-increment = #3.0
@} @}
@end example
score, the part containing the longer durations will be spaced too
widely.
-There is no convenient mechanism to manually override spacing.
+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.
@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.
-@cindex paper size
-@cindex page size
-@cindex @code{papersize}
+@node Titling
+@subsection Titling
-To change the paper size, there are two commands,
-@example
- #(set-default-paper-size "a4")
- \paper@{
- #(set-paper-size "a4")
- @}
-@end example
-The second one sets the size of the @code{\paper} block that it's in.
+Titles are created for each @code{\score} block, and over a
+@code{\book}.
-@refcommands
+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
-@cindex @code{\newpage}
-@code{\newpage}.
+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
-@seealso
+Different fonts may be selected for each element, by using a
+@code{\markup}, e.g.
-In this manual: @ref{Invoking lilypond}.
+@verbatim
+ \header {
+ title = \markup { \italic { The italic title } }
+ }
+@end verbatim
-Examples: @inputfileref{input/regression,between-systems.ly}.
+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.
-Internals: @internalsref{NonMusicalPaperColumn}.
+
-@refbugs
+@cindex header
+@cindex footer
+@cindex page layout
+@cindex titles
-LilyPond has no concept of page layout, which makes it difficult to
-reliably choose page breaks in longer pieces.
+@node Page breaking
+@subsection Page breaking
-@node Output details
-@section Output details
+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.
-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.
+Page breaks are computed by the @code{page-breaking} function in the
+@code{\bookpaper} block.
-Now the music is output system by system (a `system' consists of all
-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.
+@refcommands
-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.
+@cindex @code{\pageBreak}
+@code{\pageBreak}
+@cindex @code{\noPageBreak}
+@code{\noPageBreak}
-It is possible to fine-tune the vertical offset further by defining the
-macro @code{\lilypondscoreshift}:
+@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
-\def\lilypondscoreshift@{0.25\baselineskip@}
+ #(set-default-paper-size "a4")
+ \paper@{
+ #(set-paper-size "a4")
+ @}
@end example
+The second one sets the size of the @code{\paper} block that it is in.
-@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}):
+@node Page layout
+@subsection Page layout
-@example
-\documentclass@{article@}
+@cindex page layout
+@cindex margins
+@cindex header, page
+@cindex footer, page
-\def\lilypondpaperlastpagefill@{@}
-\lineskip 5pt
-\def\lilypondscoreshift@{0.25\baselineskip@}
+LilyPond will do page layout, setting margins and adding headers and
+footers to each page.
-\begin@{document@}
-This is running text which includes an example music file
-\input@{foo.tex@}
-right here.
-\end@{document@}
-@end example
+The default layout responds to the following settings in the
+@code{\bookpaper} block
-The file @file{foo.tex} has been simply produced with
+@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.
+
+@cindex copyright
+@cindex tagline
+
+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})''.
+
+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}.
+
+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.
+
+
+@seealso
+
+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