X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Finput.itely;h=51f50b887e6439d05d1ac29e1674d527cfac6a77;hb=a6a4b3fc2009f17a1a48cca0c11bfd3f38645937;hp=38f447aebb0d8f3495b2d4e270cbc69c29930fc1;hpb=1ce5e85efda360c05b7db51cb1772fccce4e582c;p=lilypond.git

diff --git a/Documentation/user/input.itely b/Documentation/user/input.itely
index 38f447aebb..51f50b887e 100644
--- a/Documentation/user/input.itely
+++ b/Documentation/user/input.itely
@@ -7,12 +7,12 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.51"
+@c \version "2.11.61"
 
-@node Input syntax
-@chapter Input syntax
+@node General input and output
+@chapter General input and output
 
-This section deals with general LilyPond input syntax issues,
+This section deals with general LilyPond input and output issues,
 rather than specific notation.
 
 @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,12 @@ A multi-line comment delimited by @code{%@{ .. %@}}.
 
 @end itemize
 
-@seealso
 
+@seealso
 Learning Manual:
 @rlearning{How LilyPond input files work}.
 
+
 @node Titles and headers
 @section Titles and headers
 
@@ -348,7 +378,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 +404,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
@@ -428,13 +459,13 @@ may use any @ref{Formatting text}, commands in the header.
 \book {
   \header {
     dedication = "dedicated to me"
-    title = \markup \center-align { "Title first line" "Title second line,
+    title = \markup \center-column { "Title first line" "Title second line,
 longer" }
     subtitle = "the subtitle,"
     subsubtitle = #(string-append "subsubtitle LilyPond version "
 (lilypond-version))
     poet = "Poet"
-    composer =  \markup \center-align { "composer" \small "(1847-1973)" }
+    composer =  \markup \center-column { "composer" \small "(1847-1973)" }
     texttranslator = "Text Translator"
     meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
 "r" }
@@ -498,14 +529,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 +666,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,16 +777,17 @@ 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
@@ -859,11 +893,13 @@ 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
@@ -1083,8 +1119,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 +1128,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.
@@ -1130,7 +1167,7 @@ Unicode-aware editor and saving the file with UTF-8 encoding.  Most
 popular modern editors have UTF-8 support, for example, vim, Emacs,
 jEdit, and GEdit do.  All MS Windows systems later than NT use
 Unicode as their native character encoding, so even Notepad can
-edit and save a file in UTF-8 format.  A more functional 
+edit and save a file in UTF-8 format.  A more functional
 alternative for Windows is BabelPad.
 
 If a LilyPond input file containing a non-ASCII character is not
@@ -1145,7 +1182,8 @@ will be generated.
 Here is an example showing Cyrillic, Hebrew and Portuguese
 text:
 
-@lilypond[verbatim,quote]
+@lilypond[quote]
+%c No verbatim here as the code does not display correctly in PDF
 % Cyrillic
 bulgarian = \lyricmode {
   Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
@@ -1170,22 +1208,38 @@ portuguese = \lyricmode {
 @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
+is known but which is not available in the editor being used, use
+@code{\char ##xhhhh} within a @code{\markup} block, where
+@code{hhhh} is the hexadecimal code for the character required.
+For example, @code{\char ##x03BE} enters 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.  Of course, a font containing all
+such encoded characters must be installed and available to LilyPond.
+
+The following example shows UTF-8 coded characters being used 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
-
-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.
+@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" \char ##x00A9 }
+@end lilypond
 
-@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
@@ -1267,6 +1321,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
@@ -1284,7 +1339,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,19 +1389,18 @@ settings.  Therefore the midi file should not have more than 15 staves
 
 @menu
 * Creating MIDI files::
-* What goes into the MIDI output?::
 * MIDI block::
-* MIDI instrument names::
+* What goes into the MIDI output?::
 * Repeats in MIDI::
 * Controlling MIDI dynamics::
-* Microtones in MIDI::
+* Percussion in MIDI::
 @end menu
 
 @node Creating MIDI files
 @subsection Creating MIDI files
 
-To create a MIDI output file from a LilyPond input file, add a @code{\midi} block
-to a score, for example,
+To create a MIDI output file from a LilyPond input file, add a
+@code{\midi} block to a score, for example,
 
 @example
 \score @{
@@ -1382,6 +1438,33 @@ 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}.
 
+@unnumberedsubsubsec Instrument names
+
+@cindex instrument names
+@funindex Staff.midiInstrument
+
+The MIDI instrument to be used is specified by setting the
+@code{Staff.midiInstrument} property to the instrument name.
+The name should be chosen from the list in @ref{MIDI instruments}.
+
+@example
+\new Staff @{
+  \set Staff.midiInstrument = "glockenspiel"
+  @var{...notes...}
+@}
+@end example
+
+@example
+\new Staff \with @{midiInstrument = "cello"@} @{
+  @var{...notes...}
+@}
+@end example
+
+If the selected instrument does not exactly match an instrument from
+the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
+instrument is used.
+
+
 @snippets
 
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
@@ -1418,44 +1501,6 @@ Not all midi players correctly handle tempo changes in the midi
 output.  Players that are known to work include MS Windows Media
 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
 
-@node What goes into the MIDI output?
-@subsection What goes into the MIDI output?
-
-@c TODO Check grace notes - timing is suspect?
-
-@unnumberedsubsubsec Supported in MIDI
-
-The following items of notation are reflected in the MIDI output:
-
-@itemize
-@item Pitches
-@item Microtones
-@item Chords entered as chord names
-@item Rhythms entered as note durations, including tuplets
-@item Tremolos entered without @q{@code{:}[@var{number}]}
-@item Ties
-@item Dynamic marks
-@item Crescendi, decrescendi over multiple notes
-@item Tempo changes entered with a tempo marking
-@end itemize
-
-@unnumberedsubsubsec Unsupported in MIDI
-
-The following items of notation have no effect on the MIDI output:
-
-@itemize
-@item Rhythms entered as annotations, e.g. swing
-@item Tempo changes entered as annotations with no tempo marking
-@item Staccato and other articulations and ornamentations
-@item Slurs and Phrasing slurs
-@item Crescendi, decrescendi over a single note
-@item Tremolos entered with @q{@code{:}[@var{number}]}
-@item Figured bass
-@c TODO Check Lyrics
-@item Lyrics
-@end itemize
-
-
 @node MIDI block
 @subsection MIDI block
 @cindex MIDI block
@@ -1526,24 +1571,56 @@ in a @code{\score} block.
 @}
 @end example
 
-@node MIDI instrument names
-@subsection MIDI instrument names
+@node What goes into the MIDI output?
+@subsection What goes into the MIDI output?
 
-@cindex instrument names
-@funindex Staff.midiInstrument
+@c TODO Check grace notes - timing is suspect?
 
-The MIDI instrument name is set by the @code{Staff.midiInstrument}
-property.  The instrument name should be chosen from the list in
-@ref{MIDI instruments}.
+@unnumberedsubsubsec Supported in MIDI
 
-@example
-\set Staff.midiInstrument = "glockenspiel"
-@var{...notes...}
-@end example
+@cindex Pitches in MIDI
+@cindex MIDI, Pitches
+@cindex Quarter tones in MIDI
+@cindex MIDI, quarter tones
+@cindex Microtones in MIDI
+@cindex MIDI, microtones
+@cindex Chord names in MIDI
+@cindex MIDI, chord names
+@cindex Rhythms in MIDI
+@cindex MIDI, Rhythms
+@c TODO etc
 
-If the selected instrument does not exactly match an instrument from
-the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
-instrument is used.
+The following items of notation are reflected in the MIDI output:
+
+@itemize
+@item Pitches
+@item Quarter tones (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
+@item Tremolos entered without @q{@code{:}[@var{number}]}
+@item Ties
+@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
+
+@c TODO index as above
+
+The following items of notation have no effect on the MIDI output:
+
+@itemize
+@item Rhythms entered as annotations, e.g. swing
+@item Tempo changes entered as annotations with no tempo marking
+@item Staccato and other articulations and ornamentations
+@item Slurs and Phrasing slurs
+@item Crescendi, decrescendi over a single note
+@item Tremolos entered with @q{@code{:}[@var{number}]}
+@item Figured bass
+@end itemize
 
 
 @node Repeats in MIDI
@@ -1606,11 +1683,13 @@ function which takes a dynamic mark as its argument and returns the
 required fraction, and setting
 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
 
-For example, if a @notation{rinforzando} dynamic marking, rfz,
-has been defined with @code{make-dynamic-script}, this will not
+For example, if a @notation{rinforzando} dynamic marking,
+@code{\rfz}, is required, this will not by default
 have any effect on the MIDI volume, as this dynamic marking is not
-included in the default set.  The following example shows how the
-MIDI volume for this new dynamic marking can be added.  The Scheme
+included in the default set.  Similarly, if a new dynamic marking
+has been defined with @code{make-dynamic-script} that too will not
+be included in the default set.  The following example shows how the
+MIDI volume for such dynamic markings might be added.  The Scheme
 function sets the fraction to 0.9 if a dynamic mark of rfz is
 found, or calls the default function otherwise.
 
@@ -1620,8 +1699,6 @@ found, or calls the default function otherwise.
       0.9
       (default-dynamic-absolute-volume dynamic)))
 
-rfz = #(make-dynamic-script "rfz")
-
 \score {
   \new Staff {
     \set Staff.midiInstrument = "cello"
@@ -1814,8 +1891,11 @@ to the same values as the previous example.
 }
 @end lilypond
 
-@node Microtones in MIDI
-@subsection Microtones in MIDI
+@ignore
+@c Delete when satisfied this is adequately covered elsewhere -td
+
+@n ode Microtones in MIDI
+@s ubsection Microtones in MIDI
 
 @cindex microtones in MIDI
 
@@ -1839,7 +1919,37 @@ copied out and compiled to test microtones in your MIDI player.
   \midi {}
 }
 @end lilypond
+@end ignore
+
+
+@node Percussion in MIDI
+@subsection Percussion in MIDI
 
+Percussion instruments are generally notated in a @code{DrumStaff}
+context and when notated in this way they are outputted correctly
+to MIDI channel@tie{}10, but some pitched percussion instruments,
+like the xylophone, marimba, vibraphone, timpani, etc., are
+treated like @qq{normal} instruments and music for these instruments
+should be entered in a normal @code{Staff} context, not a
+@code{DrumStaff} context, to obtain the correct MIDI output.
+
+Some non-pitched percussion sounds included in the general MIDI
+standard, like melodic tom, taiko drum, synth drum, etc., cannot
+be reached via MIDI channel@tie{}10, so the notation for such
+instruments should also be entered in a normal @code{Staff}
+context, using suitable normal pitches.
+
+Many percussion instruments are not included in the general MIDI
+standard, e.g. castanets.  The easiest, although unsatisfactory,
+method of producing some MIDI output when writing for such
+instruments is to substitute the nearest sound from the standard
+set.
+
+@c TODO Expand with examples, and any other issues
+
+@knownissues
 
+Because the general MIDI standard does not contain rim shots, the
+sidestick is used for this purpose instead.