From: Trevor Daniels Date: Mon, 19 May 2008 15:19:49 +0000 (+0100) Subject: GDP: NR 3.1 and 3.2.1 first pass X-Git-Tag: release/2.11.47-1~5^2~2 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=c6c11a2e6464b128f54c4c29782c8c8fb37f489b;p=lilypond.git GDP: NR 3.1 and 3.2.1 first pass --- diff --git a/Documentation/user/input.itely b/Documentation/user/input.itely index 330f9342c1..62f22e52bb 100644 --- a/Documentation/user/input.itely +++ b/Documentation/user/input.itely @@ -18,18 +18,12 @@ rather than specific notation. FIXME: don't complain about anything in this chapter. It's still under heavy development. -FIXME: add comments -@verbatim -% %{ -@end verbatim -to 3.1. - @menu -* Input structure:: -* Useful concepts and properties:: -* Titles and headers:: -* Working with input files:: -* Controlling output:: +* Input structure:: +* Useful concepts and properties:: +* Titles and headers:: +* Working with input files:: +* Controlling output:: @end menu @@ -40,21 +34,35 @@ 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 @node Structure of a score @subsection Structure of a score -A @code{\score} must contain a single music expression. However, -this music expression may be of any size. Recall that music -expressions may be included inside other expressions to form -larger expressions. All of these examples are single music -expressions; note the curly braces @{ @} or angle brackets << ->> at the beginning and ending of the music. +@funindex \score + +A @code{\score} block must contain a single music expression +delimited by curly brackets: + +@example +\score @{ +... +@} +@end example + +@warning +There must be @strong{only one} outer music expression in a +@code{\score} block, and it @strong{must} be surrounded by +curly brackets. +@end warning + +This single music expression may be of any size, and may contain +other music expressions to any complexity. All of these examples +are music expressions: @example @{ c'4 c' c' c' @} @@ -89,6 +97,21 @@ expressions; note the curly braces @{ @} or angle brackets << @} @end example +Comments are one exception to this general rule. (For others see +@ref{File structure}.) Both single-line comments and comments +delimited by @code{%@{ .. %@}} may be placed anywhere within an +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 + +Learning Manual: + +@rlearning{Working on input files}, +@rlearning{Music expressions explained}, +@rlearning{Score is a single (compound) music expression. + @node Multiple scores in a book @subsection Multiple scores in a book @@ -170,14 +193,23 @@ the top of the file is inserted. @node File structure @subsection File structure -A @code{.ly} file contains any number of toplevel expressions, where a -toplevel expression is one of the following +@funindex \paper +@funindex \midi +@funindex \layout +@funindex \header +@funindex \score +@funindex \book + +A @code{.ly} file may contain any number of toplevel expressions, where a +toplevel expression is one of the following: @itemize @item An output definition, such as @code{\paper}, @code{\midi}, and @code{\layout}. Such a definition at the toplevel changes the default -settings for the block entered. +book-wide settings. If more than one such definition of +the same type is entered at the top level any definitions in the later +expressions have precedence. @item A direct scheme expression, such as @@ -192,28 +224,24 @@ composer, title, etc. @item 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 defined in the init file @file{scm/@/lily@/.scm}. -The @code{\score} must begin with a music expression, and may -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}, 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 -defined in the init file @file{scm/@/lily@/.scm}. +(i.e., multiple @code{\score} blocks) in one document. If there +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 +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}. @item A compound music expression, such as @@ -258,7 +286,7 @@ expressions, wherever they appear. @cindex variables @item -An variable, such as +A variable, such as @example foo = @{ c4 d e d @} @end example @@ -274,7 +302,7 @@ toplevel @example \layout @{ - % movements are non-justified by default + % Don't justify the output ragged-right = ##t @} @@ -294,43 +322,122 @@ be entered: @item @code{\include} @item @code{\sourcefilename} @item @code{\sourcefileline} +@item +A single-line comment, introduced by a leading @code{%} sign. + +@item +A multi-line comment delimited by @code{%@{ .. %@}}. @end itemize +@seealso + +Learning Manual: +@rlearning{How LilyPond input files work}. @node Useful concepts and properties @section Useful concepts and properties @menu -* Input modes:: -* When to add a -:: -* Controlling direction and placement:: -* Distances and measurements:: -* Spanners:: +* Input modes:: +* When to add a -:: +* Controlling direction and placement:: +* Distances and measurements:: +* Spanners:: @end menu @node Input modes @subsection Input modes -\notemode +The way in which the notation contained within an input file is +interpreted is determined by the current input mode. + +@unnumberedsubsubsection Note mode + +This is the default mode or it may be activated with the +@code{\notemode} command. Input is interpreted as pitches, +durations, markup, etc and typeset as musical notation on a staff. + +It is not normally necessary to specify note mode explicitly, but +it may be useful to do so in certain situations, for example if you +are in \lyricmode or \chordmode or any other mode and want to insert +something that only can be done with @code(\notemode} syntax. + +For example, to indicate dynamic markings for the verses of a +choral pieces it is necessary to enter note mode to interpret +the markings: + +@lilypond{verbatim,relative=2,quote} +{ c4 c4 c4 c4 } +\addlyrics { + \notemode{\set stanza = \markup{ \dynamic f 1. } } + To be sung loudly +} +\addlyrics { + \notemode{\set stanza = \markup{ \dynamic p 2. } } + To be sung quietly +} +@end lilypond + +@unnumberedsubsubsection Lyrics mode + +This is activated with the @code{\lyricmode} command, and causes +input to be interpreted as lyric syllables with optional durations +and associated lyric modifiers. + +Lyric mode is also activated with the +@code{\addlyrics} command. This command also creates a new +@code{Lyrics} context and an implicit @code{\lyricsto} command +which associates the lyrics with the preceding music. + +@unnumberedsubsubsection Chord mode + +This is activated with the @code{\chordmode} command, and causes +input to be interpreted with the syntax of chord notation, see +@ref{Chord notation}. Chords are rendered as notes on a staff. + +Chord mode is also activated with the @code{\chords} command. +This also creates a new @code{ChordNames} context and +causes the following input to be interpreted with the syntax of +chord notation and rendered as chord names in the @code{ChordNames} +context, see @ref{Printing chord names}. + +@unnumberedsubsubsection Drum mode + +This is activated with the @code{\drummode} command, and causes +input to be interpreted with the syntax of drum notation, see +@ref{Basic percussion notation}. + +Drum mode is also activated with the @code{\drums} command. +This also creates a new @code{DrumStaff} context and causes the +following input to be interpreted with the syntax of drum notation +and rendered as drum symbols on a drum staff, see @ref{Basic +percussion notation}. + +@unnumberedsubsubsection Figure mode + +This is activated with the @code{\figuremode} command, and causes +input to be interpreted with the syntax of figured bass, see +@ref{Entering figured bass}. + +Figure mode is also activated with the @code{\figures} command. +This also creates a new @code{FiguredBass} context and causes the +following input to be interpreted with the figured bass syntax +and rendered as figured bass symbols in the @code{FiguredBass} +context, see @ref{Introduction to figured bass}. -\notemode turns the front end of LilyPond into note mode -(which is the default parsing mode). -It's certainly useful in certain situations, for example if you -are in \lyricmode or \chordmode or ... and want to insert -something that only can be done with \notemode syntax. +@unnumberedsubsubsection Fret and tab modes -See for example -http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00418.html -http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00218.html -http://lists.gnu.org/archive/html/lilypond-user/2006-12/msg00236.html -http://lists.gnu.org/archive/html/lilypond-user/2006-11/msg00061.html +There are no special input modes for entering fret and tab symbols. +To create tab diagrams, enter notes or chords in note mode and +render them in a @code{TabStaff} context, see +@ref{Default tablatures}. -\chords -\drums -\fretmode ? +To create fret diagrams above a staff, enter them as markup +above the notes using the @code{\fret-diagram} command, see +@ref{Fret diagrams}. @node When to add a -