X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fputting.itely;h=c0046654fb9c7b94926ca0a1df5c3c99f575c146;hb=0e9253e0c699653be5e569c5d81610bf724aac7c;hp=c6e24ae3692cc8d84341314ace6f806326a99489;hpb=add74ca6b8b8058f8ca4233a7302e1d75c1ac26b;p=lilypond.git

diff --git a/Documentation/user/putting.itely b/Documentation/user/putting.itely
index c6e24ae369..c0046654fb 100644
--- a/Documentation/user/putting.itely
+++ b/Documentation/user/putting.itely
@@ -1,63 +1,19 @@
-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
 @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 is an extention of the tutorial, dealing with FIXME.
+
 
 @menu
-* Suggestions for writing LilyPond files::  
 * Extending the templates::     
+* How LilyPond files work::     
+* Score is a single musical expression::  
+* Organizing larger pieces::    
+* An orchestral part::          
 @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
-don't comment the file.
-
-@end itemize
-
-
 @node Extending the templates
 @section Extending the templates
 
@@ -71,7 +27,7 @@ cello.  In this case, we would start with ``Notes and lyrics'' (for the
 soprano part).
 
 @example
-\version "2.4.0"
+\version "2.7.39"
 melody = \relative c' @{
   \clef treble
   \key c \major
@@ -86,11 +42,11 @@ 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 @}
@@ -100,7 +56,7 @@ text = \lyricmode @{
 Now we want to add a cello part.  Let's look at the ``Notes only'' example:
 
 @example
-\version "2.4.0"
+\version "2.7.39"
 melody = \relative c' @{
   \clef treble
   \key c \major
@@ -136,7 +92,7 @@ normally use bass clef.  We'll also give the cello some different
 notes.
 
 @example
-\version "2.4.0"
+\version "2.7.39"
 sopranoMusic = \relative c' @{
   \clef treble
   \key c \major
@@ -159,11 +115,11 @@ 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 @}
@@ -186,16 +142,16 @@ more than one thing (in this case staff) happening at once.  The
 
 @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 @}
 @}
@@ -205,8 +161,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.4.0"
+@lilypond[quote,verbatim,ragged-right]
+\version "2.7.39"
 sopranoMusic = \relative c' {
   \clef treble
   \key c \major
@@ -229,14 +185,14 @@ 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 }
@@ -244,3 +200,434 @@ celloMusic = \relative c {
 @end lilypond
 
 
+
+@node How LilyPond files work
+@section How LilyPond files work
+
+The LilyPond input format is quite free-form, giving experienced
+users a lot of flexibility to structure their files however they
+wish.  However, this flexibility can make things confusing for
+new users.  This section will explain some of this structure, but
+may gloss over some details in favor of simplicity.  For a complete
+description of the input format, see @ref{File structure}.
+
+Most examples in this manual are little snippets -- for example
+
+@example
+c4 a b c
+@end example
+
+As you are (hopefully) aware by now, this will not compile by
+itself.  These examples are shorthand for complete
+examples.  They all need at least curly braces to compile
+
+@example
+@{
+  c4 a b c
+@}
+@end example
+
+Most examples also make use of the @code{\relative c'}
+(or @code{c''}) command.  This is not necessary to merely
+compile the examples, but in most cases the output will
+look very odd if you omit the @code{\relative c'}.
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+\relative c'' {
+  c4 a b c
+}
+@end lilypond
+
+Now we get to the only real stumbling block: LilyPond
+input in this form is actually @emph{another}
+shorthand.  Although it compiles and displays the
+correct output, it is shorthand for
+
+@example
+\score @{
+  \relative c'' @{
+    c4 a b c
+  @}
+@}
+@end example
+
+A @code{\score} must begin with a single music
+expression.  Remember that a music expression could
+be anything from a single note to a huge
+
+@example
+@{
+  \new GrandStaff <<
+    insert the whole score of a Wagner opera in here
+  >>
+@}
+@end example
+
+@noindent
+Since everything is inside @code{@{ ... @}}, it counts
+as one music expression.
+
+The @code{\score} can contain other things, such as
+
+@example
+\score @{
+  @{ c'4 a b c' @}
+  \layout @{ @}
+  \paper @{ @}
+  \midi @{ @}
+  \header @{ @}
+@}
+@end example
+
+@noindent
+Most 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.
+
+Another great shorthand is the ability to define
+variables.  All the templates use this
+
+@example
+melody = \relative c' @{
+  c4 a b c
+@}
+
+\score @{
+  @{ \melody @}
+@}
+@end example
+
+When LilyPond looks at this file, it takes the value of
+@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.
+
+For a complete definition
+of the input format, see @ref{File structure}.
+
+
+@node Score is a single musical expression
+@section Score is a single musical expression
+
+In the previous section, @ref{How LilyPond files work},
+we saw the general organization of LilyPond input
+files.  But we seemed to skip over the most important
+part: how do we figure out what to write after
+@code{\score}?
+
+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
+
+@noindent
+You may find it useful to review
+@ref{Music expressions explained}.  In that section, we
+saw how to build big music expressions from small
+pieces -- we started from notes, then chords, etc.  Now
+we're going to start from a big music expression and
+work our way down.
+
+@example
+\score @{
+  @{   % this brace begins the overall music expression
+    \new GrandStaff <<
+      insert the whole score of a Wagner opera in here
+    >>
+  @}   % this brace ends the overall music expression
+  \layout @{ @}
+@}
+@end example
+
+A whole Wagner opera would easily double the length of
+this manual, so let's just do a singer and piano.  We
+don't need a @code{GrandStaff} for this ensemble, so we
+shall remove it.  We @emph{do} need a singer and a piano,
+though.
+
+@example
+\score @{
+  @{
+    <<
+      \new Staff = "singer" <<
+      >>
+      \new PianoStaff = piano <<
+      >>
+    >>
+  @}
+  \layout @{ @}
+@}
+@end example
+
+Remember that we use @code{<<} and @code{>>} to show
+simultaneous music.  And we definitely want to show
+the vocal part and piano part at the same time!
+
+@example
+\score @{
+  @{
+    <<
+      \new Staff = "singer" <<
+        \new Voice = "vocal" @{ @}
+      >>
+      \new Lyrics \lyricsto vocal \new Lyrics @{ @}
+      \new PianoStaff = "piano" <<
+        \new Staff = "upper" @{ @}
+        \new Staff = "lower" @{ @}
+      >>
+    >>
+  @}
+  \layout @{ @}
+@}
+@end example
+
+Now we have a lot more details.  We have the singer's
+staff: it contains a @code{Voice} (in LilyPond, this
+term refers to a set of notes, not necessarily vocal
+notes -- for example, a violin generally plays one
+voice) and some lyrics.  We also have a piano staff:
+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{\new Voice = vocal},
+we could start writing
+
+@example
+\relative c'' @{
+  a4 b c d
+@}
+@end example
+
+But if we did that, the @code{\score} section would
+get pretty long, and it would be harder to understand
+what was happening.  So let's use identifiers (or
+variables) instead.
+
+@example
+melody = @{ @}
+text = @{ @}
+upper = @{ @}
+lower = @{ @}
+\score @{
+  @{
+    <<
+      \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 @{ @}
+@}
+@end example
+
+@noindent
+Remember that you can use almost any name you like.  The
+limitations on identifier names are detailed in
+@ref{File structure}.
+
+When writing a @code{\score} section, or when reading
+one, just take it slowly and carefully.  Start with
+the outer layer, then work on each smaller
+layer.  It also really helps to be strict with
+indentation -- make sure that each item on the same
+layer starts on the same horizontal position in your
+text editor!
+
+
+@node Organizing larger pieces
+@section Organizing larger pieces
+
+When all of the elements discussed earlier are combined to produce
+larger files, the @code{\score} blocks get a lot bigger, because the
+music expressions are longer, and, in the case of polyphonic pieces,
+more deeply nested.  Such large expressions can become unwieldy.
+
+By using variables, also known as identifiers, it is possible to break
+up complex music expressions.  An identifier is assigned as follows
+
+@example
+namedMusic = @{ @dots{} @}
+@end example
+
+@noindent
+The contents of the music expression @code{namedMusic}, can be used
+later by preceding the name with a backslash, i.e., @code{\namedMusic}.
+In the next example, a two-note motive is repeated two times by using
+variable substitution
+
+@lilypond[quote,ragged-right,verbatim,nofragment]
+seufzer = {
+  e'4( dis'4)
+}
+{ \seufzer \seufzer }
+@end lilypond
+
+The name of an identifier should have alphabetic characters only; no
+numbers, underscores or dashes.  The assignment should be outside of
+running music.
+
+It is possible to use variables for many other types of objects in the
+input.  For example,
+
+@example
+width = 4.5\cm
+name = "Wendy"
+aFivePaper = \paper @{ paperheight = 21.0 \cm @}
+@end example
+
+Depending on its contents, the identifier can be used in different
+places.  The following example uses the above variables
+
+@example
+\paper @{
+  \aFivePaper
+  line-width = \width
+@}
+@{ c4^\name @}
+@end example
+
+More information on the possible uses of identifiers is given in the
+technical manual, in @ref{Input variables and Scheme}.
+@c fixme: the ref is too technical.
+
+
+@node An orchestral part
+@section An orchestral part
+
+In orchestral music, all notes are printed twice.  Once in a part for
+the musicians, and once in a full score for the conductor.  Identifiers 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
+@samp{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 @samp{R} followed by a duration
+(1@tie{}for a whole note, 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
+
+More in-depth information on preparing parts and scores can be found
+in the notation manual; see @ref{Orchestral music}.
+
+Setting run-time variables (`properties') is discussed in
+@ref{Changing context properties on the fly}.
+
+