Documentation/application/suggestions.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2
   3 @ignore
   4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
   5
   6     When revising a translation, copy the HEAD committish of the
   7     version that you are working on.  See TRANSLATION for details.
   8 @end ignore
   9
  10 @c \version "2.12.0"
  11
  12 @node Suggestions for writing files
  13 @chapter Suggestions for writing files
  14
  15 Now you're ready to begin writing larger LilyPond input files --
  16 not just the little examples in the tutorial, but whole pieces.
  17 But how should you go about doing it?
  18
  19 As long as LilyPond can understand your input files and produce
  20 the output that you want, it doesn't matter what your input files
  21 look like.  However, there are a few other things to consider when
  22 writing LilyPond input files.
  23
  24 @itemize
  25 @item What if you make a mistake?  The structure of a LilyPond
  26 file can make certain errors easier (or harder) to find.
  27
  28 @item What if you want to share your input files with somebody
  29 else?  In fact, what if you want to alter your own input files in
  30 a few years?  Some LilyPond input files are understandable at
  31 first glance; others may leave you scratching your head
  32 for an hour.
  33
  34 @item What if you want to upgrade your LilyPond file for use
  35 with a later version of LilyPond?  The input syntax changes
  36 occasionally as LilyPond improves.  Most changes can be
  37 done automatically with @code{convert-ly}, but some changes
  38 might require manual assistance.  LilyPond input files can be
  39 structured in order to be easier (or harder) to update.
  40
  41 @end itemize
  42
  43 @menu
  44 * General suggestions::
  45 * Typesetting existing music::
  46 * Large projects::
  47 @end menu
  48
  49
  50 @node General suggestions
  51 @section General suggestions
  52
  53 Here are a few suggestions that can help you to avoid or fix
  54 problems:
  55
  56 @itemize
  57 @item @strong{Include @code{\version} numbers in every file}.  Note that all
  58 templates contain @code{\version} information.  We
  59 highly recommend that you always include the @code{\version}, no matter
  60 how small your file is.  Speaking from personal experience, it's
  61 quite frustrating to try to remember which version of LilyPond you were
  62 using a few years ago.  @command{convert-ly} requires you to declare
  63 which version of LilyPond you used.
  64
  65 @item @strong{Include checks}: @ruser{Bar and bar number checks},
  66 @ruser{Octave checks}.  If you include checks every so often, then
  67 if you make a mistake, you can pinpoint it quicker.  How often is
  68 @q{every so often}?  It depends on the complexity of the music.
  69 For very simple music, perhaps just once or twice.  For very
  70 complex music, perhaps every bar.
  71
  72 @item @strong{One bar per line of text}.  If there is anything complicated,
  73 either in the music
  74 itself or in the output you desire, it's often good to write only one bar
  75 per line.  Saving screen space by cramming eight bars per line just isn't
  76 worth it if you have to @q{debug} your input files.
  77
  78 @item @strong{Comment your input files}.  Use either bar numbers
  79 (every so often) or
  80 references to musical themes (@q{second theme in violins,} @q{fourth
  81 variation,} etc.).  You may not need comments when you're writing the piece
  82 for the first time, but if you want to go back to change something two or
  83 three years later, or if you pass the source over to a friend, it will
  84 be much more
  85 challenging to determine your intentions or how your file is structured if
  86 you didn't comment the file.
  87
  88 @item @strong{Indent your braces}.  A lot of problems are caused by an
  89 imbalance
  90 in the number of @code{@{} and @code{@}}.
  91
  92 @item @strong{Explicitly add durations} at the beginnings of sections
  93 and variables.  If you specify @code{c4 d e} at the beginning of a
  94 phrase (instead of just @code{c d e}) you can save yourself some
  95 problems if you rearrange your music later.
  96
  97 @item @strong{Separate tweaks} from music definitions.  See
  98 @rlearning{Saving typing with variables and functions}, and
  99 @rlearning{Style sheets}.
 100
 101 @end itemize
 102
 103
 104 @node Typesetting existing music
 105 @section Typesetting existing music
 106
 107 If you are entering music from an existing score (i.e., typesetting a
 108 piece of existing sheet music),
 109
 110 @itemize
 111
 112 @item Enter the manuscript (the physical copy of the music) into
 113 LilyPond one system at a time (but still only one bar per line of text),
 114 and check each system when you finish it.  You may use the
 115 @code{showLastLength} or @code{showFirstLength} properties to speed up
 116 processing -- see @ruser{Skipping corrected music}.
 117
 118 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
 119 in the input file whenever the manuscript has a line break.  This
 120 makes it much easier to compare the LilyPond music to the original
 121 music.  When you are finished proofreading your score, you may
 122 define @code{mBreak = @{ @}} to remove all those line breaks.  This
 123 will allow LilyPond to place line breaks wherever it feels are
 124 best.
 125
 126 @item When entering a part for a transposing instrument into a
 127 variable, it is recommended that the notes are wrapped in
 128
 129 @example
 130 \transpose c natural-pitch @{...@}
 131 @end example
 132 (where @code{natural-pitch} is the open pitch of the instrument) so
 133 that the music in the variable is effectively in C. You can transpose
 134 it back again when the variable is used, if required, but you might
 135 not want to (e.g., when printing a score in concert pitch,
 136 converting a trombone part from treble to bass clef, etc.)
 137 Mistakes in transpositions are less likely if all the music in
 138 variables is at a consistent pitch.
 139
 140 Also, only ever transpose to/from C. That means that the only other
 141 keys you will use are the natural pitches of the instruments - bes
 142 for a B-flat trumpet, aes for an A-flat clarinet, etc.
 143
 144 @end itemize
 145
 146
 147 @node Large projects
 148 @section Large projects
 149
 150 When working on a large project, having a clear structure to your
 151 lilypond input files becomes vital.
 152
 153 @itemize
 154
 155 @item @strong{Use a variable for each voice}, with a minimum of
 156 structure inside the definition.  The structure of the
 157 @code{\score} section is the most likely thing to change;
 158 the @code{violin} definition is extremely unlikely to change
 159 in a new version of LilyPond.
 160
 161 @example
 162 violin = \relative c'' @{
 163 g4 c'8. e16
 164 @}
 165 ...
 166 \score @{
 167   \new GrandStaff @{
 168     \new Staff @{
 169       \violin
 170     @}
 171   @}
 172 @}
 173 @end example
 174
 175 @item @strong{Separate tweaks from music definitions}.  This
 176 point was made previously, but for large
 177 projects it is absolutely vital.  We might need to change
 178 the definition of @code{fthenp}, but then we only need
 179 to do this once, and we can still avoid touching anything
 180 inside @code{violin}.
 181
 182 @example
 183 fthenp = _\markup@{
 184   \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
 185 violin = \relative c'' @{
 186 g4\fthenp c'8. e16
 187 @}
 188 @end example
 189
 190 @end itemize
 191
 192
 193