+@c -*-texinfo-*-
@c TODO:
@c - Reinsert subsection commands that were lost in the
@c ancient conversion from YODL! /MB
@c - Fix indexing (keyindex) so it doesn't add line breaks /MB
@node Reference Manual, , , Top
+@chapter Reference Manual
+
@menu
-* Overview:: Overview
-* Top level:: Top level
-* notenames:: notenames
-* Lexical conventions:: Lexical conventions
-* Other languages:: notelang
-* modes:: modes
-* Types:: Types
-* Music expressions:: Music expressions
-* Atomic music expressions:: Atomic music expressions
-* Note specification:: notedesc
-* barlines:: barlines
-* Manual beams:: Manual beam
-* stem tremolo:: tremolo
-* Compound music expressions:: Compound music expressions
-* relative:: relative
-* Repeats:: Repeats
-* transpose:: transpose
-* Ambiguities:: Ambiguities
-* Notation conversion specifics:: Notation conversion specifics
-* autobeam:: autobeam
-* lyricprint:: lyricprint
-* Notation Contexts:: Notation Contexts
-* Properties:: Changing formatting
-* Notation output definitions:: Notation output definitions
-* paper:: paper
-* Paper variables:: papervars
-* contextdefs:: contextdefs
-* engravers:: engravers
-* Sound output:: Sound output
-* midilist:: midilist
-* Pre-defined Identifiers:: Pre-defined Identifiers
+* Overview:: Overview
+* Top level:: Top level
+* Pitch names:: Pitch names
+* Lexical conventions:: Lexical conventions
+* Other languages:: Note names in various languages
+* Lexical modes:: modes
+* Types:: Types
+* Music expressions:: Music expressions
+* Atomic music expressions:: Atomic music expressions
+* Note specification:: notedesc
+* barlines:: barlines
+* Manual beams:: Manual beam
+* stem tremolo:: tremolo
+* Compound music expressions:: Compound music expressions
+* relative:: relative
+* Repeats:: Repeats
+* transpose:: transpose
+* Ambiguities:: Ambiguities
+* Notation conversion specifics:: Notation conversion specifics
+* autobeam:: autobeam
+* lyricprint:: lyricprint
+* Notation Contexts:: Notation Contexts
+* Properties:: Changing formatting
+* Page layout:: Layout
+* contextdefs:: contextdefs
+* Sound output:: Sound output
+* midilist:: midilist
+* Pre-defined Identifiers:: Pre-defined Identifiers
+@c May be fragile. Better make single link to generated doco?
+* Interpretation contexts:(lilypond-internals)LilyPond interpretation contexts.
+* Engravers:(lilypond-internals)LilyPond engravers.
+* Backend:(lilypond-internals)LilyPond backend.
@end menu
-@chapter Reference Manual
-
@node Overview, , , Reference Manual
@section Overview
-This document@footnote{This document has been revised for
-LilyPond 1.2.} describes the the GNU LilyPond input format, which is
-a language for defining music. We call this language @emph{Music
-Definition Language} or @emph{Mudela}, for short.@footnote{If anybody
-comes up with a better name, we'd gladly take this. Gourlay already
-uses a ``Musical Description Language,'' ISO standard 10743 defines a
-``Standard Music Description Language.'' We're not being original
-here.}
-
-@emph{Mudela} is a language that allows you to
+This document@footnote{This document has been revised for LilyPond 1.2.}
+describes the the GNU LilyPond input format This format represents a
+piece of music in an elegant way, but contains enough information for
+both automatic typesetting and automatic performances.
+LilyPond input can be classified into three types:
@itemize @bullet
- @item create musical expressions by combining pitches, durations
- @item output those musical expressions to various formats
- @item give those musical expressions and output definitions names, so
- you can enter them in manageable chunks.
-@end itemize
+ @item musical expressions: a musical expression is some combination of
+rest, notes, lyrics
+ @item output definitions: recipes for translating those musical
+expressions into performances (MIDI) or graphics (eg. PostScript).
-@emph{Mudela} aims to define a piece of music completely, both from
-typesetting and from a performance point of view.
+ @item declarations: by declaring and naming musical expressions, you
+can enter and edit them in manageable chunks.
+@end itemize
@var{outputdefs} are zero or more output definitions. If no output
definition is supplied, the default @code{\paper} block will be added.
-
-
@cindex header
@keyindex{header}
It is customary to put the @code{\header} at the top of the file.
-@node notenames, , , Reference Manual
-
-Note name tables can be specified using
-
-@example
- \notenames@keyindex{notenames}
- @{ @var{assignmentlist} @}
-@end example
-
-@var{assignmentlist} is a list of definitions of the form
+@node Pitch names, , , Reference Manual
+Note names and chord modifiers can be customised for nationalities.
+languages and conventions. The syntax is as follows.
@example
- @var{name} = @var{pitch}
+ \pitchnames @keyindex{pitchnames} @var{scheme-alist}
+ \chordmodifiers@keyindex{chordmodifiers} @var{scheme-alist}
@end example
-Chord modifiers can be set analogously, with
-@code{\chordmodifiers}@keyindex{chordmodifiers}.
+See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
+specific examples how to do this. tables can be tailored specified
+using. Some national note names have been provided, see @ref{Other
+languages}.
A @code{\paper} block at top level sets the default paper block. A
@code{\midi} block at top level works similarly.
-LilyPond contains a Scheme interpreter (the GUILE library) for
-internal use. The following commands access the interpreter
-directly.
-
-@example
- \scm @keyindex{scm} @var{scheme} ;
-@end example
-
-Evaluates the specified Scheme code. The result is discarded.
-
-@example
-\scmfile@keyindex{scmfile} @var{filename};
-@end example
-
-Reads Scheme code from the specified file. The result is discarded.
-
-
-
Identifier assignments may appear at top level. Semicolons are
forbidden after top level assignments.
+@unnumberedsubsec Comments
+
@cindex comment
@indexcode{%}
Block comments are started by `@code{%@{}' and ended by `@code{%@}}'.
They cannot be nested.
+@unnumberedsubsec Scheme
+
+@indexcode{#}
+
+LilyPond contains a Scheme interpreter (the GUILE library) for
+internal use. The interpreter is accessed by the pound sign:
+
+Whereever the syntax allows Scheme expressions, you may enter one as
+
+@example
+ #@var{scheme}
+@end example
+
+Evaluates the specified Scheme code. If this is used at toplevel, then
+the result is discarded. Example:
+@example
+ \property Staff.TestObject \override #'symbol = #(+ 1 2)
+@end example
+
+(in this case, @code{\override} expects two Scheme expressions.
+[refer appendix/ online intro on Scheme]
+
+@unnumberedsubsec Keywords
@cindex keyword
alphabetic characters. These are all the keywords.
@example
- \accepts
- \addlyrics
- \alternative
- \bar
- \breathe
- \chordmodifiers
- \chords
- \clef
- \cm
- \consists
- \consistsend
- \context
- \duration
- \font
- \grace
- \header
- \in
- \key
- \keysignature
- \lyrics
- \mark
- \midi
- \mm
- \musicalpitch
- \name
- \notenames
- \notes
- \paper
- \partial
- \penalty
- \property
- \pt
- \relative
- \remove
- \repeat
- \repetitions
- \scm
- \scmfile
- \score
- \script
- \sequential
- \simultaneous
- \skip
- \spanrequest
- \tempo
- \textscript
- \time
- \times
- \translator
- \transpose
- \type
+apply arpeggio autochange spanrequest commandspanrequest
+simultaneous sequential accepts alternative bar breathe
+char chordmodifiers chords clef cm consists consistsend
+context denies duration dynamicscript elementdescriptions
+font grace header in lyrics key mark musicalpitch
+time times midi mm name pitchnames notes outputproperty
+override set revert partial paper penalty property pt
+relative remove repeat addlyrics partcombine score
+script stylesheet skip textscript tempo translator
+transpose type
@end example
-
-
+@unnumberedsubsec Integers
@cindex integer
operations cannot be done with integers, and integers cannot be mixed
with reals.
-
+@unnumberedsubsec Reals
@cindex real
is the internal representation of dimensions.
-
+@unnumberedsubsec
@cindex string
-
Begins and ends with the `@code{"}' character. To include a `@code{"}'
character in a string write `@code{\"}'. Various other backslash
-sequences have special interpretations as in the C language. A
-string that contains no spaces can be written without the quotes.
-See section XREF-modes [FIXME] for details on unquoted strings; their
-interpretation varies depending on the situation. Strings can be
-concatenated with the `@code{+}' operator.
+sequences have special interpretations as in the C language. A string
+that contains no spaces can be written without the quotes. See
+@ref{Lexical modes} for details on unquoted strings; their interpretation varies
+depending on the situation. Strings can be concatenated with the
+`@code{+}' operator.
-
-The tokenizer accepts the following commands. They can appear
-anywhere.
+The tokenizer accepts the following commands. They have no grammatical
+function, hence they can appear anywhere in the input.
@example
\maininput@keyindex{maininput}
This command is used in init files to signal that the user file must
be read. This command cannot be used in a user file.
+@unnumberedsubsec file inclusion
+
@example
\include@keyindex{include} @var{file}
@end example
unquoted string will not work here!) or a string identifier. The full
filename including the @file{.ly} extension must be given,
+@unnumberedsubsec Version information
+
@example
\version@keyindex{version} @var{string} ;
@end example
Specify the version of LilyPond that a file was written for. The
argument is a version string in quotes, for example @code{"1.2.0"}.
This is used to detect invalid input, and to aid
-@code{convert-mudela}, a tool that automatically upgrades input files.
+@code{convert-ly}, a tool that automatically upgrades input files.
catalan.ly do re mi fa sol la sib si -d/-s -b
@end example
-Pitch names can be redefined using the
-@code{\notenames}@keyindex{notenames} command, see
-subsection XREF-notenames [FIXME].
-
+Pitch names can be redefined using the @code{\pitchnames} command, see
+@ref{Pitch names}.
-
-@cindex lexical modes
+@cindex Lexical Modes
@cindex modes
-@node modes, , , Reference Manual
+@node Lexical modes, , , Reference Manual
-To simplify entering notes, lyrics, and chords, @emph{Mudela} has three
+To simplify entering notes, lyrics, and chords, @emph{Lilypond} has three
special input modes on top of the default mode. In each mode, words
are identified on the input. If @code{"word"} is encountered, it is
treated as a string. If @code{\word} is encountered, it is treated as
@item Normal mode.
@cindex mode!normal
- At the start of parsing, @emph{Mudela} is in Normal mode. In Normal
+ At the start of parsing, @emph{Lilypond} is in Normal mode. In Normal
mode, a word is an alphabetic character followed by alphanumeric
characters. If @code{word} is encountered on the input it is
treated as a string.
durations, you can not enter real numbers in this mode.
@end table
-It is possible to create words that break the rules by prefixing them
-with the dollar sign `@code{$}@indexcode{$}'. Regardless of the context, a
-word beginning with `@code{$}' extends until the next white space
-character. Such words can contain numbers (even in Note mode), or
-other forbidden characters. The dollar sign can be used to create
-and access identifiers that could not otherwise be used.@footnote{Use
-of `@code{$}' hampers readability and portability to future LilyPond
-versions, thus the use of the dollar sign is discouraged.}
-
-
+[todo: include short table showign differences]
@node Types, , , Reference Manual
@section Types
-@cindex types and identifiers
+@cindex Identifiers
+
+[say something about types]
+
+All of the information in a LilyPond input file, is represented as a
+Scheme value. In addition to normal Scheme data types (such as pair,
+number, boolean, etc.), LilyPond has a number of specialized data types,
+
+@itemize @bullet
+ @item Input
+ @item c++-function
+ @item Music: see @ref{Music expressions}
+ @item Identifier
+ @item Translator_def:
+See section @ref{contextdefs} for more information
+
+ @item Duration
+ @item Pitch
+ @item Score
+ @item Music_output_def (TODO: this is not really a Scheme object
+yet. Nevertheless, you can use identifiers to make references to them )
+ @item Moment (rational number)
+@end itemize
-@emph{Mudela} has a limited set of types:
+LilyPond also includes some transient object types. Objects of these
+types are built during a LilyPond run, and do not `exist' per se within
+your input file. These objects are created as a result of your input
+file, so you can include commands in the input to manipulate them,
+during a lilypond run.
@itemize @bullet
- @item integers
- @item reals
- @item strings
- @item music expressions
- @item durations of notes and rests (specified with
- @code{\notenames}@keyindex{notenames})
- @item note name tables
- @item context definitions, part of output definitions. See
- section XREF-contextdefs [FIXME] for more information
- @item output definitions (like @code{\paper}@keyindex{paper} blocks
- and @code{\midi}@keyindex{midi} blocks)
- @item score definitions (@code{\score}@keyindex{score} blocks)
+ @item Grob: short for Graphical object. See @ref{Grobs}.
+ @item Molecule: device-independent page output object,
+ including dimensions. Produced by some Grob functions
+ See @ref{Molecules}
+ @item Translator: object that produces audio objects or Grobs.
+ @item Font_metric: object representing a font. (Not yet user
+accessible.)
+
+@c @item Audio_element: (todo, smobme)
@end itemize
-Type is a syntactical property: @emph{Mudela} has no real type system,
-so there is no support for generic expressions, functions, or user
-defined types. For the same reason, it is not possible to mix reals
-and integers in arithmetic expressions, and ``type
-errors''
-@cindex type error
- (e.g., using a string identifier to
-initialize a @code{\paper}@keyindex{paper} block) will yield a ``parse
-error''.
-
-Identifiers allow objects to be assigned to names. To assign an
-identifier, you use `@var{name}=@var{value}' and to refer to an
-identifier, you preceed its name with a backslash:
+Identifiers allow objects to be assigned to names during the parse
+stage. To assign an identifier, you use `@var{name}=@var{value}' and to
+refer to an identifier, you preceed its name with a backslash:
`@code{\}@var{name}'. Identifier assignments must appear at top level
-in the @emph{Mudela} file. Semicolons are forbidden after assignments
+in the @emph{Lilypond} file. Semicolons are forbidden after assignments
appearing at top level but they are obligatory after assignments
-appearing in the @code{\paper} block, see Section XREF-paper [FIXME].
+appearing in the @code{\paper} block, see Section @ref{Page layout}.
-@var{value} is any of the types listed above.
+@var{value} is any valid Scheme value or any of the input-types listed
+above.
-An identifier can be created with any string for its name, but you
-will only be able to refer to identifiers whose names begin with a
-letter, being entirely alphanumeric. It is impossible to refer to an
-identifier whose name is the same as the name of a keyword.
+An identifier can be created with any string for its name, but you will
+only be able to refer to identifiers whose names begin with a letter,
+being entirely alphanumeric. It is impossible to refer to an identifier
+whose name is the same as the name of a keyword.
The right hand side of an identifier assignment is parsed completely
before the assignment is done, so it is allowed to redefine an
@end example
When an identifier is referenced, the information it points to is
-copied. Therefore it only makes sense to put identifiers for
-translators, output definitions, and @code{\score}@keyindex{score}
-blocks as the first item in a block. For this reason, if you
-reference a @code{\foo} variable in a @code{\foo} block, it must be the
-first item in the list following @code{\foo}.@footnote{@code{\paper@{\one
-\two@}} does not make sense, because the information of @code{\two}
-would overwrite the information of @code{\one}, thereby making the
-reference to the first identifier useless.}
+copied. For this reason, an identifier reference must always be the
+ first item in a block.
+@example
+\paper @{
+ foo = 1.0
+ \paperIdent % wrong and invalid
+@}
+\paper @{
+ \paperIdent % correct
+ foo = 1.0
+@}
+@end example
@node Music expressions, , , Reference Manual
@cindex music expressions
-Music in @emph{Mudela} is entered as a music expression. Notes, rests,
+Music in @emph{Lilypond} is entered as a music expression. Notes, rests,
lyric syllables are music expressions (the atomic
-expressions)
+expressions),
@cindex atomic music expressions
-, and you can combine
-music expressions to form new ones. This example forms a compound
-expressions out of the quarter @code{c} note and a @code{d}
-note:
+and you can combine music expressions to form new ones. This example
+forms a compound expressions out of the quarter @code{c} note and a
+@code{d} note:
@example
\sequential @{ c4 d4 @}
simultaneously, for instance).
Atomic music expression are discussed in
-subsection XREF-atomicmusic [FIXME]. Compound music expressions are
-discussed in subsection XREF-compoundmusic [FIXME].
+subsection @ref{Atomic music expressions}. Compound music expressions are
+discussed in subsection @ref{Compound music expressions}.
natural, negative to add flats, or positive to add sharps.
In Note and Chord mode, pitches may be designated by names. See
-section XREF-notelang [FIXME] for pitch names in different languages.
+section @ref{Other languages} for pitch names in different languages.
The syntax for duration specification is
@var{dotcount}.
In Note, Chord, and Lyrics mode, durations may be designated by
-numbers and dots. See Section XREF-notelang [FIXME] for details.
+numbers and dots.
@node Note specification, , , Reference Manual
The default names are the Dutch note names. The notes are specified
by the letters `@code{c}' through `@code{b}', where `@code{c}' is an
octave below middle C and the letters span the octave above that C.
-In Dutchcindex(notenames!Dutch), a sharp is formed by adding
-`@code{-is}' to the end of a pitch name. A flat is formed by adding
-`@code{-es}'. Double sharps and double flats are obtained by adding
-`@code{-isis}' or `@code{-eses}'. `@code{aes}' and `@code{ees}' are
-contracted to `@code{as}' and `@code{es}' in Dutch, but both forms will
-be accepted.
+In Dutch,
+@cindex notenames!Dutch
+a sharp is formed by adding `@code{-is}' to the end of a pitch name. A
+flat is formed by adding `@code{-es}'. Double sharps and double flats
+are obtained by adding `@code{-isis}' or `@code{-eses}'. `@code{aes}'
+and `@code{ees}' are contracted to `@code{as}' and `@code{es}' in Dutch,
+but both forms will be accepted.
LilyPond has predefined sets of notenames for various languages. See
-section XREF-notelang [FIXME] for details.
+@ref{Other languages}.
+
The optional octave specification takes the form of a series of
(`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one
octave; each @code{,} lowers the pitch by an octave.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
c' d' e' f' g' a' b' c''
-@end mudela
+@end lilypond
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
cis' dis' eis' fis' gis' ais' bis'
-@end mudela
+@end lilypond
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
ces' des' es' fes' ges' as' bes'
-@end mudela
+@end lilypond
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
cisis' eisis' gisis' aisis' beses'
-@end mudela
+@end lilypond
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
ceses' eses' geses' ases' beses'
-@end mudela
+@end lilypond
Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
will determine what accidentals to typeset depending on the key and
accidental within parentheses can be obtained by adding the question
mark `@code{?}@indexcode{?}' after the pitch.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
cis' d' e' cis' c'? d' e' c'!
-@end mudela
+@end lilypond
@cindex duration
@quotation
-@mudela[]
+@lilypond[]
\score {
\notes \relative c'' {
a\longa a\breve
} %}
}
}
-@end mudela
+@end lilypond
@end quotation
@quotation
@quotation
-@mudela[]
+@lilypond[]
\score {
\notes \relative c'' {
r\longa r\breve
r1 r2 r4 r8 r16 r32 r64 r64
}
\paper {
- loose_column_distance = 2.5 * \interline;
+ loose_column_distance = 2.5 * \staffspace;
linewidth = -1.0;
\translator {
\StaffContext
}
}
}
-@end mudela
+@end lilypond
@end quotation
If the duration is omitted then it is set equal to the previous
assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}')
to obtain dotted note lengths.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
a'4. b'4.
-@end mudela
+@end lilypond
You can alter the length of duration by writing
`@code{*}@var{fraction}' after it. This will not affect the
appearance of note heads or rests.
-Rests are entered like notes, with note name `@code{r}@indexcode{r}',
-or `@code{R}@indexcode{R}'. There is also a note name `@code{s}@indexcode{s}',
-which produces a space of the specified duration.
-`@code{R}' is specifically meant for entering parts: the @code{R} rest
-can expand to fill a score with rests, or it can be printed as a
+Rests are entered like notes, with note name `@code{r}@indexcode{r}', or
+`@code{R}@indexcode{R}'. There is also a note name
+`@code{s}@indexcode{s}', which produces a space of the specified
+duration. `@code{R}' is specifically meant for entering parts: the
+@code{R} rest can expand to fill a score with rests, or it can be
+printed as a single multimeasure rest.
+
+You can control the expansion by setting the property
+@code{Score.skipBars}. If this is set to true, Lily will not expand
+empty measures, and the multimeasure rests automatically adds the
+appropriate number.
+
+Note that there is currently no way to condense multiple rests into a
single multimeasure rest.
+
@cindex lyrics expressions
Syllables are entered like notes, with pitches replaced by text. For
example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each
with quarter note duration. Note that the hyphen has no special
meaning for lyrics, and does not introduce special symbols. See
-section XREF-modes [FIXME] for a description of what is interpreted as
+section @ref{Lexical modes} for a description of what is interpreted as
lyrics.
Spaces can be introduced into a lyric either by using quotes
(`@code{"}') or by using an underscore without quotes: `@code{He_could4
not4}'. All unquoted underscores are converted to spaces. Printing
-lyrics is discussed in section XREF-lyricprint [FIXME].
+lyrics is discussed in section @ref{lyricprint}.
you need to know exactly how the backend works. Example:
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\relative c'' { c4
\context Staff \outputproperty
#(make-type-checker 'Note_head)
#'extra-offset = #'(5.0 . 7.5)
<c8 e g> }
-@end mudela
+@end lilypond
This selects all note heads occurring at current staff level, and sets
the extra-offset of those heads to (5,7.5), shifting them up and
right.
Use of this feature is entirely on your own risk: if you use this, the
-result will depend very heavily on the implentation of the backend,
-which we change unscrupulously.
-
-
+result will depend very heavily on the implementation of the backend,
+which we change regularly and unscrupulously.
@cindex commands
@example
-
@code{\key}@keyindex{key} @var{pitch} @var{type} @code{;}
@end example
@code{\phrygian}@keyindex{phrygian}, and @code{\dorian}@keyindex{dorian}
are also defined.
-@example
-
- @code{\keysignature}@keyindex{keysignature} @var{pitchseq} @code{;}
-@end example
-
-Specify an arbitrary key signature. The pitches from @var{pitch} will
-be printed in the key signature in the order that they appear on the
-list.
-
@example
\mark@keyindex{mark} @var{unsigned};
\mark @var{string};
@end example
-Prints a mark over or under (depending on the
-@code{markDirection}@indexcode{markDirection} property) the staff. You must add
-@code{Mark_engraver}@indexcode{Mark_engraver} to either the Score or Staff context for
+Prints a mark over or under the staff. You must add
+@code{Mark_engraver}@indexcode{Mark_engraver} to the Score context for
this to work.
@node barlines, , , Reference Manual
\bar@keyindex{bar} @var{bartype};
@end example
-This is a request to print a special bar symbol. It replaces the
-regular bar symbol with a special
-symbol. The argument @var{bartype} is a string which specifies the
-kind of bar to print. Options are @code{":|"}
-@cindex "|A@@@code{:|}
-,
-@code{"|:"}
-@cindex "|B@@@code{|:}
-, @code{":|:"}
-@cindex "|C@@@code{:|:}
-,
-@code{"||"}
-@cindex "|D@@@code{||}
-, @code{"|."}
-@cindex "|E@@@code{|.}
-,
-@code{".|"}
-@cindex "|F@@@code{.|}
-, and @code{".|."}
-@cindex "|G@@@code{.|.}
-.
-These produce, respectively, a right repeat, a left repeat, a double
-repeat, a double bar, a start bar, an end bar, and a thick double
-bar. If @var{bartype} is set to @code{"empty"} then nothing is
-printed, but a line break is allowed at that spot.
-
-You are encouraged to use @code{\repeat} for repetitions.
-See section XREF-sec-repeats [FIXME].
+This is a short-cut for doing
+@example
+ \property Score.whichBar = @var{bartype}
+@end example
-
+You are encouraged to use @code{\repeat} for repetitions. See
+@ref{Repeats}, and the documentation of @code{whichBar} in
+@ref{(lilypond-internals)LilyPond context properties}.
@example
-
\time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;}
@end example
-Change the time signature. The default time signature is 4/4.
-The time signature is used to generate bar lines.
+A short-cut for doing
+@example
+ \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
+@end example
+
+See the documentation of @code{timeSignatureFraction}
@example
requests output with 76 quarter notes per minute.
@example
-
\partial@keyindex{partial} @var{duration} @code{;}
@end example
+Short cut for
+
+@example
+ \property Score.measurePosition = @var{length of duration}
+@end example
+
+See the documentation of @code{measurePosition}.
+
@cindex anacrusis
@cindex upstep
-This creates an incomplete measure (anacrusis, upbeat) at the start of
-the music, e.g., `@code{\partial 8*2;}' creates a starting measure
-lasting two eighth notes.
-
@example
@code{|}@indexcode{|}
`@code{|}' is a bar check. Whenever a bar check is encountered during
interpretation, a warning message is issued if it doesn't fall at a
-measure boundary. This can help you finding errors in the input.
-The beginning of the measure will be relocated, so this can also
-be used to shorten measures.
+measure boundary. This can help you finding errors in the input.
+Depending on the value of @code{barCheckNoSynchronize}
+@indexcode{barCheckNoSynchronize} The beginning of the measure will be
+relocated, so this can also be used to shorten measures.
@example
-
\penalty@keyindex{penalty} @var{int} @code{;}
@end example
section [on identifiers] [FIXME].
@example
-
\clef@keyindex{clef} @var{clefname} @code{;}
@end example
-Music expression that sets the current clef. The argument is a
-string which specifies the name of the clef. Several clef names are
-supported. If `@code{_8}' or `@code{^8}' is added to the end of a clef
-name, then the clef lowered or raised an octave will be generated.
-Here are the supported clef names with middle C shown in each
-clef:
-
-@quotation
-
-@mudela[]
-\score {
- \notes {
- \cadenzaOn
- %\property Voice.textStyle = typewriter
- \clef subbass; c'4-"\kern -5mm subbass"
- \clef bass; c'4^"\kern -2mm bass"
- \clef baritone; c'4_"\kern -5mm baritone"
- \clef varbaritone; c'4^"\kern -6mm varbaritone"
- \clef tenor; c'4_"\kern -3mm tenor"
- \clef "G_8"; c'4^"\kern -2mm G\\_8"
- }
- \paper {
- linewidth = -1.0;
- }
-}
-@end mudela
-@end quotation
+Short-cut for
-@quotation
+@example
+ \property Clef.clefGlyph = @var{symbol associated with clefname}
+ \property Clef.clefPosition = @var{clef Y-position for clefname}
+ \property Clef.clefOctavation = @var{extra pitch of clefname}
+@end example
-@mudela[]
-\score {
- \notes {
- \cadenzaOn
- \clef alto; c'4_"\kern -2mm alto"
- \clef mezzosoprano; c'4^"\kern -9mm mezzosoprano"
- \clef soprano; c'4_"\kern -6mm soprano"
- \clef treble; c'4^"\kern -4mm treble"
- \clef french; c'4_"\kern -4mm french"
- }
- \paper {
- linewidth = 4.5 \in;
- }
-}
-@end mudela
-@end quotation
+Supported clef-names include
-The three clef symbols can also be obtained using the names `@code{G}',
-`@code{C}' or `@code{F}', optionally followed by an integer which
-indicates at which note line the clef is located. An as example, the
-@code{mezzosoprano} clef can also be given as `@code{C2}'.
+[todo]
@example
A beam is specified by surrounding the beamed notes with brackets
`@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
[a'8 a'] [a'16 a' a' a']
-@end mudela
+@end lilypond
Some more elaborate constructions:
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
[a'16 <a' c''> c'' <a' c''>]
\times 2/3 { [e'8 f' g'] }
-@end mudela
+@end lilypond
-Beaming can be generated automatically; see section XREF-autobeam [FIXME].
+Beaming can be generated automatically; see section @ref{autobeam}.
-[OUTDATED, FIXME]
-To place tremolo marks
+To place tremolo marks between notes, use @code{\repeat} with tremolo
+style.
@cindex tremolo beams
- between two notes, begin
-with `@code{[:}@var{length}' and end with `@code{]}'. Tremolo marks
-will appear instead of beams. Putting more than two notes in such a
-construction will produce odd effects. To create tremolo beams on a
-single note, simply attach `@code{:}@var{length}' to the note itself
-(see also section XREF-tremolo [FIXME]).
-
-@ignore
-@mu dela[fragment,verbatim,center]
- [:16 e'1 g'] [:8 e'4 f']
-@end mudela
-
-@mud ela[fragment,verbatim,center]
- c'4:32 [:16 c'8 d'8]
-@end mudela
-@end ignore
+To create tremolo beams on a single note, simply attach
+`@code{:}@var{length}' to the note itself.
+
+@lilypond[fragment,verbatim,center]
+ \repeat "tremolo" 8 { c16 d16 }
+ \repeat "tremolo" 4 { c16 d16 }
+@end lilypond
+
+@lilypond[fragment,verbatim,center]
+ c'4:32
+@end lilypond
+
@cindex --@@@code{-}@code{-}
If you try to tie together chords which have no common pitches, a
warning message will appear and no ties will be created.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
e' ~ e' <c' e' g'> ~ <c' e' g'>
-@end mudela
+@end lilypond
respectively. Here is a chart showing symbols above notes, with the
name of the corresponding symbol appearing underneath.
-@mudela[]
+@lilypond[]
\score {
< \notes {
}
}
-@end mudela
+@end lilypond
In addition, it is possible to place arbitrary strings of text or
@TeX{} above or below notes by using a string instead of an
supported) and single characters shorthands exist for a few
common symbols
-@mudela[]
+@lilypond[]
\score {
\notes {
}
}
-@end mudela
+@end lilypond
Dynamic marks are specified by using an identifier after a note:
`@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'.
first note in the slur. This makes it possible to put a note in
slurs from both sides:
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
-@end mudela
+@end lilypond
@cindex crescendo
bound to notes, if you want to get several marks during one note, you
must use spacer notes.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
c'' \< \! c'' d'' \decr e'' \rced
< f''1 { s4 \< \! s2 \> \! s4 } >
-@end mudela
+@end lilypond
@example
You can attach a (general) span request to a note using
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
c'4-\spanrequest \start "slur"
c'4-\spanrequest \stop "slur"
-@end mudela
+@end lilypond
The slur syntax with parentheses is a shorthand for this.
used, or the value of the @code{tremoloFlags}@indexcode{tremoloFlags} property if there was
no last value.
-@mudela[verbatim,fragment,center]
+@lilypond[verbatim,fragment,center]
c'2:8 c':32
-@end mudela
+@end lilypond
expressions any way you like. This simple example shows how three
chords can be expressed in two different ways:
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\notes \context Staff {
\cadenzaOn
<a c'> <b d' > <c' e'>
< { a b c' } { c' d' e' } >
}
-@end mudela
+@end lilypond
@cindex context selection
@c @keyindex{context}
Interpret @var{musicexpr} within a context of type @var{contexttype}.
If the context does not exist, it will be created. The new context
-can optionally be given a name. See
-section XREF-contextselection [FIXME] and XREF-contextdefs [FIXME] for more
-information on interpretation contexts.
-
-
+can optionally be given a name.
@cindex input modes
@var{musicexpr}, and @code{\lyrics} @keyindex{lyrics} @var{musicexpr}.
These expressions do not add anything to the meaning of their
arguments. They are just a way to indicate that the arguments should
-be parsed in indicated mode. See section XREF-modes [FIXME] for more
+be parsed in indicated mode. See @ref{Lexical modes} for more
information on modes.
-More information on context selection can be found in
-section XREF-contextselection [FIXME].
-
-
-
@cindex sequential music
If you try to use a chord as the first thing in your score, you might
get multiple staffs instead of a chord.
-@mudela[verbatim,center]
+@lilypond[verbatim,center]
\score {
\notes <c''4 e''>
\paper {
linewidth = -1.;
}
}
-@end mudela
+@end lilypond
This happens because the chord is interpreted by a score context.
Each time a note is encountered a default Voice context (along with a
Staff context) is created. The solution is to explicitly instantiate
a Voice context:
-@mudela[verbatim,center]
+@lilypond[verbatim,center]
\score {
\notes\context Voice <c''4 e''>
\paper {
linewidth = -1.;
}
}
-@end mudela
+@end lilypond
Entering scales is straightforward in relative mode.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\relative c' {
c d e f g a b c c,
}
-@end mudela
+@end lilypond
And octave changing marks are used for intervals greater than a fourth.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\relative c'' {
c g c f, c' a, e'' }
-@end mudela
+@end lilypond
If the preceding item is a chord, the first note of the chord is used
to determine the first note of the next chord. But other notes
within the second chord are determined by looking at the immediately
preceding note.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\relative c' {
c <c e g>
<c' e g>
<c, e' g>
}
-@end mudela
+@end lilypond
The pitch after the @code{\relative} contains a notename. To parse
the pitch as a notename, you have to be in note mode, so there must
Chord names are a way to generate simultaneous music expressions that
correspond with traditional chord names. It can only be used in
-Chord mode (see section XREF-modes [FIXME]).
+Chord mode (see section @ref{Lexical modes}).
@example
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\transpose c'' {
\chords {
c1 c:3- c:7 c:8
}
}
-@end mudela
+@end lilypond
@end quotation
The second type of modifier that may appear after the `@code{:}' is a
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\transpose c'' {
\chords {
c1:m c:min7 c:maj c:aug c:dim c:sus
}
}
-@end mudela
+@end lilypond
@end quotation
notes to be subtracted are listed after a `@code{^}' character,
separated by dots.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\transpose c'' {
\chords {
c1^3 c:7^5.3 c:8^7
}
}
-@end mudela
+@end lilypond
Chord inversions can be specified by appending `@code{/}@indexcode{/}' and
the name of a single note to a chord. This has the effect of
note in the chord. If the specified note is not in the chord, a
warning will be printed.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\transpose c''' {
\chords {
c1 c/e c/g c:7/e
}
}
-@end mudela
+@end lilypond
Bass notes can be added by `@code{/+}@indexcode{/+}' and
the name of a single note to a chord. This has the effect of
adding the specified note to the chord, lowered by an octave,
so it becomes the lowest note in the chord.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\transpose c''' {
\chords {
c1 c/+c c/+g c:7/+b
}
}
-@end mudela
+@end lilypond
Throughout these examples, chords have been shifted around the staff
using @code{\transpose}.
which 3 notes have the length of 2, so the notes are 2/3 of
their written length:
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
g'4 \times 2/3 {c'4 c' c'} d'4 d'4
-@end mudela
+@end lilypond
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\relative c'' {
\grace c8 c4 \grace { [c16 c16] } c4
\grace { \property Grace.flagStyle = "" c16 } c4
}
-@end mudela
+@end lilypond
@end quotation
At present, nesting @code{\grace}@keyindex{grace} notes, e.g.
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
c'1
\repeat volta 2 { c'4 d' e' f' }
\repeat volta 2 { f' e' d' c' }
-@end mudela
+@end lilypond
@end quotation
With alternative endings:
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
c'1
\repeat volta 2 {c'4 d' e' f'}
\alternative { {d'2 d'} {f' f} }
-@end mudela
+@end lilypond
@end quotation
Folded repeats look like this:@footnote{Folded repeats offer little
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
c'1
\repeat fold 2 {c'4 d' e' f'}
\alternative { {d'2 d'} {f' f} }
-@end mudela
+@end lilypond
@end quotation
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\context Staff {
\relative c' {
\partial 4;
}
}
-@end mudela
+@end lilypond
@end quotation
If you don't give enough alternatives for all of the repeats, then
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\context Staff {
\relative c' {
\repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | }
}
}
-@end mudela
+@end lilypond
@end quotation
It is possible to nest @code{\repeat}. This is not entirely
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\context Staff {
\clef "F";
{ \key e \major; c d e f }
\transpose cis'' { \key e \major; c d e f }
}
-@end mudela
+@end lilypond
@end quotation
If you want to use both @code{\transpose} and @code{\relative}, then
@quotation
-@mudela[verbatim,fragment]
+@lilypond[verbatim,fragment]
\addlyrics
\transpose c'' {
\property Voice.automaticMelismata = ##t
\context Lyrics \lyrics {
do4 re mi fa }
-@end mudela
+@end lilypond
@end quotation
You should use a single rhythm melody, and single rhythm lyrics (a
@quotation
-@mudela[verbatim,fragment]
+@lilypond[verbatim,fragment]
\addlyrics
\transpose c'' {
c8 () cis d8. e16 f2
< { do4 re mi fa }
{ do8 re mi fa } >
-@end mudela
+@end lilypond
@end quotation
It is valid (but probably not very useful) to use notes instead of
@node autobeam, , , Reference Manual
+[FIXME: UPDATEME]
+
By default, LilyPond will generate beams automatically. This feature
-can be disabled by setting the @code{Voice.noAutoBeaming}@indexcode{Voice.noAutoBeaming}
-property to 1. It can be overridden for specific cases by
-specifying explicit beams as described in
-section XREF-manualbeam [FIXME].
+can be disabled by setting the
+@code{Voice.noAutoBeaming}@indexcode{Voice.noAutoBeaming} property to 1.
+It can be overridden for specific cases by specifying explicit beams.
A large number of Voice properties are used to decide how to generate
-beams. Their default values appear in @file{auto-beam-settings.ly}.
-In general, beams can begin anywhere, but their ending location is
-significant. Beams can end on a beat, or at durations specified by
-the @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} property. To end beams every
-quarter note, for example, you could set
-@code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} equal to `@code{"1/4"}'. To end beams
-at every three eighth notes you would set it to `@code{"3/8"}'. The
-same syntax can be used to specify beam starting points using
+beams. Their default values appear in @file{auto-beam-settings.ly}. In
+general, beams can begin anywhere, but their ending location is
+significant. Beams can end on a beat, or at durations specified by the
+@code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} property. To end
+beams every quarter note, for example, you could set
+@code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} equal to
+`@code{"1/4"}'. To end beams at every three eighth notes you would set
+it to `@code{"3/8"}'. The same syntax can be used to specify beam
+starting points using
@code{Voice.beamAutoBegin}@indexcode{Voice.beamAutoBegin}.
To allow different settings for different time signatures, these
property names can start with `@code{time}@var{N}@code{_}@var{M}' to
restrict the definition to `@var{N}@code{/}@var{M}' time. For example,
-to specify beams ending only for 6/8 time you would use the
-property @code{Voice.time6_8beamAutoEnd}. To allow different endings
-for notes of different durations, the duration can be tacked onto the
-end of the property. To specify beam endings for beams that contain
-32nd notes, you would use @code{Voice.beamAutoEnd_32}.
+to specify beams ending only for 6/8 time you would use the property
+@code{Voice.time6_8beamAutoEnd}. To allow different endings for notes
+of different durations, the duration can be tacked onto the end of the
+property. To specify beam endings for beams that contain 32nd notes,
+you would use @code{Voice.beamAutoEnd_32}.
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
<
\context ChordNames {
\chords{a b c} \notes{<d f g> <e g b>}
}
>
-@end mudela
+@end lilypond
@end quotation
LilyPond examines chords specified as lists of notes to determine a
name to give the chord. By default, LilyPond will not try to
identify chord inversions:
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
<
\context ChordNameVoice \notes {
<e'1 g' c''>
<e'1 g' c''>
}
>
-@end mudela
+@end lilypond
If you want inversions to be recognized, you must set the property
@code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}:
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
<
\property Score.chordInversion = ##t
\context ChordNameVoice \notes {
<e'1 g' c''>
}
>
-@end mudela
+@end lilypond
@quotation
-@mudela[verbatim]
+@lilypond[verbatim]
\score {
<
\notes \transpose c'' {
>
}
-@end mudela
+@end lilypond
@end quotation
You may want a continuous line after the syllables to show melismata.
@quotation
-@mudela[verbatim]
+@lilypond[verbatim]
\score {
<
\notes \relative c'' {
>
}
-@end mudela
+@end lilypond
@end quotation
@quotation
-@mudela[verbatim]
+@lilypond[verbatim]
\score {
<
\notes \transpose c'' {
>
}
-@end mudela
+@end lilypond
@end quotation
expression; it contains information like
@itemize @bullet
- @item What notes are playing at this point?
- @item What symbols will be printed at this point?
- @item In what style will they printed?
- @item What is the current key signature, time signature, point within
+ @item What notes are playing at this point?
+ @item What symbols will be printed at this point?
+ @item In what style will they printed?
+ @item What is the current key signature, time signature, point within
the measure, etc.?
@end itemize
@quotation
-@mudela[verbatim]
+@lilypond[verbatim]
\score {
\notes \relative c'' {
c4 <d4 \context Staff = "another" e4> f
}
}
-@end mudela
+@end lilypond
@end quotation
In this example, the @code{c} and @code{d} are printed on the
doesn't result in this:
-@mudela[]
+@lilypond[]
\score {
\notes \relative c'' {
}
}
-@end mudela
+@end lilypond
For the @code{c4}, a default @code{Staff} (with a contained
@code{Voice}) context is created. After the @code{c4} ends, no
The @code{d4} gets interpreted in the same context
as @code{c4}.
-
-
-These are the contexts supplied with the package. They are defined
-in the initialization file @file{ly/engraver.ly}.
-
-@table @samp
- @item @code{Grace}@indexcode{Grace}
- The context for handling grace notes. It is instantiated
- automatically when you use @code{\grace}. Basically, it is an
- `embedded' miniature of the Score context. Since this context
- needs special interaction with the rest of LilyPond, you should
- not explicitly instantiate it.
-
- @item @code{LyricVoice}@indexcode{LyricVoice}
- Corresponds to a voice with lyrics. Handles the printing of a
- single line of lyrics.
-
- @item @code{Thread}@indexcode{Thread}
- Handles note heads, and is contained in the Voice context. You
- have to instantiate this explicitly if you want to adjust the
- style of individual note heads.
-
- @item @code{Voice}@indexcode{Voice}
- Corresponds to a voice on a staff. This context handles the
- conversion of dynamic signs, stems, beams, super- and subscripts,
- slurs, ties, and rests.
-
- You have to instantiate this explicitly if you want to have
- multiple voices on the same staff.
-
- @item @code{ChordNamesVoice}@indexcode{ChordNamesVoice}
- A voice with chord names. Handles printing of a line of chord
- names.
-
- @item @code{ChordNames}@indexcode{ChordNames}
- Typesets chord names. Can contain @code{ChordNamesVoice}
- contexts.
-
- @item @code{Lyrics}@indexcode{Lyrics}
- Typesets lyrics. It can contain @code{LyricVoice} contexts.
-
- @item @code{Staff}@indexcode{Staff}
- Handles clefs, bar lines, keys, accidentals. It can contain
- @code{Voice} contexts.
-
- @item @code{RhythmicStaff}@indexcode{RhythmicStaff}
- A context like @code{Staff} but for printing rhythms. Pitches are
- ignored; the notes are printed on one line. It can contain
- @code{Voice} contexts.
-
- @item @code{GrandStaff}@indexcode{GrandStaff}
- Contains @code{Staff} or @code{RhythmicStaff} contexts. It adds a
- brace on the left side, grouping the staffs together. The bar
- lines of the contained staffs are connected vertically. It can
- contain @code{Staff} contexts.
-
- @item @code{PianoStaff}@indexcode{PianoStaff}
- Just like @code{GrandStaff} but with @code{minVerticalAlign} set
- equal to @code{maxVerticalAlign} so that interstaff beaming and
- slurring can be used.
-
- @item @code{StaffGroup}@indexcode{StaffGroup}
- Contains @code{Staff} or @code{RhythmicStaff} contexts. Adds a
- bracket on the left side, grouping the staffs together. The bar
- lines of the contained staffs are connected vertically. It can
- contain @code{Staff}, @code{RhythmicStaff}, @code{GrandStaff}, or
- @code{Lyrics} contexts.
-
- @item @code{ChoirStaff}@indexcode{ChoirStaff}
- Identical to @code{StaffGroup} except that the contained staffs
- are not connected vertically.
-
- @item @code{Score}@indexcode{Score}
- This is the top level notation context. No other context can
- contain a @code{Score} context. This context handles the
- administration of time signatures. It also makes sure that items
- such as clefs, time signatures, and key-signatures are aligned
- across staffs. It can contain @code{Lyrics}, @code{Staff},
- @code{RhythmicStaff}, @code{GrandStaff}, @code{StaffGroup}, and
- @code{ChoirStaff} contexts.
-
- You cannot explicitly instantiate a Score context (since it is
- not contained in any other context). It is instantiated
- automatically when an output definition (a @code{\score} or
- @code{\paper} block) is processed.
-@end table
-
-
-
Properties that are set in one context are inherited by all of the
contained contexts. This means that a property valid for the
@code{Voice} context can be set in the @code{Score} context (for
is
@example
-
@var{propname} @code{=} @var{value}
@end example
This assignment happens before interpretation starts, so a
@code{\property} expression will override any predefined settings.
-The @code{\property} expression will create any property you specify.
-There is no guarantee that a property will be used. So if you spell
-a property name wrong, there will be no error message.
-
The property settings are used during the interpretation phase. They
are read by the LilyPond modules where interpretation contexts are
built of. These modules are called @emph{translators}. Translators for
notation are called @emph{engravers}, and translators for sound are
called @emph{performers}.
-The precise result of a property is determined by the implementation
-of the translator that reads them. Therefore, the result of a
-property can vary, since it is implementation and configuration
-dependent.
-
-In order to fully find out what properties are used, you must
-currently search the source code for calls to @code{get_property}.
-The rest of the section is devoted to an (incomplete) overview of
-available properties.
-
@mbinclude properties.itely
-@node Notation output definitions, , , Reference Manual
-@section Notation output definitions
-
-@cindex output
-
-@cindex notation output
-
-@cindex output definition
+@node Page layout, , , Reference Manual
-@node paper, , , Reference Manual
+@subsection Paper block
The most important output definition is the @code{\paper} block, for
music notation. The syntax is
@example
-
@code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
@end example
@itemize @bullet
@item An assignment. The assignment must be terminated by a
- semicolon. See section XREF-papervars [FIXME] for information on
- paper variables.
+ semicolon.
- @item A context definition. See section XREF-contextdefs [FIXME] for
+ @item A context definition. See section @ref{contextdefs} for
more information on context definitions.
- @item
- FIXME now in SCM
+@ignore
+
+ FIXME
+
+ @item
+
A margin shape declaration. The syntax is
@example
the successive pairs of dimensions. The last pair of
dimensions will define the characeristics of all lines beyond
those explicitly specified.
+@end ignore
- @item A font declaration. Its syntax is
-
+ @item \stylesheet declaration. Its syntax is
@example
-
- @var{fontsize} @code{=} \font@keyindex{font} @var{fontname}
+ \stylesheet @var{alist}
@end example
- @var{fontsize} is an integer describing the font to be used.
- 0 is the default font. @var{fontname} is the basename of
- a font (usually a member of the Feta family).
+ See @file{font.scm} for details of @var{alist}.
@end itemize
+@subsection Paper variables
-@cindex changing font size and paper size
-The Feta font provides musical symbols at six different sizes. These
-fonts are 11 point, 13 point, 16 point, 20 point,
-23 point, and 26 point. The point size of a font is the
-height of the five lines in a staff when displayed in the font.
-
-Definitions for these sizes are the files @file{paperSZ.ly}, where
-@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include
-any of these files, the identifiers @code{paper_eleven},
-@code{paper_thirteen}, @code{paper_sixteen}, @code{paper_twenty},
-@code{paper_twentythree}, and @code{paper_twentysix} are defined
-respectively. The default @code{\paper} block is also set.
-
-To change the paper size, you must first set the
-@code{papersize}@indexcode{papersize} variable at top level. Set it to the strings
-@code{a4}, @code{letter}, or @code{legal}. After this specification,
-you must set the font as described above. If you want the default
-font, then use the 20 point font. The new paper size will not
-take effect if the font is not loaded and selected afterwards. Paper
-size selection works by loading a file named after the paper size you
-select.
-
-
-
-@cindex paper variables
-
-@node Paper variables, , , Reference Manual
-
-There is a large number of paper variables that are used to control
-details of the layout. These variables control the defaults for the
-entire score. Usually, they do not have to be changed; they are by
-default set to values that depend on the font size in use. The
-values are used by the graphic objects while formatting the score;
-they are therefore implementation dependent. Most variables are
-accompanied by documentation in the initalization file
-@file{params.ly} or @file{paperSZ.ly}, where @code{SZ} is the staff
-height in points.
-
-Nevertheless, here are some variables you may want to use or change:
+The paper block has some variables you may want to use or change:
@table @samp
@item @code{indent}@indexcode{indent}
The indentation of the first line of music.
- @item @code{interline}@indexcode{interline}
+ @item @code{staffspace}@indexcode{staffspace}
The distance between two staff lines, calculated from the center
of the lines. You should use either this or @code{rulethickness}
as a unit for distances you modify.
@item @code{interscoreline}@indexcode{interscoreline}
Sets the spacing between the score lines. Defaults to 16 pt.
- @item @code{output}@indexcode{output}
- Specifies an alternate name for the the output @file{s}.
- A @file{.tex}, @file{.midi} or @file{.ps} extension will be
- added to the string you specify.
+ @item @code{interscorelinefill}@indexcode{interscorelinefill}
+ If set to a positive number, the distance between the score
+ lines will stretch in order to fill the full page. In that
+ case @code{interscoreline} specifies the minimum spacing.
+ Defaults to 0.
- @item @code{rulethickness}@indexcode{rulethickness}
- Determines the thickness of staff and bar lines.
+ @item @code{stafflinethickness}@indexcode{stafflinethickness}
+ Determines the thickness of staff lines, and also acts as a scaling
+ parameter for other line thicknesses.
@end table
+@subsection Line breaks
+
+@cindex line breaks
+@cindex breaking lines
+
+Line breaks are normally computed automatically. They are chosen such
+that the resulting spacing has low variation, and looks neither cramped
+nor loose.
+
+Occasionally you might want to override the automatic breaks; you can do
+this by specifying @code{\break} (see also @ref{Pre-defined
+Identifiers}). This will force a line break at this point. Do remember
+that line breaks can only occur at places where there are barlines. If
+you want to have a line break where there is no barline, you can force a
+barline by entering @code{\bar "";}.
+
+@subsection Page breaks
+
+Page breaks are normally computed by @TeX{}, so they are not under direct
+control. However, you can insert a commands into the .tex output to
+instruct @TeX{} where to break pages. For more details, see the
+example file @file{input/test/between-systems.ly}
+
+
+@cindex page breaks
+@cindex breaking pages
+
+
+@subsection Font size
+
+@cindex font size
+@cindex paper size
+
+The Feta font provides musical symbols at six different sizes. These
+fonts are 11 point, 13 point, 16 point, 20 point,
+23 point, and 26 point. The point size of a font is the
+height of the five lines in a staff when displayed in the font.
+
+Definitions for these sizes are the files @file{paperSZ.ly}, where
+@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
+these files, the identifiers @code{paperEleven}, @code{paperThirteen},
+@code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
+@code{paperTwentysix} are defined respectively. The default
+@code{\paper} block is also set.
+
+The font definitions are generated using a Scheme function. For more
+details, see the file @file{font.scm}.
+
+@subsection paper size
+
+@cindex paper size
+@cindex page size
+
+To change the paper size, you must first set the
+@code{papersize}@indexcode{papersize} variable at top level. Set it to
+the strings @code{a4}, @code{letter}, or @code{legal}. After this
+specification, you must set the font as described above. If you want
+the default font, then use the 20 point font. The new paper size will
+not take effect if the font is not loaded and selected afterwards.
+
+@example
+ papersize = "a4"
+ \include "paper16.ly"
+
+ \score @{
+ ...
+ \paper @{ \paperSixteen @}
+ @}
+@end example
+
+The file "paper16.ly" will now include a file named @file{a4.ly}, which
+will set the paper variables @code{hsize} and @code{vsize} (used by
+@code{ly2dvi})
+
@node contextdefs, , , Reference Manual
@cindex context definition
+@cindex translator definition
+@cindex engraver hacking
+
A notation contexts is defined by the following information
@itemize @bullet
@item @code{\consists} @var{engravername} @code{;}
Add @var{engravername} to the list of modules in this context.
- Section XREF-engravers [FIXME] contains an overview of the engravers
- available. The order of engravers added with @code{\consists} is
+ The order of engravers added with @code{\consists} is
significant.
@item @code{\consistsend} @var{engravername} @code{;}
@item @code{\accepts} @var{contextname} @code{;}
Add @var{contextname} to the list of context this context can
- contain. The first listed context the context to create by
+ contain. The first listed context is the context to create by
default.
+
+ @item @code{\denies}. The opposite of @code{\accepts}. Added for
+completeness, but is never used in practice.
+
@item @code{\remove} @var{engravername} @code{;}
Remove a previously added (with @code{\consists}) engraver.
@end quotation
-
-@node engravers, , , Reference Manual
-
-The engravers for paper output are:
-
-[incomplete, FIXME]
-
-@table @samp
- @item @code{Bar_engraver}@indexcode{Bar_engraver}
- Engraves bar lines. Normally in @code{Staff} and
- @code{RhythmicStaff}.
-
- @item @code{Bar_number_engraver}@indexcode{Bar_number_engraver}
- Engrave bar numbers. These numbers appear at the start of each
- line. Not normally in any translator. Can be added to
- @code{Score} for score-wide numbering or to @code{Staff} for
- numbering on each staff.
-
- @item @code{Beam_engraver}@indexcode{Beam_engraver}
- Handles beam requests by engraving beams. Normally appears in
- the @code{Voice} translator. If omitted, then notes will be
- printed with flags instead of beams.
-
- @item @code{Beam_req_swallow_translator}
- @indexcode{Beam_req_swallow_translator}
- Swallows beam requests. In @code{LyricVoice}.
-
- @item @code{Chord_name_engraver}@indexcode{Chord_name_engraver}
- Engraves chord names. Normally in @code{ChordNameVoice} .
-
- @item @code{Chord_tremolo_engraver}@indexcode{Chord_tremolo_engraver}
-
- @item @code{Clef_engraver}@indexcode{Clef_engraver}
- Engraves the clef symbol. Normally in @code{Staff}.
-
- @item @code{Collision_engraver}@indexcode{Collision_engraver}
-
- @item @code{Dot_column_engraver}@indexcode{Dot_column_engraver}
- Engraves dots on dotted notes shifted to the right of the note.
- Normally in @code{Voice}. If omitted, then dots appear on top of
- the notes.
-
- @item @code{Dynamic_engraver}@indexcode{Dynamic_engraver}
- Engraves dynamics symbols. Normally in @code{Voice}.
-
- @item @code{Font_size_engraver}@indexcode{Font_size_engraver}
-
- @item @code{Key_engraver}@indexcode{Key_engraver}
- Engraves the key signature. Normally in @code{Staff}.
-
- @item @code{Local_key_engraver}@indexcode{Local_key_engraver}
-
- @item @code{Lyric_engraver}@indexcode{Lyric_engraver}
- Engraves lyrics. Normally in @code{LyricVoice}.
-
- @item @code{Multi_measure_rest_engraver}
- @indexcode{Multi_measure_rest_engraver}
- Engraves multi-measure rests that are produced with @code{R}.
- Normally in @code{Voice}.
-
- @item @code{Piano_bar_engraver}@indexcode{Piano_bar_engraver}
-
- @item @code{Pitch_squash_engraver}@indexcode{Pitch_squash_engraver}
- Treat all pitches as middle C. Used in @code{RhythmicStaff}.
- Note that the notes move, but the locations of accidentals stay
- the same.
-
- @item @code{Priority_horizontal_align_engraver}
- @indexcode{Priority_horizontal_align_engraver}
-
- @item @code{Repeat_engraver}@indexcode{Repeat_engraver}
- Handles repeats? In @code{Staff} and @code{RhythmicStaff}.
-
- @item @code{Rest_collision_engraver}@indexcode{Rest_collision_engraver}
- Handles collisions of rests. In @code{Staff}.
-
- @item @code{Rest_engraver}@indexcode{Rest_engraver}
- Engraves rests. Normally in @code{Voice}.
-
- @item @code{Rhythmic_column_engraver}@indexcode{Rhythmic_column_engraver}
-
- @item @code{Score_priority_engraver}@indexcode{Score_priority_engraver}
-
- @item @code{Script_engraver}@indexcode{Script_engraver}
- Handles note ornaments generated by @code{\script}. Normally in
- @code{Voice}.
-
- @item @code{Separating_line_group_engraver}
- @indexcode{Separating_line_group_engraver}
-
- @item @code{Skip_req_swallow_translator}
- @indexcode{Skip_req_swallow_translator}
-
- @item @code{Slur_engraver}@indexcode{Slur_engraver}
- Engraves slurs. Normally in @code{Voice}.
-
- @item @code{Span_bar_engraver}@indexcode{Span_bar_engraver}
- Engraves lines across multiple staffs. Normally in
- @code{Staffgroup} and @code{GrandStaff}. Removing this from
- @code{StaffGroup} gives the definition of @code{ChoirStaff}.
-
- @item @code{Span_score_bar_engraver}@indexcode{Span_score_bar_engraver}
-
- @item @code{Staff_group_bar_engraver}@indexcode{Staff_group_bar_engraver}
-
- @item @code{Instrument_name_engraver}@indexcode{Instrument_name_engraver}
- Prints the name of the instrument (specified by
- @code{Staff.instrument} and @code{Staff.instr}) at the left of the
- staff.
-
- @item @code{Staff_sym_engraver}@indexcode{Staff_sym_engraver}
-
- @item @code{Stem_engraver}@indexcode{Stem_engraver}
- Engraves stems. Normally in @code{Voice}.
-
- @item @code{Ties_engraver}@indexcode{Ties_engraver}
- Engraves ties. Normally in @code{Voice}.
-
- @item @code{Time_signature_engraver}@indexcode{Time_signature_engraver}
- Engraves the time signature. Normally in @code{Staff} and
- @code{RhythmicStaff}.
-
- @item @code{Timing_engraver}@indexcode{Timing_engraver}
- Responsible for synchronizing timing information from staffs.
- Normally in @code{Score}. In order to create polyrhythmic music,
- this engraver should be removed from @code{Score} and placed in
- @code{Staff}.
-
- @item @code{Tuplet_engraver}@indexcode{Tuplet_engraver}
- Engraves tuplet brackets? In @code{Staff}.
-
- @item @code{Vertical_align_engraver}@indexcode{Vertical_align_engraver}
-@end table
-
-
-
@node Sound output, , , Reference Manual
@section Sound output
-
-
-The MIDI block is analogous to the paper block, but it is simpler.
-The @code{\midi} block can contain:
+The MIDI block is analogous to the paper block, but it is somewhat
+simpler. The @code{\midi} block can contain:
@cindex MIDI block
@itemize @bullet
@c @end quotation
-@cindex MIDI types and performers
-
-The types available for MIDI translators are:
-
-@table @samp
- @item @code{Performer_group_performer}@indexcode{Performer_group_performer}
- @item @code{Score_performer}@indexcode{Score_performer}
- @item @code{Staff_performer}@indexcode{Staff_performer}
-@end table
-
-The performers for MIDI translators are:
-
-@table @samp
- @item @code{Key_performer}@indexcode{Key_performer}
- @item @code{Time_signature_performer}@indexcode{Time_signature_performer}
- @item @code{Note_performer}@indexcode{Note_performer}
- @item @code{Lyric_performer}@indexcode{Lyric_performer}
- @item @code{Swallow_performer}@indexcode{Swallow_performer}
-@end table
-
-
@node Pre-defined Identifiers, , , Reference Manual
Various identifiers are defined in the initialization files to
provide shorthands for some settings. Most of them are in
-@file{ly/declarations.ly}.
+@file{ly/declarations.ly} and @file{ly/property.ly}.
@table @samp
@item @code{\break}@keyindex{break}
Force a line break in music by using a large argument for the
keyword @code{\penalty}.
- @item @code{\center}@keyindex{center}
- Used for setting direction properties. Equals 0.
-
- @item @code{\down}@keyindex{down}
- Used for setting direction setting properties. Is equal
- to -1.
-
- @item @code{\free}@keyindex{free}
- Used for setting direction setting properties. Is equal
- to 0.
-
- @item @code{\left}@keyindex{left}
- Used for setting text alignment property. Is equal to -1.
-
@item @code{\nobreak}@keyindex{nobreak}
Prevent a line break in music by using a large negative argument
for the keyword @code{\penalty}.
- @item @code{\none}@keyindex{none}
- Used for setting @code{Score.beamslopedamping} and
- @code{Score.beamquantisation} properties. Is equal to 0.
-
- @item @code{\normal}@keyindex{normal}
- Used for setting @code{Score.beamslopedamping} and
- @code{Score.beamquantisation} properties. Is equal to 1.
-
- @item @code{\normalkey}@keyindex{normalkey}
- Select normal key signatures where each octave has the same key
- signature. This sets the @code{Staff.keyoctaviation} property.
+ @item @code{\shiftOff}@keyindex{shiftOff}
+ Disable horizontal shifting of note heads that collide.
- @item @code{\right}@keyindex{right}
- Used for setting text alignment property. Is set to 1.
-
- @item @code{\shiftoff}@keyindex{shiftoff}
- Disable horizontal shifting of note heads that collide. Sets the
- @code{Voice.horizontalNoteShift} property.
-
- @item @code{\shifton}@keyindex{shifton}
+ @item @code{\shiftOn}@keyindex{shiftOn}
Enable note heads that collide with other note heads to be
- shifted horiztonally. Sets the @code{Voice.horizontalNoteShift}
- property.
-
- @item @code{\slurboth}@keyindex{slurboth}
- Allow slurs to be above or below notes. This sets the
- @code{Voice.slurVerticalDirection} property.
-
- @item @code{\slurdown}@keyindex{slurdown}
- Force slurs to be below notes. This sets the
- @code{Voice.slurVerticalDirection} property.
+ shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
+set different shift values.
- @item @code{\slurup}@keyindex{slurup}
- Force slurs to be above notes. This sets the
- @code{Voice.slurVerticalDirection} property.
-
- @item @code{\specialkey}@keyindex{specialkey}
- Allow key signatures do differ in different octaves. This sets
- the @code{Staff.keyoctaviation} property.
-
- @item @code{\stemboth}@keyindex{stemboth}
+ @item @code{\stemBoth}@keyindex{stemBoth}
Allow stems, beams, and slurs to point either upwards or
- downwards, decided automatically by LilyPond. This sets the
- @code{Voice.verticalDirection} property.
+ downwards, decided automatically by LilyPond.
@item @code{\stemdown}@keyindex{stemdown}
- Force stems, beams, and slurs to point down. This sets the
- @code{Voice.verticalDirection} property.
+ Force stems, beams, and slurs to point down.
- @item @code{\stemup}@keyindex{stemup}
- Force stems, beams and slurs to point up. This sets the
- @code{Voice.verticalDirection} property.
+ @item @code{\stemUp}@keyindex{stemUp}
+ Force stems, beams and slurs to point up.
- @item @code{\traditional}@keyindex{traditional}
- Used for setting the @code{Score.beamquantisation} property. Is
- equal to 2.
-
- @item @code{\up}@keyindex{up}
- Used for setting various direction properties. Is equal
- to 1.
@end table
+
projects / lilypond.git / blobdiff