From: Graham Percival <graham@percival-music.ca>
Date: Sat, 17 Feb 2007 06:42:26 +0000 (-0800)
Subject: Jonathan Henkleman's doc edits.
X-Git-Tag: release/2.11.19-1^2
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=2db1ce60d2c0c4cb73c543eb6834c69abeebc74d;p=lilypond.git

Jonathan Henkleman's doc edits.
---

diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely
index 66cacbe0db..777c92b44b 100644
--- a/Documentation/user/advanced-notation.itely
+++ b/Documentation/user/advanced-notation.itely
@@ -266,12 +266,12 @@ c2\startTextSpan b c\stopTextSpan a
 
 @refcommands
 
-@cindex textSpannerUp
-@code{textSpannerUp},
-@cindex textSpannerDown
-@code{textSpannerDown},
-@cindex textSpannerNeutral
-@code{textSpannerNeutral}.
+@funindex textSpannerUp
+@code{\textSpannerUp},
+@funindex textSpannerDown
+@code{\textSpannerDown},
+@funindex textSpannerNeutral
+@code{\textSpannerNeutral}.
 
 
 @commonprop
@@ -2232,7 +2232,9 @@ of @code{font-size} is a number indicating the size relative to the
 standard size for the current staff height.  Each step up is an
 increase of approximately 12% of the font size.  Six steps is exactly a
 factor two.  The Scheme function @code{magstep} converts a
-@code{font-size} number to a scaling factor.
+@code{font-size} number to a scaling factor.  The @code{font-size}
+property can also be set directly, so that only certain layout objects are
+affected.
 
 @lilypond[quote,fragment,relative=1,verbatim]
 c8
diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index 8137506bf0..21d66115f0 100644
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -444,7 +444,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
@@ -917,8 +917,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 +1004,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 +1100,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 +1117,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
@@ -1246,8 +1246,15 @@ ossia = { f4 f f f }
 
 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::        
@@ -1271,7 +1278,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 +1372,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 +1388,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 +1447,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.
 
 
diff --git a/Documentation/user/instrument-notation.itely b/Documentation/user/instrument-notation.itely
index b6bc2c96b2..61473e29e4 100644
--- a/Documentation/user/instrument-notation.itely
+++ b/Documentation/user/instrument-notation.itely
@@ -425,7 +425,7 @@ Modifiers can be mixed with additions
 @funindex m
 
 Since an unaltered 11 does not sound good when combined with an
-unaltered 3, the 11 is removed in this case (unless it is added
+unaltered 13, the 11 is removed in this case (unless it is added
 explicitly)
 @lilypond[quote,ragged-right,fragment,verbatim]
 \chordmode { c:13 c:13.11 c:m13 }
@@ -441,7 +441,7 @@ as bass notes, can be specified by appending
 @end lilypond
 @funindex /+
 
-A bass note can be added instead transposed out of the chord,
+A bass note can be added instead of transposed out of the chord,
 by using @code{/+}@var{pitch}.
 
 @lilypond[quote,ragged-right,fragment,verbatim]
diff --git a/Documentation/user/non-music.itely b/Documentation/user/non-music.itely
index 7569c5a71c..790ecaa928 100644
--- a/Documentation/user/non-music.itely
+++ b/Documentation/user/non-music.itely
@@ -34,10 +34,10 @@ these files end with @samp{.ly}.
 
 @menu
 * File structure (introduction)::  
-* Multiple scores in a book::   
-* Extracting fragments of notation::  
 * File structure::              
 * A single music expression::   
+* Multiple scores in a book::   
+* Extracting fragments of notation::  
 * Including LilyPond files::    
 * Text encoding::               
 @end menu
@@ -74,125 +74,8 @@ c'4
 @noindent
 will result in a parsing error.  Instead, music should be inside other
 expressions, which may be put in a file by themselves.  Such
-expressions are called toplevel expressions.  The next section enumerates
-them all.
-
-
-@node Multiple scores in a book
-@subsection Multiple scores in a book
-
-@funindex \book
-@cindex movements, multiple
-
-A document may contain multiple pieces of music and texts.  Examples
-of these are an etude book, or an orchestral part with multiple
-movements.  Each movement is entered with a @code{\score} block,
-
-@example
-\score @{
-  @var{..music..}
-@}
-@end example
-
-and texts are entered with a @code{\markup} block,
-
-@example
-\markup @{
-  @var{..text..}
-@}
-@end example
-
-@funindex \book
-
-All the movements and texts which appear in the same @code{.ly} file 
-will normally be typeset in the form of a single output file. 
-
-@example
-\score @{
-  @var{..}
-@}
-\markup @{
-  @var{..}
-@}
-\score @{
-  @var{..}
-@}
-@end example
-
-However, if you want multiple output files from the same @code{.ly}
-file, then you can add multiple @code{\book} blocks, where each such
-@code{\book} block will result in a separate output. If you do not
-specify any @code{\book} block in the file, LilyPond will implicitly
-treat the full file as a single @code{\book} block, see @ref{File
-structure}. One important exception is within lilypond-book documents,
-where you explicitly have to add a @code{\book} block, otherwise only
-the first @code{\score} or @code{\markup} will appear in the output.
-
-The header for each piece of music can be put inside the @code{\score}
-block.  The @code{piece} name from the header will be printed before
-each movement.  The title for the entire book can be put inside the
-@code{\book}, but if it is not present, the @code{\header} which is at
-the top of the file is inserted.
-
-@example
-\header @{
-  title = "Eight miniatures"
-  composer = "Igor Stravinsky"
-@}
-\score @{
-  @dots{}
-  \header @{ piece = "Romanze" @}
-@}
-\markup @{
-   ..text of second verse..
-@}
-\markup @{
-   ..text of third verse..
-@}
-\score @{
-  @dots{}
-  \header @{ piece = "Menuetto" @}
-@}
-@end example
-
-@node Extracting fragments of notation
-@subsection Extracting fragments of notation
-
-It is possible to quote small fragments of a large score directly from
-the output. This can be compared to clipping a piece of a paper score
-with scissors.
-
-This is done by definining the measures that need to be cut out
-separately. For example, including the following definition
-
-
-@verbatim
-\layout {
-  clip-regions
-  = #(list
-      (cons
-       (make-rhythmic-location 5 1 2)
-       (make-rhythmic-location 7 3 4)))
-}       
-@end verbatim
-
-@noindent
-will extract a fragment starting halfway the fifth measure, ending in
-the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
-in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
-
-More clip regions can be defined by adding more pairs of
-rhythmic-locations to the list. 
-
-In order to use this feature, LilyPond must be invoked with
-@code{-dclip-systems}. The clips are output as EPS files, and are
-converted to PDF and PNG if these formats are switched on as well.
-
-For more information on output formats, see @ref{Invoking lilypond}.
-
-@seealso
-
-Examples: @inputfileref{input/regression/,clip-systems.ly}
+expressions are called toplevel expressions; see @ref{File structure} for
+a list of all such expressions.
 
 
 @node File structure
@@ -371,6 +254,123 @@ expressions; note the curly braces @{ @} or angle brackets <<
 @end example
 
 
+@node Multiple scores in a book
+@subsection Multiple scores in a book
+
+@funindex \book
+@cindex movements, multiple
+
+A document may contain multiple pieces of music and texts.  Examples
+of these are an etude book, or an orchestral part with multiple
+movements.  Each movement is entered with a @code{\score} block,
+
+@example
+\score @{
+  @var{..music..}
+@}
+@end example
+
+and texts are entered with a @code{\markup} block,
+
+@example
+\markup @{
+  @var{..text..}
+@}
+@end example
+
+@funindex \book
+
+All the movements and texts which appear in the same @code{.ly} file 
+will normally be typeset in the form of a single output file. 
+
+@example
+\score @{
+  @var{..}
+@}
+\markup @{
+  @var{..}
+@}
+\score @{
+  @var{..}
+@}
+@end example
+
+However, if you want multiple output files from the same @code{.ly}
+file, then you can add multiple @code{\book} blocks, where each such
+@code{\book} block will result in a separate output. If you do not
+specify any @code{\book} block in the file, LilyPond will implicitly
+treat the full file as a single @code{\book} block, see @ref{File
+structure}. One important exception is within lilypond-book documents,
+where you explicitly have to add a @code{\book} block, otherwise only
+the first @code{\score} or @code{\markup} will appear in the output.
+
+The header for each piece of music can be put inside the @code{\score}
+block.  The @code{piece} name from the header will be printed before
+each movement.  The title for the entire book can be put inside the
+@code{\book}, but if it is not present, the @code{\header} which is at
+the top of the file is inserted.
+
+@example
+\header @{
+  title = "Eight miniatures"
+  composer = "Igor Stravinsky"
+@}
+\score @{
+  @dots{}
+  \header @{ piece = "Romanze" @}
+@}
+\markup @{
+   ..text of second verse..
+@}
+\markup @{
+   ..text of third verse..
+@}
+\score @{
+  @dots{}
+  \header @{ piece = "Menuetto" @}
+@}
+@end example
+
+@node Extracting fragments of notation
+@subsection Extracting fragments of notation
+
+It is possible to quote small fragments of a large score directly from
+the output. This can be compared to clipping a piece of a paper score
+with scissors.
+
+This is done by definining the measures that need to be cut out
+separately. For example, including the following definition
+
+
+@verbatim
+\layout {
+  clip-regions
+  = #(list
+      (cons
+       (make-rhythmic-location 5 1 2)
+       (make-rhythmic-location 7 3 4)))
+}       
+@end verbatim
+
+@noindent
+will extract a fragment starting halfway the fifth measure, ending in
+the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
+in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
+
+More clip regions can be defined by adding more pairs of
+rhythmic-locations to the list. 
+
+In order to use this feature, LilyPond must be invoked with
+@code{-dclip-systems}. The clips are output as EPS files, and are
+converted to PDF and PNG if these formats are switched on as well.
+
+For more information on output formats, see @ref{Invoking lilypond}.
+
+@seealso
+
+Examples: @inputfileref{input/regression/,clip-systems.ly}
+
+
 @node Including LilyPond files
 @subsection Including LilyPond files
 
@@ -487,8 +487,8 @@ some pieces include a lot more information.
 @node Creating titles
 @subsection Creating titles
 
-Titles are created for each @code{\score} block, and for the full input
-file (or @code{\book} block).
+Titles are created for each @code{\score} block, as well as for the full
+input file (or @code{\book} block).
 
 The contents of the titles are taken from the @code{\header} blocks.
 The header block for a book supports the following