version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.55"
+@c \version "2.11.61"
@node Changing defaults
@chapter Changing defaults
-@strong{N.B. This Chapter is still being developed at present.}
-
The purpose of LilyPond's design is to provide the finest quality
output by default. Nevertheless, it may happen that you need to
change this default layout. The layout is controlled through a large
@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
and is also included with the LilyPond documentation package.
-@c TODO The following is at variance to what actually follows. Fix -td
-
-@ignore
-There are four areas where the default settings may be changed:
-
-@itemize
-@item
-Automatic notation: changing the automatic creation of notation
-elements. For example, changing the beaming rules.
-
-@item
-Output: changing the appearance of individual
-objects. For example, changing stem directions or the location of
-subscripts.
-
-@item
-Context: changing aspects of the translation from music events to
-notation. For example, giving each staff a separate time signature.
-
-@item
-Page layout: changing the appearance of the spacing, line
-breaks, and page dimensions. These modifications are discussed
-@c in @ref{notation}, and @ref{Spacing issues}.
-@end itemize
-
Internally, LilyPond uses Scheme (a LISP dialect) to provide
infrastructure. Overriding layout decisions in effect accesses the
program internals, which requires Scheme input. Scheme elements are
@code{#}.@footnote{@rlearning{Scheme tutorial}, contains a short tutorial
on entering numbers, lists, strings, and symbols in Scheme.}
-@end ignore
-
@menu
* Interpretation contexts::
* Modifying properties::
* Useful concepts and properties::
* Advanced tweaks::
-* Discussion of specific tweaks::
@end menu
This section describes what contexts are, and how to modify them.
@menu
-* Contexts explained::
-* Creating contexts::
-* Modifying context plug-ins::
-* Changing context default settings::
-* Defining new contexts::
-* Aligning contexts::
+* Contexts explained::
+* Creating contexts::
+* Modifying context plug-ins::
+* Changing context default settings::
+* Defining new contexts::
+* Aligning contexts::
@end menu
+@seealso
+
+Learning Manual:
+@rlearning{Contexts and engravers}.
+
+Installed files:
+@file{ly/@/engraver@/-init@/.ly},
+@file{ly/@/performer@/-init@/.ly}.
+
+Snippets:
+@rlsr{Contexts and engravers}.
+
+Internals Reference:
+@rinternals{Contexts},
+@rinternals{Engravers and Performers}.
+
@node Contexts explained
@subsection Contexts explained
@c TODO Describe propagation of property values -td
-Contexts are arranged heirarchically:
+Contexts are arranged hierarchically:
@menu
* Score - the master of all contexts::
Groups staves while adding a bracket on the left side, grouping
the staves together. The bar lines of the contained staves are
-connected vertically. StaffGroup only consists of a collection
+connected vertically. @code{StaffGroup} only consists of a collection
of staves, with a bracket in front and spanning bar lines.
@strong{@emph{ChoirStaff}}
-Identical to StaffGroup except that the bar lines of the contained
-staves are not connected vertically.
+Identical to @code{StaffGroup} except that the bar lines of the
+contained staves are not connected vertically.
@strong{@emph{GrandStaff}}
-A group of staves, with a brace on the left side, grouping
-the staves together. The bar lines of the contained staves are
+A group of staves, with a brace on the left side, grouping the
+staves together. The bar lines of the contained staves are
connected vertically.
@strong{@emph{PianoStaff}}
-TODO No longer correct? Check. -td
-
-Just like GrandStaff but with a forced distance between the
-staves, so cross staff beaming and slurring can be used.
-
-@strong{@emph{InnerStaffGroup}}
-
-TODO -td
-
-@strong{@emph{InnerChoirStaff}}
-
-TODO -td
+Just like @code{GrandStaff}, but with support for instrument names
+to the left of each system.
@node Intermediate-level contexts - staves
@unnumberedsubsubsec Intermediate-level contexts - staves
@strong{@emph{Staff}}
-Handles clefs, bar lines, keys, accidentals. It can contain
-Voice contexts.
+Handles clefs, bar lines, keys, accidentals. It can contain
+@code{Voice} contexts.
@strong{@emph{RhythmicStaff}}
-Like Staff but for printing rhythms. Pitches are ignored;
+Like @code{Staff} but for printing rhythms. Pitches are ignored;
the notes are printed on one line.
@strong{@emph{TabStaff}}
-Context for generating tablature. By default lays the music
+Context for generating tablature. By default lays the music
expression out as a guitar tablature, printed on six lines.
@strong{@emph{DrumStaff}}
-Handles typesetting for percussion. Can contain DrumVoice
+Handles typesetting for percussion. Can contain @code{DrumVoice}
@strong{@emph{VaticanaStaff}}
-Same as Staff, except that it is designed for typesetting
+Same as @code{Staff}, except that it is designed for typesetting
a piece in gregorian style.
@strong{@emph{MensuralStaff}}
-Same as Staff, except that it is designed for typesetting
+Same as @code{Staff}, except that it is designed for typesetting
a piece in mensural style.
@node Bottom-level contexts - voices
@strong{@emph{Voice}}
-Corresponds to a voice on a staff. This context handles the
+Corresponds to a voice on a staff. This context handles the
conversion of dynamic signs, stems, beams, super- and sub-scripts,
slurs, ties, and rests. You have to instantiate this explicitly
if you require multiple voices on the same staff.
@strong{@emph{VaticanaVoice}}
-Same as Voice, except that it is designed for typesetting a piece
-in gregorian style.
+Same as @code{Voice}, except that it is designed for typesetting
+a piece in gregorian style.
@strong{@emph{MensuralVoice}}
-Same as Voice, with modifications for typesetting a piece in
+Same as @code{Voice}, with modifications for typesetting a piece in
mensural style.
@strong{@emph{Lyrics}}
-Corresponds to a voice with lyrics. Handles the printing of a
+Corresponds to a voice with lyrics. Handles the printing of a
single line of lyrics.
@strong{@emph{DrumVoice}}
@strong{@emph{FiguredBass}}
-The context in which BassFigure objects are created from
+The context in which @code{BassFigure} objects are created from
input entered in @code{\figuremode} mode.
@strong{@emph{TabVoice}}
-The voice context used within a TabStaff context. Usually left to
-be created implicitly.
+The voice context used within a @code{TabStaff} context. Usually
+left to be created implicitly.
@strong{@emph{ChordNames}}
Typesets chord names.
-------------------------------
-
+@ignore
TODO
Then the following, which I don't know what to do with:
Silently discards all musical information given to this
context.
+@end ignore
@node Creating contexts
@subsection Creating contexts
@node Changing context default settings
@subsection Changing context default settings
-The adjustments of the previous subsections (
-@ref{The set command}, @ref{Modifying context plug-ins}, and
-@ref{Overview of modifying properties}) can also be entered
-separately from the music in the @code{\layout} block,
-
-@example
-\layout @{
- @dots{}
- \context @{
- \Staff
-
- \set fontSize = #-2
- \override Stem #'thickness = #4.0
- \remove "Time_signature_engraver"
- @}
-@}
-@end example
-
-The @code{\Staff} command brings in the existing definition of the
-staff context so that it can be modified.
-
-The statements
-@example
-\set fontSize = #-2
-\override Stem #'thickness = #4.0
-\remove "Time_signature_engraver"
-@end example
-
-@noindent
-affect all staves in the score. Other contexts can be modified
-analogously.
-
-The @code{\set} keyword is optional within the @code{\layout} block, so
+The context settings which are to be used by default in
+@code{Score}, @code{Staff} and @code{Voice} contexts may be specified
+in a @code{\layout} block, as illustrated in the following example.
+The @code{\layout} block should be placed within the @code{\score}
+block to which it is to apply, but outside any music.
-@example
-\context @{
- @dots{}
- fontSize = #-2
-@}
-@end example
+Note that the @code{\set} command itself and the context must be
+omitted when the context default values are specified in this way:
-@noindent
-will also work.
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ a4^"Really small, thicker stems, no time signature" a a a
+ a a a a
+ }
+ \layout {
+ \context {
+ \Staff
+ fontSize = #-4
+ \override Stem #'thickness = #4.0
+ \remove "Time_signature_engraver"
+ }
+ }
+}
+@end lilypond
+In this example, the @code{\Staff} command specifies that the
+subsequent specifications are to be applied to all staves within
+this score block.
+Modifications can be made to the @code{Score} context or all
+@code{Voice} contexts in a similar way.
@knownissues
@}
@end example
-TODO: add \with in here.
+@c TODO: add \with in here.
@c TODO Better example needed. Ref LM, and expand on it.
@cindex ossia
-@findex alignAboveContext
-@findex alignBelowContext
+@funindex alignAboveContext
+@funindex alignBelowContext
@lilypond[quote,ragged-right]
ossia = { f4 f f f }
}
@end lilypond
+@cindex nested contexts
+@cindex contexts, nested
+
+@funindex \accepts
+@funindex \denies
+
+Contexts like @code{PianoStaff} can contain other contexts
+nested within them. Contexts which are acceptable for nesting
+are defined by the @qq{accepts} list of a context. Contexts
+which are not in this list are placed below the outer context
+in the printed score.
+For example, the @code{PianoStaff} context is defined by default
+to accept @code{Staff} and @code{FiguredBass} contexts within
+it, but not (for example) a @code{Lyrics} context. So in the
+following structure the lyrics are placed below the piano staff
+rather than between the two staves:
+
+@lilypond[verbatim,quote,relative=1]
+\new PianoStaff
+<<
+ \new Staff { e4 d c2 }
+ \addlyrics { Three blind mice }
+ \new Staff {
+ \clef "bass"
+ { c,1 }
+ }
+>>
+@end lilypond
+
+The @qq{accepts} list of a context can be modified to include
+additional nested contexts, so if we wanted the lyrics to appear
+between the two staves we could use:
+
+@lilypond[verbatim,quote,relative=1]
+\new PianoStaff \with { \accepts Lyrics }
+<<
+ \new Staff { e4 d c2 }
+ \addlyrics { Three blind mice }
+ \new Staff {
+ \clef "bass"
+ { c,1 }
+ }
+>>
+@end lilypond
+
+The opposite of @code{\accepts} is @code{\denies}; this removes a
+context from the @qq{accepts} list.
@node Explaining the Internals Reference
@section Explaining the Internals Reference
@menu
-* Navigating the program reference::
-* Layout interfaces::
-* Determining the grob property::
-* Naming conventions::
+* Navigating the program reference::
+* Layout interfaces::
+* Determining the grob property::
+* Naming conventions::
@end menu
@node Navigating the program reference
* Input modes::
* Direction and placement::
* Distances and measurements::
+* Staff symbol properties::
* Spanners::
* Visibility of objects::
* Line styles::
@c TODO Add table showing these
-@strong{Context layout}
-
-Contexts are positioned in a system from top to bottom in the
-order in which they are encountered. Note, however, that a
-context will be created implicitly if a command is encountered
-when there is no suitable context available to contain it.
+@strong{Context layout order}
-@c TODO Add example ?
+Contexts are normally positioned in a system from top to bottom
+in the order in which they are encountered. Note, however, that
+a context will be created implicitly if a command is encountered
+when there is no suitable context available to contain it. When
+contexts are nested, the outer context will exclude inner contexts
+which are not included in its @qq{accepts} list; excluded contexts
+will be repositioned below the outer context.
-The default order in which contexts are laid out can be changed,
-see @ref{Aligning contexts}
+The default order in which contexts are laid out and the
+@qq{accepts} list can be changed, see @ref{Aligning contexts}.
@strong{Articulation direction indicators}
other page layout details, and are by default specified in
millimeters. Distances may be specified in other units by
following the quantity by @code{\mm}, @code{\cm},
-@code{\in}@tie{}(inches), or @code{\pt}@tie{}(points - 1/72 inch).
+@code{\in}@tie{}(inches), or @code{\pt}@tie{}(points, 1/72.27
+of an inch). Page layout distances can also be specified in
+scalable units (see the following paragraph) by appending
+@code{\staff-space} to the quantity.
Page layout is described in detail in @ref{Page formatting}.
Scaled distances are always specified in units of the staff-space
@ref{Setting the staff size}.
+@node Staff symbol properties
+@subsection Staff symbol properties
+
+@cindex adjusting staff symbol
+@cindex drawing staff symbol
+@cindex staff symbol, setting of
+
+@c TODO Extend or remove this section. See also NR 1.6.2 Staff symbol
+@c Need to think of uses for these properties. Eg 'line-positions
+@c is used in a snippet to thicken centre line.
+@c If retained, add @ref to here in 1.6.2 -td
+
+The vertical position of staff lines and the number of staff lines
+can be defined at the same time. As the following example shows,
+note positions are not influenced by the staff line positions.
+
+@warning{The @code{'line-positions} property overrides the
+@code{'line-count} property. The number of staff lines is
+implicitly defined by the number of elements in the list of values
+for @code{'line-positions}.}
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+ \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
+}
+{ a4 e' f b | d1 }
+@end lilypond
+
+The width of a staff can be modified. The units are staff
+spaces. The spacing of objects inside the staff is not affected by
+this setting.
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+ \override StaffSymbol #'width = #23
+}
+{ a4 e' f b | d1 }
+@end lilypond
+
+
@node Spanners
@subsection Spanners
considerations.
@menu
-* Removing the stencil::
-* Making objects transparent::
-* Painting objects white::
-* Using break-visibility::
-* Special considerations::
+* Removing the stencil::
+* Making objects transparent::
+* Painting objects white::
+* Using break-visibility::
+* Special considerations::
@end menu
beginning of a line. Or to be more precise, before a line break,
where there is no line break, or after a line break.
-Alternatively, seven of the eight combinations may be specified
+Alternatively, these eight combinations may be specified
by pre-defined functions, defined in @file{scm/output-lib.scm},
where the last three columns indicate whether the layout objects
will be visible in the positions shown at the head of the columns:
-@multitable @columnfractions .40 .15 .1 .1 .1
-@c TODO check these more carefully
+@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {yes} {yes} {yes}
@headitem Function @tab Vector @tab Before @tab At no @tab After
@headitem form @tab form @tab break @tab break @tab break
-@item @code{all-invisible} @tab @code{'#(#f #f #f)} @ @ @tab no @tab no @tab no
+@item @code{all-visible} @tab @code{'#(#t #t #t)} @tab yes @tab yes @tab yes
@item @code{begin-of-line-visible} @tab @code{'#(#f #f #t)} @tab no @tab no @tab yes
+@item @code{center-visible} @tab @code{'#(#f #t #f)} @tab no @tab yes @tab no
@item @code{end-of-line-visible} @tab @code{'#(#t #f #f)} @tab yes @tab no @tab no
-@item @code{all-visible} @tab @code{'#(#t #t #t)} @tab yes @tab yes @tab yes
-@c The center-visible function is not defined
-@c @item @code{center-visible} @tab @code{'#(#f #t #f)} @tab no @tab yes @tab no
@item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)} @tab yes @tab yes @tab no
-@item @code{end-of-line-invisible} @tab @code{'#(#f #t #t)} @tab no @tab yes @tab yes
@item @code{center-invisible} @tab @code{'#(#t #f #t)} @tab yes @tab no @tab yes
+@item @code{end-of-line-invisible} @tab @code{'#(#f #t #t)} @tab no @tab yes @tab yes
+@item @code{all-invisible} @tab @code{'#(#f #f #f)} @tab no @tab no @tab no
@end multitable
-The @code{center-visible} function is not pre-defined.
-
The default settings of @code{break-visibility} depend on the
layout object. The following table shows all the layout objects
of interest which are affected by @code{break-visibility} and the
@node Advanced tweaks
@section Advanced tweaks
+This section discusses various approaches to fine tuning the
+appearance of the printed score.
+
@menu
* Aligning objects::
* Vertical grouping of grobs::
* Modifying shapes::
@end menu
+@seealso
+
+Learning Manual:
+@rlearning{Tweaking output},
+@rlearning{Other sources of information}.
+
+Notation Reference:
+@ref{Explaining the Internals Reference},
+@ref{Modifying properties},
+@ref{Interfaces for programmers}.
+
+Installed Files:
+@file{scm/@/define@/-grobs@/.scm}.
+
+Snippets:
+@rlsr{Tweaks and overrides}.
+
+Internals Reference:
+@rinternals{All layout objects}.
+
@node Aligning objects
@subsection Aligning objects
-@node Discussion of specific tweaks
-@section Discussion of specific tweaks
-
-@c TODO What should go in here?
-
projects / lilypond.git / blobdiff