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; you may wish to simply skim this
   8 chapter.
   9
  10
  11 @menu
  12 * Suggestions for writing LilyPond files::
  13 * Troubleshooting (taking it all apart)::
  14 * Saving typing with identifiers::
  15 @end menu
  16
  17
  18 @node Suggestions for writing LilyPond files
  19 @section Suggestions for writing LilyPond files
  20
  21 Now you're ready to begin writing larger LilyPond files -- not just the
  22 little examples in the tutorial, but whole pieces.  But how should you
  23 go about doing it?
  24
  25 The best answer is ``however you want to do it.''  As long as LilyPond
  26 can understand your files and produces the output that you want, it
  27 doesn't matter what your files look like.  That said, sometimes we
  28 make mistakes when writing files.  If LilyPond can't understand your
  29 files, or produces output that you don't like, how do you fix the
  30 problem?
  31
  32 Here are a few suggestions that can help you to avoid or fix
  33 problems:
  34
  35 @itemize @bullet
  36 @item @strong{Include @code{\version} numbers in every file}.  Note that all
  37 templates contain a @code{\version "2.8.0"} string.  We
  38 highly recommend that you always include the @code{\version}, no matter
  39 how small your file is.  Speaking from personal experience, it's
  40 quite frustrating to try to remember which version of LilyPond you were
  41 using a few years ago.  @code{convert-ly} requires you to declare
  42 which version of LilyPond you used.
  43
  44 @item @strong{Include checks}: @ref{Bar check}s and @ref{Octave check}s.  If you
  45 include checks every so often, then if you make a mistake, you can pinpoint
  46 it quicker.  How often is ``every so often''?  It depends on the complexity
  47 of the music.  For very simple music, perhaps just once or twice.  For
  48 very complex music, perhaps every bar.
  49
  50 @item @strong{One bar per line of text}.  If there is anything complicated, either in the music
  51 itself or in the output you desire, it's often good to write only one bar
  52 per line.  Saving screen space by cramming eight bars per line just isn't
  53 worth it if you have to `debug' your files.
  54
  55 @item @strong{Comment your files}, with either bar numbers (every so often) or
  56 references to musical themes (``second theme in violins'', ``fourth
  57 variation'').  You may not need it when you're writing the piece for
  58 the first time, but if you want to go back and change something two
  59 or three years later, you won't know how your file is structured if you
  60 didn't comment the file.
  61
  62 @item @strong{Indent your braces}.  A lot of problems are caused by an imbalance
  63 in the number of @code{@{} and @code{@}}.
  64
  65 @end itemize
  66
  67
  68
  69
  70 If you are entering music from an existing score (i.e. typesetting a
  71 piece of existing sheet music),
  72
  73 @itemize @bullet
  74
  75 @item Enter one manuscript (the physical copy) system at a time (but still
  76 only one bar per line of text), and
  77 check each system when you finish it.  You may use the
  78 @code{showLastLength} command to speed up processing -- see
  79 @ref{Skipping corrected music}.
  80
  81 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
  82 in the input file whenever the manuscript has a line break.  This
  83 makes it much easier to compare the LilyPond music to the original
  84 music.  When you are finished proofreading your score, you may
  85 define @code{mBreak = @{ @}} to remove all those line breaks.  This
  86 will allow LilyPond to place line breaks wherever it feels are
  87 best.
  88
  89 @end itemize
  90
  91
  92 @node Troubleshooting (taking it all apart)
  93 @section Troubleshooting (taking it all apart)
  94
  95 Sooner or later, you will write a file that LilyPond cannot
  96 compile.  The messages that LilyPond gives may help
  97 you find the error, but in many cases you need to do some
  98 investigation to determine the source of the problem.
  99
 100 The most powerful tools for this purpose are the
 101 single line comment (indicated by @code{%}) and the block
 102 comment (indicated by @code{%@{ ... %@}}).  If you don't
 103 know where a problem is, start commenting out huge portions
 104 of your input file.  After you comment out a section, try
 105 compiling the file again.  If it works, then the problem
 106 must exist in the portion you just commented.  If it doesn't
 107 work, then keep on commenting out material until you have
 108 something that works.
 109
 110 In an extreme case, you might end up with only
 111
 112 @example
 113 \score @{
 114   <<
 115     % \melody
 116     % \harmony
 117     % \bass
 118   >>
 119   \layout@{@}
 120 @}
 121 @end example
 122
 123 @noindent
 124 (in other words, a file without any music)
 125
 126 If that happens, don't give up.  Uncomment a bit -- say,
 127 the bass part -- and see if it works.  If it doesn't work,
 128 then comment out all of the bass music (but leave
 129 @code{\bass} in the @code{\score} uncommented.
 130
 131 @example
 132 bass = \relative c' @{
 133 %@{
 134   c4 c c c
 135   d d d d
 136 %@}
 137 @}
 138 @end example
 139
 140 Now start slowly uncommenting more and more of the
 141 @code{bass} part until you find the problem line.
 142
 143
 144 @node Saving typing with identifiers
 145 @section Saving typing with identifiers
 146
 147 By this point, you've seen this kind of thing:
 148
 149 @lilypond[quote,verbatim,ragged-right]
 150 hornNotes = \relative c'' { c4 b dis c }
 151 \score {
 152   {
 153     \hornNotes
 154   }
 155 }
 156 @end lilypond
 157
 158 You may even realize that this could be useful in minimalist music:
 159
 160 @lilypond[quote,verbatim,ragged-right]
 161 fragA = \relative c'' { a4 a8. b16 }
 162 fragB = \relative c'' { a8. gis16 ees4 }
 163 violin = \new Staff { \fragA \fragA \fragB \fragA }
 164 \score {
 165   {
 166     \violin
 167   }
 168 }
 169 @end lilypond
 170
 171 However, you can also use these identifiers (also known as
 172 variables, macros, or (user-defined) command) for tweaks:
 173
 174 @lilypond[quote,verbatim,ragged-right]
 175 dolce = \markup{ \italic \bold dolce }
 176 padText = { \once \override TextScript #'padding = #5.0 }
 177 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
 178 violin = \relative c'' {
 179   \repeat volta 2 {
 180     c4._\dolce b8 a8 g a b |
 181     \padText
 182     c4.^"hi there!" d8 e' f g d |
 183     c,4.\fthenp b8 c4 c-. |
 184   }
 185 }
 186 \score {
 187   {
 188     \violin
 189   }
 190 \layout{ragged-right=##t}
 191 }
 192 @end lilypond
 193
 194 These identifiers are obviously useful for saving
 195 typing.  But they're worth considering even if you
 196 only use them once -- they reduce complexity.  Let's
 197 look at the previous example without any
 198 identifiers.  It's a lot harder to read, especially
 199 the last line.
 200
 201 @example
 202 violin = \relative c'' @{
 203   \repeat volta 2 @{
 204     c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
 205     \once \override TextScript #'padding = #5.0
 206     c4.^"hi there!" d8 e' f g d |
 207     c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
 208       \hspace #0.1 \dynamic p @} b8 c4 c-. |
 209   @}
 210 @}
 211 @end example
 212
 213 So far we've seen static substitution -- when LilyPond
 214 sees @code{\padText}, it replaces it with the stuff that
 215 we've defined it to be (ie the stuff to the right of
 216 @code{padtext=}).
 217
 218 LilyPond can handle non-static substitution, too (you
 219 can think of these as functions).
 220
 221 @lilypond[quote,verbatim,ragged-right]
 222 padText =
 223 #(define-music-function (parser location padding) (number?)
 224  #{
 225     \once \override TextScript #'padding = #$padding
 226  #})
 227
 228 \relative c''' {
 229   c4^"piu mosso" b a b
 230   \padText #1.8
 231   c4^"piu mosso" d e f
 232   \padText #2.6
 233   c4^"piu mosso" fis a g
 234 }
 235 @end lilypond
 236
 237
 238