+2006-04-28 Graham Percival <gpermus@gmail.com>
+
+ * Documentaiton/user/ various: major new sections in the
+ Learning manual, slight reorg elsewhere.
+
2006-04-27 Han-Wen Nienhuys <hanwen@lilypond.org>
* scm/framework-ps.scm (output-framework): remove PageMedia
@menu
-* Common tweaks::
* Constructing a tweak::
* Navigating the program reference::
* Layout interfaces::
-@node Common tweaks
-@subsection Common tweaks
-
-@c Should we point at ly/property-init.ly ? -gp
-Some overrides are so common that predefined commands are provided as
-short-cuts, for example, @code{\slurUp} and @code{\stemDown}. These
-commands are described in
-@ifhtml
-the
-@end ifhtml
-@c @ref{Notation manual},
-Notation manual
-@c FIXME
-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 few of these:
-
-@itemize @bullet
-@item The @code{extra-offset} property, which
-@cindex @code{extra-offset}
-has a pair of numbers as value, moves objects around 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[quote,fragment,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, ties, and beams can be attached to it.
-
-@cindex transparent objects
-@cindex removing objects
-@cindex hiding 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,
-
-@lilypond[quote,fragment,relative=2]
-<< {
- b8~ b8\noBeam
-} \\ {
- b[ g8]
-} >>
-@end lilypond
-
-@noindent
-and blanking the first up-stem in that voice, the tie appears to cross
-voices:
-
-@lilypond[quote,fragment,relative=2,verbatim]
-<< {
- \once \override Stem #'transparent = ##t
- b8~ b8\noBeam
-} \\ {
- b[ g8]
-} >>
-@end lilypond
-
-@item
-The @code{padding} property for objects with
-@cindex @code{padding}
-@code{side-position-interface} can be set to increase the distance between
-symbols that are printed above or below notes. We provide two
-examples; a more elaborate explanation is in @ref{Constructing a
-tweak}:
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c2\fermata
-\override Script #'padding = #3
-b2\fermata
-@end lilypond
-
-@lilypond[quote,fragment,relative=1,verbatim]
-% This will not work, see below:
-\override MetronomeMark #'padding = #3
-\tempo 4=120
-c1
-% This works:
-\override Score.MetronomeMark #'padding = #3
-\tempo 4=80
-d1
-@end lilypond
-
-Note in the second example how important it is to figure out what
-context handles a certain object. Since the @code{MetronomeMark} object
-is handled in the Score context, property changes in the @code{Voice}
-context will not be noticed.
-
-@end itemize
-
-Some tweakable options are called ``subproperties'' and reside inside
-properties. To tweak those, use
-
-@example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
-@end example
-
-@cindex Tweaks, distances
-@cindex Distances
-
-Distances in LilyPond are measured in staff-spaces, while most
-thickness properties are measured in line-thickness. Some
-properties are different; for example, the thickness of beams
-is measured in staff-spaces. For more information, see the
-relevant portion of the program reference.
-
-More specific overrides are also possible. The next section
-discusses in depth how to figure out these statements for yourself.
-
-
@node Constructing a tweak
@subsection Constructing a tweak
More information on formatting piano music is given in @ref{Piano music}.
-
@menu
* Fixing overlapping notation::
+* Common tweaks::
+* Advanced tweaks with scheme::
@end menu
taste in notation. Try the above example with 2.3... but also try higher
(and lower) numbers. Which do you think looks the best?
+The @code{staff-padding} property is closely related. @code{padding}
+controls the minimum amount of space between an object and the nearest
+other object (generally the note or the staff lines);
+@code{staff-padding} controls the minimum amount of space between an
+object and the staff. This is a subtle difference, but you can see
+the behavior here.
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+c4^"piu mosso" b a b
+\once \override TextScript #'padding = #2.6
+c4^"piu mosso" d e f
+\once \override TextScript #'staff-padding = #2.6
+c4^"piu mosso" fis a g
+\break
+c,,4^"piu mosso" b a b
+\once \override TextScript #'padding = #2.6
+c4^"piu mosso" d e f
+\once \override TextScript #'staff-padding = #2.6
+c4^"piu mosso" fis a g
+@end lilypond
+
@cindex extra-offset
Another solution gives us complete control over placing the object -- we
looking at the output. You might prefer the text to be slightly higher,
or to the left, or whatever. Try it and look at the result!
+One final warning: in this section, we used
+
+@example
+\once \override TextScript @dots{}
+@end example
+
+This tweaks the display of text for the next note. If the note has
+no text, this tweak does nothing (and does @strong{not} wait until
+the next bit of text).
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=3]
+c4^"piu mosso" b
+\once \override TextScript #'padding = #2.6
+ a4 b
+c4^"piu mosso" d e f
+\once \override TextScript #'padding = #2.6
+c4^"piu mosso" d e f
+c4^"piu mosso" d e f
+\break
+\override TextScript #'padding = #2.6
+c4^"piu mosso" d e f
+c4^"piu mosso" d e f
+@end lilypond
+
@seealso
This manual: @ref{The \override command}, @ref{Common tweaks}.
+
+@menu
+* Common tweaks::
+@end menu
+
+@node Common tweaks
+@section Common tweaks
+
+@c Should we point at ly/property-init.ly ? -gp
+Some overrides are so common that predefined commands are provided as
+short-cuts, for example, @code{\slurUp} and @code{\stemDown}. These
+commands are described in
+@ifhtml
+the
+@end ifhtml
+@c @ref{Notation manual},
+Notation manual
+@c FIXME
+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 few of these:
+
+@itemize @bullet
+@item The @code{extra-offset} property, which
+@cindex @code{extra-offset}
+has a pair of numbers as value, moves objects around 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[quote,fragment,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, ties, and beams can be attached to it.
+
+@cindex transparent objects
+@cindex removing objects
+@cindex hiding 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,
+
+@lilypond[quote,fragment,relative=2]
+<< {
+ b8~ b8\noBeam
+} \\ {
+ b[ g8]
+} >>
+@end lilypond
+
+@noindent
+and blanking the first up-stem in that voice, the tie appears to cross
+voices:
+
+@lilypond[quote,fragment,relative=2,verbatim]
+<< {
+ \once \override Stem #'transparent = ##t
+ b8~ b8\noBeam
+} \\ {
+ b[ g8]
+} >>
+@end lilypond
+
+@item
+The @code{padding} property for objects with
+@cindex @code{padding}
+@code{side-position-interface} can be set to increase the distance between
+symbols that are printed above or below notes. We provide two
+examples; a more elaborate explanation is in @ref{Constructing a
+tweak}:
+
+@lilypond[quote,fragment,relative=1,verbatim]
+c2\fermata
+\override Script #'padding = #3
+b2\fermata
+@end lilypond
+
+@lilypond[quote,fragment,relative=1,verbatim]
+% This will not work, see below:
+\override MetronomeMark #'padding = #3
+\tempo 4=120
+c1
+% This works:
+\override Score.MetronomeMark #'padding = #3
+\tempo 4=80
+d1
+@end lilypond
+
+Note in the second example how important it is to figure out what
+context handles a certain object. Since the @code{MetronomeMark} object
+is handled in the Score context, property changes in the @code{Voice}
+context will not be noticed.
+
+@end itemize
+
+Some tweakable options are called ``subproperties'' and reside inside
+properties. To tweak those, use
+
+@example
+\override Stem #'details #'beamed-lengths = #'(4 4 3)
+@end example
+
+@cindex Tweaks, distances
+@cindex Distances
+
+Distances in LilyPond are measured in staff-spaces, while most
+thickness properties are measured in line-thickness. Some
+properties are different; for example, the thickness of beams
+is measured in staff-spaces. For more information, see the
+relevant portion of the program reference.
+
+More specific overrides are also possible. The next section
+discusses in depth how to figure out these statements for yourself.
+
+
+@node Advanced tweaks with scheme
+@section Advanced tweaks with scheme
+
+We have seen how LilyPond output can be heavily modified using
+commands like
+@code{\override TextScript #'extra-offset = ( 1 . -1)}. But
+we have even more power if we use scheme.
+
+FIXME scheme stuffs
+
@menu
* Suggestions for writing LilyPond files::
+* Updating old files::
* Troubleshooting (taking it all apart)::
* Saving typing with identifiers::
+* Style sheets::
@end menu
@end itemize
+@node Updating old files
+@section Updating old files
+
+The LilyPond input syntax occasionally changes. As LilyPond itself
+improves, the syntax (input language) is modified accordingly. Sometimes
+the changes are made to make the input easier to read and write, and
+sometimes the changes are made to accomodate new features of LilyPond.
+
+LilyPond comes with a file that makes this updating easier:
+@code{convert-ly}. For details about how to run this program, see
+@ref{Updating files with convert-ly}.
+
+Unforunately, @code{convert-ly} cannot handle all input changes. It
+takes care of simple search-and-replace changes (such as @code{raggedright}
+becoming @code{ragged-right}), but some changes are too
+complicated. The syntax changes that @code{convert-ly} cannot handle
+are listed in @ref{Updating files with convert-ly}.
+
+For example, in LilyPond 2.4 and earlier, accents and non-English
+letters were entered using LaTeX -- for example,
+"@code{No\"el}" (Christmas). In LilyPond 2.6 and above, the special
+"@code{ë}" must be entered directly into the LilyPond file as an
+UTF-8 character. @code{convert-ly} cannot change all the LaTeX
+special characters into UTF-8 characters; you must manually update
+your old LilyPond files.
+
+
@node Troubleshooting (taking it all apart)
@section Troubleshooting (taking it all apart)
}
@end lilypond
+Using identifiers is also a good way to reduce work if the
+LilyPond input syntax changes (see @ref{Updating old files}). If
+you have a single definition (such as @code{\dolce}) for all your
+files (see @ref{Style sheets}), then if the syntax changes, you
+only need to update your single @code{\dolce} definition,
+instead of making changes throughout every @code{.ly} file.
+
+
+@node Style sheets
+@section Style sheets
+
+The output that LilyPond produces can be heavily modified; see
+@ref{Tweaking output} for details. But what if you have many
+files that you want to apply your tweaks to? Or what if you
+simply want to separate your tweaks from the actual music? This
+is quite easy to do.
+
+Let's look at an example. Don't worry if you don't understand
+the parts with all the #(). This is explained in
+@ref{Advanced tweaks with scheme}.
+
+@lilypond[quote,verbatim,ragged-right]
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line(#:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup { \bold $markp }
+#})
+
+\relative c'' {
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+}
+@end lilypond
+
+There are some problems with overlapping output; we'll fix those using
+the techiques in @ref{Fixing overlapping notation}. But let's also
+do something about the @code{mpdolce} and @code{tempoMark}
+definitions. They produce the output we desire, but we might want
+to use them in another piece. We could simply copy-and-paste them
+at the top of every file, but that's an annoyance. It also leaves
+those definitions in our music files, and I personally find all
+the #() somewhat ugly. Let's hide them in another file:
+
+@example
+%%% save this to a file called "definitions.ly"
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line(#:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#@{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup @{ \bold $markp @}
+#@})
+@end example
+
+Now let's modify our music (let's save this file as @file{"music.ly"}).
+
+@c We have to do this awkward example/lilypond-non-verbatim
+@c because we can't do the \include stuff in the manual.
+
+@example
+\include "definitions.ly"
+
+\relative c'' @{
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \once \override Score.RehearsalMark #'padding = #2.0
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+@}
+@end example
+
+@lilypond[quote,ragged-right]
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line(#:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup { \bold $markp }
+#})
+
+\relative c'' {
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \once \override Score.RehearsalMark #'padding = #2.0
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+}
+@end lilypond
+
+That looks better, but let's make a few changes. The glissando is hard
+to see, so let's make it thicker and closer to the noteheads. Let's
+put the metronome marking above the clef, instead of over the first
+note. And finally, my composition professor hates "C" time signatures,
+so we'd better make that "4/4" instead.
+
+Don't change @file{music.ly}, though. Replace our @file{definitions.ly}
+with this:
+
+@example
+%%% definitions.ly
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line( #:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#@{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup @{ \bold $markp @}
+#@})
+
+\layout@{
+ \context @{ \Score
+ \override MetronomeMark #'extra-offset = #'(-9 . 0)
+ \override MetronomeMark #'padding = #'3
+ @}
+ \context @{ \Staff
+ \override TimeSignature #'style = #'numbered
+ @}
+ \context @{ \Voice
+ \override Glissando #'thickness = #3
+ \override Glissando #'gap = #0.1
+ @}
+@}
+@end example
+
+@lilypond[quote,ragged-right]
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line( #:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup { \bold $markp }
+#})
+
+\layout{
+ \context { \Score
+ \override MetronomeMark #'extra-offset = #'(-9 . 0)
+ \override MetronomeMark #'padding = #'3
+ }
+ \context { \Staff
+ \override TimeSignature #'style = #'numbered
+ }
+ \context { \Voice
+ \override Glissando #'thickness = #3
+ \override Glissando #'gap = #0.1
+ }
+}
+
+\relative c'' {
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \once \override Score.RehearsalMark #'padding = #2.0
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+}
+@end lilypond
+
+That looks nicer! But now suppose that I want to publish this
+piece. My composition professor doesn't like "C" time
+signatures, but I'm somewhat fond of them. Let's copy the
+current @file{definitions.ly} to @file{web-publish.ly} and
+modify that. Since this music is aimed at produce a pdf which
+will be displayed on the screen, we'll also increase the
+overall size of the output.
+
+@example
+%%% definitions.ly
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line( #:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#@{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup @{ \bold $markp @}
+#@})
+
+#(set-global-staff-size 23)
+\layout@{
+ \context @{ \Score
+ \override MetronomeMark #'extra-offset = #'(-9 . 0)
+ \override MetronomeMark #'padding = #'3
+ @}
+ \context @{ \Staff
+ @}
+ \context @{ \Voice
+ \override Glissando #'thickness = #3
+ \override Glissando #'gap = #0.1
+ @}
+@}
+@end example
+
+@lilypond[quote,ragged-right]
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line( #:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup { \bold $markp }
+#})
+
+#(set-global-staff-size 23)
+\layout{
+ \context { \Score
+ \override MetronomeMark #'extra-offset = #'(-9 . 0)
+ \override MetronomeMark #'padding = #'3
+ }
+ \context { \Voice
+ \override Glissando #'thickness = #3
+ \override Glissando #'gap = #0.1
+ }
+}
+
+\relative c'' {
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \once \override Score.RehearsalMark #'padding = #2.0
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+}
+@end lilypond
+
+Now in our music, I can either simply replace
+@code{\include "definitions.ly"} with
+@code{\include "web-publish.ly"}. Of course, we could make this
+even more convenient. We could make a @file{definitions.ly} file which only
+contains the definitions of @code{mpdolce} and @code{tempoMark}, a
+@file{web-publish.ly} file which only contains the @code{\layout}
+section listed above, and a @file{university.ly} file which
+contains the tweaks to produce the output that my professor
+prefers. The top of @file{music.ly} would then look like this:
+
+@example
+\include "definitions.ly"
+
+%%% Only uncomment one of these two lines!
+\include "web-publish.ly"
+%\include "university.ly"
+@end example
+
+This approach can be useful even if you are only producing
+one set of parts. I use half a dozen different
+"style sheet" files for my projects. I begin every music
+file with @code{\include "../global.ly"}, which contains
+
+@example
+%%% global.ly
+\version "2.8.0"
+#(ly:set-option 'point-and-click #f)
+\include "../init/init-defs.ly"
+\include "../init/init-layout.ly"
+\include "../init/init-headers.ly"
+\include "../init/init-paper.ly"
+@end example
projects / lilypond.git / commitdiff