Merge commit 'origin/dev/jneeman' into systems-per-page

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

diff --git a/Documentation/user/working.itely b/Documentation/user/working.itely
index c912e5999c85bcff1972978254ad6ce797814986..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.61"
+@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
 
 
@@ -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
@@ -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
 
 
@@ -555,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