@c -*- coding: utf-8; mode: texinfo; -*-

@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c \version "2.12.0"

@node Suggestions for writing files
@chapter Suggestions for writing files

Now you're ready to begin writing larger LilyPond input files --
not just the little examples in the tutorial, but whole pieces.
But how should you go about doing it?

As long as LilyPond can understand your input files and produce
the output that you want, it doesn't matter what your input files
look like.  However, there are a few other things to consider when
writing LilyPond input files.

@itemize
@item What if you make a mistake?  The structure of a LilyPond
file can make certain errors easier (or harder) to find.

@item What if you want to share your input files with somebody
else?  In fact, what if you want to alter your own input files in
a few years?  Some LilyPond input files are understandable at
first glance; others may leave you scratching your head
for an hour.

@item What if you want to upgrade your LilyPond file for use
with a later version of LilyPond?  The input syntax changes
occasionally as LilyPond improves.  Most changes can be
done automatically with @code{convert-ly}, but some changes
might require manual assistance.  LilyPond input files can be
structured in order to be easier (or harder) to update.

@end itemize

@menu
* General suggestions::
* Typesetting existing music::
* Large projects::
@end menu


@node General suggestions
@section General suggestions

Here are a few suggestions that can help you to avoid or fix
problems:

@itemize
@item @strong{Include @code{\version} numbers in every file}.  Note that all
templates contain @code{\version} information.  We
highly recommend that you always include the @code{\version}, no matter
how small your file is.  Speaking from personal experience, it's
quite frustrating to try to remember which version of LilyPond you were
using a few years ago.  @command{convert-ly} requires you to declare
which version of LilyPond you used.

@item @strong{Include checks}: @ruser{Bar and bar number checks},
@ruser{Octave checks}.  If you include checks every so often, then
if you make a mistake, you can pinpoint it quicker.  How often is
@q{every so often}?  It depends on the complexity of the music.
For very simple music, perhaps just once or twice.  For very
complex music, perhaps every bar.

@item @strong{One bar per line of text}.  If there is anything complicated,
either in the music
itself or in the output you desire, it's often good to write only one bar
per line.  Saving screen space by cramming eight bars per line just isn't
worth it if you have to @q{debug} your input files.

@item @strong{Comment your input files}.  Use either bar numbers
(every so often) or
references to musical themes (@q{second theme in violins,} @q{fourth
variation,} etc.).  You may not need comments when you're writing the piece
for the first time, but if you want to go back to change something two or
three years later, or if you pass the source over to a friend, it will
be much more
challenging to determine your intentions or how your file is structured if
you didn't comment the file.

@item @strong{Indent your braces}.  A lot of problems are caused by an
imbalance
in the number of @code{@{} and @code{@}}.

@item @strong{Explicitly add durations} at the beginnings of sections
and variables.  If you specify @code{c4 d e} at the beginning of a
phrase (instead of just @code{c d e}) you can save yourself some
problems if you rearrange your music later.

@item @strong{Separate tweaks} from music definitions.  See
@rlearning{Saving typing with variables and functions}, and
@rlearning{Style sheets}.

@end itemize


@node Typesetting existing music
@section Typesetting existing music

If you are entering music from an existing score (i.e., typesetting a
piece of existing sheet music),

@itemize

@item Enter the manuscript (the physical copy of the music) into
LilyPond one system at a time (but still only one bar per line of text),
and check each system when you finish it.  You may use the
@code{showLastLength} or @code{showFirstLength} properties to speed up
processing -- see @ruser{Skipping corrected music}.

@item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
in the input file whenever the manuscript has a line break.  This
makes it much easier to compare the LilyPond music to the original
music.  When you are finished proofreading your score, you may
define @code{mBreak = @{ @}} to remove all those line breaks.  This
will allow LilyPond to place line breaks wherever it feels are
best.

@item When entering a part for a transposing instrument into a
variable, it is recommended that the notes are wrapped in

@example
\transpose c natural-pitch @{...@}
@end example
(where @code{natural-pitch} is the open pitch of the instrument) so
that the music in the variable is effectively in C. You can transpose
it back again when the variable is used, if required, but you might
not want to (e.g., when printing a score in concert pitch,
converting a trombone part from treble to bass clef, etc.)
Mistakes in transpositions are less likely if all the music in
variables is at a consistent pitch.

Also, only ever transpose to/from C. That means that the only other
keys you will use are the natural pitches of the instruments - bes
for a B-flat trumpet, aes for an A-flat clarinet, etc.

@end itemize


@node Large projects
@section Large projects

When working on a large project, having a clear structure to your
lilypond input files becomes vital.

@itemize

@item @strong{Use a variable for each voice}, with a minimum of
structure inside the definition.  The structure of the
@code{\score} section is the most likely thing to change;
the @code{violin} definition is extremely unlikely to change
in a new version of LilyPond.

@example
violin = \relative c'' @{
g4 c'8. e16
@}
...
\score @{
  \new GrandStaff @{
    \new Staff @{
      \violin
    @}
  @}
@}
@end example

@item @strong{Separate tweaks from music definitions}.  This
point was made previously, but for large
projects it is absolutely vital.  We might need to change
the definition of @code{fthenp}, but then we only need
to do this once, and we can still avoid touching anything
inside @code{violin}.

@example
fthenp = _\markup@{
  \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
violin = \relative c'' @{
g4\fthenp c'8. e16
@}
@end example

@end itemize