(option_parser): update to 2.7.40

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

diff --git a/Documentation/user/global.itely b/Documentation/user/global.itely
index 4a164f67cce3a68cde7fa597a7ad13270dc525da..cdd72d9e19175c02eab11ea4ac6b97030212c4d8 100644 (file)
--- a/Documentation/user/global.itely
+++ b/Documentation/user/global.itely
@@ -13,7 +13,7 @@ specific notation.
 
 @menu
 * Input files::                 
 
 @menu
 * Input files::                 

-* Music expressions again::     
+* A single music expression::   

 * Titles and headers::          
 * Paper and pages::             
 * Music layout::                
 * Titles and headers::          
 * Paper and pages::             
 * Music layout::                


@@ -83,6 +83,11 @@ An output definition, such as @code{\paper}, @code{\midi}, and
 @code{\layout}.  Such a definition at the toplevel changes the default
 settings for the block entered.
 
 @code{\layout}.  Such a definition at the toplevel changes the default
 settings for the block entered.
 

+@item
+A direct scheme expression, such as
+@code{#(set-default-paper-size "a7" 'landscape)} or
+@code{#(ly:set-option 'point-and-click #f)}.
+

 @item
 A @code{\header} block.  This sets the global header block.  This
 is the block containing the definitions for book-wide settings, like
 @item
 A @code{\header} block.  This sets the global header block.  This
 is the block containing the definitions for book-wide settings, like


@@ -100,14 +105,14 @@ This behavior can be changed by setting the variable
 @code{toplevel-score-handler} at toplevel.  The default handler is
 defined in the init file @file{scm/@/lily@/.scm}.
 
 @code{toplevel-score-handler} at toplevel.  The default handler is
 defined in the init file @file{scm/@/lily@/.scm}.
 

-The @code{\score} must begin with music, and may contain only
-one music block.
+The @code{\score} must begin with a music expression, and may
+contain only one music expression.

 
 @item
 A @code{\book} block logically combines multiple movements
 
 @item
 A @code{\book} block logically combines multiple movements

-(i.e., multiple @code{\score} blocks) in one document.  A number of
-@code{\scores} creates a single output file, where all movement are
-concatenated.
+(i.e., multiple @code{\score} blocks) in one document.  If there are
+a number of @code{\scores}, a single output file will be created
+in which all movements are concatenated.

 
 This behavior can be changed by setting the variable
 @code{toplevel-book-handler} at toplevel.  The default handler is
 
 This behavior can be changed by setting the variable
 @code{toplevel-book-handler} at toplevel.  The default handler is


@@ -289,11 +294,48 @@ To use a Unicode escape sequence, use
 
 
 
 
 
 

-@c  FIXME: --must-- delete/modify this before 2.8.0!!!  -gp
-@node Music expressions again
-@section Music expressions again
+@node A single music expression
+@section A single music expression
+
+A @code{\score} must contain a single music expression.  However,
+this music expression may be of any size.  Recall that music
+expressions may be included inside other expressions to form
+larger expressions.  All of these examples are single music
+expressions; note the curly braces @{ @} or angle brackets <<
+>> at the beginning and ending of the music.

 
 

-Should we include anything about this here?
+@example
+@{ c'4 c' c' c' @}
+@end example
+
+@lilypond[ragged-right,verbatim,quote]
+{
+  { c'4 c' c' c'}
+  { d'4 d' d' d'}
+}
+@end lilypond
+
+@lilypond[ragged-right,verbatim,quote]
+<<
+  \new Staff { c'4 c' c' c' }
+  \new Staff { d'4 d' d' d' }
+>>
+@end lilypond
+
+@example
+@{
+  \new GrandStaff <<
+    \new StaffGroup <<
+      \new Staff @{ \flute @}
+      \new Staff @{ \oboe @}
+    >>
+    \new StaffGroup <<
+      \new Staff @{ \violinI @}
+      \new Staff @{ \violinII @}
+    >>
+  >>
+@}
+@end example

 
 
 @node Titles and headers
 
 
 @node Titles and headers


@@ -417,12 +459,12 @@ Here is a short example.
   composer = "Composer"
 @}
 \header @{
   composer = "Composer"
 @}
 \header @{

-  title = "Title"
+  piece = "Piece"

 @}
 \score @{
   \new Staff @{ c'4 @}
   \header @{
 @}
 \score @{
   \new Staff @{ c'4 @}
   \header @{

-    title = "New title"  % overwrite previous one
+    piece = "New piece"  % overwrite previous one

   @}
 @}
 @end example
   @}
 @}
 @end example


@@ -576,6 +618,10 @@ and wider line widths will be set correspondingly.
 #(set-default-paper-size "a6" 'landscape)
 @end example 
 
 #(set-default-paper-size "a6" 'landscape)
 @end example 
 

+Setting the paper size will adjust a number of @code{\paper} variables
+(such as margins).  To use a particular paper size with altered
+@code{\paper} variables, set the paper size before setting the variables.
+

 
 @node Page formatting
 @subsection Page formatting
 
 @node Page formatting
 @subsection Page formatting


@@ -648,14 +694,15 @@ printable area.
 
 @cindex @code{ragged-bottom}
 @item ragged-bottom
 
 @cindex @code{ragged-bottom}
 @item ragged-bottom

-If set to true, systems will not be spread across the page.
+If set to true, systems will not be spread vertically across the page.  This
+does not affect the last page.

 
 This should be set to true for pieces that have only two or three
 systems per page, for example orchestral scores.
  
 @cindex @code{ragged-last-bottom}
 @item ragged-last-bottom
 
 This should be set to true for pieces that have only two or three
 systems per page, for example orchestral scores.
  
 @cindex @code{ragged-last-bottom}
 @item ragged-last-bottom

-If set to false, systems will be spread to fill the last page.
+If set to false, systems will be spread vertically to fill the last page.

 
 Pieces that amply fill two pages or more should have this set to
 true.
 
 Pieces that amply fill two pages or more should have this set to
 true.


@@ -719,11 +766,14 @@ The markup command @code{\slashSeparator} is provided as a sensible
 default,  for example
 
 @lilypond[ragged-right]
 default,  for example
 
 @lilypond[ragged-right]

-\paper {
-  systemSeparatorMarkup = \slashSeparator
+\book {
+  \score {
+    \relative { c1 \break c1 }
+  }
+  \paper {
+    systemSeparatorMarkup = \slashSeparator
+  }

 }
 }

-
-\relative { c1 \break c1 }

 @end lilypond
 
 
 @end lilypond
 
 


@@ -1009,11 +1059,12 @@ more systems onto one page.
 
 Normally staves are stacked vertically.  To make staves maintain a
 distance, their vertical size is padded.  This is done with the
 
 Normally staves are stacked vertically.  To make staves maintain a
 distance, their vertical size is padded.  This is done with the

-property @code{minimum-Y-extent}.  It takes a pair of numbers, so
-if you want to make it smaller than its default @code{#'(-4 . 4)},
-then you could set. When applied to a
+property @code{minimum-Y-extent}.  When applied to a

 @internalsref{VerticalAxisGroup}, it controls the size of a horizontal
 @internalsref{VerticalAxisGroup}, it controls the size of a horizontal

-line, such as a staff or a line of lyrics.  
+line, such as a staff or a line of lyrics.  @code{minimum-Y-extent}
+takes a pair of numbers, so
+if you want to make it smaller than its default @code{#'(-4 . 4)}
+then you could set

 
 @example
 \override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
 
 @example
 \override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)


@@ -1352,6 +1403,7 @@ No work-around exists for decreasing the amount of space.
 @cindex @code{indent}
 @cindex @code{line-width}
 @cindex @code{ragged-right}
 @cindex @code{indent}
 @cindex @code{line-width}
 @cindex @code{ragged-right}

+@cindex @code{ragged-last}

 
 @c Although line-width can be set in \layout, it should be set in paper
 @c block, to get page layout right.
 
 @c Although line-width can be set in \layout, it should be set in paper
 @c block, to get page layout right.


@@ -1364,21 +1416,30 @@ control the indentation of the first line of music, and the lengths of
 the lines.
 
 If @code{ragged-right} is set to true in the @code{\layout} block, then
 the lines.
 
 If @code{ragged-right} is set to true in the @code{\layout} block, then

-the lines are justified at their natural length.  This is useful for
+systems ends at their natural horizontal length, instead of being spread
+horizontally to fill the whole line.  This is useful for

 short fragments, and for checking how tight the natural spacing is.
 
 @cindex page layout
 @cindex vertical spacing
 
 short fragments, and for checking how tight the natural spacing is.
 
 @cindex page layout
 @cindex vertical spacing
 

-The option @code{raggedlast} is similar to @code{ragged-right}, but
+The option @code{ragged-last} is similar to @code{ragged-right}, but

 only affects the last line of the piece.  No restrictions are put on
 that line.  The result is similar to formatting text paragraphs.  In a
 only affects the last line of the piece.  No restrictions are put on
 that line.  The result is similar to formatting text paragraphs.  In a

-paragraph, the last line simply takes its natural length.
+paragraph, the last line simply takes its natural horizontal length.

 @c Note that for text there are several options for the last line.
 @c While Knuth TeX uses natural length, lead typesetters use the same
 @c stretch as the previous line.  eTeX uses \lastlinefit to
 @c interpolate between both these solutions.
 
 @c Note that for text there are several options for the last line.
 @c While Knuth TeX uses natural length, lead typesetters use the same
 @c stretch as the previous line.  eTeX uses \lastlinefit to
 @c interpolate between both these solutions.
 

+@example
+\layout @{
+  indent = #0
+  line-width = #150
+  ragged-last = ##t
+@}
+@end example
+

 
 @node Line breaking
 @subsection Line breaking
 
 @node Line breaking
 @subsection Line breaking


@@ -1432,6 +1493,18 @@ fit pages in a second formatting run.  This is fairly new and
 complicated; see @inputfileref{input/regression/,page-layout-twopass.ly}
 for details.
 
 complicated; see @inputfileref{input/regression/,page-layout-twopass.ly}
 for details.
 

+@refbugs
+
+Line breaks can only occur if there is a ``proper'' bar line.  A note
+which is hanging over a bar line is not proper, such as
+
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+c4 c2 c2 \break   % this does nothing
+c2 c4 |           % a break here would work
+c4 c2 c4 ~ \break % as does this break
+c4 c2 c4
+@end lilypond
+

 
 @node Page breaking
 @subsection Page breaking
 
 @node Page breaking
 @subsection Page breaking


@@ -1627,7 +1700,12 @@ their two extremes.  The fractions can be adjusted by
 For each type of MIDI instrument, a volume range can be defined.  This
 gives a basic equalizer control, which can enhance the quality of
 the MIDI output remarkably.  The equalizer can be controlled by
 For each type of MIDI instrument, a volume range can be defined.  This
 gives a basic equalizer control, which can enhance the quality of
 the MIDI output remarkably.  The equalizer can be controlled by

-setting @code{instrumentEqualizer}.
+setting @code{instrumentEqualizer}, or by setting
+
+@example
+\set Staff.midiMinimumVolume = #0.2
+\set Staff.midiMaximumVolume = #0.8
+@end example

 
 To remove dynamics from the MIDI output, insert the following lines
 in the @code{\midi@{@}} section.
 
 To remove dynamics from the MIDI output, insert the following lines
 in the @code{\midi@{@}} section.