Documentation/user/working.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @node Working on LilyPond projects
   3 @chapter Working on LilyPond projects
   4
   5 This section explains a how to solve or avoid certain common
   6 problems.  If you have programming experience, many of these
   7 tips may seem obvious, but it is still advisable to read
   8 this chapter.
   9
  10
  11 @menu
  12 * Suggestions for writing LilyPond files::
  13 * Typesetting existing music::
  14 * Updating old files::
  15 * Troubleshooting (taking it all apart)::
  16 * Saving typing with identifiers and functions::
  17 * Style sheets::
  18 @end menu
  19
  20
  21 @node Suggestions for writing LilyPond files
  22 @section Suggestions for writing LilyPond files
  23
  24 Now you're ready to begin writing larger LilyPond files -- not just the
  25 little examples in the tutorial, but whole pieces.  But how should you
  26 go about doing it?
  27
  28 The best answer is ``however you want to do it.''  As long as LilyPond
  29 can understand your files and produces the output that you want, it
  30 doesn't matter what your files look like.  That said, sometimes we
  31 make mistakes when writing files.  If LilyPond can't understand your
  32 files, or produces output that you don't like, how do you fix the
  33 problem?
  34
  35 Here are a few suggestions that can help you to avoid or fix
  36 problems:
  37
  38 @itemize @bullet
  39 @item @strong{Include @code{\version} numbers in every file}.  Note that all
  40 templates contain a @code{\version "2.8.0"} string.  We
  41 highly recommend that you always include the @code{\version}, no matter
  42 how small your file is.  Speaking from personal experience, it's
  43 quite frustrating to try to remember which version of LilyPond you were
  44 using a few years ago.  @code{convert-ly} requires you to declare
  45 which version of LilyPond you used.
  46
  47 @item @strong{Include checks}: @ref{Bar check} and @ref{Octave check}.  If
  48 you
  49 include checks every so often, then if you make a mistake, you can pinpoint
  50 it quicker.  How often is ``every so often''?  It depends on the complexity
  51 of the music.  For very simple music, perhaps just once or twice.  For
  52 very complex music, perhaps every bar.
  53
  54 @item @strong{One bar per line of text}.  If there is anything complicated,
  55 either in the music
  56 itself or in the output you desire, it's often good to write only one bar
  57 per line.  Saving screen space by cramming eight bars per line just isn't
  58 worth it if you have to `debug' your files.
  59
  60 @item @strong{Comment your files}.  Use either bar numbers (every so often)
  61 or
  62 references to musical themes (``second theme in violins,'' ``fourth
  63 variation'', etc).  You may not need comments when you're writing the piece
  64 for the first time, but if you want to go back to change something two or
  65 three years later, or if you pass the source over to a friend, it will
  66 be much more
  67 challenging to determine your intentions or how your file is structured if
  68 you didn't comment the file.
  69
  70 @item @strong{Indent your braces}.  A lot of problems are caused by an
  71 imbalance
  72 in the number of @code{@{} and @code{@}}.
  73
  74 @end itemize
  75
  76
  77 @node Typesetting existing music
  78 @section Typesetting existing music
  79
  80 If you are entering music from an existing score (i.e., typesetting a
  81 piece of existing sheet music),
  82
  83 @itemize @bullet
  84
  85 @item Enter one manuscript (the physical copy) system at a time (but still
  86 only one bar per line of text), and
  87 check each system when you finish it.  You may use the
  88 @code{showLastLength} command to speed up processing -- see
  89 @ref{Skipping corrected music}.
  90
  91 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
  92 in the input file whenever the manuscript has a line break.  This
  93 makes it much easier to compare the LilyPond music to the original
  94 music.  When you are finished proofreading your score, you may
  95 define @code{mBreak = @{ @}} to remove all those line breaks.  This
  96 will allow LilyPond to place line breaks wherever it feels are
  97 best.
  98
  99 @end itemize
 100
 101
 102 @node Updating old files
 103 @section Updating old files
 104
 105 The LilyPond input syntax occasionally changes.  As LilyPond itself
 106 improves, the syntax (input language) is modified accordingly.  Sometimes
 107 these changes are made to make the input easier to read and write or
 108 sometimes the changes are made to accomodate new features of LilyPond.
 109
 110 LilyPond comes with a file that makes this updating easier:
 111 @code{convert-ly}.  For details about how to run this program, see
 112 @ref{Updating files with convert-ly}.
 113
 114 Unforunately, @code{convert-ly} cannot handle all input changes.  It
 115 takes care of simple search-and-replace changes (such as @code{raggedright}
 116 becoming @code{ragged-right}), but some changes are too
 117 complicated.  The syntax changes that @code{convert-ly} cannot handle
 118 are listed in @ref{Updating files with convert-ly}.
 119
 120 For example, in LilyPond 2.4 and earlier, accents and non-English
 121 letters were entered using LaTeX -- for example,
 122 "@code{No\"el}" (this would print the French word for
 123 `Christmas').  In LilyPond 2.6 and above, the special
 124 "@code{ë}" must be entered directly into the LilyPond file as an
 125 UTF-8 character.  @code{convert-ly} cannot change all the LaTeX
 126 special characters into UTF-8 characters; you must manually update
 127 your old LilyPond files.
 128
 129
 130 @node Troubleshooting (taking it all apart)
 131 @section Troubleshooting (taking it all apart)
 132
 133 Sooner or later, you will write a file that LilyPond cannot
 134 compile.  The messages that LilyPond gives may help
 135 you find the error, but in many cases you need to do some
 136 investigation to determine the source of the problem.
 137
 138 The most powerful tools for this purpose are the
 139 single line comment (indicated by @code{%}) and the block
 140 comment (indicated by @code{%@{ ... %@}}).  If you don't
 141 know where a problem is, start commenting out huge portions
 142 of your input file.  After you comment out a section, try
 143 compiling the file again.  If it works, then the problem
 144 must exist in the portion you just commented.  If it doesn't
 145 work, then keep on commenting out material until you have
 146 something that works.
 147
 148 In an extreme case, you might end up with only
 149
 150 @example
 151 \score @{
 152   <<
 153     % \melody
 154     % \harmony
 155     % \bass
 156   >>
 157   \layout@{@}
 158 @}
 159 @end example
 160
 161 @noindent
 162 (in other words, a file without any music)
 163
 164 If that happens, don't give up.  Uncomment a bit -- say,
 165 the bass part -- and see if it works.  If it doesn't work,
 166 then comment out all of the bass music (but leave
 167 @code{\bass} in the @code{\score} uncommented.
 168
 169 @example
 170 bass = \relative c' @{
 171 %@{
 172   c4 c c c
 173   d d d d
 174 %@}
 175 @}
 176 @end example
 177
 178 Now start slowly uncommenting more and more of the
 179 @code{bass} part until you find the problem line.
 180
 181
 182 @node Saving typing with identifiers and functions
 183 @section Saving typing with identifiers and functions
 184
 185 By this point, you've seen this kind of thing:
 186
 187 @lilypond[quote,verbatim,ragged-right]
 188 hornNotes = \relative c'' { c4 b dis c }
 189 \score {
 190   {
 191     \hornNotes
 192   }
 193 }
 194 @end lilypond
 195
 196 You may even realize that this could be useful in minimalist music:
 197
 198 @lilypond[quote,verbatim,ragged-right]
 199 fragA = \relative c'' { a4 a8. b16 }
 200 fragB = \relative c'' { a8. gis16 ees4 }
 201 violin = \new Staff { \fragA \fragA \fragB \fragA }
 202 \score {
 203   {
 204     \violin
 205   }
 206 }
 207 @end lilypond
 208
 209 However, you can also use these identifiers (also known as
 210 variables, macros, or (user-defined) command) for tweaks:
 211
 212 @lilypond[quote,verbatim,ragged-right]
 213 dolce = \markup{ \italic \bold dolce }
 214 padText = { \once \override TextScript #'padding = #5.0 }
 215 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
 216 violin = \relative c'' {
 217   \repeat volta 2 {
 218     c4._\dolce b8 a8 g a b |
 219     \padText
 220     c4.^"hi there!" d8 e' f g d |
 221     c,4.\fthenp b8 c4 c-. |
 222   }
 223 }
 224 \score {
 225   {
 226     \violin
 227   }
 228 \layout{ragged-right=##t}
 229 }
 230 @end lilypond
 231
 232 These identifiers are obviously useful for saving
 233 typing.  But they're worth considering even if you
 234 only use them once -- they reduce complexity.  Let's
 235 look at the previous example without any
 236 identifiers.  It's a lot harder to read, especially
 237 the last line.
 238
 239 @example
 240 violin = \relative c'' @{
 241   \repeat volta 2 @{
 242     c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
 243     \once \override TextScript #'padding = #5.0
 244     c4.^"hi there!" d8 e' f g d |
 245     c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
 246       \hspace #0.1 \dynamic p @} b8 c4 c-. |
 247   @}
 248 @}
 249 @end example
 250
 251 So far we've seen static substitution -- when LilyPond
 252 sees @code{\padText}, it replaces it with the stuff that
 253 we've defined it to be (ie the stuff to the right of
 254 @code{padtext=}).
 255
 256 LilyPond can handle non-static substitution, too (you
 257 can think of these as functions).
 258
 259 @lilypond[quote,verbatim,ragged-right]
 260 padText =
 261 #(define-music-function (parser location padding) (number?)
 262   #{
 263     \once \override TextScript #'padding = #$padding
 264   #})
 265
 266 \relative c''' {
 267   c4^"piu mosso" b a b
 268   \padText #1.8
 269   c4^"piu mosso" d e f
 270   \padText #2.6
 271   c4^"piu mosso" fis a g
 272 }
 273 @end lilypond
 274
 275 Using identifiers is also a good way to reduce work if the
 276 LilyPond input syntax changes (see @ref{Updating old files}).  If
 277 you have a single definition (such as @code{\dolce}) for all your
 278 files (see @ref{Style sheets}), then if the syntax changes, you
 279 only need to update your single @code{\dolce} definition,
 280 instead of making changes throughout every @code{.ly} file.
 281
 282
 283 @node Style sheets
 284 @section Style sheets
 285
 286 The output that LilyPond produces can be heavily modified; see
 287 @ref{Tweaking output} for details.  But what if you have many
 288 files that you want to apply your tweaks to?  Or what if you
 289 simply want to separate your tweaks from the actual music?  This
 290 is quite easy to do.
 291
 292 Let's look at an example.  Don't worry if you don't understand
 293 the parts with all the #().  This is explained in
 294 @ref{Advanced tweaks with Scheme}.
 295
 296 @lilypond[quote,verbatim,ragged-right]
 297 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
 298   #:line(#:dynamic "mp" #:text #:italic "dolce" )))
 299 tempoMark = #(define-music-function (parser location markp) (string?)
 300 #{
 301   \once \override Score . RehearsalMark #'self-alignment-X = #left
 302   \once \override Score . RehearsalMark #'no-spacing-rods = ##t
 303   \mark \markup { \bold $markp }
 304 #})
 305
 306 \relative c'' {
 307   \tempo 4=50
 308   a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
 309   \tempoMark "Poco piu mosso"
 310   cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
 311 }
 312 @end lilypond
 313
 314 There are some problems with overlapping output; we'll fix those using
 315 the techniques in @ref{Moving objects}.  But let's also
 316 do something about the @code{mpdolce} and @code{tempoMark}
 317 definitions.  They produce the output we desire, but we might want
 318 to use them in another piece.  We could simply copy-and-paste them
 319 at the top of every file, but that's an annoyance.  It also leaves
 320 those definitions in our music files, and I personally find all
 321 the #() somewhat ugly.  Let's hide them in another file:
 322
 323 @example
 324 %%% save this to a file called "definitions.ly"
 325 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
 326   #:line(#:dynamic "mp" #:text #:italic "dolce" )))
 327 tempoMark = #(define-music-function (parser location markp) (string?)
 328 #@{
 329   \once \override Score . RehearsalMark #'self-alignment-X = #left
 330   \once \override Score . RehearsalMark #'no-spacing-rods = ##t
 331   \mark \markup @{ \bold $markp @}
 332 #@})
 333 @end example
 334
 335 Now let's modify our music (let's save this file as @file{"music.ly"}).
 336
 337 @c  We have to do this awkward example/lilypond-non-verbatim
 338 @c  because we can't do the \include stuff in the manual.
 339
 340 @example
 341 \include "definitions.ly"
 342
 343 \relative c'' @{
 344   \tempo 4=50
 345   a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
 346   \once \override Score.RehearsalMark #'padding = #2.0
 347   \tempoMark "Poco piu mosso"
 348   cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
 349 @}
 350 @end example
 351
 352 @lilypond[quote,ragged-right]
 353 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
 354   #:line(#:dynamic "mp" #:text #:italic "dolce" )))
 355 tempoMark = #(define-music-function (parser location markp) (string?)
 356 #{
 357   \once \override Score . RehearsalMark #'self-alignment-X = #left
 358   \once \override Score . RehearsalMark #'no-spacing-rods = ##t
 359   \mark \markup { \bold $markp }
 360 #})
 361
 362 \relative c'' {
 363   \tempo 4=50
 364   a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
 365   \once \override Score.RehearsalMark #'padding = #2.0
 366   \tempoMark "Poco piu mosso"
 367   cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
 368 }
 369 @end lilypond
 370
 371 That looks better, but let's make a few changes.  The glissando is hard
 372 to see, so let's make it thicker and closer to the noteheads.  Let's
 373 put the metronome marking above the clef, instead of over the first
 374 note.  And finally, my composition professor hates "C" time signatures,
 375 so we'd better make that "4/4" instead.
 376
 377 Don't change @file{music.ly}, though.  Replace our @file{definitions.ly}
 378 with this:
 379
 380 @example
 381 %%%  definitions.ly
 382 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
 383   #:line( #:dynamic "mp" #:text #:italic "dolce" )))
 384 tempoMark = #(define-music-function (parser location markp) (string?)
 385 #@{
 386   \once \override Score . RehearsalMark #'self-alignment-X = #left
 387   \once \override Score . RehearsalMark #'no-spacing-rods = ##t
 388   \mark \markup @{ \bold $markp @}
 389 #@})
 390
 391 \layout@{
 392   \context @{ \Score
 393     \override MetronomeMark #'extra-offset = #'(-9 . 0)
 394     \override MetronomeMark #'padding = #'3
 395   @}
 396   \context @{ \Staff
 397     \override TimeSignature #'style = #'numbered
 398   @}
 399   \context @{ \Voice
 400     \override Glissando #'thickness = #3
 401     \override Glissando #'gap = #0.1
 402   @}
 403 @}
 404 @end example
 405
 406 @lilypond[quote,ragged-right]
 407 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
 408   #:line( #:dynamic "mp" #:text #:italic "dolce" )))
 409 tempoMark = #(define-music-function (parser location markp) (string?)
 410 #{
 411   \once \override Score . RehearsalMark #'self-alignment-X = #left
 412   \once \override Score . RehearsalMark #'no-spacing-rods = ##t
 413   \mark \markup { \bold $markp }
 414 #})
 415
 416 \layout{
 417   \context { \Score
 418     \override MetronomeMark #'extra-offset = #'(-9 . 0)
 419     \override MetronomeMark #'padding = #'3
 420   }
 421   \context { \Staff
 422     \override TimeSignature #'style = #'numbered
 423   }
 424   \context { \Voice
 425     \override Glissando #'thickness = #3
 426     \override Glissando #'gap = #0.1
 427   }
 428 }
 429
 430 \relative c'' {
 431   \tempo 4=50
 432   a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
 433   \once \override Score.RehearsalMark #'padding = #2.0
 434   \tempoMark "Poco piu mosso"
 435   cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
 436 }
 437 @end lilypond
 438
 439 That looks nicer!  But now suppose that I want to publish this
 440 piece.  My composition professor doesn't like "C" time
 441 signatures, but I'm somewhat fond of them.  Let's copy the
 442 current @file{definitions.ly} to @file{web-publish.ly} and
 443 modify that.  Since this music is aimed at producing a pdf which
 444 will be displayed on the screen, we'll also increase the
 445 overall size of the output.
 446
 447 @example
 448 %%%  definitions.ly
 449 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
 450   #:line( #:dynamic "mp" #:text #:italic "dolce" )))
 451 tempoMark = #(define-music-function (parser location markp) (string?)
 452 #@{
 453   \once \override Score . RehearsalMark #'self-alignment-X = #left
 454   \once \override Score . RehearsalMark #'no-spacing-rods = ##t
 455   \mark \markup @{ \bold $markp @}
 456 #@})
 457
 458 #(set-global-staff-size 23)
 459 \layout@{
 460   \context @{ \Score
 461     \override MetronomeMark #'extra-offset = #'(-9 . 0)
 462     \override MetronomeMark #'padding = #'3
 463   @}
 464   \context @{ \Staff
 465   @}
 466   \context @{ \Voice
 467     \override Glissando #'thickness = #3
 468     \override Glissando #'gap = #0.1
 469   @}
 470 @}
 471 @end example
 472
 473 @lilypond[quote,ragged-right]
 474 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
 475   #:line( #:dynamic "mp" #:text #:italic "dolce" )))
 476 tempoMark = #(define-music-function (parser location markp) (string?)
 477 #{
 478   \once \override Score . RehearsalMark #'self-alignment-X = #left
 479   \once \override Score . RehearsalMark #'no-spacing-rods = ##t
 480   \mark \markup { \bold $markp }
 481 #})
 482
 483 #(set-global-staff-size 23)
 484 \layout{
 485   \context { \Score
 486     \override MetronomeMark #'extra-offset = #'(-9 . 0)
 487     \override MetronomeMark #'padding = #'3
 488   }
 489   \context { \Voice
 490     \override Glissando #'thickness = #3
 491     \override Glissando #'gap = #0.1
 492   }
 493 }
 494
 495 \relative c'' {
 496   \tempo 4=50
 497   a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
 498   \once \override Score.RehearsalMark #'padding = #2.0
 499   \tempoMark "Poco piu mosso"
 500   cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
 501 }
 502 @end lilypond
 503
 504 Now in our music, I simply replace
 505 @code{\include "definitions.ly"} with
 506 @code{\include "web-publish.ly"}.  Of course, we could make this
 507 even more convenient.  We could make a @file{definitions.ly} file which
 508 contains only the definitions of @code{mpdolce} and @code{tempoMark}, a
 509 @file{web-publish.ly} file which contains only the @code{\layout}
 510 section listed above, and a @file{university.ly} file which
 511 contains only the tweaks to produce the output that my professor
 512 prefers.  The top of @file{music.ly} would then look like this:
 513
 514 @example
 515 \include "definitions.ly"
 516
 517 %%%  Only uncomment one of these two lines!
 518 \include "web-publish.ly"
 519 %\include "university.ly"
 520 @end example
 521
 522 This approach can be useful even if you are only producing
 523 one set of parts.  I use half a dozen different
 524 ``style sheet'' files for my projects.  I begin every music
 525 file with @code{\include "../global.ly"}, which contains
 526
 527 @example
 528 %%%   global.ly
 529 \version "2.8.0"
 530 #(ly:set-option 'point-and-click #f)
 531 \include "../init/init-defs.ly"
 532 \include "../init/init-layout.ly"
 533 \include "../init/init-headers.ly"
 534 \include "../init/init-paper.ly"
 535 @end example
 536
 537