X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Fsuggestions.itely;h=56ddfe24c84b5061429a72aaf1aec56ce528012b;hb=b451acd8959a79b3b522b59ca2e03005bb3fe9cc;hp=6efd86a8aa2fdf7eefac37f4c34f1483f469a1b2;hpb=95a4237d0aca94993bd3b91afc4ff0e4e2daec9f;p=lilypond.git

diff --git a/Documentation/usage/suggestions.itely b/Documentation/usage/suggestions.itely
index 6efd86a8aa..56ddfe24c8 100644
--- a/Documentation/usage/suggestions.itely
+++ b/Documentation/usage/suggestions.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.13.36"
+@c \version "2.19.21"
 
 @node Suggestions for writing files
 @chapter Suggestions for writing files
@@ -53,51 +53,92 @@ structured in order to be easier (or harder) to update.
 @node General suggestions
 @section General suggestions
 
-Here are a few suggestions that can help you to avoid or fix
-problems:
+Here are a few suggestions that can help to avoid (and fix) the most
+common problems when typesetting:
 
 @itemize
-@item @strong{Include @code{\version} numbers in every file}.  Note that all
-templates contain @code{\version} information.  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.  @command{convert-ly} requires you to declare
-which version of LilyPond you used.
-
-@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
-complex music, perhaps every bar.
-
-@item @strong{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 @q{debug} your input files.
-
-@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
-for the first time, but if you want to go back to change something two or
-three years later, or if you pass the source over to a friend, it will
-be much more
-challenging to determine your intentions or how your file is structured if
-you didn't comment the file.
-
-@item @strong{Indent your braces}.  A lot of problems are caused by an
-imbalance
-in the number of @code{@{} and @code{@}}.
-
-@item @strong{Explicitly add durations} at the beginnings of sections
-and variables.  If you specify @code{c4 d e} at the beginning of a
-phrase (instead of just @code{c d e}) you can save yourself some
-problems if you rearrange your music later.
-
-@item @strong{Separate tweaks} from music definitions.  See
+@item
+@strong{Always include a @code{\version} number in your input files} no
+matter how small they are.  This prevents having to remember which
+version of LilyPond the file was created with and is especially relevant
+when @ref{Updating files with convert-ly} command (which requires the
+@code{\version} statement to be present); or if sending your input files
+to other users (e.g. when asking for help on the mail lists).  Note that
+all of the LilyPond templates contain @code{\version} numbers.
+
+@item
+@strong{For each line in your input file, write one bar of music}.  This
+will make debugging any problems in your input files much simpler.
+
+@item
+@strong{Include @ruser{Bar and bar number checks} as well as
+@ruser{Octave checks}}.  Including @q{checks} of this type in your input
+files will help pinpoint mistakes more quickly. How often checks are
+added will depend on the complexity of the music being typeset.  For
+simple compositions, checks added at a few at strategic points within
+the music can be enough but for more complex music, with many voices
+and/or staves, checks may be better placed after every bar.
+
+@item
+@strong{Add comments within input files}.  References to musical themes
+(i.e. @q{second theme in violins},  @q{fourth variation,} etc.), or
+simply including bar numbers as comments, will make navigating the input
+file much simpler especically if something needs to be altered later
+on or if passing on LilyPond input files to another person.
+
+@item
+@strong{Add explicit note durations at the start of @q{sections}}.  For
+example, @code{c4 d e f} instead of just @code{c d e f} can make
+rearranging the music later on simpler.
+
+@item
+@strong{Learn to indent and align braces and parallel music}.  Many
+problems are often caused by either @q{missing} braces.  Clearly
+indenting @q{opening} and @q{closing} braces (or @code{<<} and @code{>>}
+indicators) will help avoid such problems.  For example;
+
+@example
+\new Staff @{
+  \relative @{
+    r4 g'8 g c8 c4 d |
+    e4 r8 |
+    % Ossia section
+    <<
+      @{ f8 c c | @}
+      \new Staff @{
+        f8 f c |
+      @}
+    >>
+    r4 |
+  @}
+@}
+@end example
+
+@noindent
+is much easier to follow than;
+
+@example
+\new Staff @{ \relative @{ r4 g'8 g c4 c8 d | e4 r8
+% Ossia section
+<< @{ f8 c c @} \new Staff @{ f8 f c @} >> r4 | @} @}
+@end example
+
+
+@item
+@strong{Keep music and style separate} by putting overrides in the
+@code{\layout} block;
+
+@example
+\score @{
+  @var{@dots{}music@dots{}}
+  \layout @{
+   \override TabStaff.Stemstencil = ##f
+ @}
+@}
+@end example
+
+This will not create a new context but it will apply when one is
+created.  Also see
 @rlearning{Saving typing with variables and functions}, and
 @rlearning{Style sheets}.
 
@@ -130,7 +171,7 @@ best.
 variable, it is recommended that the notes are wrapped in
 
 @example
-\transpose c natural-pitch @{...@}
+\transpose c natural-pitch @{@dots{}@}
 @end example
 
 @noindent
@@ -164,10 +205,10 @@ the @code{violin} definition is extremely unlikely to change
 in a new version of LilyPond.
 
 @example
-violin = \relative c'' @{
-g4 c'8. e16
+violin = \relative @{
+g'4 c'8. e16
 @}
-...
+@dots{}
 \score @{
   \new GrandStaff @{
     \new Staff @{
@@ -177,18 +218,17 @@ g4 c'8. e16
 @}
 @end example
 
-@item @strong{Separate tweaks from music definitions}.  This
-point was made previously, but for large
-projects it is absolutely vital.  We might need to change
-the definition of @code{fthenp}, but then we only need
-to do this once, and we can still avoid touching anything
-inside @code{violin}.
+@item @strong{Separate tweaks from music definitions}.  This point was
+made previously, but for large projects it is absolutely vital.  We
+might need to change the definition of @code{fthenp}, but then we only
+need to do this once, and we can still avoid touching anything inside
+@code{violin}.
 
 @example
 fthenp = _\markup@{
   \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
-violin = \relative c'' @{
-g4\fthenp c'8. e16
+violin = \relative @{
+g'4\fthenp c'8. e16
 @}
 @end example
 
@@ -205,7 +245,7 @@ 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
+comment (indicated by @code{%@{@dots{}%@}}).  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
@@ -235,9 +275,9 @@ then comment out all of the bass music (but leave
 @code{\bass} in the @code{\score} uncommented.
 
 @example
-bass = \relative c' @{
+bass = \relative @{
 %@{
-  c4 c c c
+  c'4 c c c
   d d d d
 %@}
 @}
@@ -281,11 +321,11 @@ See the @strong{GNU Make Manual} for full details on using
 can do.
 
 The commands to define rules in a makefile differ
-according to platform; for instance the various forms of Linux and
+according to platform; for instance the various forms of GNU/Linux and
 MacOS use @code{bash}, while Windows uses @code{cmd}.  Note that on
 MacOS X, you need to configure the system to use the command-line
 interpreter.  Here are some example makefiles, with versions for both
-Linux/MacOS and Windows.
+GNU/Linux/MacOS and Windows.
 
 The first example is for an orchestral work in four
 movements with a directory structure as follows:
@@ -326,7 +366,7 @@ files in the @file{Notes} directory:
 
 @example
 %%% top of file "symphony-cello.ly"
-\include ../definitions.ily
+\include ../symphonyDefs.ily
 \include ../Notes/cello.ily
 @end example