Info about \set and \override.

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

diff --git a/Documentation/user/global.itely b/Documentation/user/global.itely
index 1dc1698af19c1c98a672949ae4d7d0b36c2c81bb..f98e7c928af049381a6aaf3cc91bb28548a8c389 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


@@ -222,8 +227,8 @@ VERSION is in the form ``2.6.1'') are on the path and available to
 current working directory are available to \include, but a file of the same
 name in LilyPond's installation takes precedence.  Files are
 available to \include from directories in the search path specified as an
 current working directory are available to \include, but a file of the same
 name in LilyPond's installation takes precedence.  Files are
 available to \include from directories in the search path specified as an

-option when invoking @code{lilypond --include=DIR} which adds DIR to the search
-path.
+option when invoking @code{lilypond --include=DIR} which adds DIR to the 
+search path.

 
 The @code{\include} statement can use full path information, but with the Unix
 convention @code{"/"} rather than the DOS/Windows @code{"\"}.  For example,
 
 The @code{\include} statement can use full path information, but with the Unix
 convention @code{"/"} rather than the DOS/Windows @code{"\"}.  For example,


@@ -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

 
 

-Should we include anything about this here?
+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.
+
+@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


@@ -376,14 +418,18 @@ may use any @ref{Text markup} commands in the header.
 \book {
   \header {
     dedication = "dedicated to me"
 \book {
   \header {
     dedication = "dedicated to me"

-    title = \markup \center-align { "Title first line" "Title second line, longer" }
+    title = \markup \center-align { "Title first line" "Title second line, 
+longer" }

     subtitle = "the subtitle,"
     subtitle = "the subtitle,"

-    subsubtitle = #(string-append "subsubtitle LilyPond version " (lilypond-version))
+    subsubtitle = #(string-append "subsubtitle LilyPond version " 
+(lilypond-version))

     poet = "Poet"
     composer =  \markup \center-align { "composer" \small "(1847-1973)" }
     texttranslator = "Text Translator"
     poet = "Poet"
     composer =  \markup \center-align { "composer" \small "(1847-1973)" }
     texttranslator = "Text Translator"

-    meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge "r" }
-    arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
+    meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge 
+"r" }
+    arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize 
+#-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }

     instrument = \markup \bold \italic "instrument"
     piece = "Piece"
   }
     instrument = \markup \bold \italic "instrument"
     piece = "Piece"
   }


@@ -417,12 +463,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


@@ -522,7 +568,9 @@ composer flush right on a single line.
 
 @refbugs
 
 
 @refbugs
 

-The @code{breakbefore=##t} header requires that there is a @code{piece} header as well.  It may be used as a normal header, or left  blank (@code{=""}) as in the example above, but it must be present.
+The @code{breakbefore=##t} header requires that there is a @code{piece} 
+header as well.  It may be used as a normal header, or left  blank 
+(@code{=""}) as in the example above, but it must be present.

 
 
 
 
 
 


@@ -552,7 +600,8 @@ To change the paper size, there are two commands,
 @}
 @end example
 
 @}
 @end example
 

-The first command sets the size of all pages.  The second command sets the size
+The first command sets the size of all pages.  The second command sets the 
+size

 of the pages that the @code{\paper} block applies to -- if the @code{\paper}
 block is at the top of the file, then it will apply to all pages.  If the
 @code{\paper} block is inside a @code{\book}, then the paper size will only
 of the pages that the @code{\paper} block applies to -- if the @code{\paper}
 block is at the top of the file, then it will apply to all pages.  If the
 @code{\paper} block is inside a @code{\book}, then the paper size will only


@@ -576,6 +625,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


@@ -588,6 +641,23 @@ and wider line widths will be set correspondingly.
 LilyPond will do page layout, set margins, and add headers and
 footers to each page.
 
 LilyPond will do page layout, set margins, and add headers and
 footers to each page.
 

+@cindex @code{annotate-spacing}
+@cindex Spacing, display of properties
+
+To graphically display the dimensions of properties that may
+be altered for page formatting, use
+
+@example
+\paper @{
+  annotate-spacing = ##t
+@}
+@end example
+
+@noindent
+All units dimensions are measured in staff spaces. The pairs
+(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
+@var{b} the upper edge of the interval.
+

 The default layout responds to the following settings in the
 @code{\paper} block.
 
 The default layout responds to the following settings in the
 @code{\paper} block.
 


@@ -648,14 +718,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 false for pieces that have only two or three
+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
 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 +790,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
 
 


@@ -764,7 +838,8 @@ can.}
 
 The header and footer are created by the functions @code{make-footer}
 and @code{make-header}, defined in @code{\paper}.  The default
 
 The header and footer are created by the functions @code{make-footer}
 and @code{make-header}, defined in @code{\paper}.  The default

-implementations are in @file{scm/@/page@/-layout@/.scm}.
+implementations are in @file{ly/@/paper@/-defaults@/.ly} and
+@file{ly/@/titling@/-init@/.ly}.

 
 The page layout itself is done by two functions in the
 @code{\paper} block, @code{page-music-height} and
 
 The page layout itself is done by two functions in the
 @code{\paper} block, @code{page-music-height} and


@@ -782,6 +857,9 @@ values of @code{left-margin} and @code{line-width}.
 The default page header puts the page number and the @code{instrument}
 field from the @code{\header} block on a line.
 
 The default page header puts the page number and the @code{instrument}
 field from the @code{\header} block on a line.
 

+The titles (from the @code{\header@{@}} section) are treated as a
+system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
+add space between the titles and the first system of the score.

 
 
 @node Music layout
 
 
 @node Music layout


@@ -1009,11 +1087,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)


@@ -1087,17 +1166,18 @@ then use the following
 
 @c let's wait for a some comments before writing more.
 
 
 @c let's wait for a some comments before writing more.
 

-The vertical spacing on a page can also be changed for each system individually.
+The vertical spacing on a page can also be changed for each system 
+individually.

 Some examples are found in the example file
 @inputfileref{input/regression/,page-spacing.ly}.
 
 Some examples are found in the example file
 @inputfileref{input/regression/,page-spacing.ly}.
 

-When setting @code{annotatespacing} in the @code{\paper} block LilyPond
+When setting @code{annotate-spacing} in the @code{\paper} block LilyPond

 will graphically indicate the dimensions of properties that may be set
 for page spacing,
 
 @lilypond[verbatim]
 #(set-default-paper-size "a7" 'landscape)
 will graphically indicate the dimensions of properties that may be set
 for page spacing,
 
 @lilypond[verbatim]
 #(set-default-paper-size "a7" 'landscape)

-\paper { annotatespacing = ##t }
+\paper { annotate-spacing = ##t }

 { c4 }
 @end lilypond
 
 { c4 }
 @end lilypond
 


@@ -1352,6 +1432,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 +1445,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 +1522,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


@@ -1466,7 +1568,9 @@ piece in several movements), use @code{breakbefore} in the header.
 
 @refbugs
 
 
 @refbugs
 

-The @code{breakbefore=##t} header requires that there is a @code{piece} header as well.  It may be used as a normal header, or left  blank (@code{=""}) as in the example above, but it must be present.
+The @code{breakbefore=##t} header requires that there is a @code{piece} 
+header as well.  It may be used as a normal header, or left  blank 
+(@code{=""}) as in the example above, but it must be present.

 
 
 
 
 
 


@@ -1627,7 +1731,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.