@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.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
+
@node Working on LilyPond projects
@chapter Working on LilyPond projects
@menu
* Suggestions for writing LilyPond files::
-* Typesetting existing music::
-* Updating old files::
-* Troubleshooting (taking it all apart)::
* Saving typing with identifiers and functions::
* Style sheets::
+* Updating old files::
+* Troubleshooting (taking it all apart)::
@end menu
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?
+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.
+
+@itemize @bullet
+@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
+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 files can be
+structured in order to be easier (or header) to update.
+@end itemize
+
+@menu
+* General suggestions::
+* Typesetting existing music::
+* Large projects::
+@end menu
+
+
+@node General suggestions
+@subsection General suggestions
Here are a few suggestions that can help you to avoid or fix
problems:
@itemize @bullet
@item @strong{Include @code{\version} numbers in every file}. Note that all
-templates contain a @code{\version "2.8.0"} string. We
+templates contain a @code{\version "2.9.13"} 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 @strong{Include checks}: @ref{Bar check}s and @ref{Octave check}s. If you
+@item @strong{Include checks}: @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
+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
+@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 `debug' your files.
+worth it if you have to @q{debug} your files.
+
+@item @strong{Comment your 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{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
-didn't comment the file.
+@item @strong{Explicity add durations} at the beginnings of sections
+and identifiers. 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{Indent your braces}. A lot of problems are caused by an imbalance
-in the number of @code{@{} and @code{@}}.
+@item @strong{Separate tweaks} from music definitions. See
+@ref{Saving typing with identifiers and functions} and
+@ref{Style sheets}.
@end itemize
@node Typesetting existing music
-@section Typesetting existing music
+@subsection Typesetting existing music
-If you are entering music from an existing score (i.e. typesetting a
+If you are entering music from an existing score (i.e., typesetting a
piece of existing sheet music),
@itemize @bullet
@end itemize
-@node Updating old files
-@section Updating old files
-
-The LilyPond input syntax occasionally changes. As LilyPond itself
-improves, the syntax (input language) is modified accordingly. Sometimes
-the changes are made to make the input easier to read and write, and
-sometimes the changes are made to accomodate 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
-@ref{Updating files with convert-ly}.
-
-Unforunately, @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 @ref{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
-`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 files.
-
-
-@node Troubleshooting (taking it all apart)
-@section Troubleshooting (taking it all apart)
+@node Large projects
+@subsection Large projects
-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.
+When working on a large project, having a clear structure to your
+lilypond files becomes vital.
-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.
+@itemize @bullet
-In an extreme case, you might end up with only
+@item @strong{Use an identifier 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 @{
- <<
- % \melody
- % \harmony
- % \bass
- >>
- \layout@{@}
+ \new GrandStaff @{
+ \new Staff @{
+ \violin
+ @}
+ @}
@}
@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.
+@item @strong{Separate tweaks from music definitions}. This
+point was made in @ref{General suggestions}, 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
-bass = \relative c' @{
-%@{
- c4 c c c
- d d d d
-%@}
+fthenp = _\markup@{
+ \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
+violin = \relative c'' @{
+g4\fthenp c'8. e16
@}
@end example
-Now start slowly uncommenting more and more of the
-@code{bass} part until you find the problem line.
+@end itemize
@node Saving typing with identifiers and functions
@section Saving typing with identifiers and functions
+@cindex variables
+@cindex identifiers
+
By this point, you've seen this kind of thing:
@lilypond[quote,verbatim,ragged-right]
violin = \relative c'' @{
\repeat volta 2 @{
c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
- \once \override TextScript #'padding = #5.0
+ \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-. |
@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
Let's look at an example. Don't worry if you don't understand
the parts with all the #(). This is explained in
-@ref{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)
tempoMark = #(define-music-function (parser location markp) (string?)
#{
\once \override Score . RehearsalMark #'self-alignment-X = #left
- \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
\mark \markup { \bold $markp }
#})
@end lilypond
There are some problems with overlapping output; we'll fix those using
-the techiques in @ref{Fixing overlapping notation}. 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
tempoMark = #(define-music-function (parser location markp) (string?)
#@{
\once \override Score . RehearsalMark #'self-alignment-X = #left
- \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
\mark \markup @{ \bold $markp @}
#@})
@end example
tempoMark = #(define-music-function (parser location markp) (string?)
#{
\once \override Score . RehearsalMark #'self-alignment-X = #left
- \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
\mark \markup { \bold $markp }
#})
tempoMark = #(define-music-function (parser location markp) (string?)
#@{
\once \override Score . RehearsalMark #'self-alignment-X = #left
- \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
\mark \markup @{ \bold $markp @}
#@})
tempoMark = #(define-music-function (parser location markp) (string?)
#{
\once \override Score . RehearsalMark #'self-alignment-X = #left
- \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
\mark \markup { \bold $markp }
#})
\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 "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 produce a pdf which
+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.
tempoMark = #(define-music-function (parser location markp) (string?)
#@{
\once \override Score . RehearsalMark #'self-alignment-X = #left
- \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
\mark \markup @{ \bold $markp @}
#@})
tempoMark = #(define-music-function (parser location markp) (string?)
#{
\once \override Score . RehearsalMark #'self-alignment-X = #left
- \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
\mark \markup { \bold $markp }
#})
\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 can either simply replace
+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 only
-contains the definitions of @code{mpdolce} and @code{tempoMark}, a
-@file{web-publish.ly} file which only contains the @code{\layout}
+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 the tweaks to produce the output that my professor
+contains only the tweaks to produce the output that my professor
prefers. The top of @file{music.ly} would then look like this:
@example
This approach can be useful even if you are only producing
one set of parts. I use half a dozen different
-``style sheet'' files for my projects. I begin every music
+@q{style sheet} files for my projects. I begin every music
file with @code{\include "../global.ly"}, which contains
@example
%%% global.ly
-\version "2.8.0"
+\version "2.9.13"
#(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
+
+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.
+
+LilyPond comes with a file that makes this updating easier:
+@code{convert-ly}. For details about how to run this program, see
+@ref{Updating files with convert-ly}.
+
+Unforunately, @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 @ref{Updating files with convert-ly}.
+
+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
+@q{Christmas}). In LilyPond 2.6 and above, the special
+@samp{ë} 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.
+
+
+@node Troubleshooting (taking it all apart)
+@section 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.
+
+
projects / lilypond.git / blobdiff