X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2Fuser%2Fnon-music.itely;h=6462f4122ca00b52d40f7ab68d9e06760ee86a16;hb=370250b3e8840a48c1ea2eabdf8a94e946706c93;hp=f477d882be488cc07f3681bfac677557bcbe4629;hpb=ea7b725981aa0c684c909d0fa8842b85e8a2c093;p=lilypond.git

diff --git a/Documentation/user/non-music.itely b/Documentation/user/non-music.itely
index f477d882be..6462f4122c 100644
--- 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
+@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
@@ -24,14 +30,14 @@ specific notation.
 @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)::  
-* 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
@@ -43,7 +49,7 @@ these files end with ``@code{.ly}''.
 A basic example of a lilypond input file is
 
 @example
-\version "2.9.13"
+\version "2.11.23"
 \score @{
   @{ @}     % this is a single music expression;
             % all the music goes in here.
@@ -68,121 +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
-
-The movements and texts are combined together in a @code{\book} block,
-like
-
-@example
-\book @{
-  \score @{
-    @var{..}
-  @}
-  \markup @{
-    @var{..}
-  @}
-  \score @{
-    @var{..}
-  @}
-@}
-@end example
-
-
-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
-\book @{
-  \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
@@ -221,8 +114,13 @@ contain only one music expression.
 @item
 A @code{\book} block logically combines multiple movements
 (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.
+a number of @code{\scores}, one output file will be created for
+each @code{\book} block, in which all corresponding movements are
+concatenated. The only reason to explicitly specify @code{\book} blocks
+in a @code{.ly} file is if you wish multiple output files from a single
+input file. One exception is within lilypond-book documents, where you
+explicitly have to add a @code{\book} block if you want more than a
+single @code{\score} or @code{\markup} in the same example.
 
 This behavior can be changed by setting the variable
 @code{toplevel-book-handler} at toplevel.  The default handler is
@@ -268,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.
 
+@cindex variables
+@cindex identifiers
+
 @item
 An identifier, such as
 @example
@@ -353,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 @rprogram{Invoking lilypond}.
+
+@seealso
+
+Examples: @lsr{non-notation,clip-systems.ly}
+
+
 @node Including LilyPond files
 @subsection Including LilyPond files
 
@@ -369,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
-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
@@ -378,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
-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
@@ -387,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
-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
 
@@ -424,7 +442,7 @@ in the input are put in the output as-is.  Extents of text items in the
 @file{texstr} backend,
 
 @example
-lilypond -b texstr input/les-nereides.ly
+lilypond -dbackend=texstr input/les-nereides.ly
 latex les-nereides.texstr
 @end example
 
@@ -432,7 +450,7 @@ The last command produces @file{les-nereides.textmetrics}, which is
 read when you execute
 
 @example
-lilypond -b tex input/les-nereides.ly
+lilypond -dbackend=tex input/les-nereides.ly
 @end example
 
 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
@@ -450,7 +468,7 @@ To use a Unicode escape sequence, use
 
 @seealso
 
-@inputfileref{input/regression,utf-8.ly}
+@lsr{text,utf-8.ly}
 
 
 
@@ -463,14 +481,16 @@ some pieces include a lot more information.
 @menu
 * Creating titles::             
 * Custom titles::               
+* Reference to page numbers::   
+* Table of contents::           
 @end menu
 
 
 @node Creating titles
 @subsection Creating titles
 
-Titles are created for each @code{\score} block, and over a
-@code{\book}.
+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
@@ -539,7 +559,7 @@ Centered at the bottom of the last page.
 @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 {
@@ -637,7 +657,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
-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.}
 
@@ -661,14 +681,13 @@ variables in the @code{\paper} block.  The init file
 @table @code
 @funindex bookTitleMarkup
 @item bookTitleMarkup
-  This is the title put over an entire @code{\book} block.  Typically,
-  it has the composer and the title of the piece
+  This is the title added at the top of the entire output document.
+Typically, it has the composer and the title of the piece
 
 @funindex scoreTitleMarkup
 @item scoreTitleMarkup
-  This is the title put over a @code{\score} block within a
-@code{\book}.  Typically, it has the name of the movement (@code{piece}
-field).
+  This is the title put over a @code{\score} block.  Typically, it has
+the name of the movement (@code{piece} field).
 
 @funindex oddHeaderMarkup
 @item oddHeaderMarkup
@@ -716,7 +735,167 @@ composer flush right on a single line.
 }
 @end verbatim
 
+@node Reference to page numbers
+@subsection Reference to page numbers
+
+A particular place of a score can be marked using the @code{\label}
+command, either at top-level or inside music.  This label can then be
+refered to in a markup, to get the number of the page where the marked
+point is placed, using the @code{\page-ref} markup command.
+
+@lilypond[verbatim,line-width=11.0\cm]
+\header { tagline = ##f }
+\book {
+  \label #'firstScore
+  \score {
+    {
+      c'1
+      \pageBreak \mark A \label #'markA
+      c'
+    }
+  }
+
+  \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
+  \markup { Mark A is on page \page-ref #'markA "0" "?" }
+}
+@end lilypond
+
+The @code{\page-ref} markup command takes three arguments:
+@enumerate
+@item the label, a scheme symbol, eg. @code{#'firstScore};
+@item a markup that will be used as a gauge to estimate the dimensions
+of the markup;
+@item a markup that will be used in place of the page number if the label 
+is not known;
+@end enumerate
+
+The reason why a gauge is needed is that, at the time markups are
+interpreted, the page breaking has not yet occured, so the page numbers
+are not yet known.  To work around this issue, the actual markup
+interpretation is delayed to a later time; however, the dimensions of
+the markup have to be known before, so a gauge is used to decide these
+dimensions.  If the book has between 10 and 99 pages, it may be "00",
+ie. a two digit number.
+
+@refcommands
+
+@funindex \label
+@code{\label}
+@funindex \page-ref
+@code{\page-ref}
+
+@node Table of contents
+@subsection Table of contents
+A table of contents is included using the @code{\markuplines \table-of-contents}
+command.  The elements which should appear in the table of contents are
+entered with the @code{\tocItem} command, which may be used either at
+top-level, or inside a music expression.
+
+@verbatim
+\markuplines \table-of-contents
+\pageBreak
+
+\tocItem \markup "First score"
+\score { 
+  {
+    c'  % ...
+    \tocItem \markup "Some particular point in the first score"
+    d'  % ... 
+  }
+}
+
+\tocItem \markup "Second score"
+\score {
+  {
+    e' % ...
+  }
+}
+@end verbatim
+
+The markups which are used to format the table of contents are defined
+in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
+for formatting the title of the table, and @code{tocItemMarkup}, for
+formatting the toc elements, composed of the element title and page
+number. These variables may be changed by the user:
+
+@verbatim
+\paper {
+  %% Translate the toc title into French:
+  tocTitleMarkup = \markup \huge \column {
+    \fill-line { \null "Table des matières" \null }
+    \hspace #1
+  }
+  %% use larfer font size
+  tocItemMarkup = \markup \large \fill-line {
+    \fromproperty #'toc:text \fromproperty #'toc:page
+  }
+}
+@end verbatim
+
+Note how the toc element text and page number are refered to in
+the @code{tocItemMarkup} definition.
+
+New commands and markups may also be defined to build more elaborated
+table of contents:
+@itemize @bullet
+@item first, define a new markup variable in the @code{\paper} block
+@item then, define a music function which aims at adding a toc element
+using this markup paper variable.
+@end itemize
+
+In the following example, a new style is defined for entering act names
+in the table of contents of an opera:
+
+@verbatim
+\paper {
+  tocActMarkup = \markup \large \column {
+    \hspace #1
+    \fill-line { \null \italic \fromproperty #'toc:text \null }
+    \hspace #1
+  }
+}
+
+tocAct = 
+#(define-music-function (parser location text) (markup?)
+   (add-toc-item! 'tocActMarkup text))
+@end verbatim
+
+@lilypond[line-width=11.0\cm]
+\header { tagline = ##f }
+\paper {
+  tocActMarkup = \markup \large \column {
+    \hspace #1
+    \fill-line { \null \italic \fromproperty #'toc:text \null }
+    \hspace #1
+  }
+}
+
+tocAct = 
+#(define-music-function (parser location text) (markup?)
+   (add-toc-item! 'tocActMarkup text))
+
+\book {
+  \markuplines \table-of-contents
+  \tocAct \markup { Atto Primo }
+  \tocItem \markup { Coro. Viva il nostro Alcide }
+  \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
+  \tocAct \markup { Atto Secondo }
+  \tocItem \markup { Sinfonia }
+  \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
+  \markup \null
+}
+@end lilypond
+
+@seealso
+
+Init files: @file{ly/@/toc@/-init@/.ly}.
+
+@refcommands
 
+@funindex \table-of-contents
+@code{\table-of-contents}
+@funindex \tocItem
+@code{\tocItem}
 
 @node MIDI output
 @section MIDI output
@@ -763,15 +942,29 @@ to a score, for example,
 @example
 \score @{
   @var{...music...}
-  \midi @{  @}
+   \midi @{
+     \context @{
+       \Score
+       tempoWholesPerMinute = #(ly:make-moment 72 4)
+       @}
+     @}
 @}
 @end example
 
-FIXME
-
-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
@@ -813,7 +1006,6 @@ in the @code{\midi@{@}} section.
   \context @{
     \Voice
     \remove "Dynamic_performer"
-    \remove "Span_dynamic_performer"
   @}
 @}
 @end example
@@ -840,6 +1032,19 @@ will not work properly but
 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