X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchanging-defaults.itely;h=fb480d6d2a66f372b8d8c5389a41160e227d6844;hb=a3f254c202987779e42f547ebd919a1e63398a74;hp=8137506bf0748383287c1f5e79f2cdfbfeddd61d;hpb=b8dd0ca9bcc448d19f7caa3833ccc5a2d5e73664;p=lilypond.git

diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index 8137506bf0..fb480d6d2a 100644
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -56,14 +56,14 @@ notation.  For example, giving each staff a separate time signature.
 @item
 Page layout: changing the appearance of the spacing, line
 breaks, and page dimensions.  These modifications are discussed
-in @ref{Non-musical notation} and @ref{Spacing issues}.
+in @ref{Non-musical notation}, and @ref{Spacing issues}.
 @end itemize
 
 Internally, LilyPond uses Scheme (a LISP dialect) to provide
 infrastructure.  Overriding layout decisions in effect accesses the
 program internals, which requires Scheme input.  Scheme elements are
 introduced in a @code{.ly} file with the hash mark
-@code{#}.@footnote{@ref{Scheme tutorial} contains a short tutorial
+@code{#}.@footnote{@ref{Scheme tutorial}, contains a short tutorial
 on entering numbers, lists, strings, and symbols in Scheme.}
 
 
@@ -437,6 +437,7 @@ This section describes what contexts are, and how to modify them.
 * Changing context default settings::  
 * Defining new contexts::       
 * Aligning contexts::           
+* Vertical grouping of grobs::  
 @end menu
 
 
@@ -444,7 +445,7 @@ This section describes what contexts are, and how to modify them.
 @subsection Contexts explained
 
 When music is printed, a lot of notational elements must be added to the
-input.  For example, compare the input and output of the following example:
+output.  For example, compare the input and output of the following example:
 
 @lilypond[quote,verbatim,relative=2,fragment]
 cis4 cis2. g4
@@ -889,7 +890,7 @@ Here @var{name} is the name of a graphical object, like @code{Stem} or
 @code{NoteHead}, and @var{property} is an internal variable of the
 formatting system (@q{grob property} or @q{layout property}).  The latter is a
 symbol, so it must be quoted.  The subsection @ref{Constructing a
-tweak} explains what to fill in for @var{name}, @var{property}, and
+tweak}, explains what to fill in for @var{name}, @var{property}, and
 @var{value}.  Here we only discuss the functionality of this command.
 
 The command
@@ -917,8 +918,8 @@ within the current @context{Staff}.  After the command is interpreted
 all stems are thickened.
 
 Analogous to @code{\set}, the @var{context} argument may be left out,
-causing it to default to @context{Voice}, and adding @code{\once} applies
-the change during one timestep only
+causing the default context @context{Voice} to be used.  Adding
+@code{\once} applies the change during one timestep only.
 
 @lilypond[quote,fragment,verbatim,relative=2]
 c4
@@ -1004,8 +1005,8 @@ from the music in the @code{\layout} block,
 @}
 @end example
 
-Here @code{\Staff} takes the existing definition for context @context{Staff} from the
-identifier @code{\Staff}.
+The @code{\Staff} command brings in the existing definition of the
+staff context so that it can be modified.
 
 The statements
 @example
@@ -1100,11 +1101,10 @@ These settings are defined within a @code{\context} block inside a
 @}
 @end example
 
-In the following discussion, the example input shown should go on the
-@dots{} in the previous fragment.
+In the following discussion, the example input shown should go in place
+of the @dots{} in the previous fragment.
 
-First the context's name is defined.  Instead of @context{Voice} it
-will be called @context{ImproVoice},
+First it is necessary to define a name for the new context:
 
 @example
 \name ImproVoice
@@ -1118,14 +1118,15 @@ giving the new context an alias @context{Voice},
 \alias Voice
 @end example
 
-The context will print notes, and instructive texts
+The context will print notes and instructive texts, so we need to add
+the engravers which provide this functionality,
 
 @example
 \consists Note_heads_engraver
 \consists Text_engraver
 @end example
 
-but only on the center line,
+but we only need this on the center line,
 
 @example
 \consists Pitch_squash_engraver
@@ -1240,14 +1241,31 @@ ossia = { f4 f f f }
 @end lilypond
 
 
+@node Vertical grouping of grobs
+@subsection Vertical grouping of grobs
+
+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
+VerticalAxisGroup. 
+
 
 @node The \override command
-@section The \override command
+@section The @code{\override} command
 
 In the previous section, we have already touched on a command that
 changes layout details: the @code{\override} command.  In this section,
-we will look in more detail at how to use the command in practice.
+we will look in more detail at how to use the command in practice.  The
+general syntax of this command is:
 
+@example
+\override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value}
+@end example
+
+This will set the @var{layout_property} of the specified @var{layout_object},
+which is a member of the @var{context}, to the @var{value}.
 
 @menu
 * Constructing a tweak::        
@@ -1255,7 +1273,8 @@ we will look in more detail at how to use the command in practice.
 * Layout interfaces::           
 * Determining the grob property::  
 * Objects connected to the input::  
-* \set vs. \override::          
+* Using Scheme code instead of \tweak::  
+* \set versus \override::       
 * Difficult tweaks::            
 @end menu
 
@@ -1271,7 +1290,7 @@ Commands which change output generally look like
 @end example
 
 @noindent
-This means that we must determine these bits of information:
+To construct this tweak we must determine these bits of information:
 
 @itemize
 @item the context: here @context{Voice}.
@@ -1365,6 +1384,14 @@ second bit of information listed under @b{See also} in the Notation
 manual.
 @end ignore
 
+@ifnothtml
+The programmer's reference is available as an HTML document.  It is
+highly recommended that you read it in HTML form, either online or
+by downloading the HTML documentation.  This section will be much more
+difficult to understand if you are using the 
+PDF manual.
+@end ifnothtml
+
 Follow the link to @internalsref{Fingering}.  At the top of the
 page, you will see
 
@@ -1373,8 +1400,8 @@ Fingering objects are created by: @internalsref{Fingering_engraver} and
 @internalsref{New_fingering_engraver}.
 @end quotation
 
-By clicking around in the program reference, we can follow the
-flow of information within the program, following links like this:
+By following related links inside the program reference, we can follow the
+flow of information within the program:
 
 @itemize @bullet
 
@@ -1432,7 +1459,7 @@ The page for @code{Fingering} lists the definitions for the
 @end quotation
 
 @noindent
-which means that the number will be kept at a distance of at least 0.6
+which means that the number will be kept at a distance of at least 0.5
 of the note head.
 
 
@@ -1584,7 +1611,7 @@ Fingering_engraver is part of contexts: @dots{} @internalsref{Voice}
 @funindex \tweak
 
 In some cases, it is possible to take a short-cut for tuning graphical
-objects. For objects that result directly from a piece of the input,
+objects.  For objects that result directly from a piece of the input,
 you can use the @code{\tweak} function, for example
 
 @lilypond[relative=2,fragment,verbatim,ragged-right]
@@ -1596,7 +1623,7 @@ you can use the @code{\tweak} function, for example
 >4-\tweak #'padding #10 -.
 @end lilypond
 
-As you can see, properties are set directly in the objects directly,
+As you can see, properties are set in the objects directly,
 without mentioning the grob name or context where this should be
 applied.
 
@@ -1604,8 +1631,8 @@ This technique only works for objects that are directly connected to
 an @internalsref{event} from the input, for example
 
 @itemize @bullet
-@item note heads, caused by chord-pitch (i.e., notes inside a chord).
-@item articulation signs, caused by articulation instructions.
+@item note heads, caused by chord-pitch (i.e., notes inside a chord)
+@item articulation signs, caused by articulation instructions
 @end itemize
 
 It notably does not work for stems and accidentals (these are caused
@@ -1621,12 +1648,58 @@ to output, so
 @end example
 
 @noindent
-will not change color.  See @ref{Displaying music expressions} for
+does not change color.  See @ref{Displaying music expressions}, for
 details.
 
 
-@node \set vs. \override
-@subsection \set vs. \override
+@node Using Scheme code instead of \tweak
+@subsection Using Scheme code instead of @code{\tweak}
+
+The main disadvantage of @code{\tweak} is its syntactical
+inflexibility.  For example, the following produces a syntax error.
+
+@example
+F = \tweak #'font-size #-3 -\flageolet
+
+\relative c'' @{
+  c4^\F c4_\F
+@}
+@end example
+
+@noindent
+With other words, @code{\tweak} doesn't behave like an articulation
+regarding the syntax; in particular, it can't be attached with
+@samp{^} and @samp{_}.
+
+Using Scheme, this problem can be circumvented.  The route to the
+result is given in @ref{Adding articulation to notes (example)},
+especially how to use @code{\displayMusic} as a helping guide.
+
+@example
+F = #(let ((m (make-music 'ArticulationEvent
+                          'articulation-type "flageolet")))
+       (set! (ly:music-property m 'tweaks)
+             (acons 'font-size -3
+                    (ly:music-property m 'tweaks)))
+       m)
+ 
+\relative c'' @{
+  c4^\F c4_\F
+@}
+@end example
+
+@noindent
+Here, the @code{tweaks} properties of the flageolet object
+@samp{m} (created with @code{make-music}) are extracted with
+@code{ly:music-property}, a new key-value pair to change the
+font size is prepended to the property list with the
+@code{acons} Scheme function, and the result is finally
+written back with @code{set!}.  The last element of the
+@code{let} block is the return value, @samp{m} itself.
+
+
+@node \set versus \override
+@subsection @code{\set} vs. @code{\override}
 
 We have seen two methods of changing properties: @code{\set} and
 @code{\override}.  There are actually two different kinds of
@@ -1747,16 +1820,20 @@ one.  For example, if using this with @code{Hairpin},
 
 
 @item Some objects cannot be changed with @code{\override} for
-technical reasons. Examples of those are @code{NonMusicalPaperColumn}
+technical reasons.  Examples of those are @code{NonMusicalPaperColumn}
 and @code{PaperColumn}.  They can be changed with the
-@code{\outputProperty} function, which works similar to @code{\once
-\override}, but uses a different syntax,
+@code{\overrideProperty} function, which works similar to @code{\once
+\override}, but uses a different syntax.
 
 @example
-\outputProperty
+\overrideProperty
 #"Score.NonMusicalPaperColumn"  % Grob name
 #'line-break-system-details     % Property name
 #'((next-padding . 20))         % Value
 @end example
 
+Note, however, that @code{\override}, applied to
+@code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
+expected within @code{\context} blocks.
+
 @end itemize