Notes, dynamic signs, etc. are grouped
with a set of horizontal lines, into a staff (plural `staves'). In our
-system, these lines are drawn using a separate graphical object called
+system, these lines are drawn using a separate layout object called
staff symbol.
This object is created whenever a @internalsref{Staff} context is
@cindex automatic beams, tuning
@cindex tuning automatic beaming
-[TODO: use \applycontext]
+@c [TODO: use \applycontext]
In normal time signatures, automatic beams can start on any note but can
only end in a few positions within the measure: beams can end on a beat,
@internalsref{MultiMeasureRestMusicGroup},
@internalsref{MultiMeasureRest},
-The graphical object @internalsref{MultiMeasureRestNumber} is for the
+The layout object @internalsref{MultiMeasureRestNumber} is for the
default number, and @internalsref{MultiMeasureRestText} for user
specified texts.
object, and set a object property in that object.
@menu
-* Predefined variables::
* Tuning objects ::
+* Constructing a tweak::
* Applyoutput::
* Outputproperty::
* Font selection::
* Text markup::
@end menu
-@node Predefined variables
-@subsection Predefined variables
-
-
-
-slurUp
-slurDown
-slurBoth
-
-slurDotted
-slurSolid
-
-phrasingSlurUp
-phrasingSlurDown
-phrasingSlurBoth
-
-shiftOn
-shiftOnn
-shiftOnnn
-shiftOff
-
-
-dynamicUp
-dynamicDown
-dynamicBoth
-
-scriptUp
-scriptDown
-scriptBoth
-
-dotsUp
-dotsDown
-dotsBoth
-
-
@node Tuning objects
By adding variables on top of these existing definitions, the system
-defaults is overriden, and the appearance of a graphical objects is
+defaults is overriden, and the appearance of a layout objects is
altered.
@syntax
@internalsref{OverrideProperty}, @internalsref{RevertProperty},
@internalsref{PropertySet}, @internalsref{backend properties},
-@internalsref{All Graphical Objects}.
+@internalsref{All layout objects}.
@refbugs
Similarly, reverting properties that are system defaults may also lead
to crashes.
+@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
+
+
+
+Using @code{\override} and @code{\set}, requires three pieces of
+information: 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{LilyPond website,http://lilypond.org}, click
+``Documentation: Index'' on the side bar, look in the ``Information
+for users'' section, and click on ``Documentation of internals.'' It
+is advisable to bookmark either the local HTML files if possilbe. 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: the documentation 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]
+c-2
+\stemUp
+f
+@end lilypond
+
+If you visit the documentation of @code{Fingering} (in @ref{Fingering
+instructions}), you will notice that it says
+
+@quotation
+@seealso
+
+@internalsref{FingerEvent} and @internalsref{Fingering}.
+@end quotation
+
+This implies that 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}.
+
+@ifhtml
+When we follow the link of @internalsref{Fingering},
+@end ifhtml
+@ifnothtml
+When we look up @internalsref{Fingering} in the generated
+documentation,
+@end ifnothtml
+we see a list of interfaces. The Fingering object has a number of
+different functions, and each of those is captured in an interface.
+
+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} 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
+ side-position-interface
+
+ Position a victim object (this one) next to other objects (the
+ support). In this case, the direction signifies where to put the
+ victim object relative to the support (left or right, up or down?)
+@end quotation
+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 \property Voice.Fingering \set #'padding = #3
+@end example
+
+Before the object is created, we get
+@lilypond[relative=2,fragment]
+\once \property Voice.Fingering
+ \set #'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}
+@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 and TabVoice
+@end example
+so tuning the settings for Fingering should be done using either
+@example
+ \property Voice.Fingering \set @dots{}
+@end example
+or
+@example
+ \property TabVoice.Fingering \set @dots{}
+@end example
+
+Since the @code{TabVoice} is only used for tab notation, we see that
+the first guess @code{Voice} was indeed correct.
+
+Of course, the tweak may also done in a larger context than
+@code{Voice}, for example, @internalsref{Staff} or
+@internalsref{Score}.
+
+The internals document also contains alphabetical lists of
+@internalsref{All contexts}, @internalsref{All layout objects} and
+@internalsref{All music types}, so you can also find which objects to
+tweak by browsing the internals document.
+
@node Applyoutput
@subsection Applyoutput
@c -*-texinfo-*-
@c TODO:
-@c * LilyPond Lilypond lilypond (sometimes: the program)
@c * more details about running lilypond; error messages,
@c compiling/viewing (emacs?)
@c * where to go from First steps+More basics?
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, we can
-alter the look of a formatted score.
+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 0]
c4
@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 the @ref{Notation manual}.
+commands are described in the @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 internal documentation of the respective
+object. However, many layout objects share properties, which can be
+used to apply generic tweaks. We mention a couple of these:
-
-
-
-@node Organising larger pieces
-@section Organising larger pieces
-
-TODO: discuss identifiers, p&c, .
-
-
-
-
-In this section we show some ways to fine tune the final output of a
-piece. We do so using a single measure of a moderately complex piano
-piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the
-tuned and the untuned versions) are in @file{input/tutorial/}.
-
-The code for the untuned example shows us some new things.
-
-@lilypondfile[verbatim]{brahms-original.ly}
-
-
-@cindex dynamics
-@cindex loudness
-@cindex forte
-@cindex crescendo
-
-
-
-
-Now that we have the basic piece of music entered, we want to fine
-tune it so that we get something that resembles the original printed
-edition by Schott/Universal Edition:
-
-@lilypondfile{brahms-tweaked.ly}
-
-@cindex tuning graphical objects
-
-Fine tuning involves overriding the defaults of the printing system.
-We do this by setting variables which control how Lilypond prints
-symbols. Printed symbols are called graphical objects (often
-abbreviated to @emph{grob}). Each object is described by a bunch of
-settings. Every setting is a variable: it has a name and a value
-which you can change. These values determine the fonts, offsets,
-sub-routines to be called on the object, etc. The initial values of
-these settings are set in the Scheme file
-@file{scm/grob-description.scm}.
-
-@cindex slur attachments
-
-We start with the slur in the upper part, running from F sharp to A. In
-the printed edition, this slur runs from stem to stem; in our version,
-the slur begins at the note head of the F sharp. The following property
-setting forces all slurs to run from stem to stem (not from or to note
-heads!).
-
-@example
- \property Voice.Slur \set #'attachment = #'(stem . stem)
-@end example
-
-More precisely, this command modifies the definition of the @code{Slur}
-object in the current @code{Voice}. The variable @code{attachment} is
-set to the pair of symbols @code{'(stem . stem)}.
-
-@cindex internal documentation
-@cindex finding graphical objects
-@cindex graphical object descriptions
-
-This command fixes one particular problem with a slur. The rest of
-this section explains how to figure out which properties to tune for
-your own scores. To discover this, you must have a copy of the
-internals document. This is a set of HTML pages which should be
-included if you installed a binary distribution. [TODO: revise for
-new site.] These HTML pages are also available on the web: go to the
-LilyPond website, click ``Documentation: Index'' on the side bar, look
-in the ``Information for users'' section, and click on ``Documentation
-of internals.''
-
-You might want to bookmark either the HTML files on your disk, or the
-one on the web (the HTML on your hard drive will load much faster than
-the ones on the web!). One word of caution: the internals
-documentation is generated from the definitions that the program uses.
-Hence, the internals documentation is strongly tied to the version you
-use. Before you proceed, make sure that the program and documentation
-have matching version numbers.
-
-@c TODO: the quote is incorrect, although that shouldn't be a big
-@c problem for the reader.
-Suppose that you wanted to tune the behavior of the slur. The first
-step is to get some general information on slurs in LilyPond. Turn to
-the index, and look up ``slur''. The section on slurs says
-@quotation
-The grob for this object is @internalsref{Slur}, generally in
-@internalsref{Voice} context.
-@end quotation
-
-So the graphical object for this object is called @code{Slur}, and
-slurs are created in the @code{Voice} context. If you are reading
-this tutorial in the HTML version, then you can simply click Slur,
-otherwise, you should look it up the internal documentation: click
-``grob overview'' and select ``slur'' (the list is alphabetical).
-
-Now you get a list of all the properties that the slur object
-supports, along with their default values. Among the properties we
-find the @code{attachment} property with its default setting.
-The property documentation explains that the following setting will
-produce the desired effect:
-@example
- \property Voice.Slur \set #'attachment = #'(stem . stem)
-@end example
-
-@c this is a long section, and adding an extra space here helps to
-@c break it into smaller subsections and thus is easier to understand.
-@separate
-
-Next we want to move the fingering `3'. In the printed edition it is
-not above the stem, but a little lower and slightly left of the stem.
-From the user manual we find that the associated graphical object is
-called @code{Fingering}, but how do we know if we should use
-@code{Voice} or @code{Staff}? In many cases, @code{Voice} is a safe
-bet, but you can also deduce this information from the internals
-documentation: if you visit the documentation of @code{Fingering}, you
-will notice
-@example
-Fingering grobs are created by: Fingering_engraver
-@end example
-
-Clicking @code{Fingering_engraver} will show you 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 and TabVoice
-@end example
-so tuning the settings for Fingering should be done using either
-@example
- \property Voice.Fingering \set @dots{}
-@end example
-or
-@example
- \property TabVoice.Fingering \set @dots{}
-@end example
-
-Since the @code{TabVoice} is only used for tab notation, we see that
-the first guess @code{Voice} was indeed correct.
-
-@cindex setting object properties
+@itemize @bullet
@cindex @code{extra-offset}
+@item The @code{extra-offset} property
+moves around objects in the printout. The unit of these offsets are
+staff-spaces. 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
+@code{extra-offset} is a low-level feature: the formatting engine is
+completely oblivious to these offsets.
-For shifting the fingering, we use the property @code{extra-offset}.
-The following command manually adds an offset to the object. We move
-it a little to the left, and 1.8 staff space downwards.
-@example
- \once \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
-@end example
-The @code{extra-offset} is a low-level feature: it moves around
-objects in the printout; the formatting engine is completely oblivious
-to these offsets. The unit of these offsets are staff-spaces. 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.
-We only want to offset a single object, so this statement is adorned
-with @code{\once}.
-
-@cindex property types
-@cindex translator properties
-@cindex grob properties
-@cindex music properties
-@separate
-
-There are three different types of variables in LilyPond, something
-which can be confusing at first (and for some people it stays
-confusing). Variables such as @code{extra-offset} and
-@code{attachment} are called grob properties. They are not the same
-as translator properties, like @code{autoBeaming}. Finally, music
-expressions are internally stored using properties (so-called music
-properties). You will encounter music properties if you run Scheme
-functions on music using @code{\apply}.
-
-The second fingering instruction should be moved up a little to avoid
-a collision with the slur. This could be achieved with
-@code{extra-offset}, but in this case, a simpler mechanism also
-works. We insert an empty text between the 5 and the note. The empty
-text pushes the fingering instruction away:
-@example
- a-)^" "^\markup @{ \finger "5" @}
-@end example
+In the following example example, the second fingering is moved a
+little to the left, and 1.8 staff space downwards.
-A fingering instruction, which would be entered as @code{^5}, is put
-as close to the notes as possible, closer than the space entered to
-push away the 5. Hence, the 5 is entered as a normal text, with the
-formatting of fingering instructions.
-
-@separate
-
-Normally one would specify all dynamics in the same voice, so that
-dynamics (such as @b{f} and @b{p}) will be aligned with hairpins. But
-in this case, we do not want the decrescendo to be aligned with the
-piano sign. We achieve this by putting the dynamic markings in different
-voices. The crescendo should be above the upper staff. This can be
-forced by using the precooked command
-@example
- \dynamicsUp
-@end example
-
-However, if you do that the decrescendo will be too close to the upper
-voice and collide with the stems. Looking at the manual for dynamics,
-we notice that ``Vertical positioning of these symbols is handled by
-the @internalsref{DynamicLineSpanner} grob.''. If we turn to the
-documentation of @code{DynamicLineSpanner}, we find that
-@code{DynamicLineSpanner} supports several so-called `interfaces'.
-This object not only puts objects next to the staff
-(@code{side-position-interface}), but it also groups dynamic objects
-(@code{axis-group-interface}), is considered a dynamic sign itself
-(@code{dynamic-interface}), and is an spanning object
-(@code{spanner-interface}). It also has the standard
-@code{grob-interface} with all the variables that come with it.
-
-For the moment we are interested in side positioning:
-@quotation
- side-position-interface
-
- Position a victim object (this one) next to other objects (the
- support). In this case, the direction signifies where to put the
- victim object relative to the support (left or right, up or down?)
-@end quotation
-Between the object and its support (in this case, the descending
-notes), there should be more space. This space is controlled by
-@code{padding}, so we increase it.
-@example
- \property Voice.DynamicLineSpanner \override #'padding = #5.0
-@end example
+@cindex setting object properties
+@lilypond[relative=1,verbatim]
+\stemUp
+f-5
+\once \property Voice.Fingering
+ \set #'extra-offset = #'(-0.3 . -1.8)
+f-5
+@end lilypond
-@separate
+@lilypond[relative=1,verbatim]
+\stemUp
+f-5
+\once \property Voice.Fingering
+ \set #'extra-offset = #'(-0.3 . -1.8)
+f-5
+@end lilypond
-Brahms uses music notation is a slightly unorthodox way. Ties
-usually happen only within one voice. In this piece, the composer
-gladly produces ties that jump voices. We deal with this by faking
-these ties: whenever we need such a tie, we insert a notehead in a
-different voice, and blank the stem. This is done in the following
-snippet of code.
+@item
+Setting the @code{transparent} property will make an object be
+printed in `invisible ink': the object is not printed, but all its
+other behavior is retained. The object still takes space, takes part
+in collisions, and slurs, ties and beams can be attached to it.
@cindex transparent objects
@cindex removing objects
@cindex invisible objects
-@example
-\property Voice.Stem \set #'transparent = ##t
-d'
-@end example
-Blanking the stem should be done for only one object. One of the ways
-to achieve that, is by setting the property before a note. Reverting
-it afterwards is tedious, so for setting a property only once, we have
-the syntax @code{\once}: it reverts the property directly before
-proceeding to the next step in time.
+The following example demonstrates how to connect different voices
+using ties. Normally ties only happen between notes of the same
+voice. By introducing a tie in a different voice, and blanking a stem
+in that voice, the tie appears to cross voices.
-The @code{\once} keyword is added to @code{\property}.
+@lilypond[fragment,relative=1]
+< {
+ \once \property Voice.Stem \set #'transparent = ##t
+ b8~ b8
+ } \\ {
+ b-[ g8-]
+ } >
+@end lilypond
+@item
+The @code{padding} property for objects with
+@code{side-position-interface} can be set to increase distance between
+symbols that are printed above or below notes. An example of the use
+of padding is in @ref{Constructing a tweak}.
+@end itemize
-Finally, the last tie is forced up using @code{\tieUp}.
+More specific overrides are also possible. The notation manual
+discusses in depth how to figure out these statements for yourself, in
+@ref{Tuning output}.
-@separate
+@node Organising larger pieces
+@section Organising larger pieces
-Here is the complete ``fine tuned'' version, which includes all the
-modifications we discussed in this section:
+TODO: discuss identifiers, p&c, .
-@lilypondfile[verbatim]{brahms-tweaked.ly}
@node An orchestral part
@section An orchestral part
+This command fixes one particular problem with a slur. The rest of
+this section explains how to figure out which properties to tune for
+your own scores.
+
+
TODO:
\markup, mmrest, transposing, cue notes, identifiers?.
$ cd input/tutorial
$ mkdir -p out/
$ lilypond-book --outdir=out/ lilbook.tex
-lilypond-book (GNU LilyPond) 1.7.16
+lilypond-book (GNU LilyPond) 1.7.23
Reading `input/tutorial/lilbook.tex'
Reading `input/screech-boink6.ly'
@var{lots of stuff deleted}
$ xdvi lilbook
@end example
-Notice the @code{outdir} option to lilypond-book. Running lilypond-book
-and running latex creates a lot of temporary files, and you would not want
-those to clutter up your working directory. Hence, we have them created
-in a separate subdirectory.
+Running lilypond-book and running latex creates a lot of temporary
+files, and you would not want those to clutter up your working
+directory. The @code{outdir} option to lilypond-book creates the
+temporary files in a separate subdirectory @file{out}.
The result looks more or less like this:
projects / lilypond.git / commitdiff