New doc section on fixing overlapping notation.

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

@c -*- coding: latin-1; mode: texinfo; -*-
@node Putting it all together
@chapter Putting it all together

This section explains how to use the rest of the documentation and
how to solve common problems.

@menu
* Suggestions for writing LilyPond files::  
* Extending the templates::     
* Fixing overlapping notation::  
@end menu


@node Suggestions for writing LilyPond files
@section Suggestions for writing LilyPond files

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

The best answer is ``however you want to do it.''  As long as LilyPond
can understand your files and produces the output that you want, it
doesn't matter what your files look like.  That said, sometimes we
make mistakes when writing files.  If LilyPond can't understand your
files, or produces output that you don't like, how do you fix the
problem?

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

@itemize @bullet
@item Include @code{\version} numbers in every file.  Note that all
templates contain a @code{\version "2.6.0"} string.  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.  @code{convert-ly} requires you to declare
which version of LilyPond you used.

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

@item One bar per line.  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 `debug' your files.

@item Comment your files, with either bar numbers (every so often) or
references to musical themes (``second theme in violins'', ``fourth
variation'').  You may not need it when you're writing the piece for
the first time, but if you want to go back and change something two
or three years later, you won't know how your file is structured if you
don't comment the file.

@end itemize


@node Extending the templates
@section Extending the templates

You've read the tutorial, you know how to write music.  But how can you
get the staves that you want?  The templates are ok, but what if you
want something that isn't covered?

Start off with the template that seems closest to what you want to end
up with.  Let's say that you want to write something for soprano and
cello.  In this case, we would start with ``Notes and lyrics'' (for the
soprano part).

@example
\version "2.4.0"
melody = \relative c' @{
  \clef treble
  \key c \major
  \time 4/4

  a4 b c d
@}

text = \lyricmode @{
  Aaa Bee Cee Dee
@}

\score@{
  <<
    \context Voice = one @{
      \autoBeamOff
      \melody
    @}
    \lyricsto "one" \new Lyrics \text
  >>
  \layout @{ @}
  \midi @{ \tempo 4=60 @}
@}
@end example

Now we want to add a cello part.  Let's look at the ``Notes only'' example:

@example
\version "2.4.0"
melody = \relative c' @{
  \clef treble
  \key c \major
  \time 4/4

  a4 b c d
@}
     
\score @{
\new Staff \melody
\layout @{ @}
\midi @{ \tempo 4=60 @}
@}
@end example

We don't need two @code{\version} commands.  We'll need the @code{melody}
section.  We don't want two @code{\score} sections -- if we had two
@code{\score}s, we'd get the two parts separately.  We want them together,
as a duet.  Within the @code{\score} section, we don't need two
@code{\layout} or @code{\midi}.

If we simply cut and paste the @code{melody} section, we would end up with
two @code{melody} sections.  So let's rename them.  We'll call the one
for the soprano @code{sopranoMusic}, and the one for the cello can be
called @code{celloMusic}.  While we're doing this, let's rename @code{text}
to be @code{sopranoLyrics}.  Remember to rename both instances of all
these names -- both the initial definition (the
@code{melody = relative c' @{ } part) and the name's use (in the
@code{\score} section).

While we're doing this, let's change the cello part's staff -- celli
normally use bass clef.  We'll also give the cello some different
notes.

@example
\version "2.4.0"
sopranoMusic = \relative c' @{
  \clef treble
  \key c \major
  \time 4/4

  a4 b c d
@}

sopranoLyrics = \lyricmode @{
  Aaa Bee Cee Dee
@}

celloMusic = \relative c @{
  \clef bass
  \key c \major
  \time 4/4

  d4 g fis8 e d4
@}

\score@{
  <<
    \context Voice = one @{
      \autoBeamOff
      \sopranoMusic
    @}
    \lyricsto "one" \new Lyrics \sopranoLyrics
  >>
  \layout @{ @}
  \midi @{ \tempo 4=60 @}
@}
@end example

This is looking promising, but the cello part won't appear in the
score -- we haven't used it in the @code{\score} section.  If we
want the cello part to appear under the soprano part, we need to add

@example
\new Staff \celloMusic
@end example

@noindent
underneath the soprano stuff.  We also need to add @code{<<} and
@code{>>} around the music -- that tells LilyPond that there's
more than one thing (in this case staff) happening at once.  The
@code{\score} looks like this now

@example
\score@{
<<
  <<
    \context Voice = one @{
      \autoBeamOff
      \sopranoMusic
    @}
    \lyricsto "one" \new Lyrics \sopranoLyrics
  >>
  \new Staff \celloMusic
>>
  \layout @{ @}
  \midi @{ \tempo 4=60 @}
@}
@end example

@noindent
This looks a bit messy; the indentation is messed up now.  That is
easily fixed.  Here's the complete soprano and cello template.

@lilypond[quote,verbatim,raggedright]
\version "2.4.0"
sopranoMusic = \relative c' {
  \clef treble
  \key c \major
  \time 4/4

  a4 b c d
}

sopranoLyrics = \lyricmode {
  Aaa Bee Cee Dee
}

celloMusic = \relative c {
  \clef bass
  \key c \major
  \time 4/4

  d4 g fis8 e d4
}

\score{
  <<
  <<
    \context Voice = one {
      \autoBeamOff
      \sopranoMusic
    }
    \lyricsto "one" \new Lyrics \sopranoLyrics
  >>
  \new Staff \celloMusic
  >>
  \layout { }
  \midi { \tempo 4=60 }
}
@end lilypond



@node Fixing overlapping notation
@section Fixing overlapping notation

This may come as a surprise, but LilyPond isn't perfect.  Some notation
elements can overlap.  This is unfortunate, but (in most cases) is easily
solved.

@lilypond[quote,fragment,raggedright,verbatim,relative=2]
e4^\markup{ \italic ritenuto } g b e
@end lilypond

@cindex padding

The easiest solution is to increase the distance between the object
(in this case text, but it could easily be fingerings or dynamics
instead) and the note.  In LilyPond, this is called the
@code{padding} property.  For most objects, it is around 1.0 or
less (it varies with each object).  We want to increase it, so let's
try 1.5

@lilypond[quote,fragment,raggedright,verbatim,relative=2]
\once \override TextScript #'padding = #1.5
e4^\markup{ \italic ritenuto } g b e
@end lilypond

That looks better, but it isn't quite big enough.  After experimenting
with a few values, I think 2.3 is the best number.  I leave this as an
exercise for the reader.

@cindex extra-offset

Another solution gives us complete control over placing the object -- we
can move it horizontally or vertically.  This is done with the
@code{extra-offset} property.  It is slightly more complicated and can
cause other problems.  When we move objects with @code{extra-offset},
the movement is done after LilyPond has placed all other objects.  This means
that the result can overlap with other objects.

@lilypond[quote,fragment,raggedright,verbatim,relative=2]
\once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
e4^\markup{ \italic ritenuto } g b e
@end lilypond

With @code{extra-offset}, the first number controls the horizontal
movement (left is negative); the second number controls the vertial
movement (up is positive).  After a bit of experimenting, I decided
that these values look good

@lilypond[quote,fragment,raggedright,verbatim,relative=2]
\once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
e4^\markup{ \italic ritenuto } g b e
@end lilypond


@seealso

This manual: @ref{The \override command}, @ref{Common tweaks}.