Doc: Issue 5032: Using \with with \chords, \drums and \figures

[lilypond.git] / Documentation / notation / changing-defaults.itely

diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index 60702dc4f70b3141f312bd2dc581aa78ac3797cc..8457f6dba0aaa65b2739ec73e5b2b489773c716d 100644 (file)
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -522,8 +522,8 @@ Notation Reference:
 
 Contexts are usually terminated at the first musical moment in
 which they have nothing to do.  So @code{Voice} contexts die as
-soon as they contain no events; @code{Staff} contexts die as soon
-as all the @code{Voice} contexts within them contain no events; etc.
+soon as they contain no events, @code{Staff} contexts die as soon
+as all the @code{Voice} contexts within them contain no events, etc.
 This can cause difficulties if earlier contexts which have died
 have to be referenced, for example, when changing staves with
 @code{\change} commands, associating lyrics with a voice with
@@ -1005,8 +1005,26 @@ command:
 @}
 @end example
 
-Since such a @q{context modification} is specified inside of
-music, it will affect @emph{all} outputs (typesetting @emph{and}
+Alternatively, if the music is being entered using the short form of the
+input mode-specifying commands, e.g. @code{\chords} rather than
+@code{\chordmode}, the @code{\with} command must be placed immediately
+after the mode-specifying command:
+
+@example
+\chords \with @{ [context settings for this (implicit) context instance only] @}
+@{
+  @dots{}
+@}
+@end example
+
+@noindent
+as it is the implicit context created by these short forms which should
+be modified.  The same consideration applies to the other input
+mode-specifying short forms (@code{\drums}, @code{\figures}), see
+@ref{Input modes}.
+
+Since context modifications specified in @code{\with} blocks are inside
+music, they will affect @emph{all} outputs (typesetting @emph{and}
 Midi) as opposed to changes within an output definition.
 
 The following types of settings may be specified:
@@ -1082,6 +1100,10 @@ A predefined command such as @code{\dynamicUp}
 
 @end itemize
 
+@seealso
+Notation Reference:
+@ref{Input modes}
+
 @node Order of precedence
 @unnumberedsubsubsec Order of precedence
 
@@ -4146,7 +4168,7 @@ The VerticalAlignment and VerticalAxisGroup grobs work together.
 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
 etc.  VerticalAlignment then vertically aligns the different grobs
 grouped together by VerticalAxisGroup.  There is usually only one
-VerticalAlignment per score but every Staff, Lyrics, etc. has its own
+VerticalAlignment per score but every Staff, Lyrics, etc., has its own
 VerticalAxisGroup.
 
 
@@ -4546,7 +4568,7 @@ layout. Settings chosen for @code{\alterBroken} may be unsuitable
 for a spanner that is no longer broken or is split into more
 segments than before.  Explicit use of @code{\break} can guard
 against this situation.
- 
+
 The @code{\alterBroken} command is ineffective for spanner
 properties accessed before line-breaking such as
 @code{direction}.
@@ -4712,7 +4734,7 @@ must return @code{#t}.
 
 @item @code{@var{@dots{}music@dots{}}}
 @tab normal LilyPond input, using @code{$} (in places where only
-Lilypond constructs are allowed) or @code{#} (to use it as a Scheme
+LilyPond constructs are allowed) or @code{#} (to use it as a Scheme
 value or music function argument or music inside of music lists) to
 reference arguments
 (eg. @samp{#arg1}).
@@ -4743,7 +4765,7 @@ are also allowed.
 Notation Reference:
 @ref{Predefined type predicates}.
 
-Extending Lilypond:
+Extending LilyPond:
 @rextend{Music functions}.
 
 Installed Files: