X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fputting.itely;h=0cc5ecd908ff926d5c6b9226482325ee3f4d314f;hb=af770f3440264c18ce01525dce1aa76b86ace0d5;hp=d4af541acf33d37655a60c2594370f419ff07118;hpb=56bb0f94b4441aceafbeaf194e9c02f81acf350c;p=lilypond.git diff --git a/Documentation/user/putting.itely b/Documentation/user/putting.itely index d4af541acf..0cc5ecd908 100644 --- a/Documentation/user/putting.itely +++ b/Documentation/user/putting.itely @@ -2,90 +2,17 @@ @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. +This chapter discusses general LilyPond concepts and how to +create @code{\score} blocks. + @menu -* Suggestions for writing LilyPond files:: * Extending the templates:: -* Fixing overlapping notation:: * How LilyPond files work:: * Score is a single musical expression:: -* Troubleshooting (taking it all apart):: @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.7.32"} 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 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. - -@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 -didn't comment the file. - -@item Ident your braces. A lot of problems are caused by an imbalance -in the number of @code{@{} and @code{@}}. - -@end itemize - -If you are entering music from an existing score (ie typesetting a -piece of existing sheet music), - -@itemize @bullet - -@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} command to speed up processing -- see -@ref{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. - -@end itemize - - @node Extending the templates @section Extending the templates @@ -99,7 +26,7 @@ cello. In this case, we would start with ``Notes and lyrics'' (for the soprano part). @example -\version "2.7.39" +\version "2.9.13" melody = \relative c' @{ \clef treble \key c \major @@ -121,14 +48,14 @@ text = \lyricmode @{ \new Lyrics \lyricsto "one" \text >> \layout @{ @} - \midi @{ \tempo 4=60 @} + \midi @{ @} @} @end example Now we want to add a cello part. Let's look at the ``Notes only'' example: @example -\version "2.7.39" +\version "2.9.13" melody = \relative c' @{ \clef treble \key c \major @@ -136,11 +63,11 @@ melody = \relative c' @{ a4 b c d @} - + \score @{ \new Staff \melody \layout @{ @} -\midi @{ \tempo 4=60 @} +\midi @{ @} @} @end example @@ -151,9 +78,9 @@ 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} +two @code{melody} sections. So let's rename them. We'll call the section +for the soprano @code{sopranoMusic} and the section for the cello +@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 @@ -164,7 +91,7 @@ normally use bass clef. We'll also give the cello some different notes. @example -\version "2.7.39" +\version "2.9.13" sopranoMusic = \relative c' @{ \clef treble \key c \major @@ -194,7 +121,7 @@ celloMusic = \relative c @{ \new Lyrics \lyricsto "one" \sopranoLyrics >> \layout @{ @} - \midi @{ \tempo 4=60 @} + \midi @{ @} @} @end example @@ -209,7 +136,7 @@ want the cello part to appear under the soprano part, we need to add @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 +more than one thing (in this case, @code{Staff}) happening at once. The @code{\score} looks like this now @example @@ -225,7 +152,7 @@ more than one thing (in this case staff) happening at once. The \new Staff \celloMusic >> \layout @{ @} - \midi @{ \tempo 4=60 @} + \midi @{ @} @} @end example @@ -234,7 +161,7 @@ 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,ragged-right] -\version "2.7.39" +\version "2.9.13" sopranoMusic = \relative c' { \clef treble \key c \major @@ -267,78 +194,12 @@ celloMusic = \relative c { \new Staff \celloMusic >> \layout { } - \midi { \tempo 4=60 } + \midi { } } @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,ragged-right,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; it is measured in staff spaces. For most -objects, this value 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,ragged-right,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, we think 2.3 is the best number in this case. However, -this number is merely the result of experimentation and my personal -taste in notation. Try the above example with 2.3... but also try higher -(and lower) numbers. Which do you think looks the best? - -@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,ragged-right,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, we decided -that these values look good - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\once \override TextScript #'extra-offset = #'( -1.6 . 1.0 ) -e4^\markup{ \italic ritenuto } g b e -@end lilypond - -@noindent -Again, these numbers are simply the result of a few experiments and -looking at the output. You might prefer the text to be slightly higher, -or to the left, or whatever. Try it and look at the result! - - -@seealso - -This manual: @ref{The \override command}, @ref{Common tweaks}. - - @node How LilyPond files work @section How LilyPond files work @@ -411,17 +272,16 @@ The @code{\score} can contain other things, such as \score @{ @{ c'4 a b c' @} \layout @{ @} - \paper @{ @} \midi @{ @} \header @{ @} @} @end example @noindent -Most people put some of those commands outside the +Some people put some of those commands outside the @code{\score} block -- for example, @code{\header} is -almost always placed above the @code{\score}. That's -just another shorthand. +often placed above the @code{\score}. That's just +another shorthand that LilyPond accepts. Another great shorthand is the ability to define variables. All the templates use this @@ -442,7 +302,9 @@ inserts it whenever it sees @code{\melody}. There's nothing special about the names -- it could be @code{melody}, @code{global}, @code{pianorighthand}, or @code{foofoobarbaz}. You -can use whatever variable names you want. +can use whatever variable names you want. For +more details, see +@ref{Saving typing with identifiers and functions}. For a complete definition of the input format, see @ref{File structure}. @@ -461,9 +323,9 @@ We didn't skip over it at all. The big mystery is simply that there @emph{is} no mystery. This line explains it all: -@example -A @code{\score} must begin with a single music expression. -@end example +@quotation +@emph{A @code{\score} must begin with a single music expression.} +@end quotation @noindent You may find it useful to review @@ -585,54 +447,3 @@ layer starts on the same horizontal position in your text editor! -@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. -