* vim/GNUmakefile: flatten dirs, add GNUmakefile.
* Documentation/user/running.itely: new file.
* lily/include/audio-element.hh (class Audio_element): remove grace_b_
* lily/score-performer.cc (finish): call Translator::finalize ().
+2004-03-05 Han-Wen Nienhuys <hanwen@xs4all.nl>
+
+ * GNUmakefile.in (EXTRA_DIST_FILES): remove VIM stuff.
+
+ * vim/GNUmakefile: flatten dirs, add GNUmakefile.
+
+ * Documentation/user/running.itely: new file.
+
+ * lily/include/audio-element.hh (class Audio_element): remove grace_b_
+
+ * lily/score-performer.cc (finish): call Translator::finalize ().
2004-03-05 Heikki Junes <hjunes@cc.hut.fi>
* GNUmakefile.in: update VIM_FILES.
* Scheme functions::
* Layout property overview::
* Context property overview::
+* Literature list::
@end menu
@include layout-properties.tely
-
+@include literature.itely
Scheme interpreter.
@menu
-* Interpretation context::
-* Scheme integration::
-* Music storage format::
-* Lexical details::
-* Output details::
+* Interpretation context::
+* Scheme integration::
+* Music storage format::
+* Lexical details::
+* Output details::
@end menu
@section Interpretation context
@menu
-* Creating contexts::
-* Default contexts::
-* Context properties::
-* Context evaluation::
-* Defining contexts::
-* Changing contexts locally::
-* Engravers and performers::
-* Defining new contexts::
+* Creating contexts::
+* Default contexts::
+* Context properties::
+* Context evaluation::
+* Defining contexts::
+* Changing contexts locally::
+* Engravers and performers::
+* Defining new contexts::
@end menu
@end ifinfo
@menu
-* Inline Scheme::
-* Input variables and Scheme::
-* Scheme data types::
-* Assignments::
+* Inline Scheme::
+* Input variables and Scheme::
+* Assignments::
@end menu
@node Inline Scheme
-@node Scheme data types
-@subsection Scheme data types
-
-Scheme is used to glue together different program modules. To aid this
-glue function, many LilyPond specific object types can be passed as
-Scheme value.
-
-The following list are all LilyPond specific types, that
-can exist during parsing:
-@table @code
-@item Duration
-@item Input
-@item Moment
-@item Music
-@item Event
-In C++ terms, an @code{Event} is a subtype of @code{Music}. However,
-both have different functions in the syntax.
-@item Music_output_def
-@item Pitch
-@item Score
-@item Translator_def
-@end table
-
-
-During a run, transient objects are also created and destroyed.
-
-@table @code
-@item Grob: short for `Graphical object'.
-@item Scheme_hash_table
-@item Music_iterator
-
-@item Stencil: Device-independent page output object,
-including dimensions.
-
-@item Spring_smob
-
-@item Translator: An object that produces audio objects or Grobs.
-It may be accessed with @code{\applyoutput}.
-
-@item Font_metric: An object representing a font.
-@end table
-
-Many functions are defined to manipulate these data structures. They
-are all listed and documented in the internals manual, see
-@internalsref{All scheme functions}.
-
-
@node Assignments
@subsection Assignments
@cindex Assignments
manipulated using Scheme functions.
@menu
-* Music expressions::
-* Internal music representation::
-* Manipulating music expressions::
+* Music expressions::
+* Internal music representation::
+* Manipulating music expressions::
@end menu
@node Music expressions
produce music is not relevant. In the following example, three chords
are expressed in two different ways:
-@lilypond[fragment,verbatim,center,quote]
+@lilypond[fragment,verbatim,center]
\notes \context Voice {
<<a c'>> <<b d'>> <<c' e'>>
<< { a b c' } { c' d' e' } >>
@node Output details
@section Output details
-LilyPond's default output format is @TeX{}. Using the option @option{-f}
+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
currently none of them work reliably.
-At the beginning of the output file, various global parameters are defined.
-It also contains a large @code{\special} call to define PostScript routines
-to draw items not representable with @TeX{}, mainly slurs and ties. A DVI
-driver must be able to understand such embedded PostScript, or the output
-will be rendered incompletely.
-
-Then the file @file{lilyponddefs.tex} is loaded to define the macros used
-in the code which follows. @file{lilyponddefs.tex} includes various other
-files, partially depending on the global parameters.
+At the beginning of the output file, various global parameters are
+defined. Then the file @file{lilyponddefs.tex} is loaded to define
+the macros used in the code which follows. @file{lilyponddefs.tex}
+includes various other files, partially depending on the global
+parameters.
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
The horizontal dimension of the @code{\hbox} is given by the
@code{linewidth} parameter from LilyPond's @code{\paper} block.
-
After the last system LilyPond emits a stronger variant of
@code{\interscoreline} only if the macro
@code{\lilypondpaperlastpagefill} is not defined (flushing the systems
@noindent
where @code{\baselineskip} is the distance from one text line to the next.
-The code produced by LilyPond should be run through La@TeX{}, not
-plain @TeX{}.
-
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}):
The file @file{foo.tex} has been simply produced with
@example
-lilypond foo.ly
+ lilypond-bin foo.ly
@end example
-It is important to set the @code{indent} parameter to zero in the
-@code{\paper} block of @file{foo.ly}.
-
The call to @code{\lineskip} assures that there is enough vertical space
between the LilyPond box and the surrounding text lines.
* Tutorial:: A tutorial introduction.
* Notation manual:: All notation supported, and how to
produce it.
-* Literature list:: Books about notation and engraving.
+* Using LilyPond:: How it all works.
* Technical manual:: How it all works.
* Invoking LilyPond:: Operation.
* Converting from other formats:: Converting to lilypond source format.
@include introduction.itely
@include tutorial.itely
@include refman.itely
-@include literature.itely
+@include running.itely
@include internals.itely
@include invoking.itexi
@include lilypond-book.itely
@node Literature list
-@chapter Literature list
+@section Literature list
If you need to know more about music notation, here are some
interesting titles to read. The source archive includes a more
the website.
@table @cite
-@item Banter 1987
-Harald Banter, Akkord Lexikon. Schott's S@"{o}hne
-1987. Mainz, Germany ISBN 3-7957-2095-8.
-
-This book is a comprehensive overview of commonly used chords and
-suggests a unification for all different kinds of chord names.
-
@item Ignatzek 1995
Klaus Ignatzek, Die Jazzmethode f@"{u}r Klavier. Schott's S@"{o}hne
1995. Mainz, Germany ISBN 3-7957-5140-3.
A tutorial introduction to playing Jazz on the piano. One of the first
chapters contains an overview of chords in common use for Jazz music.
-
@item Gerou 1996
Tom Gerou and Linda Lusk, Essential Dictionary of Music
A concise, alphabetically ordered list of typesetting and music
(notation) issues which covers most of the normal cases.
-
-@item Hader 1948
-
-Karl Hader, Aus der Werkstatt eines Notenstechers. Waldheim--Eberle
-Verlag, Vienna 1948.
-
-Hader was the chief-engraver of an Austrian engraving firm. This
-beautiful booklet was intended as an introduction for laymen on the
-art of engraving. It contains a step by step, in-depth explanation of
-how to cut and stamp music into zinc plates. It also contains a few
-compactly formulated rules on musical orthography. This book is out of
-print.
-
-
@item Read 1968
Gardner Read, Music Notation: a Manual of Modern Practice.
Taplinger Publishing, New York (2nd edition).
A standard work on music notation.
-
@item Ross 1987
Ted Ross, Teach yourself the art of music engraving and processing.
Hansen House, Miami, Florida 1987.
starts out with a thorough overview of existing traditional notation
practices.
-@item Wanske 1988
-
-Helene Wanske, Musiknotation --- Von der Syntax des Notenstichs zum
-EDV-gesteuerten Notensatz. Schott-Verlag, Mainz 1988. ISBN
-3-7957-2886-x.
-
-A book in two parts: 1. A very thorough overview of engraving
-practices of various craftsmen. It includes detailed specs of
-characters, dimensions etc. 2. a thorough overview of a anonymous
-automated system, which must be antiquated by now. EDV means
-E(lektronischen) D(aten)v(erarbeitung), electronic data processing.
-
-
@end table
* Ancient notation::
* Contemporary notation::
* Special notation::
-* Tuning output::
-* Text markup::
-* Global layout::
-* Sound::
@end menu
@c FIXME: Note entry vs Music entry at top level menu is confusing.
(`@code{,}') characters. Each @code{'} raises the pitch by one
octave; each @code{,} lowers the pitch by an octave:
-@lilypond[fragment,verbatim,center]
+@lilypond[fragment,verbatim]
c' c'' es' g' as' gisis' ais'
@end lilypond
lengths:
@cindex @code{.}
-@lilypond[fragment,verbatim,center]
+@lilypond[fragment,verbatim]
a' b' c''8 b' a'4 a'4. b'4.. c'8.
@end lilypond
@cindex @code{r}
slurs, which indicate articulation, or phrasing slurs, which indicate
musical phrasing. A tie is entered using the tilde symbol `@code{~}':
-@lilypond[fragment,verbatim,center]
+@lilypond[fragment,verbatim]
e' ~ e' <c' e' g'> ~ <c' e' g'>
@end lilypond
to the augmentation dot; in the following example there are two ways of
notating exactly the same concept:
@c
-@lilypond[fragment,raggedright,quote]
+@lilypond[fragment,raggedright]
\time 3/4 c'2. c'2 ~ c'4
@end lilypond
If you need to tie a lot of notes over bars, it may be easier to use automatic
notes have the length of 2, so the notes are 2/3 of their written
length:
-@lilypond[fragment,verbatim,center]
+@lilypond[fragment,verbatim]
g'4 \times 2/3 {c'4 c' c'} d'4 d'4
@end lilypond
predecessor of the first note of @var{musicexpr}.
Here is the relative mode shown in action:
-@lilypond[fragment,raggedright,verbatim,center]
+@lilypond[fragment,raggedright,verbatim]
\relative c'' {
b c d c b c bes a
}
@end lilypond
Octave changing marks are used for intervals greater than a fourth:
-@lilypond[fragment,verbatim,center]
+@lilypond[fragment,verbatim]
\relative c'' {
c g c f, c' a, e'' }
@end lilypond
If the preceding item is a chord, the first note of the chord is used
to determine the first note of the next chord:
-@lilypond[fragment,verbatim,center]
+@lilypond[fragment,verbatim]
\relative c' {
c <c e g>
<c' e g>
end at 3 eights; the third beam can only be corrected by specifying
manual beaming.
-@lilypond[raggedright,fragment,relative,noverbatim,quote]
+@lilypond[raggedright,fragment,relative,noverbatim]
#(override-auto-beam-setting '(end * * * *) 3 8)
% rather show case where it goes wrong
%\time 12/8 c'8 c c c16 c c c c c c[ c c c] c8[ c] c4
This leads to some weird and often unwanted results
because accidentals from one voice do not get canceled in other
voices:
-@lilypond[raggedright,relative,fragment,verbatim,quote]
+@lilypond[raggedright,relative,fragment,verbatim]
\context Staff <<
#(set-accidental-style 'voice)
<<
@syntax
They are entered using parentheses:
-@lilypond[relative=1,fragment,verbatim,center]
+@lilypond[relative=1,fragment,verbatim]
f( g)( a) a8 b( a4 g2 f4)
<c e>2( <b d>2)
@end lilypond
indicate a musical sentence. It is started using @code{\(} and @code{\)}
respectively:
-@lilypond[fragment,verbatim,center,relative]
+@lilypond[fragment,verbatim,relative]
\time 6/4 c'\( d( e) f( e) d\)
@end lilypond
with @code{\!}. Because these marks are bound to notes, if you must
use spacer notes if multiple marks during one note are needed:
-@lilypond[fragment,verbatim,center,quote]
+@lilypond[fragment,verbatim]
c''\< c''\! d''\decr e''\rced
<< f''1 { s4 s4\< s4\! \> s4\! } >>
@end lilypond
length is omitted, then then the last value (stored in
@code{tremoloFlags}) is used:
-@lilypond[verbatim,fragment,center]
+@lilypond[verbatim,fragment]
c'2:8 c':32 | c': c': |
@end lilypond
@internalsref{DrumStaff} and @internalsref{DrumVoice} contexts:
@c
-@lilypond[raggedright,verbatim,quote]
+@lilypond[raggedright,verbatim]
up = \drums { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat }
down = \drums { bassdrum4 snare8 bd r bd sn4 }
\score {
point), and it looks ahead skipping over rests to switch in
advance. Here is a practical example:
-@lilypond[verbatim,raggedright,quote]
+@lilypond[verbatim,raggedright]
\score { \notes \context PianoStaff <<
\context Staff = "up" {
\autochange \new Voice \relative c' {
names. It is introduced by the keyword @code{\chords}.
In chords mode, a chord is entered by the root, which is entered
like a common pitch:
-@lilypond[fragment,verbatim,quote,relative=1]
+@lilypond[fragment,verbatim,relative=1]
\chords { es4. d8 c2 }
@end lilypond
@cindex chord entry
Other chords may be entered by suffixing a colon, and introducing a
modifier, and optionally, a number:
@c
-@lilypond[fragment,verbatim,quote]
+@lilypond[fragment,verbatim]
\chords { e1:m e1:7 e1:m7 }
@end lilypond
The first number following the root is taken to be the `type' of the
to a chord. Additions are added after the number following
the colon, and are separated by dots:
@c
-@lilypond[verbatim,fragment,quote]
+@lilypond[verbatim,fragment]
\chords { c:5.6 c:3.7.8 c:3.6.13 }
@end lilypond
Chord steps can be altered by suffixing a @code{-} or @code{+} sign
to the number:
-@lilypond[verbatim,fragment,quote]
+@lilypond[verbatim,fragment]
\chords { c:7+ c:5+.3- c:3-.5-.7- }
@end lilypond
Removals are specified similarly, and are introduced by a caret. They
An inversion (putting one pitch of the chord on the bottom), as well
as bass notes, can be specified by appending
@code{/}@var{pitch} to the chord:
-@lilypond[fragment,verbatim,center]
+@lilypond[fragment,verbatim]
\chords { c1 c/g c/f }
@end lilypond
@cindex @code{/+}
A bass note can be added instead of transposed out of the chord,
by using @code{/+}@var{pitch}.
-@lilypond[fragment,verbatim,center]
+@lilypond[fragment,verbatim]
\chords { c1 c/+g c/+f }
@end lilypond
the letters. Printing the PostScript file obtained does produce the
correct result.
-
-
-@node Tuning output
-@section Tuning output
-
-There are situations where default layout decisions are not
-sufficient. In this section we discuss ways to override these
-defaults.
-
-Formatting is internally done by manipulating so called objects
-(graphic objects). Each object carries with it a set of properties
-(object or layout properties) specific to that object. For example, a
-stem object has properties that specify its direction, length and
-thickness.
-
-The most direct way of tuning the output is by altering the values of
-these properties. There are two ways of doing that: first, you can
-temporarily change the definition of one type of object, thus
-affecting a whole set of objects. Second, you can select one specific
-object, and set a layout property in that object.
-
-Do not confuse layout properties with translation
-properties. Translation properties always use a mixed caps style
-naming, and are manipulated using @code{\set} and @code{\unset}:
-@example
- \set Context.propertyName = @var{value}
-@end example
-
-Layout properties are use Scheme style variable naming, i.e. lower
-case words separated with dashes. They are symbols, and should always
-be quoted using @code{#'}. For example, this could be an imaginary
-layout property name:
-@example
- #'layout-property-name
-@end example
-
-@seealso
-
-The introduction of the @ref{Technical manual} gives a more in-depth
-treatment of the difference between translation and layout.
-
-@menu
-* Tuning objects::
-* Constructing a tweak::
-* Applyoutput::
-* Font selection::
-@end menu
-
-
-
-@node Tuning objects
-@subsection Tuning objects
-
-@cindex object description
-
-The definition of an object is a list of default object
-properties. For example, the definition of the Stem object (available
-in @file{scm/define-grobs.scm}), includes the following definitions
-for @internalsref{Stem}:
-
-@example
- (thickness . 1.3)
- (beamed-lengths . (3.5 3.5 3.5 4.5 5.0))
- (Y-extent-callback . ,Stem::height)
- @var{...}
-@end example
-
-
-Adding variables on top of this existing definition overrides the
-system default, and alters the resulting appearance of the layout
-object.
-
-@syntax
-
-
-Changing a variable for only one object is commonly achieved with
-@code{\once}:
-
-@example
-\once \override @var{context}.@var{objectname}
- @var{symbol} = @var{value}
-@end example
-Here @var{symbol} is a Scheme expression of symbol type, @var{context}
-and @var{objectname} is a string and @var{value} is a Scheme expression.
-This command applies a setting only during one moment in the score.
-
-In the following example, only one @internalsref{Stem} object is
-changed from its original setting:
-
-@lilypond[verbatim,fragment,relative=1]
- c4
- \once \override Voice.Stem #'thickness = #4
- c4
- c4
-@end lilypond
-@cindex @code{\once}
-
-For changing more objects, the same command, without @code{\once} can
-be used:
-@example
-\override @var{context}.@var{objectname} @var{symbol} = @var{value}
-@end example
-This command adds @code{@var{symbol} = @var{value}} to the definition
-of @var{objectname} in the context @var{context}, and this definition
-stays in place until it is removed.
-
-An existing definition may be removed by the following command:
-@c
-@example
-\property @var{context}.@var{objectname} \revert @var{symbol}
-@end example
-@c
-
-Some examples:
-@lilypond[verbatim,quote]
-c'4 \override Stem #'thickness = #4.0
-c'4
-c'4 \revert Stem #'thickness
-c'4
-@end lilypond
-
-The following example gives exactly the same result as the previous
-one (assuming the system default for stem thickness is 1.3):
-@c
-@lilypond[verbatim,quote]
- c'4 \override Stem #'thickness = #4.0
- c'4
- c'4 \override Stem #'thickness = #1.3
- c'4
-@end lilypond
-
-Reverting a setting which was not set in the first place has no
-effect.
-
-
-@seealso
-
-Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
-@internalsref{PropertySet}, @internalsref{All-backend-properties}, and
-@internalsref{All-layout-objects}.
-
-
-@refbugs
-
-The back-end is not very strict in type-checking object properties.
-Cyclic references in Scheme values for properties can cause hangs
-and/or crashes.
-
-@menu
-* Constructing a tweak::
-* Applyoutput::
-* Font selection::
-* Text markup::
-@end menu
-
-@node Constructing a tweak
-@subsection Constructing a tweak
-
-
-@cindex internal documentation
-@cindex finding graphical objects
-@cindex graphical object descriptions
-@cindex tweaking
-@cindex @code{\override}
-@cindex @code{\set}
-@cindex internal documentation
-
-
-
-Three pieces of information are required to use @code{\override} and
-@code{\set}: the name of the layout object, the context and the name
-of the property. We demonstrate how to glean this information from
-the notation manual and the generated documentation.
-
-The generated documentation is a set of HTML pages which should be
-included if you installed a binary distribution, typically in
-@file{/usr/share/doc/lilypond}. They are also available on the web:
-go to the @uref{http://lilypond.org,LilyPond website}, click
-``Documentation'', select the correct version, and click then
-``Program reference.'' It is advisable to bookmark the local HTML
-files. They will load faster than the ones on the web. If you use the
-version from the web, you must check whether the documentation matches
-the program version: it is generated from the definitions that the
-program uses, and therefore it is strongly tied to the LilyPond
-version.
-
-
-@c [TODO: revise for new site.]
-
-Suppose we want to move the fingering indication in the fragment below:
-
-@lilypond[relative=2,verbatim]
-c-2
-\stemUp
-f
-@end lilypond
-
-If you visit the documentation of @code{Fingering} (in @ref{Fingering
-instructions}), you will notice that there is written:
-
-@quotation
-@seealso
-
-Internals: @internalsref{FingerEvent} and @internalsref{Fingering}.
-
-@end quotation
-
-@separate
-
-@noindent
-In other words, the fingerings once entered, are internally stored as
-@code{FingerEvent} music objects. When printed, a @code{Fingering}
-layout object is created for every @code{FingerEvent}.
-
-The Fingering object has a number of different functions, and each of
-those is captured in an interface. The interfaces are listed under
-@internalsref{Fingering} in the program reference.
-
-
-
-The @code{Fingering} object has a fixed size
-(@internalsref{item-interface}), the symbol is a piece of text
-(@internalsref{text-interface}), whose font can be set
-(@internalsref{font-interface}). It is centered horizontally
-(@internalsref{self-alignment-interface}), it is placed next to other
-objects (@internalsref{side-position-interface}) vertically, and its
-placement is coordinated with other scripts
-(@internalsref{text-script-interface}). It also has the standard
-@internalsref{grob-interface} (grob stands for Graphical object)
-@cindex grob
-@cindex graphical object
-@cindex layout object
-@cindex object, layout
-with all the variables that come with
-it. Finally, it denotes a fingering instruction, so it has
-@internalsref{finger-interface}.
-
-For the vertical placement, we have to look under
-@code{side-position-interface}:
-@quotation
-@code{side-position-interface}
-
- Position a victim object (this one) next to other objects (the
- support). In this case, the property @code{direction} signifies where to put the
- victim object relative to the support (left or right, up or down?)
-@end quotation
-
-@cindex padding
-@noindent
-below this description, the variable @code{padding} is described as
-@quotation
-@table @code
-@item padding
- (dimension, in staff space)
-
- add this much extra space between objects that are next to each
-other. Default value: @code{0.6}
-@end table
-@end quotation
-
-By increasing the value of @code{padding}, we can move away the
-fingering. The following command inserts 3 staff spaces of white
-between the note and the fingering:
-@example
-\once \override Fingering #'padding = #3
-@end example
-
-Inserting this command before the Fingering object is created,
-i.e. before @code{c2}, yields the following result:
-
-@lilypond[relative=2,fragment,verbatim]
-\once \override Fingering
- #'padding = #3
-c-2
-\stemUp
-f
-@end lilypond
-
-The context name @code{Voice} in the example above can be determined
-as follows. In the documentation for @internalsref{Fingering}, it says
-@quotation
-Fingering grobs are created by: @internalsref{Fingering_engraver} @c
-@end quotation
-
-Clicking @code{Fingering_engraver} shows the documentation of
-the module responsible for interpreting the fingering instructions and
-translating them to a @code{Fingering} object. Such a module is called
-an @emph{engraver}. The documentation of the @code{Fingering_engraver}
-says
-@example
-Fingering_engraver is part of contexts: Voice
-@end example
-so tuning the settings for Fingering should be done with
-@example
- \override Fingering @dots{}
-@end example
-
-Of course, the tweak may also done in a larger context than
-@code{Voice}, for example, @internalsref{Staff} or
-@internalsref{Score}.
-
-@seealso
-
-Internals: the program reference also contains alphabetical lists of
-@internalsref{Contexts}, @internalsref{All-layout-objects} and
-@internalsref{Music-expressions}, so you can also find which objects
-to tweak by browsing the internals document.
-
-
-@node Applyoutput
-@subsection Applyoutput
-
-The most versatile way of tuning an object is @code{\applyoutput}. Its
-syntax is
-@example
-\applyoutput @var{proc}
-@end example
-
-@noindent
-where @var{proc} is a Scheme function, taking three arguments.
-
-When interpreted, the function @var{proc} is called for every layout
-object found in the context, with the following arguments:
-@itemize @bullet
-@item the layout object itself,
-@item the context where the layout object was created, and
-@item the context where @code{\applyoutput} is processed.
-@end itemize
-
-
-In addition, the cause of the layout object, i.e. the music
-expression or object that was responsible for creating it, is in the
-object property @code{cause}. For example, for a note head, this is a
-@internalsref{NoteHead} event, and for a @internalsref{Stem} object,
-this is a @internalsref{NoteHead} object.
-
-Here is a simple example of @code{\applyoutput}; it blanks note-heads on the
-center-line:
-@example
-(define (blanker grob grob-origin context)
- (if (and (memq (ly:grob-property grob 'interfaces)
- note-head-interface)
- (eq? (ly:grob-property grob 'staff-position) 0))
-
- (ly:grob-set-property! grob 'transparent #t)))
-@end example
-
-
-
-@node Font selection
-@subsection Font selection
-
-The most common thing to change about the appearance of fonts is their
-size. The font size of any context can be easily changed by setting
-the @code{fontSize} property for that context. Its value is a number:
-negative numbers make the font smaller, positive numbers larger. An
-example is given below:
-@c
-@lilypond[fragment,relative=1,verbatim,quote]
- c4 c4 \set fontSize = #-1
- f4 g4
-@end lilypond
-This command will set @code{font-size} (see below), and does
-not change the size of variable symbols, such as beams or slurs.
-
-One of the uses of @code{fontSize} is to get smaller symbols for cue
-notes. An elaborate example of those is in
-@inputfileref{input/test,cue-notes.ly}.
-
-@cindex magnification
-@cindex cue notes
-
-The font used for printing a object can be selected by setting
-@code{font-name}, e.g.
-@example
- \override Staff.TimeSignature
- #'font-name = #"cmr17"
-@end example
-
-@noindent
-Any font can be used, as long as it is available to @TeX{}. Possible
-fonts include foreign fonts or fonts that do not belong to the
-Computer Modern font family. The size of fonts selected in this way
-can be changed with the @code{font-magnification} property. For
-example, @code{2.0} blows up all letters by a factor 2 in both
-directions.
-
-@cindex font size
-@cindex font magnification
-
-Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
-can also be adjusted with a more fine-grained mechanism. By setting
-the object properties described below, you can select a different font;
-all three mechanisms work for every object that supports
-@code{font-interface}:
-
-
-@table @code
-@item font-family
- is a symbol indicating the general class of the typeface. Supported are
-@code{roman} (Computer Modern), @code{braces} (for piano staff
-braces), @code{music} (the standard music font, including ancient
-glyphs), @code{dynamic} (for dynamic signs) and @code{typewriter}.
-
-@item font-shape
- is a symbol indicating the shape of the font, there are typically several
- font shapes available for each font family. Choices are @code{italic},
- @code{caps} and @code{upright}.
-
-@item font-series
-is a symbol indicating the series of the font. There are typically several
-font series for each font family and shape. Choices are @code{medium}
-and @code{bold}.
-
-@end table
-
-For any of these properties, the value @code{*} (i.e. the symbol
-@code{*}, entered as @code{#'*}), acts as a wildcard. This can be used
-to override default setting, which are always present. For example:
-@example
- \override Lyrics .LyricText #'font-series = #'bold
- \override Lyrics .LyricText #'font-family = #'typewriter
- \override Lyrics .LyricText #'font-shape = #'*
-@end example
-
-@cindex @code{font-style}
-
-The font size is set by modifying the @code{font-size} property. Its
-value is a number indicating the size relative to the standard size.
-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 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 @code{font-size} mechanism does not work for fonts selected
-through @code{font-name}. These may be scaled with
-@code{font-magnification}.
-
-@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}.
-
-@seealso
-
-Init files: @file{ly/declarations-init.ly} contains hints how new
-fonts may be added to LilyPond.
-
-@refbugs
-
-There is no style sheet provided for other fonts besides the @TeX{}
-Computer Modern family.
-
-@cindex font selection
-@cindex font magnification
-@cindex @code{font-interface}
-
-
-@node Text markup
-@section Text markup
-@cindex text markup
-@cindex markup text
-
-
-@cindex typeset text
-
-LilyPond has an internal mechanism to typeset texts. You can access it
-with the keyword @code{\markup}. Within markup mode, you can enter texts
-similar to lyrics: simply enter them, surrounded by spaces:
-@cindex markup
-
-@lilypond[verbatim,fragment,relative=1]
- c1^\markup { hello }
- c1_\markup { hi there }
- c1^\markup { hi \bold there, is \italic anyone home? }
-@end lilypond
-
-@cindex font switching
-
-The markup in the example demonstrates font switching commands. The
-command @code{\bold} and @code{\italic} only apply to the first
-following word; enclose a set of texts with braces to apply a command
-to more words:
-@example
- \markup @{ \bold @{ hi there @} @}
-@end example
-
-@noindent
-For clarity, you can also do this for single arguments, e.g.
-
-@verbatim
- \markup { is \italic { anyone } home }
-@end verbatim
-
-@cindex font size, texts
-
-
-In markup mode you can compose expressions, similar to mathematical
-expressions, XML documents and music expressions. The braces group
-notes into horizontal lines. Other types of lists also exist: you can
-stack expressions grouped with @code{<}, and @code{>} vertically with
-the command @code{\column}. Similarly, @code{\center-align} aligns
-texts by their center lines:
-
-@lilypond[verbatim,fragment,relative=1]
- c1^\markup { \column < a bbbb c > }
- c1^\markup { \center-align < a bbbb c > }
- c1^\markup { \line < a b c > }
-@end lilypond
-
-
-Markups can be stored in variables, and these variables
-may be attached to notes, like
-@verbatim
-allegro = \markup { \bold \large { Allegro } }
-\notes { a^\allegro b c d }
-@end verbatim
-
-
-Some objects have alignment procedures of their own, which cancel out
-any effects of alignments applied to their markup arguments as a
-whole. For example, the @internalsref{RehearsalMark} is horizontally
-centered, so using @code{\mark \markup @{ \left-align .. @}} has no
-effect. Similarly, whole texts over notes cannot be moved vertically
-with @code{\raise}. For moving and aligning complete objects, grob
-properties should be used.
-
-
-
-@seealso
-
-Init files: @file{scm/new-markup.scm}.
-
-
-@refbugs
-
-Text layout is ultimately done by @TeX{}, which does kerning of
-letters. LilyPond does not account for kerning, so texts will be
-spaced slightly too wide.
-
-Syntax errors for markup mode are confusing.
-
-Markup texts cannot be used in the titling of the @code{\header}
-field. Titles are made by La@TeX{}, so La@TeX{} commands should be used
-for formatting.
-
-
-
-@menu
-* Overview of text markup commands::
-* Markup construction in scheme::
-* Markup command definition::
-@end menu
-
-@node Overview of text markup commands
-@subsection Overview of text markup commands
-
-@include markup-commands.tely
-
-@node Markup construction in scheme
-@subsection Markup construction in scheme
-
-@cindex defining markup commands
-
-The @code{markup} macro builds markup expressions in Scheme while
-providing a LilyPond-like syntax. For example,
-@example
-(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
- #:bigger #:line ("foo" "bar" "baz")))
-@end example
-
-@noindent
-is equivalent to:
-@example
-\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
- \bigger @{ foo bar baz @} >
-@end example
-
-@noindent
-This example exposes the main translation rules between regular
-LilyPond markup syntax and scheme markup syntax, which are summed up
-is this table:
-@multitable @columnfractions .5 .5
-@item @b{LilyPond} @tab @b{Scheme}
-@item @code{\command} @tab @code{#:command}
-@item @code{\variable} @tab @code{variable}
-@item @code{@{ ... @}} @tab @code{#:line ( ... )}
-@item @code{\center-align < ... >} @tab @code{#:center ( ... )}
-@item @code{string} @tab @code{"string"}
-@item @code{#scheme-arg} @tab @code{scheme-arg}
-@end multitable
-
-Besides, the whole scheme language is accessible inside the
-@code{markup} macro: thus, one may use function calls inside
-@code{markup} in order to manipulate character strings for
-instance. This proves useful when defining new markup commands (see
-@ref{Markup command definition}).
-
-@refbugs
-
-One can not feed the @code{#:line} (resp @code{#:center},
-@code{#:column}) command with a variable or the result of a function
-call. Eg:
-@lisp
-(markup #:line (fun-that-returns-markups))
-@end lisp
-is illegal. One should use the @code{make-line-markup} (resp
-@code{make-center-markup}, @code{make-column-markup}) function
-instead:
-@lisp
-(markup (make-line-markup (fun-that-returns-markups)))
-@end lisp
-
-@node Markup command definition
-@subsection Markup command definition
-
-New markup commands can be defined thanks to the @code{def-markup-command} scheme macro.
-@lisp
-(def-markup-command (@var{command-name} @var{paper} @var{props} @var{arg1} @var{arg2} ...)
- (@var{arg1-type?} @var{arg2-type?} ...)
- ..command body..)
-
- @var{argi}: i@var{th} command argument
- @var{argi-type?}: a type predicate for the i@var{th} argument
- @var{paper}: the `paper' definition
- @var{props}: a list of alists, containing all active properties.
-@end lisp
-
-As a simple example, we show how to add a @code{\smallcaps} command,
-which selects @TeX{}'s small caps font. Normally, we could select the
-small caps font as follows:
-
-@verbatim
- \markup { \override #'(font-shape . caps) Text-in-caps }
-@end verbatim
-
-This selects the caps font by setting the @code{font-shape} property to
-@code{#'caps} for interpreting @code{Text-in-caps}.
-
-To make the above available as @code{\smallcaps} command, we have to
-define a function using @code{def-markup-command}. The command should
-take a single argument, of markup type. Therefore, the start of the
-definition should read
-@example
- (def-markup-command (smallcaps paper props argument) (markup?)
-@end example
-
-@noindent
-
-What follows is the content of the command: we should interpret
-the @code{argument} as a markup, i.e.
-
-@example
- (interpret-markup paper @dots{} argument)
-@end example
-
-@noindent
-This interpretation should add @code{'(font-shape . caps)} to the active
-properties, so we substitute the the following for the @dots{} in the
-above example:
-
-@example
- (cons (list '(font-shape . caps) ) props)
-@end example
-
-@noindent
-The variable @code{props} is a list of alists, and we prepend to it by
-consing a list with the extra setting.
-
-However, suppose that we are using a font that does not have a
-small-caps variant. In that case, we have to fake the small caps font,
-by setting a string in upcase, with the first letter a little larger:
-
-@example
-#(def-markup-command (smallcaps paper props str) (string?)
- "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
- (interpret-markup paper props
- (make-line-markup
- (map (lambda (s)
- (if (= (string-length s) 0)
- s
- (markup #:large (string-upcase (substring s 0 1))
- #:translate (cons -0.6 0)
- #:tiny (string-upcase (substring s 1)))))
- (string-split str #\Space)))))
-@end example
-
-The @code{smallcaps} command first splits its string argument into
-tokens separated by spaces (@code{(string-split str #\Space)}); for
-each token, a markup is built with the first letter made large and
-upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
-second markup built with the following letters made tiny and upcased
-(@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
-introduces a space between markups on a line, the second markup is
-translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
-the markups built for each token are put in a line
-(@code{(make-line-markup ...)}). Finally, the resulting markup is
-passed to the @code{interpret-markup} function, with the @code{paper}
-and @code{props} arguments.
-
-Finally, suppose that we are typesetting a recitative in an opera, and
-we would like to define a command that will show character names in a
-custom manner. Names should be printed with small caps and translated a
-bit to the left and top. We will define a @code{\character} command
-that takes into account the needed translation, and uses the newly
-defined @code{\smallcaps} command:
-
-@verbatim
-#(def-markup-command (character paper props name) (string?)
- "Print the character name in small caps, translated to the left and
- top. Syntax: \\character #\"name\""
- (interpret-markup paper props
- (markup "" #:translate (cons -4 2) #:smallcaps name)))
-@end verbatim
-
-There is one complication that needs explanation: texts above and below
-the staff are moved vertically to be at a certain distance (the
-@code{padding} property) from the staff and the notes. To make sure
-that this mechanism does not annihilate the vertical effect of our
-@code{#:translate}, we add an empty string (@code{""}) before the
-translated text. Now the @code{""} will be put above the notes, and the
-@code{name} is moved in relation to that empty string. The net effect is
-that the text is moved to the upper left.
-
-The final result is as follows:
-@verbatim
-\score {
- \notes { \fatText
- c''^\markup \character #"Cleopatra"
- e'^\markup \character #"Giulio Cesare"
- }
-}
-@end verbatim
-
-@lilypond[raggedright]
-#(def-markup-command (smallcaps paper props str) (string?)
- "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
- (interpret-markup paper props
- (make-line-markup
- (map (lambda (s)
- (if (= (string-length s) 0)
- s
- (markup #:large (string-upcase (substring s 0 1))
- #:translate (cons -0.6 0)
- #:tiny (string-upcase (substring s 1)))))
- (string-split str #\Space)))))
-
-#(def-markup-command (character paper props name) (string?)
- "Print the character name in small caps, translated to the left and
- top. Syntax: \\character #\"name\""
- (interpret-markup paper props
- (markup "" #:translate (cons -4 0) #:smallcaps name)))
-
-\score {
- \notes { \fatText
- c''^\markup \character #"Cleopatra"
- e'^\markup \character #"Giulio Cesare"
- }
-}
-@end lilypond
-
-
-
-@node Global layout
-@section Global layout
-
-The global layout 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,
-which influences where line breaks breaks are chosen, and thus
-ultimately how many pages a piece of music takes. This section
-explains how to tune the algorithm for spacing.
-
-Globally spoken, this procedure happens in three steps: first,
-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.
-
-
-
-@menu
-* Vertical spacing::
-* Horizontal spacing::
-* Font Size::
-* Line breaking::
-* Page layout::
-@end menu
-
-
-@node Vertical spacing
-@subsection Vertical spacing
-
-@cindex vertical spacing
-@cindex distance between staves
-@cindex staff distance
-@cindex between staves, distance
-@cindex staffs per page
-@cindex space between staves
-
-The height of each system is determined automatically by LilyPond, to
-keep 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{minimumVerticalExtent}. It takes a pair
-of numbers, so if you want to make it smaller from its, then you could
-set
-@example
- \set Staff.minimumVerticalExtent = #'(-4 . 4)
-@end example
-This sets the vertical size of the current staff to 4 staff spaces on
-either side of the center staff line. The argument of
-@code{minimumVerticalExtent} 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 piano staves are handled a little differently: to make cross-staff
-beaming work correctly, it is necessary that the distance between staves
-is fixed beforehand. This is also done with a
-@internalsref{VerticalAlignment} object, created in
-@internalsref{PianoStaff}. In this object the distance between the
-staves is fixed by setting @code{forced-distance}. If you want to
-override this, use a @code{\translator} block as follows:
-@example
- \paper @{
- \translator @{
- \PianoStaffContext
- \override VerticalAlignment #'forced-distance = #9
- @}
- @dots{}
- @}
-@end example
-This would bring the staves together at a distance of 9 staff spaces,
-measured from the center line of each staff.
-
-@seealso
-
-Internals: Vertical alignment of staves is handled by the
-@internalsref{VerticalAlignment} object.
-
-
-
-
-@node Horizontal spacing
-@subsection Horizontal Spacing
-
-The spacing engine translates differences in durations into
-stretchable distances (``springs'') of differing 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[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8
-c8 c4 c4 c4
-@end lilypond
-
-Normally, @code{shortest-duration-space} is set to 1.2, which is the
-width of a note head, and @code{shortest-duration-space} is set to
-2.0, meaning that the shortest note gets 2 NHW (i.e. 2 times
-@code{shortest-duration-space}) of space. For normal notes, this space
-is always 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
-32th 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 the most commonly found shortest note. Notes that are even
-shorter this 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[fragment,verbatim,relative=2]
- c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
-@end lilypond
-
-The most common shortest duration is determined as follows: in every
-measure, the shortest duration is determined. The most common short
-duration, is taken as the basis for the spacing, with the stipulation
-that this shortest duration should always be equal to or shorter than
-1/8th note. The shortest duration is printed when you run lilypond
-with @code{--verbose}. 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 1/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}
-
-In the introduction it was explained that stem directions influence
-spacing. This is controlled with @code{stem-spacing-correction}
-property in @internalsref{NoteSpacing}, which are generated for every
-@internalsref{Voice} context. The @code{StaffSpacing} object
-(generated at @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
- \score { \notes {
- 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|
- }
- \paper { raggedright = ##t } }
-@end lilypond
-
-@cindex SpacingSpanner, overriding properties
-
-Properties of the @internalsref{SpacingSpanner} must be overridden
-from the @code{\paper} block, since the @internalsref{SpacingSpanner} is
-created before any property commands are interpreted.
-@example
-\paper @{ \translator @{
- \ScoreContext
- SpacingSpanner \override #'spacing-increment = #3.0
-@} @}
-@end example
-
-
-@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.
-
-
-
-@node Font Size
-@subsection Font size
-@cindex font size, setting
-@cindex staff size, setting
-@cindex @code{paper} file
-
-The Feta font provides musical symbols at eight seven different
-sizes. Each font is tuned for a different staff size: at smaller sizes
-the font gets heavier, to match the relatively heavier staff lines.
-The recommended font sizes are listed in the following table:
-
-@multitable @columnfractions .25 .25 .25 .25
-
-@item @b{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.60pt
-@tab 4.4mm
-@tab
-
-@item feta14
-@tab 14.14pt
-@tab 5.0mm
-@tab
-
-@item feta16
-@tab 15.87pt
-@tab 5.6mm
-@tab
-
-@item feta18
-@tab 17.82pt
-@tab 6.3mm
-@tab song books
-
-@item feta20
-@tab 17.82pt
-@tab 7.0mm
-@tab standard parts
-
-@item feta23
-@tab 22.45 pt
-@tab 7.9mm
-@tab
-
-@item feta20
-@tab 25.2 pt
-@tab 8.9mm
-@tab
-@c modern rental material ?
-
-@end multitable
-
-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 size for individual
-staffs. The size of individual staffs are relative to the global size,
-which can be set in the following manner:
-
-@example
- #(set-global-staff-size 14)
-@end example
-
-This sets the global default size to 14pt staff height, and scales all
-fonts accordingly.
-
-
-
-@node Line breaking
-@subsection Line breaking
-
-@cindex line breaks
-@cindex breaking lines
-
-Line breaks are normally computed automatically. They are chosen such
-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}, @code{\noBreak}
-@cindex @code{\break}
-@cindex @code{\noBreak}
-
-@seealso
-
-Internals: @internalsref{BreakEvent}.
-
-
-@node Page layout
-@subsection Page layout
-
-@cindex page breaks
-@cindex breaking pages
-
-@cindex @code{indent}
-@cindex @code{linewidth}
-
-The most basic settings influencing the spacing are @code{indent} and
-@code{linewidth}. They are set in the @code{\paper} block. They
-control the indentation of the first line of music, and the lengths of
-the lines.
-
-If @code{raggedright} is set to true in the @code{\paper}
-block, then the lines are justified at their natural length. This
-useful for short fragments, and for checking how tight the natural
-spacing is.
-
-@cindex page layout
-@cindex vertical spacing
-
-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
-variable @code{textheight} sets the total height of the music on each
-page. 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 a 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}
-
-To change the paper size, use the following Scheme code:
-@example
- \paper@{
- #(set-paper-size "a4")
- @}
-@end example
-
-
-@refcommands
-
-@cindex @code{\newpage}
-@code{\newpage}.
-
-
-@seealso
-
-In this manual: @ref{Invoking lilypond}.
-
-Examples: @inputfileref{input/regression,between-systems.ly}.
-
-Internals: @internalsref{NonMusicalPaperColumn}.
-
-@refbugs
-
-LilyPond has no concept of page layout, which makes it difficult to
-reliably choose page breaks in longer pieces.
-
-
-
-
-@node Sound
-@section Sound
-@cindex Sound
-
-Entered music can also be converted to MIDI output. The performance
-is good enough for proof-hearing the music for errors.
-
-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 extremities. 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}.
-
-@refbugs
-
-Many musically interesting effects, such as swing, articulation,
-slurring, etc., are not translated to MIDI.
-
-Since slurs are not interpreted, @code{\lyricsto} and
-@code{\addlyrics} sections will be interpreted wrongly.
-
-The MIDI output allocates a channel for each Staff, and one for global
-settings. Hence, the MIDI file should not have more than 15 staves
-(or 14 if you do not use drums).
-
-
-@menu
-* MIDI block::
-* MIDI instrument names::
-@end menu
-
-
-@node MIDI block
-@subsection MIDI block
-@cindex MIDI block
-
-
-The MIDI block is analogous to the paper 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
-
-Assignments in the @code{\midi} block are not allowed.
-
-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
-\paper 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}.
-
-@refbugs
-
-If the selected string does not exactly match, then the default is
-used, which is the Grand Piano.
-
--- /dev/null
+@node Using LilyPond
+@chapter Using LilyPond
+
+@menu
+* Setting variables::
+* Fine tuning layout::
+* Tuning output::
+* Text markup::
+* Global layout::
+* Sound::
+@end menu
+
+@node Setting variables
+@section Setting variables
+
+When the music is converted from notes to print it is interpreted
+in left-to-right order. This is similar to what happens when we read
+music. During this step context-sensitive information such as the
+accidentals to print, and where bar lines must be placed, are stored in
+variables. These variables are called @emph{context properties}.
+The properties can also be manipulated from input files. Consider this input:
+@example
+\set Staff.autoBeaming = ##f
+@end example
+
+@noindent
+It sets the property named @code{autoBeaming} in the current staff at
+this point in the music to @code{##f}, which means `false'. This
+property controls whether beams are printed automatically:
+@c
+@lilypond[relative=1,fragment,verbatim]
+ c8 c c c
+ \set Staff.autoBeaming = ##f
+ c8 c c c
+@end lilypond
+
+@noindent
+LilyPond includes a built-in programming language, namely, a dialect
+of Scheme. The argument to @code{\set}, @code{##f}, is an
+expression in that language. The first hash-mark signals that a piece
+of Scheme code follows. The second hash character is part of the
+boolean value true (@code{#t}). Values of other types may be
+entered as follows:
+@itemize @bullet
+@item a string, enclosed in double quotes, for example,
+@example
+ \set Staff.instrument = #"French Horn"
+@end example
+@item a boolean: either @code{#t} or @code{#f}, for true and false
+respectively, e.g.
+@example
+ \set autoBeaming = ##f
+ \set Score.skipBars = ##t
+@end example
+
+@item a number, such as
+@example
+ \set Score.currentBarNumber = #20
+@end example
+
+@item a symbol, which is introduced by a quote character, as in
+@example
+ \set Staff.crescendoSpanner = #'dashed-line
+@end example
+
+@item a pair, which is also introduced by a quote character, like in
+the following statements, which set properties to the pairs (-7.5, 6)
+and (3, 4) respectively:
+
+@example
+ \set Staff.minimumVerticalExtent = #'(-7.5 . 6)
+ \set Staff.timeSignatureFraction = #'(3 . 4)
+@end example
+
+@item a list, which is also introduced by a quote character. In the
+following example, the @code{breakAlignOrder} property is set to a
+list of symbols:
+@example
+ \set Score.breakAlignOrder =
+ #'(left-edge time-signature key-signatures)
+@end example
+
+
+@end itemize
+
+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
+@ifhtml
+@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
+@end ifhtml
+@ifnothtml
+tips-and-tricks
+@end ifnothtml
+examples.
+
+
+@node Fine tuning layout
+@section Fine tuning layout
+
+Sometimes it is necessary to change music layout by hand. When music
+is formatted, layout objects are created for each symbol. For
+example, every clef and every note head is represented by a layout
+object. These layout objects also carry variables, which we call
+@emph{layout properties}. By changing these variables from their
+values, we can alter the look of a formatted score:
+
+@lilypond[verbatim,relative]
+ c4
+ \override Stem #'thickness = #3.0
+ c4 c4 c4
+@end lilypond
+
+@noindent
+In the example shown here, the layout property @code{thickness} (a
+symbol) is set to 3 in the @code{Stem} layout objects of the current
+As a result, the notes following @code{\override} have thicker
+stems.
+
+For the most part, a manual override is needed only on a case by
+case basis and not for all subsequent instances of the altered
+property. To accomplish this, simply prefix @code{\once} to the
+@code{\override} statement and the override will apply only once,
+immediately reverting to its default setting, i.e.
+
+@example
+ \once \override Stem #'thickness = #3.0
+@end example
+
+@lilypond[relative]
+ c4
+ \once \override Stem #'thickness = #3.0
+ c4 c4 c4
+@end lilypond
+
+@noindent
+Some overrides are so common that predefined commands are provided as
+a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
+commands are described in
+@ifhtml
+the
+@end ifhtml
+@ref{Notation manual}, under the sections for slurs and stems
+respectively.
+
+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:
+
+@itemize @bullet
+@item The @code{extra-offset} property, which
+@cindex @code{extra-offset}
+has a pair of numbers as value, moves around objects in the printout.
+The first number controls left-right movement; a positive number will
+move the object to the right. The second number controls up-down
+movement; a positive number will move it higher. The units of these
+offsets are staff-spaces. The @code{extra-offset} property is a
+low-level feature: the formatting engine is completely oblivious to
+these offsets.
+
+In the following example, the second fingering is moved a little to
+the left, and 1.8 staff space downwards:
+
+@cindex setting object properties
+
+@lilypond[relative=1,verbatim]
+\stemUp
+f-5
+\once \override Fingering
+ #'extra-offset = #'(-0.3 . -1.8)
+f-5
+@end lilypond
+
+@item
+Setting the @code{transparent} property will cause an object to be printed
+in `invisible ink': the object is not printed, but all its other
+behavior is retained. The object still takes up space, it takes part in
+collisions, and slurs, and ties and beams can be attached to it.
+
+@cindex transparent objects
+@cindex removing objects
+@cindex invisible objects
+The following example demonstrates how to connect different voices
+using ties. Normally, ties only connect two notes in the same
+voice. By introducing a tie in a different voice, and blanking a stem
+in that voice, the tie appears to cross voices:
+
+@lilypond[fragment,relative=1,verbatim]
+ c4 << {
+ \once \override Stem #'transparent = ##t
+ b8~ b8
+ } \\ {
+ b[ g8]
+ } >>
+@end lilypond
+
+@item
+The @code{padding} property for objects with
+@cindex @code{padding}
+@code{side-position-interface} can be set to increase distance between
+symbols that are printed above or below notes. We only give an
+example; a more elaborate explanation is in @ref{Constructing a
+tweak}:
+
+@lilypond[relative=1,verbatim]
+ c2\fermata
+ \override Script #'padding = #3
+ b2\fermata
+@end lilypond
+
+@end itemize
+
+More specific overrides are also possible. The notation manual
+discusses in depth how to figure out these statements for yourself, in
+@ref{Tuning output}.
+
+
+
+
+@node Tuning output
+@section Tuning output
+
+There are situations where default layout decisions are not
+sufficient. In this section we discuss ways to override these
+defaults.
+
+Formatting is internally done by manipulating so called objects
+(graphic objects). Each object carries with it a set of properties
+(object or layout properties) specific to that object. For example, a
+stem object has properties that specify its direction, length and
+thickness.
+
+The most direct way of tuning the output is by altering the values of
+these properties. There are two ways of doing that: first, you can
+temporarily change the definition of one type of object, thus
+affecting a whole set of objects. Second, you can select one specific
+object, and set a layout property in that object.
+
+Do not confuse layout properties with translation
+properties. Translation properties always use a mixed caps style
+naming, and are manipulated using @code{\set} and @code{\unset}:
+@example
+ \set Context.propertyName = @var{value}
+@end example
+
+Layout properties are use Scheme style variable naming, i.e. lower
+case words separated with dashes. They are symbols, and should always
+be quoted using @code{#'}. For example, this could be an imaginary
+layout property name:
+@example
+ #'layout-property-name
+@end example
+
+@seealso
+
+The introduction of the @ref{Technical manual} gives a more in-depth
+treatment of the difference between translation and layout.
+
+@menu
+* Tuning objects::
+* Constructing a tweak::
+* Applyoutput::
+* Font selection::
+@end menu
+
+
+
+@node Tuning objects
+@subsection Tuning objects
+
+@cindex object description
+
+The definition of an object is a list of default object
+properties. For example, the definition of the Stem object (available
+in @file{scm/define-grobs.scm}), includes the following definitions
+for @internalsref{Stem}:
+
+@example
+ (thickness . 1.3)
+ (beamed-lengths . (3.5 3.5 3.5 4.5 5.0))
+ (Y-extent-callback . ,Stem::height)
+ @var{...}
+@end example
+
+
+Adding variables on top of this existing definition overrides the
+system default, and alters the resulting appearance of the layout
+object.
+
+@syntax
+
+
+Changing a variable for only one object is commonly achieved with
+@code{\once}:
+
+@example
+\once \override @var{context}.@var{objectname}
+ @var{symbol} = @var{value}
+@end example
+Here @var{symbol} is a Scheme expression of symbol type, @var{context}
+and @var{objectname} is a string and @var{value} is a Scheme expression.
+This command applies a setting only during one moment in the score.
+
+In the following example, only one @internalsref{Stem} object is
+changed from its original setting:
+
+@lilypond[verbatim,fragment,relative=1]
+ c4
+ \once \override Voice.Stem #'thickness = #4
+ c4
+ c4
+@end lilypond
+@cindex @code{\once}
+
+For changing more objects, the same command, without @code{\once} can
+be used:
+@example
+\override @var{context}.@var{objectname} @var{symbol} = @var{value}
+@end example
+This command adds @code{@var{symbol} = @var{value}} to the definition
+of @var{objectname} in the context @var{context}, and this definition
+stays in place until it is removed.
+
+An existing definition may be removed by the following command:
+@c
+@example
+\property @var{context}.@var{objectname} \revert @var{symbol}
+@end example
+@c
+
+Some examples:
+@lilypond[verbatim]
+c'4 \override Stem #'thickness = #4.0
+c'4
+c'4 \revert Stem #'thickness
+c'4
+@end lilypond
+
+The following example gives exactly the same result as the previous
+one (assuming the system default for stem thickness is 1.3):
+@c
+@lilypond[verbatim]
+ c'4 \override Stem #'thickness = #4.0
+ c'4
+ c'4 \override Stem #'thickness = #1.3
+ c'4
+@end lilypond
+
+Reverting a setting which was not set in the first place has no
+effect.
+
+
+@seealso
+
+Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
+@internalsref{PropertySet}, @internalsref{All-backend-properties}, and
+@internalsref{All-layout-objects}.
+
+
+@refbugs
+
+The back-end is not very strict in type-checking object properties.
+Cyclic references in Scheme values for properties can cause hangs
+and/or crashes.
+
+@menu
+* Constructing a tweak::
+* Applyoutput::
+* Font selection::
+* Text markup::
+@end menu
+
+@node Constructing a tweak
+@subsection Constructing a tweak
+
+
+@cindex internal documentation
+@cindex finding graphical objects
+@cindex graphical object descriptions
+@cindex tweaking
+@cindex @code{\override}
+@cindex @code{\set}
+@cindex internal documentation
+
+
+
+Three pieces of information are required to use @code{\override} and
+@code{\set}: the name of the layout object, the context and the name
+of the property. We demonstrate how to glean this information from
+the notation manual and the generated documentation.
+
+The generated documentation is a set of HTML pages which should be
+included if you installed a binary distribution, typically in
+@file{/usr/share/doc/lilypond}. They are also available on the web:
+go to the @uref{http://lilypond.org,LilyPond website}, click
+``Documentation'', select the correct version, and click then
+``Program reference.'' It is advisable to bookmark the local HTML
+files. They will load faster than the ones on the web. If you use the
+version from the web, you must check whether the documentation matches
+the program version: it is generated from the definitions that the
+program uses, and therefore it is strongly tied to the LilyPond
+version.
+
+
+@c [TODO: revise for new site.]
+
+Suppose we want to move the fingering indication in the fragment below:
+
+@lilypond[relative=2,verbatim]
+c-2
+\stemUp
+f
+@end lilypond
+
+If you visit the documentation of @code{Fingering} (in @ref{Fingering
+instructions}), you will notice that there is written:
+
+@quotation
+@seealso
+
+Internals: @internalsref{FingerEvent} and @internalsref{Fingering}.
+
+@end quotation
+
+@separate
+
+@noindent
+In other words, the fingerings once entered, are internally stored as
+@code{FingerEvent} music objects. When printed, a @code{Fingering}
+layout object is created for every @code{FingerEvent}.
+
+The Fingering object has a number of different functions, and each of
+those is captured in an interface. The interfaces are listed under
+@internalsref{Fingering} in the program reference.
+
+
+
+The @code{Fingering} object has a fixed size
+(@internalsref{item-interface}), the symbol is a piece of text
+(@internalsref{text-interface}), whose font can be set
+(@internalsref{font-interface}). It is centered horizontally
+(@internalsref{self-alignment-interface}), it is placed next to other
+objects (@internalsref{side-position-interface}) vertically, and its
+placement is coordinated with other scripts
+(@internalsref{text-script-interface}). It also has the standard
+@internalsref{grob-interface} (grob stands for Graphical object)
+@cindex grob
+@cindex graphical object
+@cindex layout object
+@cindex object, layout
+with all the variables that come with
+it. Finally, it denotes a fingering instruction, so it has
+@internalsref{finger-interface}.
+
+For the vertical placement, we have to look under
+@code{side-position-interface}:
+@quotation
+@code{side-position-interface}
+
+ Position a victim object (this one) next to other objects (the
+ support). In this case, the property @code{direction} signifies where to put the
+ victim object relative to the support (left or right, up or down?)
+@end quotation
+
+@cindex padding
+@noindent
+below this description, the variable @code{padding} is described as
+@quotation
+@table @code
+@item padding
+ (dimension, in staff space)
+
+ add this much extra space between objects that are next to each
+other. Default value: @code{0.6}
+@end table
+@end quotation
+
+By increasing the value of @code{padding}, we can move away the
+fingering. The following command inserts 3 staff spaces of white
+between the note and the fingering:
+@example
+\once \override Fingering #'padding = #3
+@end example
+
+Inserting this command before the Fingering object is created,
+i.e. before @code{c2}, yields the following result:
+
+@lilypond[relative=2,fragment,verbatim]
+\once \override Fingering
+ #'padding = #3
+c-2
+\stemUp
+f
+@end lilypond
+
+The context name @code{Voice} in the example above can be determined
+as follows. In the documentation for @internalsref{Fingering}, it says
+@quotation
+Fingering grobs are created by: @internalsref{Fingering_engraver} @c
+@end quotation
+
+Clicking @code{Fingering_engraver} shows the documentation of
+the module responsible for interpreting the fingering instructions and
+translating them to a @code{Fingering} object. Such a module is called
+an @emph{engraver}. The documentation of the @code{Fingering_engraver}
+says
+@example
+Fingering_engraver is part of contexts: Voice
+@end example
+so tuning the settings for Fingering should be done with
+@example
+ \override Fingering @dots{}
+@end example
+
+Of course, the tweak may also done in a larger context than
+@code{Voice}, for example, @internalsref{Staff} or
+@internalsref{Score}.
+
+@seealso
+
+Internals: the program reference also contains alphabetical lists of
+@internalsref{Contexts}, @internalsref{All-layout-objects} and
+@internalsref{Music-expressions}, so you can also find which objects
+to tweak by browsing the internals document.
+
+
+@node Applyoutput
+@subsection Applyoutput
+
+The most versatile way of tuning an object is @code{\applyoutput}. Its
+syntax is
+@example
+\applyoutput @var{proc}
+@end example
+
+@noindent
+where @var{proc} is a Scheme function, taking three arguments.
+
+When interpreted, the function @var{proc} is called for every layout
+object found in the context, with the following arguments:
+@itemize @bullet
+@item the layout object itself,
+@item the context where the layout object was created, and
+@item the context where @code{\applyoutput} is processed.
+@end itemize
+
+
+In addition, the cause of the layout object, i.e. the music
+expression or object that was responsible for creating it, is in the
+object property @code{cause}. For example, for a note head, this is a
+@internalsref{NoteHead} event, and for a @internalsref{Stem} object,
+this is a @internalsref{NoteHead} object.
+
+Here is a simple example of @code{\applyoutput}; it blanks note-heads on the
+center-line:
+@example
+(define (blanker grob grob-origin context)
+ (if (and (memq (ly:grob-property grob 'interfaces)
+ note-head-interface)
+ (eq? (ly:grob-property grob 'staff-position) 0))
+
+ (ly:grob-set-property! grob 'transparent #t)))
+@end example
+
+
+
+@node Font selection
+@subsection Font selection
+
+The most common thing to change about the appearance of fonts is their
+size. The font size of any context can be easily changed by setting
+the @code{fontSize} property for that context. Its value is a number:
+negative numbers make the font smaller, positive numbers larger. An
+example is given below:
+@c
+@lilypond[fragment,relative=1,verbatim]
+ c4 c4 \set fontSize = #-1
+ f4 g4
+@end lilypond
+This command will set @code{font-size} (see below), and does
+not change the size of variable symbols, such as beams or slurs.
+
+One of the uses of @code{fontSize} is to get smaller symbols for cue
+notes. An elaborate example of those is in
+@inputfileref{input/test,cue-notes.ly}.
+
+@cindex magnification
+@cindex cue notes
+
+The font used for printing a object can be selected by setting
+@code{font-name}, e.g.
+@example
+ \override Staff.TimeSignature
+ #'font-name = #"cmr17"
+@end example
+
+@noindent
+Any font can be used, as long as it is available to @TeX{}. Possible
+fonts include foreign fonts or fonts that do not belong to the
+Computer Modern font family. The size of fonts selected in this way
+can be changed with the @code{font-magnification} property. For
+example, @code{2.0} blows up all letters by a factor 2 in both
+directions.
+
+@cindex font size
+@cindex font magnification
+
+Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
+can also be adjusted with a more fine-grained mechanism. By setting
+the object properties described below, you can select a different font;
+all three mechanisms work for every object that supports
+@code{font-interface}:
+
+
+@table @code
+@item font-family
+ is a symbol indicating the general class of the typeface. Supported are
+@code{roman} (Computer Modern), @code{braces} (for piano staff
+braces), @code{music} (the standard music font, including ancient
+glyphs), @code{dynamic} (for dynamic signs) and @code{typewriter}.
+
+@item font-shape
+ is a symbol indicating the shape of the font, there are typically several
+ font shapes available for each font family. Choices are @code{italic},
+ @code{caps} and @code{upright}.
+
+@item font-series
+is a symbol indicating the series of the font. There are typically several
+font series for each font family and shape. Choices are @code{medium}
+and @code{bold}.
+
+@end table
+
+For any of these properties, the value @code{*} (i.e. the symbol
+@code{*}, entered as @code{#'*}), acts as a wildcard. This can be used
+to override default setting, which are always present. For example:
+@example
+ \override Lyrics .LyricText #'font-series = #'bold
+ \override Lyrics .LyricText #'font-family = #'typewriter
+ \override Lyrics .LyricText #'font-shape = #'*
+@end example
+
+@cindex @code{font-style}
+
+The font size is set by modifying the @code{font-size} property. Its
+value is a number indicating the size relative to the standard size.
+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 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 @code{font-size} mechanism does not work for fonts selected
+through @code{font-name}. These may be scaled with
+@code{font-magnification}.
+
+@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}.
+
+@seealso
+
+Init files: @file{ly/declarations-init.ly} contains hints how new
+fonts may be added to LilyPond.
+
+@refbugs
+
+There is no style sheet provided for other fonts besides the @TeX{}
+Computer Modern family.
+
+@cindex font selection
+@cindex font magnification
+@cindex @code{font-interface}
+
+
+@node Text markup
+@section Text markup
+@cindex text markup
+@cindex markup text
+
+
+@cindex typeset text
+
+LilyPond has an internal mechanism to typeset texts. You can access it
+with the keyword @code{\markup}. Within markup mode, you can enter texts
+similar to lyrics: simply enter them, surrounded by spaces:
+@cindex markup
+
+@lilypond[verbatim,fragment,relative=1]
+ c1^\markup { hello }
+ c1_\markup { hi there }
+ c1^\markup { hi \bold there, is \italic anyone home? }
+@end lilypond
+
+@cindex font switching
+
+The markup in the example demonstrates font switching commands. The
+command @code{\bold} and @code{\italic} only apply to the first
+following word; enclose a set of texts with braces to apply a command
+to more words:
+@example
+ \markup @{ \bold @{ hi there @} @}
+@end example
+
+@noindent
+For clarity, you can also do this for single arguments, e.g.
+
+@verbatim
+ \markup { is \italic { anyone } home }
+@end verbatim
+
+@cindex font size, texts
+
+
+In markup mode you can compose expressions, similar to mathematical
+expressions, XML documents and music expressions. The braces group
+notes into horizontal lines. Other types of lists also exist: you can
+stack expressions grouped with @code{<}, and @code{>} vertically with
+the command @code{\column}. Similarly, @code{\center-align} aligns
+texts by their center lines:
+
+@lilypond[verbatim,fragment,relative=1]
+ c1^\markup { \column < a bbbb c > }
+ c1^\markup { \center-align < a bbbb c > }
+ c1^\markup { \line < a b c > }
+@end lilypond
+
+
+Markups can be stored in variables, and these variables
+may be attached to notes, like
+@verbatim
+allegro = \markup { \bold \large { Allegro } }
+\notes { a^\allegro b c d }
+@end verbatim
+
+
+Some objects have alignment procedures of their own, which cancel out
+any effects of alignments applied to their markup arguments as a
+whole. For example, the @internalsref{RehearsalMark} is horizontally
+centered, so using @code{\mark \markup @{ \left-align .. @}} has no
+effect. Similarly, whole texts over notes cannot be moved vertically
+with @code{\raise}. For moving and aligning complete objects, grob
+properties should be used.
+
+
+
+@seealso
+
+Init files: @file{scm/new-markup.scm}.
+
+
+@refbugs
+
+Text layout is ultimately done by @TeX{}, which does kerning of
+letters. LilyPond does not account for kerning, so texts will be
+spaced slightly too wide.
+
+Syntax errors for markup mode are confusing.
+
+Markup texts cannot be used in the titling of the @code{\header}
+field. Titles are made by La@TeX{}, so La@TeX{} commands should be used
+for formatting.
+
+
+
+@menu
+* Overview of text markup commands::
+* Markup construction in scheme::
+* Markup command definition::
+@end menu
+
+@node Overview of text markup commands
+@subsection Overview of text markup commands
+
+@include markup-commands.tely
+
+@node Markup construction in scheme
+@subsection Markup construction in scheme
+
+@cindex defining markup commands
+
+The @code{markup} macro builds markup expressions in Scheme while
+providing a LilyPond-like syntax. For example,
+@example
+(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
+ #:bigger #:line ("foo" "bar" "baz")))
+@end example
+
+@noindent
+is equivalent to:
+@example
+\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
+ \bigger @{ foo bar baz @} >
+@end example
+
+@noindent
+This example exposes the main translation rules between regular
+LilyPond markup syntax and scheme markup syntax, which are summed up
+is this table:
+@multitable @columnfractions .5 .5
+@item @b{LilyPond} @tab @b{Scheme}
+@item @code{\command} @tab @code{#:command}
+@item @code{\variable} @tab @code{variable}
+@item @code{@{ ... @}} @tab @code{#:line ( ... )}
+@item @code{\center-align < ... >} @tab @code{#:center ( ... )}
+@item @code{string} @tab @code{"string"}
+@item @code{#scheme-arg} @tab @code{scheme-arg}
+@end multitable
+
+Besides, the whole scheme language is accessible inside the
+@code{markup} macro: thus, one may use function calls inside
+@code{markup} in order to manipulate character strings for
+instance. This proves useful when defining new markup commands (see
+@ref{Markup command definition}).
+
+@refbugs
+
+One can not feed the @code{#:line} (resp @code{#:center},
+@code{#:column}) command with a variable or the result of a function
+call. Eg:
+@lisp
+(markup #:line (fun-that-returns-markups))
+@end lisp
+is illegal. One should use the @code{make-line-markup} (resp
+@code{make-center-markup}, @code{make-column-markup}) function
+instead:
+@lisp
+(markup (make-line-markup (fun-that-returns-markups)))
+@end lisp
+
+@node Markup command definition
+@subsection Markup command definition
+
+New markup commands can be defined thanks to the @code{def-markup-command} scheme macro.
+@lisp
+(def-markup-command (@var{command-name} @var{paper} @var{props} @var{arg1} @var{arg2} ...)
+ (@var{arg1-type?} @var{arg2-type?} ...)
+ ..command body..)
+
+ @var{argi}: i@var{th} command argument
+ @var{argi-type?}: a type predicate for the i@var{th} argument
+ @var{paper}: the `paper' definition
+ @var{props}: a list of alists, containing all active properties.
+@end lisp
+
+As a simple example, we show how to add a @code{\smallcaps} command,
+which selects @TeX{}'s small caps font. Normally, we could select the
+small caps font as follows:
+
+@verbatim
+ \markup { \override #'(font-shape . caps) Text-in-caps }
+@end verbatim
+
+This selects the caps font by setting the @code{font-shape} property to
+@code{#'caps} for interpreting @code{Text-in-caps}.
+
+To make the above available as @code{\smallcaps} command, we have to
+define a function using @code{def-markup-command}. The command should
+take a single argument, of markup type. Therefore, the start of the
+definition should read
+@example
+ (def-markup-command (smallcaps paper props argument) (markup?)
+@end example
+
+@noindent
+
+What follows is the content of the command: we should interpret
+the @code{argument} as a markup, i.e.
+
+@example
+ (interpret-markup paper @dots{} argument)
+@end example
+
+@noindent
+This interpretation should add @code{'(font-shape . caps)} to the active
+properties, so we substitute the the following for the @dots{} in the
+above example:
+
+@example
+ (cons (list '(font-shape . caps) ) props)
+@end example
+
+@noindent
+The variable @code{props} is a list of alists, and we prepend to it by
+consing a list with the extra setting.
+
+However, suppose that we are using a font that does not have a
+small-caps variant. In that case, we have to fake the small caps font,
+by setting a string in upcase, with the first letter a little larger:
+
+@example
+#(def-markup-command (smallcaps paper props str) (string?)
+ "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
+ (interpret-markup paper props
+ (make-line-markup
+ (map (lambda (s)
+ (if (= (string-length s) 0)
+ s
+ (markup #:large (string-upcase (substring s 0 1))
+ #:translate (cons -0.6 0)
+ #:tiny (string-upcase (substring s 1)))))
+ (string-split str #\Space)))))
+@end example
+
+The @code{smallcaps} command first splits its string argument into
+tokens separated by spaces (@code{(string-split str #\Space)}); for
+each token, a markup is built with the first letter made large and
+upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
+second markup built with the following letters made tiny and upcased
+(@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
+introduces a space between markups on a line, the second markup is
+translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
+the markups built for each token are put in a line
+(@code{(make-line-markup ...)}). Finally, the resulting markup is
+passed to the @code{interpret-markup} function, with the @code{paper}
+and @code{props} arguments.
+
+Finally, suppose that we are typesetting a recitative in an opera, and
+we would like to define a command that will show character names in a
+custom manner. Names should be printed with small caps and translated a
+bit to the left and top. We will define a @code{\character} command
+that takes into account the needed translation, and uses the newly
+defined @code{\smallcaps} command:
+
+@verbatim
+#(def-markup-command (character paper props name) (string?)
+ "Print the character name in small caps, translated to the left and
+ top. Syntax: \\character #\"name\""
+ (interpret-markup paper props
+ (markup "" #:translate (cons -4 2) #:smallcaps name)))
+@end verbatim
+
+There is one complication that needs explanation: texts above and below
+the staff are moved vertically to be at a certain distance (the
+@code{padding} property) from the staff and the notes. To make sure
+that this mechanism does not annihilate the vertical effect of our
+@code{#:translate}, we add an empty string (@code{""}) before the
+translated text. Now the @code{""} will be put above the notes, and the
+@code{name} is moved in relation to that empty string. The net effect is
+that the text is moved to the upper left.
+
+The final result is as follows:
+@verbatim
+\score {
+ \notes { \fatText
+ c''^\markup \character #"Cleopatra"
+ e'^\markup \character #"Giulio Cesare"
+ }
+}
+@end verbatim
+
+@lilypond[raggedright]
+#(def-markup-command (smallcaps paper props str) (string?)
+ "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
+ (interpret-markup paper props
+ (make-line-markup
+ (map (lambda (s)
+ (if (= (string-length s) 0)
+ s
+ (markup #:large (string-upcase (substring s 0 1))
+ #:translate (cons -0.6 0)
+ #:tiny (string-upcase (substring s 1)))))
+ (string-split str #\Space)))))
+
+#(def-markup-command (character paper props name) (string?)
+ "Print the character name in small caps, translated to the left and
+ top. Syntax: \\character #\"name\""
+ (interpret-markup paper props
+ (markup "" #:translate (cons -4 0) #:smallcaps name)))
+
+\score {
+ \notes { \fatText
+ c''^\markup \character #"Cleopatra"
+ e'^\markup \character #"Giulio Cesare"
+ }
+}
+@end lilypond
+
+
+
+@node Global layout
+@section Global layout
+
+The global layout 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,
+which influences where line breaks breaks are chosen, and thus
+ultimately how many pages a piece of music takes. This section
+explains how to tune the algorithm for spacing.
+
+Globally spoken, this procedure happens in three steps: first,
+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.
+
+
+
+@menu
+* Vertical spacing::
+* Horizontal spacing::
+* Font Size::
+* Line breaking::
+* Page layout::
+@end menu
+
+
+@node Vertical spacing
+@subsection Vertical spacing
+
+@cindex vertical spacing
+@cindex distance between staves
+@cindex staff distance
+@cindex between staves, distance
+@cindex staffs per page
+@cindex space between staves
+
+The height of each system is determined automatically by LilyPond, to
+keep 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{minimumVerticalExtent}. It takes a pair
+of numbers, so if you want to make it smaller from its, then you could
+set
+@example
+ \set Staff.minimumVerticalExtent = #'(-4 . 4)
+@end example
+This sets the vertical size of the current staff to 4 staff spaces on
+either side of the center staff line. The argument of
+@code{minimumVerticalExtent} 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 piano staves are handled a little differently: to make cross-staff
+beaming work correctly, it is necessary that the distance between staves
+is fixed beforehand. This is also done with a
+@internalsref{VerticalAlignment} object, created in
+@internalsref{PianoStaff}. In this object the distance between the
+staves is fixed by setting @code{forced-distance}. If you want to
+override this, use a @code{\translator} block as follows:
+@example
+ \paper @{
+ \translator @{
+ \PianoStaffContext
+ \override VerticalAlignment #'forced-distance = #9
+ @}
+ @dots{}
+ @}
+@end example
+This would bring the staves together at a distance of 9 staff spaces,
+measured from the center line of each staff.
+
+@seealso
+
+Internals: Vertical alignment of staves is handled by the
+@internalsref{VerticalAlignment} object.
+
+
+
+
+@node Horizontal spacing
+@subsection Horizontal Spacing
+
+The spacing engine translates differences in durations into
+stretchable distances (``springs'') of differing 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[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8
+c8 c4 c4 c4
+@end lilypond
+
+Normally, @code{shortest-duration-space} is set to 1.2, which is the
+width of a note head, and @code{shortest-duration-space} is set to
+2.0, meaning that the shortest note gets 2 NHW (i.e. 2 times
+@code{shortest-duration-space}) of space. For normal notes, this space
+is always 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
+32th 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 the most commonly found shortest note. Notes that are even
+shorter this 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[fragment,verbatim,relative=2]
+ c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
+@end lilypond
+
+The most common shortest duration is determined as follows: in every
+measure, the shortest duration is determined. The most common short
+duration, is taken as the basis for the spacing, with the stipulation
+that this shortest duration should always be equal to or shorter than
+1/8th note. The shortest duration is printed when you run lilypond
+with @code{--verbose}. 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 1/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}
+
+In the introduction it was explained that stem directions influence
+spacing. This is controlled with @code{stem-spacing-correction}
+property in @internalsref{NoteSpacing}, which are generated for every
+@internalsref{Voice} context. The @code{StaffSpacing} object
+(generated at @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
+ \score { \notes {
+ 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|
+ }
+ \paper { raggedright = ##t } }
+@end lilypond
+
+@cindex SpacingSpanner, overriding properties
+
+Properties of the @internalsref{SpacingSpanner} must be overridden
+from the @code{\paper} block, since the @internalsref{SpacingSpanner} is
+created before any property commands are interpreted.
+@example
+\paper @{ \translator @{
+ \ScoreContext
+ SpacingSpanner \override #'spacing-increment = #3.0
+@} @}
+@end example
+
+
+@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.
+
+
+
+@node Font Size
+@subsection Font size
+@cindex font size, setting
+@cindex staff size, setting
+@cindex @code{paper} file
+
+The Feta font provides musical symbols at eight seven different
+sizes. Each font is tuned for a different staff size: at smaller sizes
+the font gets heavier, to match the relatively heavier staff lines.
+The recommended font sizes are listed in the following table:
+
+@multitable @columnfractions .25 .25 .25 .25
+
+@item @b{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.60pt
+@tab 4.4mm
+@tab
+
+@item feta14
+@tab 14.14pt
+@tab 5.0mm
+@tab
+
+@item feta16
+@tab 15.87pt
+@tab 5.6mm
+@tab
+
+@item feta18
+@tab 17.82pt
+@tab 6.3mm
+@tab song books
+
+@item feta20
+@tab 17.82pt
+@tab 7.0mm
+@tab standard parts
+
+@item feta23
+@tab 22.45 pt
+@tab 7.9mm
+@tab
+
+@item feta20
+@tab 25.2 pt
+@tab 8.9mm
+@tab
+@c modern rental material ?
+
+@end multitable
+
+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 size for individual
+staffs. The size of individual staffs are relative to the global size,
+which can be set in the following manner:
+
+@example
+ #(set-global-staff-size 14)
+@end example
+
+This sets the global default size to 14pt staff height, and scales all
+fonts accordingly.
+
+
+
+@node Line breaking
+@subsection Line breaking
+
+@cindex line breaks
+@cindex breaking lines
+
+Line breaks are normally computed automatically. They are chosen such
+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}, @code{\noBreak}
+@cindex @code{\break}
+@cindex @code{\noBreak}
+
+@seealso
+
+Internals: @internalsref{BreakEvent}.
+
+
+@node Page layout
+@subsection Page layout
+
+@cindex page breaks
+@cindex breaking pages
+
+@cindex @code{indent}
+@cindex @code{linewidth}
+
+The most basic settings influencing the spacing are @code{indent} and
+@code{linewidth}. They are set in the @code{\paper} block. They
+control the indentation of the first line of music, and the lengths of
+the lines.
+
+If @code{raggedright} is set to true in the @code{\paper}
+block, then the lines are justified at their natural length. This
+useful for short fragments, and for checking how tight the natural
+spacing is.
+
+@cindex page layout
+@cindex vertical spacing
+
+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
+variable @code{textheight} sets the total height of the music on each
+page. 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 a 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}
+
+To change the paper size, use the following Scheme code:
+@example
+ \paper@{
+ #(set-paper-size "a4")
+ @}
+@end example
+
+
+@refcommands
+
+@cindex @code{\newpage}
+@code{\newpage}.
+
+
+@seealso
+
+In this manual: @ref{Invoking lilypond}.
+
+Examples: @inputfileref{input/regression,between-systems.ly}.
+
+Internals: @internalsref{NonMusicalPaperColumn}.
+
+@refbugs
+
+LilyPond has no concept of page layout, which makes it difficult to
+reliably choose page breaks in longer pieces.
+
+
+
+
+@node Sound
+@section Sound
+@cindex Sound
+
+Entered music can also be converted to MIDI output. The performance
+is good enough for proof-hearing the music for errors.
+
+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 extremities. 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}.
+
+@refbugs
+
+Many musically interesting effects, such as swing, articulation,
+slurring, etc., are not translated to MIDI.
+
+Since slurs are not interpreted, @code{\lyricsto} and
+@code{\addlyrics} sections will be interpreted wrongly.
+
+The MIDI output allocates a channel for each Staff, and one for global
+settings. Hence, the MIDI file should not have more than 15 staves
+(or 14 if you do not use drums).
+
+
+@menu
+* MIDI block::
+* MIDI instrument names::
+@end menu
+
+
+@node MIDI block
+@subsection MIDI block
+@cindex MIDI block
+
+
+The MIDI block is analogous to the paper 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
+
+Assignments in the @code{\midi} block are not allowed.
+
+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
+\paper 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}.
+
+@refbugs
+
+If the selected string does not exactly match, then the default is
+used, which is the Grand Piano.
+
* Titling::
* Single staff polyphony::
* Piano staves::
-* Setting variables::
-* Fine tuning layout::
* Organizing larger pieces::
* An orchestral part::
* Integrating text and music::
More information on formatting piano music is in @ref{Piano music}.
-@node Setting variables
-@section Setting variables
-
-When the music is converted from notes to print it is interpreted
-in left-to-right order. This is similar to what happens when we read
-music. During this step context-sensitive information such as the
-accidentals to print, and where bar lines must be placed, are stored in
-variables. These variables are called @emph{context properties}.
-The properties can also be manipulated from input files. Consider this input:
-@example
-\set Staff.autoBeaming = ##f
-@end example
-
-@noindent
-It sets the property named @code{autoBeaming} in the current staff at
-this point in the music to @code{##f}, which means `false'. This
-property controls whether beams are printed automatically:
-@c
-@lilypond[relative=1,fragment,verbatim]
- c8 c c c
- \set Staff.autoBeaming = ##f
- c8 c c c
-@end lilypond
-
-@noindent
-LilyPond includes a built-in programming language, namely, a dialect
-of Scheme. The argument to @code{\set}, @code{##f}, is an
-expression in that language. The first hash-mark signals that a piece
-of Scheme code follows. The second hash character is part of the
-boolean value true (@code{#t}). Values of other types may be
-entered as follows:
-@itemize @bullet
-@item a string, enclosed in double quotes, for example,
-@example
- \set Staff.instrument = #"French Horn"
-@end example
-@item a boolean: either @code{#t} or @code{#f}, for true and false
-respectively, e.g.
-@example
- \set autoBeaming = ##f
- \set Score.skipBars = ##t
-@end example
-
-@item a number, such as
-@example
- \set Score.currentBarNumber = #20
-@end example
-
-@item a symbol, which is introduced by a quote character, as in
-@example
- \set Staff.crescendoSpanner = #'dashed-line
-@end example
-
-@item a pair, which is also introduced by a quote character, like in
-the following statements, which set properties to the pairs (-7.5, 6)
-and (3, 4) respectively:
-
-@example
- \set Staff.minimumVerticalExtent = #'(-7.5 . 6)
- \set Staff.timeSignatureFraction = #'(3 . 4)
-@end example
-
-@item a list, which is also introduced by a quote character. In the
-following example, the @code{breakAlignOrder} property is set to a
-list of symbols:
-@example
- \set Score.breakAlignOrder =
- #'(left-edge time-signature key-signatures)
-@end example
-
-
-@end itemize
-
-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
-@ifhtml
-@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
-@end ifhtml
-@ifnothtml
-tips-and-tricks
-@end ifnothtml
-examples.
-
-
-@node Fine tuning layout
-@section Fine tuning layout
-
-Sometimes it is necessary to change music layout by hand. When music
-is formatted, layout objects are created for each symbol. For
-example, every clef and every note head is represented by a layout
-object. These layout objects also carry variables, which we call
-@emph{layout properties}. By changing these variables from their
-values, we can alter the look of a formatted score:
-
-@lilypond[verbatim,relative]
- c4
- \override Stem #'thickness = #3.0
- c4 c4 c4
-@end lilypond
-
-@noindent
-In the example shown here, the layout property @code{thickness} (a
-symbol) is set to 3 in the @code{Stem} layout objects of the current
-As a result, the notes following @code{\override} have thicker
-stems.
-
-For the most part, a manual override is needed only on a case by
-case basis and not for all subsequent instances of the altered
-property. To accomplish this, simply prefix @code{\once} to the
-@code{\override} statement and the override will apply only once,
-immediately reverting to its default setting, i.e.
-
-@example
- \once \override Stem #'thickness = #3.0
-@end example
-
-@lilypond[relative]
- c4
- \once \override Stem #'thickness = #3.0
- c4 c4 c4
-@end lilypond
-
-@noindent
-Some overrides are so common that predefined commands are provided as
-a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
-commands are described in
-@ifhtml
-the
-@end ifhtml
-@ref{Notation manual}, under the sections for slurs and stems
-respectively.
-
-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:
-
-@itemize @bullet
-@item The @code{extra-offset} property, which
-@cindex @code{extra-offset}
-has a pair of numbers as value, moves around objects in the printout.
-The first number controls left-right movement; a positive number will
-move the object to the right. The second number controls up-down
-movement; a positive number will move it higher. The units of these
-offsets are staff-spaces. The @code{extra-offset} property is a
-low-level feature: the formatting engine is completely oblivious to
-these offsets.
-
-In the following example, the second fingering is moved a little to
-the left, and 1.8 staff space downwards:
-
-@cindex setting object properties
-
-@lilypond[relative=1,verbatim]
-\stemUp
-f-5
-\once \override Fingering
- #'extra-offset = #'(-0.3 . -1.8)
-f-5
-@end lilypond
-
-@item
-Setting the @code{transparent} property will cause an object to be printed
-in `invisible ink': the object is not printed, but all its other
-behavior is retained. The object still takes up space, it takes part in
-collisions, and slurs, and ties and beams can be attached to it.
-
-@cindex transparent objects
-@cindex removing objects
-@cindex invisible objects
-The following example demonstrates how to connect different voices
-using ties. Normally, ties only connect two notes in the same
-voice. By introducing a tie in a different voice, and blanking a stem
-in that voice, the tie appears to cross voices:
-
-@lilypond[fragment,relative=1,verbatim]
- c4 << {
- \once \override Stem #'transparent = ##t
- b8~ b8
- } \\ {
- b[ g8]
- } >>
-@end lilypond
-
-@item
-The @code{padding} property for objects with
-@cindex @code{padding}
-@code{side-position-interface} can be set to increase distance between
-symbols that are printed above or below notes. We only give an
-example; a more elaborate explanation is in @ref{Constructing a
-tweak}:
-
-@lilypond[relative=1,verbatim]
- c2\fermata
- \override Script #'padding = #3
- b2\fermata
-@end lilypond
-
-@end itemize
-
-More specific overrides are also possible. The notation manual
-discusses in depth how to figure out these statements for yourself, in
-@ref{Tuning output}.
-
@node Organizing larger pieces
@section Organizing larger pieces
@end example
More information on the possible uses of identifiers is in the
-technical manual, in @ref{Scheme data types}.
+technical manual, in TODO.
@node An orchestral part
mf ly tex ps scm \
po make \
cygwin debian stepmake \
- Documentation input
+ Documentation input \
+ vim
#
SCRIPTS = configure aclocal.m4 autogen.sh lexer-gcc-3.1.sh
README_TXT_FILES = AUTHORS.txt README.txt INSTALL.txt NEWS.txt
IN_FILES := $(wildcard *.in)
PATCH_FILES = emacsclient.patch server.el.patch darwin.patch
-VIM_FILES = vim/filetype.vim vim/compiler/lilypond.vim vim/ftplugin/lilypond.vimvim/indent/lilypond.vim vim/syntax/lilypond.vim
EXTRA_DIST_FILES = VERSION .cvsignore $(README_FILES) $(SCRIPTS) $(IN_FILES) \
- $(PATCH_FILES) $(VIM_FILES)
+ $(PATCH_FILES)
NON_ESSENTIAL_DIST_FILES = $(README_TXT_FILES)
INSTALLATION_DIR=$(local_lilypond_datadir)
INSTALLATION_FILES=$(config_make) VERSION
PACKAGE_NAME=LilyPond
MAJOR_VERSION=2
MINOR_VERSION=1
-PATCH_LEVEL=28
-MY_PATCH_LEVEL=hwn1
+PATCH_LEVEL=29
+MY_PATCH_LEVEL=
#!/bin/sh
+# WARNING WARNING WARNING
+# do not edit! this is autogen.sh, generated from /home/hanwen/usr/src/lilypond/stepmake/autogen.sh
+#!/bin/sh
# Run this to generate configure and initial GNUmakefiles
srcdir=`dirname $0`
Audio_element::Audio_element ()
{
- grace_b_ = false;
}
Audio_element::~Audio_element ()
{
}
-
+char const *
+Audio_element::name () const
+{
+ return classname (this);
+}
trg->check_removal ();
if (trg->is_removable ())
{
- recurse_down_translators (trg, &Translator::finalize, DOWN);
+ recurse_down_translators (trg, &Translator::finalize, UP);
remove_context (trg);
}
}
public:
Audio_element ();
virtual ~Audio_element ();
-
-
-
- // should we use a scm list?
- bool grace_b_;
-
+ virtual const char* name () const;
protected:
};
TRANSLATOR_DECLARATIONS(Score_performer);
~Score_performer ();
Performance *performance_;
-
+
protected:
virtual void prepare (Moment mom);
+ virtual void finish ();
virtual void one_time_step ();
virtual void initialize ();
virtual void announce_element (Audio_element_info);
recurse_down_translators (daddy_context_, &Translator::start_translation_timestep, UP);
}
-
+void
+Score_performer::finish ()
+{
+ recurse_down_translators (daddy_context_, &Translator::finalize, UP);
+}
+
void
Score_performer::one_time_step ()
{
protected:
virtual void stop_translation_timestep ();
virtual void start_translation_timestep ();
- virtual void acknowledge_grob (Audio_element_info);
+ virtual void acknowledge_audio_element (Audio_element_info);
virtual bool try_music (Music*);
virtual void process_music ();
public:
}
void
-Tie_performer::acknowledge_grob (Audio_element_info inf)
+Tie_performer::acknowledge_audio_element (Audio_element_info inf)
{
if (Audio_note * an = dynamic_cast<Audio_note *> (inf.elem_))
{
(define-public (alterations-in-key pitch-list)
"Count number of sharps minus number of flats"
- (/ (apply + (map cdr pitch-list))) 2)
+ (/ (apply + (map cdr pitch-list)) 2))
projects / lilypond.git / commitdiff