Merge branch 'master' into jneeman

[lilypond.git] / Documentation / user / non-music.itely

diff --git a/Documentation/user/non-music.itely b/Documentation/user/non-music.itely
index 9fb163d7c0742c579367e23aabf8a6691fc6c5c1..52c18dbf70b76cc5b181506a2393e86d48d5bb71 100644 (file)
--- a/Documentation/user/non-music.itely
+++ b/Documentation/user/non-music.itely
@@ -1,5 +1,11 @@
 @c -*- coding: utf-8; mode: texinfo; -*-
 @c This file is part of lilypond.tely
 @c -*- coding: utf-8; mode: texinfo; -*-
 @c This file is part of lilypond.tely

+@ignore
+    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+    When revising a translation, copy the HEAD committish of the
+    version that you are working on.  See TRANSLATION for details.
+@end ignore

 
 @c A menu is needed before every deeper *section nesting of @node's; run
 @c     M-x texinfo-all-menus-update
 
 @c A menu is needed before every deeper *section nesting of @node's; run
 @c     M-x texinfo-all-menus-update


@@ -24,14 +30,14 @@ specific notation.
 @section Input files
 
 The main format of input for LilyPond are text files.  By convention,
 @section Input files
 
 The main format of input for LilyPond are text files.  By convention,

-these files end with ``@code{.ly}''.
+these files end with @samp{.ly}.

 
 @menu
 * File structure (introduction)::  
 
 @menu
 * File structure (introduction)::  

-* Multiple scores in a book::   
-* Extracting fragments of notation::  

 * File structure::              
 * A single music expression::   
 * File structure::              
 * A single music expression::   

+* Multiple scores in a book::   
+* Extracting fragments of notation::  

 * Including LilyPond files::    
 * Text encoding::               
 @end menu
 * Including LilyPond files::    
 * Text encoding::               
 @end menu


@@ -43,7 +49,7 @@ these files end with ``@code{.ly}''.
 A basic example of a lilypond input file is
 
 @example
 A basic example of a lilypond input file is
 
 @example

-\version "2.9.13"
+\version "2.11.15"

 \score @{
   @{ @}     % this is a single music expression;
             % all the music goes in here.
 \score @{
   @{ @}     % this is a single music expression;
             % all the music goes in here.


@@ -68,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
 @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
 
 
 @node File structure


@@ -277,6 +166,9 @@ A markup text, a verse for example
 Markup texts are rendered above, between or below the scores or music
 expressions, wherever they appear.
 
 Markup texts are rendered above, between or below the scores or music
 expressions, wherever they appear.
 

+@cindex variables
+@cindex identifiers
+

 @item
 An identifier, such as
 @example
 @item
 An identifier, such as
 @example


@@ -362,6 +254,123 @@ expressions; note the curly braces @{ @} or angle brackets <<
 @end example
 
 
 @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
 
 @node Including LilyPond files
 @subsection Including LilyPond files
 


@@ -378,7 +387,7 @@ file, use
 The line @code{\include "file.ly"} is equivalent to pasting the contents
 of file.ly into the current file at the place where you have the
 \include.  For example, for a large project you might write separate files
 The line @code{\include "file.ly"} is equivalent to pasting the contents
 of file.ly into the current file at the place where you have the
 \include.  For example, for a large project you might write separate files

-for each instrument part and create a ``full score'' file which brings
+for each instrument part and create a @q{full score} file which brings

 together the individual instrument files.
 
 The initialization of LilyPond is done in a number of files that are
 together the individual instrument files.
 
 The initialization of LilyPond is done in a number of files that are


@@ -387,7 +396,7 @@ user.  Run lilypond --verbose to see a list of paths and files that Lily
 finds.
 
 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
 finds.
 
 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where

-VERSION is in the form ``2.6.1'') are on the path and available to
+VERSION is in the form @q{2.6.1}) are on the path and available to

 @code{\include}.  Files in the
 current working directory are available to \include, but a file of the same
 name in LilyPond's installation takes precedence.  Files are
 @code{\include}.  Files in the
 current working directory are available to \include, but a file of the same
 name in LilyPond's installation takes precedence.  Files are


@@ -396,7 +405,7 @@ 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
 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,
+convention @samp{/} rather than the DOS/Windows @samp{\}.  For example,

 if @file{stuff.ly} is located one directory higher than the current working
 directory, use
 
 if @file{stuff.ly} is located one directory higher than the current working
 directory, use
 


@@ -459,7 +468,7 @@ To use a Unicode escape sequence, use
 
 @seealso
 
 
 @seealso
 

-@inputfileref{input/regression,utf-8.ly}
+@lsr{text,utf-8.ly}

 
 
 
 
 
 


@@ -478,8 +487,8 @@ some pieces include a lot more information.
 @node Creating titles
 @subsection Creating titles
 
 @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
 
 The contents of the titles are taken from the @code{\header} blocks.
 The header block for a book supports the following


@@ -548,7 +557,7 @@ Centered at the bottom of the last page.
 @end table
 
 Here is a demonstration of the fields available.  Note that you
 @end table
 
 Here is a demonstration of the fields available.  Note that you

-may use any @ref{Text markup} commands in the header.
+may use any @ref{Text markup}, commands in the header.

 
 @lilypond[quote,verbatim,line-width=11.0\cm]
 \paper {
 
 @lilypond[quote,verbatim,line-width=11.0\cm]
 \paper {


@@ -646,7 +655,7 @@ You may change this behavior (and print all the headers when defining
 The default footer is empty, except for the first page, where the
 @code{copyright} field from @code{\header} is inserted, and the last
 page, where @code{tagline} from @code{\header} is added.  The default
 The default footer is empty, except for the first page, where the
 @code{copyright} field from @code{\header} is inserted, and the last
 page, where @code{tagline} from @code{\header} is added.  The default

-tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
+tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely

 printed parts are good PR for us, so please leave the tagline if you
 can.}
 
 printed parts are good PR for us, so please leave the tagline if you
 can.}
 


@@ -780,9 +789,20 @@ to a score, for example,
 @}
 @end example
 
 @}
 @end example
 

-The tempo is specified using the @code{\tempo} command.  In this
-example the tempo of quarter notes is set to 72 beats per minute.
+The tempo can be specified using the @code{\tempo} command within the 
+actual music, see @ref{Metronome marks}.  An alternative, which does not
+result in a metronome mark in the printed score, is shown in the example
+above. In this example the tempo of quarter notes is set to 72 beats per
+minute. 
+This kind of tempo
+specification can not take dotted note lengths as an argument. In this
+case, break the dotted notes into smaller units. For example, a tempo
+of 90 dotted quarter notes per minute can be specified as 270 eighth
+notes per minute

 
 

+@example
+tempoWholesPerMinute = #(ly:make-moment 270 8)
+@end example

 
 If there is a @code{\midi} command in a @code{\score}, only MIDI will
 be produced.  When notation is needed too, a @code{\layout} block must
 
 If there is a @code{\midi} command in a @code{\score}, only MIDI will
 be produced.  When notation is needed too, a @code{\layout} block must


@@ -824,7 +844,6 @@ in the @code{\midi@{@}} section.
   \context @{
     \Voice
     \remove "Dynamic_performer"
   \context @{
     \Voice
     \remove "Dynamic_performer"

-    \remove "Span_dynamic_performer"

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


@@ -851,6 +870,19 @@ will not work properly but
 will.
 
 
 will.
 
 

+MIDI output is only created when the @code{\midi} command is within
+a @code{\score} block.  If you put it within an explicitly instantiated
+context ( i.e. @code{\new Score} ) the file will fail.  To solve this,
+enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
+
+@example
+\score @{
+  \new Score @{ @dots{}notes@dots{} @}
+  \midi
+@}
+@end example
+
+

 @node MIDI block
 @subsection MIDI block
 @cindex MIDI block
 @node MIDI block
 @subsection MIDI block
 @cindex MIDI block