Do not dist non-existent ChangeLog.

[lilypond.git] / Documentation / user / working.itely

diff --git a/Documentation/user/working.itely b/Documentation/user/working.itely
index 8077bb3a6068051f0ca8b6a16c35b7c448513d04..84acc5f6f4cda16e3afb2d909b029a3f7fa4006e 100644 (file)
--- a/Documentation/user/working.itely
+++ b/Documentation/user/working.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.38"
+@c \version "2.12.0"
 
 @node Working on LilyPond projects
 @chapter Working on LilyPond projects
@@ -19,16 +19,16 @@ this chapter.
 
 
 @menu
-* Suggestions for writing LilyPond input files::  
-* When things don't work::      
-* Scores and parts::            
+* Suggestions for writing LilyPond input files::
+* When things don't work::
+* Scores and parts::
 @end menu
 
 
 @node Suggestions for writing LilyPond input files
 @section Suggestions for writing LilyPond input files
 
-Now you're ready to begin writing larger LilyPond input files -- 
+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?
 
@@ -53,14 +53,15 @@ occasionally as LilyPond improves.  Most changes can be
 done automatically with @code{convert-ly}, but some changes
 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::                
+* General suggestions::
+* Typesetting existing music::
+* Large projects::
+* Saving typing with variables and functions::
+* Style sheets::
 @end menu
 
 
@@ -79,8 +80,8 @@ quite frustrating to try to remember which version of LilyPond you were
 using a few years ago.  @command{convert-ly} requires you to declare
 which version of LilyPond you used.
 
-@item @strong{Include checks}: @ruser{Bar and barnumber checks},
-@ruser{Octave check}.  If you include checks every so often, then
+@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
@@ -92,7 +93,7 @@ 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 input files.
 
-@item @strong{Comment your input files}.  Use either bar numbers 
+@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
@@ -129,8 +130,8 @@ piece of existing sheet music),
 @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
-@ruser{Skipping corrected music}.
+@code{showLastLength} or @code{showFirstLength} properties to speed up
+processing -- see @ruser{Skipping corrected music}.
 
 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
 in the input file whenever the manuscript has a line break.  This
@@ -140,6 +141,24 @@ define @code{mBreak = @{ @}} to remove all those line breaks.  This
 will allow LilyPond to place line breaks wherever it feels are
 best.
 
+@item When entering a part for a transposing instrument into a
+variable, it is recommended that the notes are wrapped in
+
+@example
+\transpose c natural-pitch @{...@}
+@end example
+(where @code{natural-pitch} is the open pitch of the instrument) so
+that the music in the variable is effectively in C. You can transpose
+it back again when the variable is used, if required, but you might
+not want to (e.g., when printing a score in concert pitch,
+converting a trombone part from treble to bass clef, etc.)
+Mistakes in transpositions are less likely if all the music in
+variables is at a consistent pitch.
+
+Also, only ever transpose to/from C. That means that the only other
+keys you will use are the natural pitches of the instruments - bes
+for a B-flat trumpet, aes for an A-flat clarinet, etc.
+
 @end itemize
 
 
@@ -209,9 +228,9 @@ hornNotes = \relative c'' { c4 b dis c }
 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
@@ -261,6 +280,9 @@ violin = \relative c'' @{
 @}
 @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
@@ -552,9 +574,9 @@ file with @code{\include "../global.ly"}, which contains
 @section When things don't work
 
 @menu
-* Updating old input files::          
-* Troubleshooting (taking it all apart)::  
-* Minimal examples::            
+* Updating old input files::
+* Troubleshooting (taking it all apart)::
+* Minimal examples::
 @end menu
 
 @node Updating old input files