X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Finput.itely;h=ead89488c46b67a63e918c886467f8fcb8c8093f;hb=1423508c355989fa26a8cfe5985b0d6e1ab0a538;hp=7c199fef71247d4aa649605d8153b8f529547f61;hpb=ce49c007e453c5575cc82fc0c26f2d1e8ff11803;p=lilypond.git

diff --git a/Documentation/user/input.itely b/Documentation/user/input.itely
index 7c199fef71..ead89488c4 100644
--- a/Documentation/user/input.itely
+++ b/Documentation/user/input.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.57"
+@c \version "2.12.0"
 
 @node General input and output
 @chapter General input and output
@@ -16,11 +16,11 @@ This section deals with general LilyPond input and output issues,
 rather than specific notation.
 
 @menu
-* Input structure::             
-* Titles and headers::          
-* Working with input files::    
-* Controlling output::          
-* MIDI output::                 
+* Input structure::
+* Titles and headers::
+* Working with input files::
+* Controlling output::
+* MIDI output::
 @end menu
 
 
@@ -31,9 +31,9 @@ The main format of input for LilyPond are text files.  By convention,
 these files end with @code{.ly}.
 
 @menu
-* Structure of a score::        
-* Multiple scores in a book::   
-* File structure::              
+* Structure of a score::
+* Multiple scores in a book::
+* File structure::
 @end menu
 
 
@@ -99,10 +99,9 @@ input file.  They may be placed inside or outside a @code{\score}
 block, and inside or outside the single music expression within a
 @code{\score} block.
 
-@seealso
 
+@seealso
 Learning Manual:
-
 @rlearning{Working on input files},
 @rlearning{Music expressions explained},
 @rlearning{Score is a (single) compound musical expression}.
@@ -185,6 +184,30 @@ the top of the file is inserted.
 @}
 @end example
 
+@funindex \bookpart
+
+Pieces of music may be grouped into book parts using @code{\bookpart}
+blocks.  Book parts are separated by a page break, and can start with a
+title, like the book itself, by specifying a @code{\header} block.
+
+@example
+\bookpart @{
+  \header @{
+    title = "Book title"
+    subtitle = "First part"
+  @}
+  \score @{ @dots{} @}
+  @dots{}
+@}
+\bookpart @{
+  \header @{
+    subtitle = "Second part"
+  @}
+  \score @{ @dots{} @}
+  @dots{}
+@}
+@end example
+
 @node File structure
 @subsection File structure
 
@@ -194,6 +217,7 @@ the top of the file is inserted.
 @funindex \header
 @funindex \score
 @funindex \book
+@funindex \bookpart
 
 A @code{.ly} file may contain any number of toplevel expressions, where a
 toplevel expression is one of the following:
@@ -238,6 +262,11 @@ changed by setting the variable @code{toplevel-book-handler} at
 toplevel.  The default handler is defined in the init file
 @file{../scm/@/lily@/.scm}.
 
+@item
+A @code{\bookpart} block.  A book may be divided into several parts,
+using @code{\bookpart} blocks, in order to ease the page breaking,
+or to use different @code{\paper} settings in different parts.
+
 @item
 A compound music expression, such as
 @example
@@ -287,7 +316,7 @@ foo = @{ c4 d e d @}
 @end example
 
 This can be used later on in the file by entering @code{\foo}.  The
-name of an variable should have alphabetic characters only; no
+name of a variable should have alphabetic characters only; no
 numbers, underscores or dashes.
 
 @end itemize
@@ -325,11 +354,33 @@ A multi-line comment delimited by @code{%@{ .. %@}}.
 
 @end itemize
 
-@seealso
+@cindex whitespace
+
+Whitespace between items in the input stream is generally ignored,
+and may be freely omitted or extended to enhance readability.
+However, whitespace should always be used in the following
+circumstances to avoid errors:
 
+@itemize
+@item Around every opening and closing curly bracket.
+@item After every command or variable, i.e. every item that
+begins with a @code{\} sign.
+@item After every item that is to be interpreted as a Scheme
+expression, i.e. every item that begins with a @code{#} sign.
+@item To separate all elements of a Scheme expression.
+@item In @code{lyricmode} to separate all the terms in both
+@code{\override} and @code{\set} commands.  In particular, spaces
+must be used around the dot and the equals sign in commands like
+@code{\override Score . LyricText #'font-size = #5} and before and
+after the entire command.
+
+@end itemize
+
+@seealso
 Learning Manual:
 @rlearning{How LilyPond input files work}.
 
+
 @node Titles and headers
 @section Titles and headers
 
@@ -337,10 +388,10 @@ Almost all printed music includes a title and the composer's name;
 some pieces include a lot more information.
 
 @menu
-* Creating titles::             
-* Custom titles::               
-* Reference to page numbers::   
-* Table of contents::           
+* Creating titles::
+* Custom titles::
+* Reference to page numbers::
+* Table of contents::
 @end menu
 
 
@@ -348,7 +399,8 @@ some pieces include a lot more information.
 @subsection Creating titles
 
 Titles are created for each @code{\score} block, as well as for the full
-input file (or @code{\book} block).
+input file (or @code{\book} block) and book parts (created by
+@code{\bookpart} blocks).
 
 The contents of the titles are taken from the @code{\header} blocks.
 The header block for a book supports the following
@@ -373,32 +425,32 @@ Subsubtitle, centered below the subtitle.
 
 @funindex poet
 @item poet
-Name of the poet, flush-left below the subtitle.
+Name of the poet, flush-left below the subsubtitle.
+
+@funindex instrument
+@item instrument
+Name of the instrument, centered below the subsubtitle.  Also
+centered at the top of pages (other than the first page).
 
 @funindex composer
 @item composer
-Name of the composer, flush-right below the subtitle.
+Name of the composer, flush-right below the subsubtitle.
 
 @funindex meter
 @item meter
 Meter string, flush-left below the poet.
 
-@funindex opus
-@item opus
-Name of the opus, flush-right below the composer.
-
 @funindex arranger
 @item arranger
-Name of the arranger, flush-right below the opus.
-
-@funindex instrument
-@item instrument
-Name of the instrument, centered below the arranger.  Also
-centered at the top of pages (other than the first page).
+Name of the arranger, flush-right below the composer.
 
 @funindex piece
 @item piece
-Name of the piece, flush-left below the instrument.
+Name of the piece, flush-left below the meter.
+
+@funindex opus
+@item opus
+Name of the opus, flush-right below the arranger.
 
 @cindex page breaks, forcing
 @funindex breakbefore
@@ -498,14 +550,14 @@ Note that the music expression must come before the @code{\header}.
 }
 @end lilypond
 
-@funindex printallheaders
+@funindex print-all-headers
 @noindent
 You may change this behavior (and print all the headers when defining
 @code{\header} inside @code{\score}) by using
 
 @example
 \paper@{
-  printallheaders=##t
+  print-all-headers = ##t
 @}
 @end example
 
@@ -635,12 +687,14 @@ 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.
 
-@predefined
 
+@predefined
 @funindex \label
-@code{\label}
+@code{\label},
 @funindex \page-ref
-@code{\page-ref}
+@code{\page-ref}.
+@endpredefined
+
 
 @node Table of contents
 @subsection Table of contents
@@ -744,26 +798,27 @@ tocAct =
 }
 @end lilypond
 
-@seealso
 
+@seealso
 Init files: @file{../ly/@/toc@/-init@/.ly}.
 
-@predefined
 
+@predefined
 @funindex \table-of-contents
-@code{\table-of-contents}
+@code{\table-of-contents},
 @funindex \tocItem
-@code{\tocItem}
+@code{\tocItem}.
+@endpredefined
 
 
 @node Working with input files
 @section Working with input files
 
 @menu
-* Including LilyPond files::    
-* Different editions from one source::  
-* Text encoding::               
-* Displaying LilyPond notation::  
+* Including LilyPond files::
+* Different editions from one source::
+* Text encoding::
+* Displaying LilyPond notation::
 @end menu
 
 
@@ -815,11 +870,19 @@ subdirectory called @file{parts} within the current directory, use
 @end example
 
 Files which are to be included can also contain @code{\include}
-statements of their own.  These second-level
+statements of their own.  By default, these second-level
 @code{\include} statements are not interpreted until they have
 been brought into the main file, so the file names they specify
 must all be relative to the directory containing the main file,
-not the directory containing the included file.
+not the directory containing the included file. However,
+this behavior can be changed by passing the option
+@code{-drelative-includes} option at the command line
+(or by adding @code{#(ly:set-option 'relative-includes #t)}
+at the top of the main input file). With @code{relative-includes}
+set, the path for each @code{\include} command will be taken
+relative to the file containing that command. This behavior is
+recommended and it will become the default behavior in a future
+version of lilypond.
 
 Files can also be included from a directory in a search path
 specified as an option when invoking LilyPond from the command
@@ -842,28 +905,32 @@ and in main.ly write
 
 Files which are to be included in many scores may be placed in
 the LilyPond directory @file{../ly}.  (The location of this
-directory is installation-dependent - see @rlearning{Other sources
-of information}).  These files can then be included simply by
-naming them on an @code{\include} statement.  This is how the
-language-dependent files like @file{english.ly} are included.
+directory is installation-dependent - see
+@rlearning{Other sources of information}).  These files can then
+be included simply by naming them on an @code{\include} statement.
+This is how the language-dependent files like @file{english.ly} are
+included.
 
 LilyPond includes a number of files by default when you start
 the program.  These includes are not apparent to the user, but the
 files may be identified by running @code{lilypond --verbose} from
 the command line.  This will display a list of paths and files that
 LilyPond uses, along with much other information.  Alternatively,
-the more important of these files are discussed in @rlearning{Other
-sources of information}.  These files may be edited, but changes to
-them will be lost on installing a new version of LilyPond.
+the more important of these files are discussed in
+@rlearning{Other sources of information}.  These files may be
+edited, but changes to them will be lost on installing a new
+version of LilyPond.
 
 Some simple examples of using @code{\include} are shown in
 @rlearning{Scores and parts}.
 
+
 @seealso
 Learning Manual:
 @rlearning{Other sources of information},
 @rlearning{Scores and parts}.
 
+
 @knownissues
 
 If an included file is given a name which is the same as one in
@@ -885,8 +952,8 @@ the structure of the score will make it easier to change the
 structure while leaving the notation untouched.
 
 @menu
-* Using variables::             
-* Using tags::                  
+* Using variables::
+* Using tags::
 @end menu
 
 @node Using variables
@@ -1083,8 +1150,8 @@ expression will cause @emph{all} tagged sections to be removed, as
 the first filter will remove all tagged sections except the one
 named, and the second filter will remove even that tagged section.
 
-@seealso
 
+@seealso
 Learning Manual:
 @rlearning{Organizing pieces with variables}.
 
@@ -1092,6 +1159,7 @@ Notation Reference:
 @ref{Automatic part combining},
 @ref{Including LilyPond files}.
 
+
 @ignore
 @c This warning is more general than this placement implies.
 @c Rests are not merged whether or not they come from tagged sections.
@@ -1107,6 +1175,10 @@ than one tagged section at the same place.
 @node Text encoding
 @subsection Text encoding
 
+@cindex Unicode
+@cindex UTF-8
+@cindex non-ASCII characters
+
 LilyPond uses the character repertoire defined by the Unicode
 consortium and ISO/IEC 10646.  This defines a unique name and
 code point for the character sets used in virtually all modern
@@ -1122,7 +1194,7 @@ the mapping of a subset of the Unicode code points to glyphs.
 LilyPond uses the Pango library to layout and render multi-lingual
 texts.
 
-Lilypond does not perform any input-encoding conversions.  This
+LilyPond does not perform any input-encoding conversions.  This
 means that any text, be it title, lyric text, or musical
 instruction containing non-ASCII characters, must be encoded in
 UTF-8.  The easiest way to enter such text is by using a
@@ -1170,23 +1242,50 @@ portuguese = \lyricmode {
 \addlyrics { \portuguese }
 @end lilypond
 
-To enter a single character for which the Unicode escape sequence
-is known but which is not available in the editor being used, enter
+To enter a single character for which the Unicode code point is
+known but which is not available in the editor being used, use
+either @code{\char ##xhhhh} or @code{\char #dddd} within a
+@code{\markup} block, where @code{hhhh} is the hexadecimal code for
+the character required and @code{dddd} is the corresponding decimal
+value.  Leading zeroes may be omitted, but it is usual to specify
+all four characters in the hexadecimal representation.  (Note that
+the UTF-8 encoding of the code point should @emph{not} be used
+after @code{\char}, as UTF-8 encodings contain extra bits indicating
+the number of octets.)
+
+For example, @code{\char ##x03BE} and @code{\char #958} would both
+enter the Unicode U+03BE character, which has the Unicode name
+@qq{Greek Small Letter Xi}.
+
+Any Unicode code point may be entered in this way and if all special
+characters are entered in this format it is not necessary to save
+the input file in UTF-8 format.  Of course, a font containing all
+such encoded characters must be installed and available to LilyPond.
+
+The following example shows Unicode hexadecimal values being entered
+in four places -- in a rehearsal mark, as articulation text, in
+lyrics and as stand-alone text below the score:
 
-@example
-#(ly:export (ly:wide-char->utf-8 #x03BE))
-@end example
+@lilypond[quote,verbatim]
+\score {
+  \relative c'' {
+    c1 \mark \markup { \char ##x03EE }
+    c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
+  }
+  \addlyrics { O \markup { \concat{ Ph \char ##x0153 be! } } }
+}
+\markup { "Copyright 2008--2009" \char ##x00A9 }
+@end lilypond
 
-where in this example @code{x03BE} is the hexadecimal code for the
-Unicode U+03BE character, which has the Unicode name @qq{Greek Small
-Letter Xi}.  Any Unicode hexadecimal code may be substituted, and
-if all special characters are entered in this format it is not
-necessary to save the input file in UTF-8 format.
+@cindex copyright sign
 
-@knownissues
+To enter the copyright sign in the copyright notice use:
 
-The @code{ly:export} format may be used in text within @code{\mark} or
-@code{\markup} commands but not in lyrics.
+@example
+\header @{
+  copyright = \markup @{ \char ##x00A9 "2008" @}
+@}
+@end example
 
 @node Displaying LilyPond notation
 @subsection Displaying LilyPond notation
@@ -1224,8 +1323,8 @@ lilypond file.ly >display.txt
 @section Controlling output
 
 @menu
-* Extracting fragments of music::  
-* Skipping corrected music::    
+* Extracting fragments of music::
+* Skipping corrected music::
 @end menu
 
 @node Extracting fragments of music
@@ -1268,6 +1367,7 @@ For more information on output formats, see @rprogram{Invoking lilypond}.
 
 
 @funindex skipTypesetting
+@funindex showFirstLength
 @funindex showLastLength
 
 When entering or copying music, usually only the music near the end (where
@@ -1285,7 +1385,9 @@ showLastLength = R1*5
 in your source file.  This will render only the last 5 measures
 (assuming 4/4 time signature) of every @code{\score} in the input
 file.  For longer pieces, rendering only a small part is often an order
-of magnitude quicker than rendering it completely
+of magnitude quicker than rendering it completely.  When working on the
+beginning of a score you have already typeset (e.g. to add a new part),
+the @code{showFirstLength} property may be useful as well.
 
 Skipping parts of a score can be controlled in a more fine-grained
 fashion with the property @code{Score.skipTypesetting}.  When it is
@@ -1332,12 +1434,12 @@ settings.  Therefore the midi file should not have more than 15 staves
 (or 14 if you do not use drums).  Other staves will remain silent.
 
 @menu
-* Creating MIDI files::         
-* MIDI block::                  
-* What goes into the MIDI output?::  
-* Repeats in MIDI::             
-* Controlling MIDI dynamics::   
-* Percussion in MIDI::          
+* Creating MIDI files::
+* MIDI block::
+* What goes into the MIDI output?::
+* Repeats in MIDI::
+* Controlling MIDI dynamics::
+* Percussion in MIDI::
 @end menu
 
 @node Creating MIDI files
@@ -1382,6 +1484,26 @@ can be suppressed, see @ref{Metronome marks}.  An alternative way
 of specifying the inital or overall MIDI tempo is described below,
 see @ref{MIDI block}.
 
+Due to some limitations on Windows, the default extension for
+MIDI files on Windows is @code{.mid}. Other operating systems still
+use the extension @code{.midi}. If a different extension is preferred,
+insert the following line at the top-level of the input file,
+before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
+
+@example
+#(ly:set-option 'midi-extension "midi")
+@end example
+
+The line above will set the default extension for MIDI files to
+@code{.midi}.
+
+Alternatively, this option can also be supplied on the command line:
+
+@example
+lilypond … -dmidi-extension=midi lilyFile.ly
+@end example
+
+
 @unnumberedsubsubsec Instrument names
 
 @cindex instrument names
@@ -1393,13 +1515,13 @@ The name should be chosen from the list in @ref{MIDI instruments}.
 
 @example
 \new Staff @{
-  \set Staff.midiInstrument = "glockenspiel"
+  \set Staff.midiInstrument = #"glockenspiel"
   @var{...notes...}
 @}
 @end example
 
 @example
-\new Staff \with @{midiInstrument = "cello"@} @{
+\new Staff \with @{midiInstrument = #"cello"@} @{
   @var{...notes...}
 @}
 @end example
@@ -1538,7 +1660,7 @@ The following items of notation are reflected in the MIDI output:
 
 @itemize
 @item Pitches
-@item Quarter tones (See @ref{Accidentals}. Rendering needs a
+@item Microtones (See @ref{Accidentals}. Rendering needs a
 player that supports pitch bend.)
 @item Chords entered as chord names
 @item Rhythms entered as note durations, including tuplets
@@ -1547,6 +1669,7 @@ player that supports pitch bend.)
 @item Dynamic marks
 @item Crescendi, decrescendi over multiple notes
 @item Tempo changes entered with a tempo marking
+@item Lyrics
 @end itemize
 
 @unnumberedsubsubsec Unsupported in MIDI
@@ -1563,8 +1686,7 @@ The following items of notation have no effect on the MIDI output:
 @item Crescendi, decrescendi over a single note
 @item Tremolos entered with @q{@code{:}[@var{number}]}
 @item Figured bass
-@c TODO Check Lyrics
-@item Lyrics
+@item Microtonal chords
 @end itemize
 
 
@@ -1646,7 +1768,7 @@ found, or calls the default function otherwise.
 
 \score {
   \new Staff {
-    \set Staff.midiInstrument = "cello"
+    \set Staff.midiInstrument = #"cello"
     \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
     \new Voice {
        \relative c'' {