]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/working.itely
resolve merge
[lilypond.git] / Documentation / user / working.itely
diff --git a/Documentation/user/working.itely b/Documentation/user/working.itely
deleted file mode 100644 (file)
index 84acc5f..0000000
+++ /dev/null
@@ -1,831 +0,0 @@
-@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 1 #:translate (cons 5 0)
-  #:line(#:dynamic "mp" #:text #:italic "dolce" )))
-tempoMark = #(define-music-function (parser location markp) (string?)
-#{
-  \once \override Score . RehearsalMark #'self-alignment-X = #left
-  \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
-  \mark \markup { \bold $markp }
-#})
-
-\relative c'' {
-  \tempo 4=50
-  a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
-  \tempoMark "Poco piu mosso"
-  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{tempoMark}
-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 1 #:translate (cons 5 0)
-  #:line(#:dynamic "mp" #:text #:italic "dolce" )))
-tempoMark = #(define-music-function (parser location markp) (string?)
-#@{
-  \once \override Score . RehearsalMark #'self-alignment-X = #left
-  \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
-  \mark \markup @{ \bold $markp @}
-#@})
-@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
-  \once \override Score.RehearsalMark #'padding = #2.0
-  \tempoMark "Poco piu mosso"
-  cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
-@}
-@end example
-
-@lilypond[quote,ragged-right]
-mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
-  #:line(#:dynamic "mp" #:text #:italic "dolce" )))
-tempoMark = #(define-music-function (parser location markp) (string?)
-#{
-  \once \override Score . RehearsalMark #'self-alignment-X = #left
-  \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
-  \mark \markup { \bold $markp }
-#})
-
-\relative c'' {
-  \tempo 4=50
-  a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
-  \once \override Score.RehearsalMark #'padding = #2.0
-  \tempoMark "Poco piu mosso"
-  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 1 #:translate (cons 5 0)
-  #:line( #:dynamic "mp" #:text #:italic "dolce" )))
-tempoMark = #(define-music-function (parser location markp) (string?)
-#@{
-  \once \override Score . RehearsalMark #'self-alignment-X = #left
-  \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
-  \mark \markup @{ \bold $markp @}
-#@})
-
-\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 1 #:translate (cons 5 0)
-  #:line( #:dynamic "mp" #:text #:italic "dolce" )))
-tempoMark = #(define-music-function (parser location markp) (string?)
-#{
-  \once \override Score . RehearsalMark #'self-alignment-X = #left
-  \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
-  \mark \markup { \bold $markp }
-#})
-
-\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
-  \once \override Score.RehearsalMark #'padding = #2.0
-  \tempoMark "Poco piu mosso"
-  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 1 #:translate (cons 5 0)
-  #:line( #:dynamic "mp" #:text #:italic "dolce" )))
-tempoMark = #(define-music-function (parser location markp) (string?)
-#@{
-  \once \override Score . RehearsalMark #'self-alignment-X = #left
-  \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
-  \mark \markup @{ \bold $markp @}
-#@})
-
-#(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 1 #:translate (cons 5 0)
-  #:line( #:dynamic "mp" #:text #:italic "dolce" )))
-tempoMark = #(define-music-function (parser location markp) (string?)
-#{
-  \once \override Score . RehearsalMark #'self-alignment-X = #left
-  \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
-  \mark \markup { \bold $markp }
-#})
-
-#(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
-  \once \override Score.RehearsalMark #'padding = #2.0
-  \tempoMark "Poco piu mosso"
-  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{tempoMark}, 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
-
-