Removes chord glissando from LilyPond as well as the docs.

[lilypond.git] / Documentation / notation / input.itely

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index d8746a651d56ff51ab8a8c89159d77c2760a8224..15b0831c85e147c49b484abf1d096f45e17183fc 100644 (file)
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -29,7 +29,7 @@ rather than specific notation.
 @section Input structure
 
 The main format of input for LilyPond are text files.  By convention,
 @section Input structure
 
 The main format of input for LilyPond are text files.  By convention,

-these files end with @code{.ly}.
+these files end with @file{.ly}.

 
 @menu
 * Structure of a score::
 
 @menu
 * Structure of a score::


@@ -146,7 +146,7 @@ and texts are entered with a @code{\markup} block,
 
 @funindex \book
 
 
 @funindex \book
 

-All the movements and texts which appear in the same @code{.ly} file
+All the movements and texts which appear in the same @file{.ly} file

 will normally be typeset in the form of a single output file.
 
 @example
 will normally be typeset in the form of a single output file.
 
 @example


@@ -219,11 +219,13 @@ title, like the book itself, by specifying a @code{\header} block.
 @node Multiple output files from one input file
 @subsection Multiple output files from one input file
 
 @node Multiple output files from one input file
 @subsection Multiple output files from one input file
 

-If you want multiple output files from the same .ly file, then you can
-add multiple @code{\book} blocks, where each such \book block will
-result in a separate output file. If you do not specify any
-@code{\book} block in the input file, LilyPond will implicitly treat
-the whole file as a single \book block, see @ref{File structure}.
+If you want multiple output files from the same @file{.ly} file,
+then you can add multiple @code{\book} blocks, where each
+such \book block will result in a separate output file.
+If you do not specify any @code{\book} block in the
+input file, LilyPond will implicitly treat the whole
+file as a single \book block, see
+@ref{File structure}.

 
 When producing multiple files from a single source file, Lilypond
 ensures that none of the output files from any @code{\book} block
 
 When producing multiple files from a single source file, Lilypond
 ensures that none of the output files from any @code{\book} block


@@ -343,7 +345,7 @@ The file above will produce these output files:
 @funindex \book
 @funindex \bookpart
 
 @funindex \book
 @funindex \bookpart
 

-A @code{.ly} file may contain any number of toplevel expressions, where a
+A @file{.ly} file may contain any number of toplevel expressions, where a

 toplevel expression is one of the following:
 
 @itemize
 toplevel expression is one of the following:
 
 @itemize


@@ -369,7 +371,7 @@ A @code{\score} block.  This score will be collected with other
 toplevel scores, and combined as a single @code{\book}.
 This behavior can be changed by setting the variable
 @code{toplevel-score-handler} at toplevel.  The default handler is
 toplevel scores, and combined as a single @code{\book}.
 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}.
+defined in the init file @file{../scm/lily.scm}.

 
 @item
 A @code{\book} block logically combines multiple movements
 
 @item
 A @code{\book} block logically combines multiple movements


@@ -377,14 +379,14 @@ A @code{\book} block logically combines multiple movements
 are a number of @code{\score}s, one output file will be created
 for each @code{\book} block, in which all corresponding movements
 are concatenated.  The only reason to explicitly specify
 are a number of @code{\score}s, 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 to create
+@code{\book} blocks in a @file{.ly} file is if you wish to create

 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 defined in the init file
 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 defined in the init file

-@file{../@/scm/@/lily@/.scm}.
+@file{../scm/lily.scm}.

 
 @item
 A @code{\bookpart} block.  A book may be divided into several parts,
 
 @item
 A @code{\bookpart} block.  A book may be divided into several parts,


@@ -418,7 +420,7 @@ music expression will be translated into
 
 This behavior can be changed by setting the variable
 @code{toplevel-music-handler} at toplevel.  The default handler is
 
 This behavior can be changed by setting the variable
 @code{toplevel-music-handler} at toplevel.  The default handler is

-defined in the init file @file{../@/scm/@/lily@/.scm}.
+defined in the init file @file{../scm/lily.scm}.

 
 @item
 A markup text, a verse for example
 
 @item
 A markup text, a verse for example


@@ -514,7 +516,7 @@ some pieces include a lot more information.
 
 @menu
 * Creating titles::
 
 @menu
 * Creating titles::

-* Custom titles::
+* Custom headers footers and titles::

 * Reference to page numbers::
 * Table of contents::
 @end menu
 * Reference to page numbers::
 * Table of contents::
 @end menu


@@ -706,12 +708,12 @@ Headers may be completely removed by setting them to false.
 @end example
 
 
 @end example
 
 

-@node Custom titles
-@subsection Custom titles
+@node Custom headers footers and titles
+@subsection Custom headers, footers, and titles

 
 A more advanced option is to change the definitions of the following
 variables in the @code{\paper} block.  The init file
 
 A more advanced option is to change the definitions of the following
 variables in the @code{\paper} block.  The init file

-@file{../@/ly/@/titling@/-init@/.ly} lists the default layout.
+@file{../ly/titling-init.ly} lists the default layout.

 
 @table @code
 @funindex bookTitleMarkup
 
 @table @code
 @funindex bookTitleMarkup


@@ -759,16 +761,48 @@ the name of the movement (@code{piece} field).
 The following definition will put the title flush left, and the
 composer flush right on a single line.
 
 The following definition will put the title flush left, and the
 composer flush right on a single line.
 

-@verbatim
-\paper {
-  bookTitleMarkup = \markup {
-   \fill-line {
+@example
+\paper @{
+  bookTitleMarkup = \markup @{
+   \fill-line @{

      \fromproperty #'header:title
      \fromproperty #'header:composer
      \fromproperty #'header:title
      \fromproperty #'header:composer

-   }
-  }
-}
-@end verbatim
+   @}
+  @}
+@}
+@end example
+
+The header and footer are created by the functions
+@code{make-header} and @code{make-footer}, defined in
+@code{\paper}.  The default implementations are in
+@file{ly/paper-defaults-init.ly} and
+@file{ly/titling-init.ly}.
+
+This example centers page numbers at the bottom of every page.
+
+@example
+\paper @{
+  print-page-number = ##t
+  print-first-page-number = ##t
+  oddHeaderMarkup = \markup \fill-line @{ " " @}
+  evenHeaderMarkup = \markup \fill-line @{ " " @}
+  oddFooterMarkup = \markup @{
+    \fill-line @{
+      \bold \fontsize #3
+      \on-the-fly #print-page-number-check-first
+      \fromproperty #'page:page-number-string
+    @}
+  @}
+  evenFooterMarkup = \markup @{
+    \fill-line @{
+      \bold \fontsize #3
+      \on-the-fly #print-page-number-check-first
+      \fromproperty #'page:page-number-string
+    @}
+  @}
+@}
+@end example
+

 
 @node Reference to page numbers
 @subsection Reference to page numbers
 
 @node Reference to page numbers
 @subsection Reference to page numbers


@@ -923,9 +957,25 @@ tocAct =
 }
 @end lilypond
 
 }
 @end lilypond
 

+Dots can be added to fill the line between an item and its page number:
+
+@lilypond[verbatim,quote]
+\header { tagline = ##f }
+\paper {
+  tocItemMarkup = \tocItemWithDotsMarkup
+}
+
+\book {
+  \markuplines \table-of-contents
+  \tocItem \markup { Allegro }
+  \tocItem \markup { Largo }
+  \markup \null
+}
+@end lilypond
+

 
 @seealso
 
 @seealso

-Init files: @file{../@/ly/@/toc@/-init@/.ly}.
+Init files: @file{../ly/toc-init.ly}.

 
 
 @predefined
 
 
 @predefined


@@ -1079,6 +1129,7 @@ structure while leaving the notation untouched.
 @menu
 * Using variables::
 * Using tags::
 @menu
 * Using variables::
 * Using tags::

+* Using global settings::

 @end menu
 
 @node Using variables
 @end menu
 
 @node Using variables


@@ -1297,6 +1348,33 @@ than one tagged section at the same place.
 
 @end ignore
 
 
 @end ignore
 

+@node Using global settings
+@unnumberedsubsubsec Using global settings
+
+@cindex include-settings
+
+Global settings can be included from a separate file:
+
+@example
+lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
+@end example
+
+Groups of settings such as page size, font or type face can be stored
+in separate files. This allows different editions from the same score
+as well as standard settings to be applied to many scores, simply by
+specifying the proper settings file.
+
+This technique also works well with the use of style sheets, as
+discussed in @rlearning{Style sheets}.
+
+@seealso
+Learning Manual:
+@rlearning{Organizing pieces with variables},
+@rlearning{Style sheets}.
+
+Notation Reference:
+@ref{Including LilyPond files}.
+

 @node Text encoding
 @subsection Text encoding
 
 @node Text encoding
 @subsection Text encoding
 


@@ -1402,7 +1480,7 @@ lyrics and as stand-alone text below the score:
   }
   \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
 }
   }
   \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
 }

-\markup { "Copyright 2008--2010" \char ##x00A9 }
+\markup { "Copyright 2008--2011" \char ##x00A9 }

 @end lilypond
 
 @cindex copyright sign
 @end lilypond
 
 @cindex copyright sign


@@ -1526,14 +1604,12 @@ This property is also used to control output to the MIDI file.  Note that
 it skips all events, including tempo and instrument changes.  You have
 been warned.
 
 it skips all events, including tempo and instrument changes.  You have
 been warned.
 

-@lilypond[quote,fragment,ragged-right,verbatim]
-\relative c'' {
-  c8 d
-  \set Score.skipTypesetting = ##t
-  e8 e e e e e e e
-  \set Score.skipTypesetting = ##f
-  c8 d b bes a g c2
-}
+@lilypond[quote,relative=2,ragged-right,verbatim]
+c8 d
+\set Score.skipTypesetting = ##t
+e8 e e e e e e e
+\set Score.skipTypesetting = ##f
+c8 d b bes a g c2

 @end lilypond
 
 In polyphonic music, @code{Score.skipTypesetting} will affect all
 @end lilypond
 
 In polyphonic music, @code{Score.skipTypesetting} will affect all


@@ -1610,6 +1686,10 @@ what was entered.  This is convenient for checking the music; octaves
 that are off or accidentals that were mistyped stand out very much
 when listening to the MIDI output.
 
 that are off or accidentals that were mistyped stand out very much
 when listening to the MIDI output.
 

+Standard MIDI oputput is somewhat crude; optionally, an enhanced and
+more realistic MIDI output is available by means of
+@ref{The Articulate script}.
+

 @c TODO Check this
 The midi output allocates a channel for each staff, and one for global
 settings.  Therefore the midi file should not have more than 15 staves
 @c TODO Check this
 The midi output allocates a channel for each staff, and one for global
 settings.  Therefore the midi file should not have more than 15 staves


@@ -1622,6 +1702,7 @@ settings.  Therefore the midi file should not have more than 15 staves
 * Repeats in MIDI::
 * Controlling MIDI dynamics::
 * Percussion in MIDI::
 * Repeats in MIDI::
 * Controlling MIDI dynamics::
 * Percussion in MIDI::

+* The Articulate script::

 @end menu
 
 @node Creating MIDI files
 @end menu
 
 @node Creating MIDI files


@@ -1789,7 +1870,7 @@ tempoWholesPerMinute = #(ly:make-moment 270 8)
 Context definitions follow precisely the same syntax as those
 within a @code{\layout} block.  Translation modules for sound are
 called performers.  The contexts for MIDI output are defined in
 Context definitions follow precisely the same syntax as those
 within a @code{\layout} block.  Translation modules for sound are
 called performers.  The contexts for MIDI output are defined in

-@file{../@/ly/@/performer@/-init@/.ly},
+@file{../ly/performer-init.ly},

 see @rlearning{Other sources of information}.
 For example, to remove the effect of dynamics
 from the MIDI output, insert the following lines in the
 see @rlearning{Other sources of information}.
 For example, to remove the effect of dynamics
 from the MIDI output, insert the following lines in the


@@ -1832,6 +1913,13 @@ within a score block defined with a @code{\score} command.
 @cindex MIDI, chord names
 @cindex Rhythms in MIDI
 @cindex MIDI, Rhythms
 @cindex MIDI, chord names
 @cindex Rhythms in MIDI
 @cindex MIDI, Rhythms

+@cindex Articlulate scripts
+@cindex MIDI, articulations
+@cindex articulations in MIDI
+@cindex trills in MIDI
+@cindex turns in MIDI
+@cindex rallentando in MIDI
+@cindex accelerando in MIDI

 @c TODO etc
 
 The following items of notation are reflected in the MIDI output:
 @c TODO etc
 
 The following items of notation are reflected in the MIDI output:


@@ -1850,11 +1938,22 @@ player that supports pitch bend.)
 @item Lyrics
 @end itemize
 
 @item Lyrics
 @end itemize
 

+Using @ref{The Articulate script}, a number of items are added to the
+above list:
+
+@itemize
+@item Articulations (slurs, staccato, etc)
+@item Trills, turns
+@item Rallentando and accelerando
+@end itemize
+
+

 @unnumberedsubsubsec Unsupported in MIDI
 
 @c TODO index as above
 
 @unnumberedsubsubsec Unsupported in MIDI
 
 @c TODO index as above
 

-The following items of notation have no effect on the MIDI output:
+The following items of notation have no effect on the MIDI output,
+unless you use @ref{The Articulate script}:

 
 @itemize
 @item Rhythms entered as annotations, e.g. swing
 
 @itemize
 @item Rhythms entered as annotations, e.g. swing


@@ -1892,6 +1991,10 @@ repeats to unfold repeats.
 \bar "|."
 @end lilypond
 
 \bar "|."
 @end lilypond
 

+In scores containing multiple voices, unfolding of repeats in MIDI
+output will only occur correctly if @emph{each} voice contains fully
+notated repeat indications.
+

 When creating a score file using @code{\unfoldRepeats} for MIDI,
 it is necessary to make two @code{\score} blocks: one for MIDI
 (with unfolded repeats) and one for notation (with volta, tremolo,
 When creating a score file using @code{\unfoldRepeats} for MIDI,
 it is necessary to make two @code{\score} blocks: one for MIDI
 (with unfolded repeats) and one for notation (with volta, tremolo,


@@ -1922,7 +2025,7 @@ Dynamic marks are translated to a fixed fraction of the available
 MIDI volume range.  The default fractions range from 0.25 for
 @notation{ppppp} to 0.95 for @notation{fffff}.  The set of dynamic
 marks and the associated fractions can be seen in
 MIDI volume range.  The default fractions range from 0.25 for
 @notation{ppppp} to 0.95 for @notation{fffff}.  The set of dynamic
 marks and the associated fractions can be seen in

-@file{../@/scm/@/midi.scm}, see @rlearning{Other sources of information}.
+@file{../scm/midi.scm}, see @rlearning{Other sources of information}.

 This set of fractions may be changed or extended by providing a
 function which takes a dynamic mark as its argument and returns the
 required fraction, and setting
 This set of fractions may be changed or extended by providing a
 function which takes a dynamic mark as its argument and returns the
 required fraction, and setting


@@ -1962,7 +2065,7 @@ found, or calls the default function otherwise.
 Alternatively, if the whole table of fractions needs to be
 redefined, it would be better to use the
 @notation{default-dynamic-absolute-volume} procedure in
 Alternatively, if the whole table of fractions needs to be
 redefined, it would be better to use the
 @notation{default-dynamic-absolute-volume} procedure in

-@file{../@/scm/@/midi.scm} and the associated table as a model.
+@file{../scm/midi.scm} and the associated table as a model.

 The final example in this section shows how this might be done.
 
 @unnumberedsubsubsec Overall MIDI volume
 The final example in this section shows how this might be done.
 
 @unnumberedsubsubsec Overall MIDI volume


@@ -2073,7 +2176,7 @@ If the MIDI minimum and maximum volume properties are not set
 LilyPond will, by default, apply a small degree of equalization
 to a few instruments.  The instruments and the equalization
 applied are shown in the table @notation{instrument-equalizer-alist}
 LilyPond will, by default, apply a small degree of equalization
 to a few instruments.  The instruments and the equalization
 applied are shown in the table @notation{instrument-equalizer-alist}

-in @file{../@/scm/@/midi.scm}.
+in @file{../scm/midi.scm}.

 
 This basic default equalizer can be replaced by setting
 @code{instrumentEqualizer} in the @code{Score} context to a new
 
 This basic default equalizer can be replaced by setting
 @code{instrumentEqualizer} in the @code{Score} context to a new


@@ -2083,7 +2186,7 @@ maximum volumes to be applied to that instrument.  This replacement
 is done in the same way as shown for resetting the
 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
 The default equalizer, @notation{default-instrument-equalizer}, in
 is done in the same way as shown for resetting the
 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
 The default equalizer, @notation{default-instrument-equalizer}, in

-@file{../@/scm/@/midi.scm} shows how such a procedure might be written.
+@file{../scm/midi.scm} shows how such a procedure might be written.

 
 The following example sets the relative flute and clarinet volumes
 to the same values as the previous example.
 
 The following example sets the relative flute and clarinet volumes
 to the same values as the previous example.


@@ -2197,4 +2300,40 @@ set.
 Because the general MIDI standard does not contain rim shots, the
 sidestick is used for this purpose instead.
 
 Because the general MIDI standard does not contain rim shots, the
 sidestick is used for this purpose instead.
 

+@node The Articulate script
+@subsection The Articulate script
+
+A more realistic MIDI output is possible when using the Articulate
+script.  It tries to take articulations (slurs, staccato, etc) into
+account, by replacing notes with sequential music of suitably
+time-scaled note plus skip.  It also tries to unfold trills turns
+etc., and take rallentando and accelerando into account.
+
+To use the Articulate script, you have to include it at the top of
+your input file,
+
+@example
+\include "articulate.ly"
+@end example
+
+and in the @code{\score} section do
+
+@example
+\unfoldRepeats \articulate <<
+       all the rest of the score...
+>>
+@end example
+
+After altering your input file this way, the visual output is heavily
+altered, but the standard @code{\midi} block will produce a better
+MIDI file.
+
+Although not essential for the Articulate script to work, you may want
+to insert the @code{\unfoldRepeats} command as it appears in the
+example shown above as it enables performing abbreviatures such as
+@notation{trills}.
+
+@knownissues

 
 

+Articulate shortens chords and some music (esp. organ music) could
+sound worse.