X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fputting.itely;h=0cc5ecd908ff926d5c6b9226482325ee3f4d314f;hb=b32ddd61386b517f10fbb6040e040b6303e7c0ce;hp=bc0b16799fd78b0d441138a01e1ecec44c7e407a;hpb=30c7d6a875f497931c21c8199b4ad34a4b140a83;p=lilypond.git

diff --git a/Documentation/user/putting.itely b/Documentation/user/putting.itely
index bc0b16799f..0cc5ecd908 100644
--- a/Documentation/user/putting.itely
+++ b/Documentation/user/putting.itely
@@ -2,89 +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.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
-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 public domain music),
-
-@itemize @bullet
-
-@item Enter one manuscript (the physical copy) line at a time, and
-check each line 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
 
@@ -98,7 +26,7 @@ cello.  In this case, we would start with ``Notes and lyrics'' (for the
 soprano part).
 
 @example
-\version "2.6.0"
+\version "2.9.13"
 melody = \relative c' @{
   \clef treble
   \key c \major
@@ -113,21 +41,21 @@ text = \lyricmode @{
 
 \score@{
   <<
-    \context Voice = one @{
+    \new Voice = "one" @{
       \autoBeamOff
       \melody
     @}
-    \lyricsto "one" \new Lyrics \text
+    \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.6.0"
+\version "2.9.13"
 melody = \relative c' @{
   \clef treble
   \key c \major
@@ -135,11 +63,11 @@ melody = \relative c' @{
 
   a4 b c d
 @}
-     
+
 \score @{
 \new Staff \melody
 \layout @{ @}
-\midi @{ \tempo 4=60 @}
+\midi @{ @}
 @}
 @end example
 
@@ -150,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
@@ -163,7 +91,7 @@ normally use bass clef.  We'll also give the cello some different
 notes.
 
 @example
-\version "2.6.0"
+\version "2.9.13"
 sopranoMusic = \relative c' @{
   \clef treble
   \key c \major
@@ -186,14 +114,14 @@ celloMusic = \relative c @{
 
 \score@{
   <<
-    \context Voice = one @{
+    \new Voice = "one" @{
       \autoBeamOff
       \sopranoMusic
     @}
-    \lyricsto "one" \new Lyrics \sopranoLyrics
+    \new Lyrics \lyricsto "one" \sopranoLyrics
   >>
   \layout @{ @}
-  \midi @{ \tempo 4=60 @}
+  \midi @{ @}
 @}
 @end example
 
@@ -208,23 +136,23 @@ 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
 \score@{
-<<
   <<
-    \context Voice = one @{
-      \autoBeamOff
-      \sopranoMusic
-    @}
-    \lyricsto "one" \new Lyrics \sopranoLyrics
+    <<
+      \new Voice = "one" @{
+        \autoBeamOff
+        \sopranoMusic
+      @}
+      \new Lyrics \lyricsto "one" \sopranoLyrics
+    >>
+    \new Staff \celloMusic
   >>
-  \new Staff \celloMusic
->>
   \layout @{ @}
-  \midi @{ \tempo 4=60 @}
+  \midi @{ @}
 @}
 @end example
 
@@ -232,8 +160,8 @@ more than one thing (in this case staff) happening at once.  The
 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.6.0"
+@lilypond[quote,verbatim,ragged-right]
+\version "2.9.13"
 sopranoMusic = \relative c' {
   \clef treble
   \key c \major
@@ -256,88 +184,22 @@ celloMusic = \relative c {
 
 \score{
   <<
-  <<
-    \context Voice = one {
-      \autoBeamOff
-      \sopranoMusic
-    }
-    \lyricsto "one" \new Lyrics \sopranoLyrics
-  >>
-  \new Staff \celloMusic
+    <<
+      \new Voice = "one" {
+        \autoBeamOff
+        \sopranoMusic
+      }
+      \new Lyrics \lyricsto "one" \sopranoLyrics
+    >>
+    \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,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, 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,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, we 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
-
-@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
 
@@ -369,7 +231,7 @@ Most examples also make use of the @code{\relative c'}
 compile the examples, but in most cases the output will
 look very odd if you omit the @code{\relative c'}.
 
-@lilypond[quote,fragment,raggedright,verbatim]
+@lilypond[quote,fragment,ragged-right,verbatim]
 \relative c'' {
   c4 a b c
 }
@@ -410,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
@@ -436,11 +297,14 @@ melody = \relative c' @{
 @end example
 
 When LilyPond looks at this file, it takes the value of
-@code{melody} and inserts it whenever it sees
+@code{melody} (everything after the equals sign) and
+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}.
@@ -459,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
@@ -492,10 +356,10 @@ though.
 \score @{
   @{
     <<
-      \context Staff = singer @{
-      @}
-      \context PianoStaff = piano @{
-      @}
+      \new Staff = "singer" <<
+      >>
+      \new PianoStaff = piano <<
+      >>
     >>
   @}
   \layout @{ @}
@@ -510,14 +374,14 @@ the vocal part and piano part at the same time!
 \score @{
   @{
     <<
-      \context Staff = singer @{
-        \context Voice = vocal @{ @}
-        \lyricsto vocal \new Lyrics @{ @}
-      @}
-      \context PianoStaff = piano @{
-        \context Staff = upper @{ @}
-        \context Staff = lower @{ @}
-      @}
+      \new Staff = "singer" <<
+        \new Voice = "vocal" @{ @}
+      >>
+      \new Lyrics \lyricsto vocal \new Lyrics @{ @}
+      \new PianoStaff = "piano" <<
+        \new Staff = "upper" @{ @}
+        \new Staff = "lower" @{ @}
+      >>
     >>
   @}
   \layout @{ @}
@@ -533,7 +397,7 @@ it contains an upper staff (right hand) and a lower
 staff (left hand).
 
 At this stage, we could start filling in notes.  Inside
-the curly braces next to @code{\context Voice = vocal},
+the curly braces next to @code{\new Voice = vocal},
 we could start writing
 
 @example
@@ -555,14 +419,14 @@ lower = @{ @}
 \score @{
   @{
     <<
-      \context Staff = singer @{
-        \context Voice = vocal @{ \melody @}
-        \lyricsto vocal \new Lyrics @{ \text @}
-      @}
-      \context PianoStaff = piano @{
-        \context Staff = upper @{ \upper @}
-        \context Staff = lower @{ \lower @}
-      @}
+      \new Staff = "singer" <<
+        \new Voice = "vocal" @{ \melody @}
+      >>
+      \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
+      \new PianoStaff = "piano" <<
+        \new Staff = "upper" @{ \upper @}
+        \new Staff = "lower" @{ \lower @}
+      >>
     >>
   @}
   \layout @{ @}
@@ -583,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 doens'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.
-