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
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' @}
@}
@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
@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
@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
@cindex variables
@item
-An variable, such as
+A variable, such as
@example
foo = @{ c4 d e d @}
@end example
@example
\layout @{
- % movements are non-justified by default
+ % Don't justify the output
ragged-right = ##t
@}
@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 -
projects / lilypond.git / commitdiff