Doc-es: pre-merge update of texidoc committishes.

[lilypond.git] / Documentation / user / working.itely

@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond-learning.tely
@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 Working on LilyPond projects
@chapter Working on LilyPond projects

This section explains how to solve or avoid certain common
problems.  If you have programming experience, many of these
tips may seem obvious, but it is still advisable to read
this chapter.


@menu
* Suggestions for writing LilyPond input files::
* When things don't work::
* Scores and parts::
@end menu


@node Suggestions for writing LilyPond input files
@section Suggestions for writing LilyPond input 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::
* Saving typing with variables and functions::
* Style sheets::
@end menu


@node General suggestions
@subsection 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
@ref{Saving typing with variables and functions}, and
@ref{Style sheets}.

@end itemize


@node Typesetting existing music
@subsection Typesetting existing music

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

@itemize

@item Enter one manuscript (the physical copy) 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
@subsection Large projects

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

@itemize

@item @strong{Use an 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 in 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


@node Saving typing with variables and functions
@subsection Saving typing with variables and functions

@cindex variables
@cindex variables

By this point, you've seen this kind of thing:

@lilypond[quote,verbatim,ragged-right]
hornNotes = \relative c'' { c4 b dis c }
\score {
  {
    \hornNotes
  }
}
@end lilypond

You may even realize that this could be useful in minimalist music:

@lilypond[quote,verbatim,ragged-right]
fragmentA = \relative c'' { a4 a8. b16 }
fragmentB = \relative c'' { a8. gis16 ees4 }
violin = \new Staff { \fragmentA \fragmentA \fragmentB \fragmentA }
\score {
  {
    \violin
  }
}
@end lilypond

However, you can also use these variables (also known as
variables, macros, or (user-defined) command) for tweaks:

@lilypond[quote,verbatim,ragged-right]
dolce = \markup{ \italic \bold dolce }
padText = { \once \override TextScript #'padding = #5.0 }
fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
violin = \relative c'' {
  \repeat volta 2 {
    c4._\dolce b8 a8 g a b |
    \padText
    c4.^"hi there!" d8 e' f g d |
    c,4.\fthenp b8 c4 c-. |
  }
}
\score {
  {
    \violin
  }
\layout{ragged-right=##t}
}
@end lilypond

These variables are obviously useful for saving
typing.  But they're worth considering even if you
only use them once -- they reduce complexity.  Let's
look at the previous example without any
variables.  It's a lot harder to read, especially
the last line.

@example
violin = \relative c'' @{
  \repeat volta 2 @{
    c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
    \once \override TextScript #'padding = #5.0
    c4.^"hi there!" d8 e' f g d |
    c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
      \hspace #0.1 \dynamic p @} b8 c4 c-. |
  @}
@}
@end example

@c TODO Replace the following with a better example  -td
@c Skylining handles this correctly without padText

So far we've seen static substitution -- when LilyPond
sees @code{\padText}, it replaces it with the stuff that
we've defined it to be (ie the stuff to the right of
@code{padtext=}).

LilyPond can handle non-static substitution, too (you
can think of these as functions).

@lilypond[quote,verbatim,ragged-right]
padText =
#(define-music-function (parser location padding) (number?)
  #{
    \once \override TextScript #'padding = #$padding
  #})

\relative c''' {
  c4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" d e f
  \padText #2.6
  c4^"piu mosso" fis a g
}
@end lilypond

Using variables is also a good way to reduce work if the
LilyPond input syntax changes (see @ref{Updating old input files}).  If
you have a single definition (such as @code{\dolce}) for all your
input 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
@subsection Style sheets

The output that LilyPond produces can be heavily modified; see
@ref{Tweaking output}, for details.  But what if you have many
input 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 @code{#()}.  This is explained in
@ref{Advanced tweaks with Scheme}.

@lilypond[quote,verbatim,ragged-right]
mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
  #:line(#:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))

\relative c'' {
  \tempo 4=50
  a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
  \inst "Clarinet"
  cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
}
@end lilypond

There are some problems with overlapping output; we'll fix those using
the techniques in @ref{Moving objects}.  But let's also
do something about the @code{mpdolce} and @code{inst}
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 input files, and I personally find all
the @code{#()} somewhat ugly.  Let's hide them in another file:

@example
%%% save this to a file called "definitions.ly"
mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
  #:line(#:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))
@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
  \inst "Clarinet"
  cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
@}
@end example

@lilypond[quote,ragged-right]
mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
  #:line(#:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))

\relative c'' {
  \tempo 4=50
  a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
  \inst "Clarinet"
  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 note heads.  Let's
put the metronome marking above the clef, instead of over the first
note.  And finally, my composition professor hates @q{C} time signatures,
so we'd better make that @q{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 0 #:translate '(5 . 0)
  #:line( #:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))

\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 0 #:translate '(5 . 0)
  #:line( #:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))

\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
  \inst "Clarinet"
  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 @q{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 producing 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 0 #:translate '(5 . 0)
  #:line( #:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))

#(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 0 #:translate '(5 . 0)
  #:line( #:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))

#(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
  \inst "Clarinet"
  cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
}
@end lilypond

Now in our music, I 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
contains only the definitions of @code{mpdolce} and @code{inst}, a
@file{web-publish.ly} file which contains only the @code{\layout}
section listed above, and a @file{university.ly} file which
contains only 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
@q{style sheet} files for my projects.  I begin every music
file with @code{\include "../global.ly"}, which contains

@example
%%%   global.ly
\version @w{"@version{}"}
#(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


@node When things don't work
@section When things don't work

@menu
* Updating old input files::
* Troubleshooting (taking it all apart)::
* Minimal examples::
@end menu

@node Updating old input files
@subsection Updating old input files

The LilyPond input syntax occasionally changes.  As LilyPond itself
improves, the syntax (input language) is modified accordingly.  Sometimes
these changes are made to make the input easier to read and write or
sometimes the changes are made to accommodate 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
@rprogram{Updating files with convert-ly}.

Unfortunately, @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 @rprogram{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} (this would print the French word for
@q{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 input files.


@node Troubleshooting (taking it all apart)
@subsection Troubleshooting (taking it all apart)

Sooner or later, you will write a file that LilyPond cannot
compile.  The messages that LilyPond gives may help
you find the error, but in many cases you need to do some
investigation to determine the source of the problem.

The most powerful tools for this purpose are the
single line comment (indicated by @code{%}) and the block
comment (indicated by @code{%@{ ... %@}}).  If you don't
know where a problem is, start commenting out huge portions
of your input file.  After you comment out a section, try
compiling the file again.  If it works, then the problem
must exist in the portion you just commented.  If it doesn't
work, then keep on commenting out material until you have
something that works.

In an extreme case, you might end up with only

@example
\score @{
  <<
    % \melody
    % \harmony
    % \bass
  >>
  \layout@{@}
@}
@end example

@noindent
(in other words, a file without any music)

If that happens, don't give up.  Uncomment a bit -- say,
the bass part -- and see if it works.  If it doesn't work,
then comment out all of the bass music (but leave
@code{\bass} in the @code{\score} uncommented.

@example
bass = \relative c' @{
%@{
  c4 c c c
  d d d d
%@}
@}
@end example

Now start slowly uncommenting more and more of the
@code{bass} part until you find the problem line.

Another very useful debugging technique is constructing
@ref{Minimal examples}.


@node Minimal examples
@subsection Minimal examples

A minimal example is an example which is as small as possible.  These
examples are much easier to understand than long examples.  Minimal
examples are used for

@itemize
@item Bug reports
@item Sending a help request to mailing lists
@item Adding an example to the @uref{http://lsr.dsi.unimi.it/,
LilyPond Snippet Repository}
@end itemize

To construct an example which is as small as possible, the rule is
quite simple: remove anything which is not necessary.  When trying to
remove unnecessary parts of a file, it is a very good idea to comment
out lines instead of deleting them.  That way, if you discover that you
actually @emph{do} need some lines, you can uncomment them, instead of
typing them in from scratch.

There are two exceptions to the @qq{as small as possible} rule:

@itemize
@item Include the @code{\version} number.
@item If possible, use @code{\paper@{ ragged-right=##t @}} at the
top of your example.
@end itemize

The whole point of a minimal example is to make it easy to read:

@itemize
@item Avoid using complicated notes, keys, or time signatures, unless you
wish to demonstrate something is about the behavior of those items.
@item Do not use @code{\override} commands unless that is the point of the
example.
@end itemize



@node Scores and parts
@section Scores and parts

TODO: this is really old stuff from the really old tutorial.
Rewrite, fix, etc.  Or maybe delete entirely.  -gp
Include section on tags   -td
and then move to section 5. Working ...  -td

In orchestral music, all notes are printed twice.  Once in a part for
the musicians, and once in a full score for the conductor.  Variables can
be used to avoid double work.  The music is entered once, and stored in
a variable.  The contents of that variable is then used to generate
both the part and the full score.

It is convenient to define the notes in a special file.  For example,
suppose that the file @file{horn-music.ly} contains the following part
of a horn/@/bassoon duo

@example
hornNotes = \relative c @{
  \time 2/4
  r4 f8 a cis4 f e d
@}
@end example

@noindent
Then, an individual part is made by putting the following in a file

@example
\include "horn-music.ly"
\header @{
  instrument = "Horn in F"
@}

@{
 \transpose f c' \hornNotes
@}
@end example

The line

@example
\include "horn-music.ly"
@end example

@noindent
substitutes the contents of @file{horn-music.ly} at this position in
the file, so @code{hornNotes} is defined afterwards.  The command
@code{\transpose f@tie{}c'} indicates that the argument, being
@code{\hornNotes}, should be transposed by a fifth upwards.  Sounding
@code{f} is denoted by notated @code{c'}, which corresponds with the
tuning of a normal French Horn in@tie{}F.  The transposition can be seen
in the following output

@lilypond[quote,ragged-right]
\transpose f c' \relative c {
  \time 2/4
  r4 f8 a cis4 f e d
}
@end lilypond

In ensemble pieces, one of the voices often does not play for many
measures.  This is denoted by a special rest, the multi-measure
rest.  It is entered with a capital @code{R} followed by a duration
(@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
etc.).  By multiplying the
duration, longer rests can be constructed.  For example, this rest
takes 3@tie{}measures in 2/4 time

@example
R2*3
@end example

When printing the part, multi-rests
must be condensed.  This is done by setting a run-time variable

@example
\set Score.skipBars = ##t
@end example

@noindent
This command sets the property @code{skipBars} in the
@code{Score} context to true (@code{##t}).  Prepending the rest and
this option to the music above, leads to the following result

@lilypond[quote,ragged-right]
\transpose f c' \relative c {
  \time 2/4
  \set Score.skipBars = ##t
  R2*3
  r4 f8 a cis4 f e d
}
@end lilypond


The score is made by combining all of the music together.  Assuming
that the other voice is in @code{bassoonNotes} in the file
@file{bassoon-music.ly}, a score is made with

@example
\include "bassoon-music.ly"
\include "horn-music.ly"

<<
  \new Staff \hornNotes
  \new Staff \bassoonNotes
>>
@end example

@noindent
leading to

@lilypond[quote,ragged-right]
\relative c <<
  \new Staff {
    \time 2/4 R2*3
    r4 f8 a cis4 f e d
  }
  \new Staff {
    \clef bass
    r4 d,8 f | gis4 c | b bes |
    a8 e f4 | g d | gis f
  }
>>
@end lilypond