@c -*- coding: utf-8; mode: texinfo; -*-
-@c This file is part of lilypond.tely
+@c This file is part of lilypond-learning.tely
@ignore
Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.11.61"
+
@node Working on LilyPond projects
@chapter Working on LilyPond projects
@menu
-* Suggestions for writing LilyPond files::
-* Saving typing with identifiers and functions::
-* Style sheets::
-* Updating old files::
-* Troubleshooting (taking it all apart)::
-* Minimal examples::
+* Suggestions for writing LilyPond input files::
+* When things don't work::
+* Scores and parts::
@end menu
-@node Suggestions for writing LilyPond files
-@section Suggestions for writing LilyPond files
+@node Suggestions for writing LilyPond input files
+@section Suggestions for writing LilyPond input 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?
+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 files and produces the output
-that you want, it doesn't matter what your files look like. However,
-there are a few other things to consider when writing lilypond files.
+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 @bullet
-@item What if you make a mistake? The structure of a lilypond
+@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 files with somebody
-else? In fact, what if you want to alter your own files in
-a few years? Some lilypond files are understandable at
-first glance; other files may leave you scratching your head
+@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
+@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 files can be
-structured in order to be easier (or header) to update.
+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
Here are a few suggestions that can help you to avoid or fix
problems:
-@itemize @bullet
+@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. @code{convert-ly} requires you to declare
+using a few years ago. @command{convert-ly} requires you to declare
which version of LilyPond you used.
-@item @strong{Include checks}: @ruser{Bar check}, @ruser{Octave check}, and
-@ruser{Barnumber check}. 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{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 files.
+worth it if you have to @q{debug} your input files.
-@item @strong{Comment your files}. Use either bar numbers (every so often)
-or
+@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
in the number of @code{@{} and @code{@}}.
@item @strong{Explicitly add durations} at the beginnings of sections
-and identifiers. If you specify @code{c4 d e} at the beginning of a
+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
-@ruser{Saving typing with identifiers and functions}, and
-@ruser{Style sheets}.
+@ref{Saving typing with variables and functions}, and
+@ref{Style sheets}.
@end itemize
If you are entering music from an existing score (i.e., typesetting a
piece of existing sheet music),
-@itemize @bullet
+@itemize
@item Enter one manuscript (the physical copy) system at a time (but still
only one bar per line of text), and
@subsection Large projects
When working on a large project, having a clear structure to your
-lilypond files becomes vital.
+lilypond input files becomes vital.
-@itemize @bullet
+@itemize
-@item @strong{Use an identifier for each voice}, with a minimum of
+@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
@end example
@item @strong{Separate tweaks from music definitions}. This
-point was made in @ruser{General suggestions}, but for large
+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
@end itemize
-@node Saving typing with identifiers and functions
-@section Saving typing with identifiers and functions
+@node Saving typing with variables and functions
+@subsection Saving typing with variables and functions
@cindex variables
-@cindex identifiers
+@cindex variables
By this point, you've seen this kind of thing:
You may even realize that this could be useful in minimalist music:
@lilypond[quote,verbatim,ragged-right]
-fragA = \relative c'' { a4 a8. b16 }
-fragB = \relative c'' { a8. gis16 ees4 }
-violin = \new Staff { \fragA \fragA \fragB \fragA }
+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 identifiers (also known as
+However, you can also use these variables (also known as
variables, macros, or (user-defined) command) for tweaks:
@lilypond[quote,verbatim,ragged-right]
}
@end lilypond
-These identifiers are obviously useful for saving
+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
-identifiers. It's a lot harder to read, especially
+variables. It's a lot harder to read, especially
the last line.
@example
@}
@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
}
@end lilypond
-Using identifiers is also a good way to reduce work if the
-LilyPond input syntax changes (see @ruser{Updating old files}). If
+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
-files (see @ruser{Style sheets}), then if the syntax changes, you
+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
-@section Style sheets
+@subsection Style sheets
The output that LilyPond produces can be heavily modified; see
-@ruser{Tweaking output}, for details. But what if you have many
-files that you want to apply your tweaks to? Or what if you
+@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
-@ruser{Advanced tweaks with Scheme}.
+@ref{Advanced tweaks with Scheme}.
@lilypond[quote,verbatim,ragged-right]
mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
@end lilypond
There are some problems with overlapping output; we'll fix those using
-the techniques in @ruser{Moving objects}. But let's also
+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 music files, and I personally find all
+those definitions in our input files, and I personally find all
the @code{#()} somewhat ugly. Let's hide them in another file:
@example
@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 noteheads. Let's
+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.
@example
%%% global.ly
-\version "2.11.23"
+\version @w{"@version{}"}
#(ly:set-option 'point-and-click #f)
\include "../init/init-defs.ly"
\include "../init/init-layout.ly"
@end example
-@node Updating old files
-@section Updating old files
+@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 accomodate new features of LilyPond.
+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
For example, in LilyPond 2.4 and earlier, accents and non-English
letters were entered using LaTeX -- for example,
-@samp{No\"el} (this would print the French word for
+@code{No\"el} (this would print the French word for
@q{Christmas}). In LilyPond 2.6 and above, the special
-@samp{ë} must be entered directly into the LilyPond file as an
+@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 files.
+your old LilyPond input files.
@node Troubleshooting (taking it all apart)
-@section 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
@code{bass} part until you find the problem line.
Another very useful debugging technique is constructing
-@ruser{Minimal examples}.
+@ref{Minimal examples}.
@node Minimal examples
-@section 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
@itemize
@item Bug reports
-@item Sending a help request to mailists
-@item Adding an example to the @uref{http://lsr@/.dsi@/.unimi@/.it/,LilyPond
-Snippet Repository}
+@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
@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
+
+
projects / lilypond.git / blobdiff