+@c -*-texinfo-*-
@c TODO:
@c - Reinsert subsection commands that were lost in the
@c ancient conversion from YODL! /MB
@c - Restructure! Separate internal commands from user level commands. /MB
@c - Add some words about Guile. /MB
@c - Fix indexing (keyindex) so it doesn't add line breaks /MB
+@c
+@c FIXME: Index has two alphabetically sorted lists @code vs plain?
+@c
+@c If we'd include the auto-generated documentation, we 'd get a lot of
+@c very useful index entries.
+@c
-@node Reference Manual, , , Top
-@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
-@c should include backend doco
-@c * engravers:: engravers
-* Sound output:: Sound output
-* midilist:: midilist
-* Pre-defined Identifiers:: Pre-defined Identifiers
-@end menu
+@node Reference Manual
@chapter Reference Manual
+@menu
+* 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
+* Automatic Beaming:: Automatic Beaming
+* Chord Names:: Chord Names
+* 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
+* Interpretation contexts:(lilypond-internals)LilyPond interpretation contexts.
+* Engravers:(lilypond-internals)LilyPond engravers.
+* Backend:(lilypond-internals)LilyPond backend.
+@end menu
-@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.}
+@node Overview
+@section Overview
-@emph{Mudela} is a language that allows you to
-@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
+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.
-@emph{Mudela} aims to define a piece of music completely, both from
-typesetting and from a performance point of view.
+LilyPond input can be classified into three types:
+@itemize @bullet
+ @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).
+ @item declarations: by declaring and naming musical expressions, you
+can enter and edit them in manageable chunks.
+@end itemize
-@node Top level, , , Reference Manual
+@node Top level
@section Top level
-@cindex top level
-
This section describes what you may enter at top level.
@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 Pitch names
+@section Pitch names
-@node notenames, , , Reference Manual
-Note name tables can be specified using
+@cindex pitch names
+@cindex note names
+@cindex chord modifier names
+Note names and chord modifiers can be customised for nationalities.
+languages and conventions. The syntax is as follows.
@example
- \notenames@keyindex{notenames}
- @{ @var{assignmentlist} @}
+ \pitchnames@keyindex{pitchnames} @var{scheme-alist}
+ \chordmodifiers@keyindex{chordmodifiers} @var{scheme-alist}
@end example
-@var{assignmentlist} is a list of definitions of the form
-
-@example
- @var{name} = @var{pitch}
-@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
+section @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
- #@var{scheme}
-@end example
-
-Evaluates the specified Scheme code. The result is discarded.
-
Identifier assignments may appear at top level. Semicolons are
forbidden after top level assignments.
+@cindex assignments
-
-@node Lexical conventions, , , Reference Manual
+@node Lexical conventions
@section Lexical conventions
@cindex lexical conventions
+@unnumberedsubsec Comments
@cindex comment
@indexcode{%}
-
A one line comment is introduced by a `@code{%}' character.
Block comments are started by `@code{%@{}' and ended by `@code{%@}}'.
They cannot be nested.
+@unnumberedsubsec Scheme
+@indexcode{#}
-@cindex keyword
+LilyPond contains a Scheme interpreter (the GUILE library) for
+internal use. The interpreter is accessed by the pound sign:
-Keywords start with a backslash, followed by a number of lower case
-alphabetic characters. These are all the keywords.
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
-[FIXME]
+Whereever the syntax allows Scheme expressions, you may enter one as
@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
+ #@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
+
+Keywords start with a backslash, followed by a number of lower case
+alphabetic characters. These are all the keywords.
+
+@example
+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.
+@cindex convert-ly
-
-@cindex other languages
-
-@node Other languages, , , Reference Manual
+@node Other languages
+@section Other languages
+@cindex Note names, international
Note name definitions have been provided in various languages.
Simply include the language specific init file. For example:
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].
-
-
-
-@cindex lexical modes
+Pitch names can be redefined using the @code{\pitchnames} command, see
+@ref{Pitch names}.
+@node Lexical modes
+@section Lexical modes
+@cindex Lexical modes
@cindex modes
-@node 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
+@section Types
+@cindex Identifiers
-@node Types, , , Reference Manual
-@section Types
+[say something about types]
-@cindex types and identifiers
+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,
-@emph{Mudela} has a limited set of 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
+
+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. This is
+not yet user accessible.
+ @item Font_metric: object representing a font. (See @ref{Font metrics})
+@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
+@node Music expressions
@section Music expressions
@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}.
-@node Atomic music expressions, , , Reference Manual
+@node Atomic music expressions
@section Atomic 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
-@cindex note specification
+@node Note specification
+@section Note specification
+@cindex Note specification
@cindex pitches
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.
-
+section @ref{Other languages}.
The optional octave specification takes the form of a series of
single quote (`@code{'}@indexcode{'}') characters or a series of comma
(`@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
+Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
will determine what accidentals to typeset depending on the key and
-context. A reminder accidental
+context. A reminder accidental
@cindex reminder accidental
- can be
-forced by adding an exclamation mark `@code{!}' after the pitch. A
-cautionary accidental,
+can be forced by adding an exclamation mark `@code{!}' after the pitch.
+A cautionary accidental,
@cindex cautionary accidental
- i.e., an
-accidental within parentheses can be obtained by adding the question
-mark `@code{?}@indexcode{?}' after the pitch.
+i.e., an 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
}
}
}
-@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
+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
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
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
+@node barlines
+@section barlines
@example
\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
this has the same effect as the space rest `@code{s}'.
+@node Manual beams
+@section Manual beams
@cindex beams
-@node Manual beams, , , Reference Manual
-
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{Automatic Beaming}.
-[OUTDATED, FIXME]
To place tremolo marks between notes, use @code{\repeat} with tremolo
style.
@cindex tremolo beams
- To create tremolo beams on a single note, simply attach
-`@code{:}@var{length}' to the note itself (see also section
-XREF-tremolo [FIXME]).
-
+To create tremolo beams on a single note, simply attach
+`@code{:}@var{length}' to the note itself.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\repeat "tremolo" 8 { c16 d16 }
\repeat "tremolo" 4 { c16 d16 }
-@end mudela
+@end lilypond
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
c'4:32
-@end mudela
+@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
-
-
-
-[TODO: explain Requests]
-
+@end lilypond
@cindex articulations
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
identifier: `@code{c^"text"}'. Fingerings
@cindex fingering
- can be
-placed by simply using digits. All of these note ornaments appear in
-the printed output but have no effect on the MIDI rendering of the
-music.
+can be placed by simply using digits. All of these note ornaments
+appear in the printed output but have no effect on the MIDI rendering of
+the music.
To save typing, fingering instructions (digits 0 to 9 are
supported) and single characters shorthands exist for a few
common symbols
-@mudela[]
+@lilypond[]
\score {
\notes {
- \property Voice.textStyle = typewriter
+ \property Voice.TextScript \set #'font-style = #'typewriter
c''4-._"c-." s4
c''4--_"c-{}-" s4
c''4-+_"c-+" s4
}
}
-@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})'.
This is equivalent to `@code{c4-6 c4-"foo"}'.
-
@cindex scripts
@example
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.
-
+@node stem tremolo
+@section stem tremolo
@cindex tremolo marks
-@node stem tremolo, , , Reference Manual
-
Tremolo marks can be printed on a single note by adding
`@code{:}[@var{length}]' after the note. The length must be at
least 8. A @var{length} value of 8 gives one line across
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
-@node Compound music expressions, , , Reference Manual
+@node Compound music expressions
@section Compound music expressions
@cindex compound music expressions
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
-@cindex relative pitch specification
-@node relative, , , Reference Manual
+@node relative
+@section relative
+@cindex relative pitch specification
It is easy to get confused by octave changing marks and accidentally
putting a pitch in the wrong octave. A much better way of entering a
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
A grace note expression has duration 0; the next real note is
assumed to be the main note.
+
You cannot have the grace note after the main note, in terms of
duration, and main notes, but you can typeset the grace notes to the
right of the main note using the property
@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.
+@node Repeats
+@section Repeats
@cindex repeats
-@node Repeats, , , Reference Manual
In order to specify repeats, use the @code{\repeat}@keyindex{repeat}
keyword. Since repeats look and sound differently when played or
@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
-@cindex transposition of pitches
-@node transpose, , , Reference Manual
+@node transpose
+@section transpose
+@cindex transposition of pitches
A music expression can be transposed with
@code{\transpose}@keyindex{transpose}. The syntax is
@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 Ambiguities, , , Reference Manual
+@node Ambiguities
@section Ambiguities
@cindex ambiguities
-@node Notation conversion specifics, , , Reference Manual
+@node Notation conversion specifics
@section Notation conversion specifics
-
+@node Automatic Beaming
+@section Automatic Beaming
@cindex automatic beam generation
+@cindex autobeam
-@node autobeam, , , Reference Manual
+@c beamAuto vs autoBeam ?
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.beamAuto}@indexcode{Voice.beamAuto} property to false.
+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
-@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}.
+beams. Their default values appear in @file{scm/auto-beam.scm}. In
+general, beams can begin anywhere, but their ending location is
+significant. Beams can end on a beat, or at durations specified by the
+properties in
+@code{Voice.autoBeamSettings}@indexcode{Voice.autoBeamSettings}.
+To end beams every quarter note, for example, you could set the property
+@code{(end * * * *)} @indexcode{(end * * * *)} to `@code{(make-moment 1
+4)}'. To end beams at every three eighth notes you would set
+it to `@code{(make-moment 1 8)}'.
+The same syntax can be used to specify beam
+starting points using
+@code{(begin * * * *)}@indexcode{(begin * * * *)}, eg:
+@quotation
+@example
+\property Voice.autoBeamSettings \override
+ #'(end * * * *) = #(make-moment 1 4)
+\property Voice.autoBeamSettings \override
+ #'(begin * * * *) = #(make-moment 1 8)
+@end example
+@end quotation
+To allow different settings for different time signatures, instead of
+the first two asterisks @code{* *} you can specify a time signature; use
+@code{(end N 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{(end 6 8 * *)}.
+To allow different endings for notes of different durations, instead of
+th last two asterisks you can specify a duration; use @code{(end * * N
+M)} to restrict the definition to beams that contain notes of
+`@var{N}@code{/}@var{M}' duration.
+
+For example, to specify beam endings for beams that contain 32nd notes,
+you would use @code{(end * * 1 32)}.
-@cindex chord names
+@node Chord Names
+@section Chord Names
+@cindex chord names
@cindex chords
@cindex printing!chord names
-For displaying printed chord names, use the @code{ChordNames}@indexcode{ChordNames}
-and @code{ChordNameVoice}@indexcode{ChordNameVoice} contexts. The chords may be entered
-either using the notation described above, or directly using
-simultaneous music.
+For displaying printed chord names, use the
+@code{ChordNames}@indexcode{ChordNames} and
+@code{ChordNameVoice}@indexcode{ChordNameVoice} contexts. The chords
+may be entered either using the notation described above, or directly
+using simultaneous music.
+
+@quotation
+@lilypond[verbatim]
+scheme = \notes {
+ \chords {a1 b c} <d f g> <e g b>
+}
+\score {
+ \notes<
+ \context ChordNamesVoice \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper { linewidth = -1.; }
+}
+@end lilypond
+@end quotation
+
+You can make the chord changes stand out more by setting property
+@code{ChordNames.chordChanges} to true. This will only display
+chord names when there's a change in the chords scheme, but always
+display the chord name after a line break:
+
+@c bug
@quotation
+@lilypond[verbatim]
+scheme = \chords {
+ c1:m \break c:m c:m c:m d
+}
-@mudela[fragment,verbatim]
-<
- \context ChordNames {
- \chords{a b c} \notes{<d f g> <e g b>}
- }
- \context Staff \notes {
- a b c' d' e'
+\score {
+ \notes <
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper{
+ linewidth = 40 * \staffspace;
+ \translator {
+ \ChordNamesContext
+ chordChanges = ##t
+ }
}
->
-
-@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:
+name to give the chord. LilyPond will not try to
+identify chord inversions or added base, which may result in strange
+chord names when chords are entered as a list of pitches:
-@mudela[fragment,verbatim,center]
+@quotation
+@lilypond[verbatim,center]
+scheme = \notes {
+ <c'1 e' g'>
+ <e' g' c''>
+ <e e' g' c''>
+}
+
+\score {
<
- \context ChordNameVoice \notes {
- <e'1 g' c''>
- }
- \context Thread \notes {
- <e'1 g' c''>
- }
+ \context ChordNamesVoice \scheme
+ \context Staff \scheme
>
-@end mudela
+ \paper { linewidth = -1.; }
+}
+@end lilypond
+@end quotation
-If you want inversions to be recognized, you must set the property
-@code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}:
+To specify chord inversions, append @code{/<notename>}. To specify an
+added bass note, append @code{/+<notename}:
-@mudela[fragment,verbatim,center]
- <
- \property Score.chordInversion = ##t
- \context ChordNameVoice \notes {
- <e'1 g' c''>
- }
- \context Thread \notes {
- <e'1 g' c''>
- }
+@quotation
+@lilypond[verbatim,center]
+scheme = \chords {
+ d1 d/a d/+gis
+}
+
+\score {
+ \notes <
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
>
-@end mudela
+ \paper { linewidth = -1.; }
+}
+@end lilypond
+@end quotation
+The chord names that LilyPond should print are fully customisable. The
+default code can be found in @file{scm/chord-name.scm}. Chord names are
+based on Banter style naming, which is unambiguous and has a logical
+structure. Typical American style chord names are implemented as a
+variation on Banter names, they can be selected by setting poperty
+@code{ChordName.style} to @code{american}:
+@quotation
+@lilypond[verbatim]
+\include "english.ly"
+
+scheme = \chords {
+ c % Major triad
+ cs:m % Minor triad
+ df:m5- % Diminished triad
+ c:5^3 % Root-fifth chord
+ c:4^3 % Suspended fourth triad
+ c:5+ % Augmented triad
+ c:2^3 % "2" chord
+ c:m5-.7- % Diminished seventh
+ c:7+ % Major seventh
+ c:7.4^3 % Dominant seventh suspended fourth
+ c:5+.7 % Augmented dominant seventh
+ c:m5-.7 % "Half" diminished seventh
+ c:5-.7 % Dominant seventh flat fifth
+ c:5-.7+ % Major seventh flat fifth
+ c:m7+ % Minor-major seventh
+ c:m7 % Minor seventh
+ c:7 % Dominant seventh
+ c:6 % Major sixth
+ c:m6 % Minor sixth
+ c:9^7 % Major triad w/added ninth
+ c:6.9^7 % Six/Nine chord
+ c:9 % Dominant ninth
+ c:7+.9 % Major ninth
+ c:m7.9 % Minor ninth
+}
+\score {
+ \notes <
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper {
+ \translator {
+ \ChordNamesContext
+ ChordName \override #'word-space = #1
+ ChordName \override #'style = #'american
+ }
+ }
+}
+@end lilypond
+@end quotation
+
+Similarly, Jazz style chord names are implemented as a variation on
+American style names:
+@quotation
+@lilypond[verbatim]
+scheme = \chords {
+ % major chords
+ c
+ c:6 % 6 = major triad with added sixth
+ c:maj % triangle = maj
+ c:6.9^7 % 6/9
+ c:9^7 % add9
+
+ % minor chords
+ c:m % m = minor triad
+ c:m.6 % m6 = minor triad with added sixth
+ c:m.7+ % m triangle = minor major seventh chord
+ c:3-.6.9^7 % m6/9
+ c:m.7 % m7
+ c:3-.9 % m9
+ c:3-.9^7 % madd9
+
+ % dominant chords
+ c:7 % 7 = dominant
+ c:7.5+ % +7 = augmented dominant
+ c:7.5- % 7b5 = hard diminished dominant
+ c:9 % 7(9)
+ c:9- % 7(b9)
+ c:9+ % 7(#9)
+ c:13^9.11 % 7(13)
+ c:13-^9.11 % 7(b13)
+ c:13^11 % 7(9,13)
+ c:13.9-^11 % 7(b9,13)
+ c:13.9+^11 % 7(#9,13)
+ c:13-^11 % 7(9,b13)
+ c:13-.9-^11 % 7(b9,b13)
+ c:13-.9+^11 % 7(#9,b13)
+
+ % half diminished chords
+ c:m5-.7 % slashed o = m7b5
+ c:9.3-.5- % o/7(pure 9)
+
+ % diminished chords
+ c:m5-.7- % o = diminished seventh chord
+}
+
+\score {
+ \notes <
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper {
+ \translator {
+ \ChordNamesContext
+ ChordName \override #'word-space = #1
+ ChordName \override #'style = #'jazz
+ }
+ }
+}
+@end lilypond
+@end quotation
+
+
+@node lyricprint
+@section lyricprint
@cindex lyrics
@cindex printing!lyrics
-@node lyricprint, , , Reference Manual
Lyric syllables must be interpreted within a @code{Lyrics} context
Here is a full example:
@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
-@node Notation Contexts, , , Reference Manual
+@node Notation Contexts
@section Notation Contexts
@cindex notation contexts
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
-@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
+@node Page layout
+@section Page layout
-@cindex notation output
-
-@cindex output definition
-
-@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 \stylesheet declaration. Its syntax is
-
@example
- \stylesheet @var{scm}
+ \stylesheet @var{alist}
@end example
-
- See font.scm for details of @var{scm}
+ 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}
@item @code{linewidth}@indexcode{linewidth}
Sets the width of the lines. If set to -1.0, a single
- unjustified line is produced.
+ unjustified line is produced. If you use this variable, you
+ probably want to define it in staff spaces, ie
+ @example
+ linewidth = 30 * \staffspace;
+ @end example
@item @code{textheight}@indexcode{textheight}
Sets the total height of the music on each page. Only used by
Defaults to 0.
@item @code{stafflinethickness}@indexcode{stafflinethickness}
- Determines the thickness of staff and bar lines.
+ Determines the thickness of staff lines, and also acts as a scaling
+ parameter for other line thicknesses.
@end table
-@node contextdefs, , , Reference Manual
+@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
+@section contextdefs
@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 Sound output, , , Reference Manual
+@node Sound output
@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
@cindex MIDI instrument names
-@node midilist, , , Reference Manual
+@node midilist
+@section midilist
The MIDI instrument name is set by the
@code{Staff.midiInstrument}@indexcode{Staff.midiInstrument} property or,
@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
+@node Pre-defined Identifiers
@section Pre-defined Identifiers
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{\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{\shiftOff}@keyindex{shiftOff}
+ Disable horizontal shifting of note heads that collide.
@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.
-
- @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.
+ shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
+set different shift values.
@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.
+ @item @code{\stemDown}@keyindex{stemDown}
+ 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{\traditional}@keyindex{traditional}
- Used for setting the @code{Score.beamquantisation} property. Is
- equal to 2.
+ Force stems, beams and slurs to point up.
- @item @code{\up}@keyindex{up}
- Used for setting various direction properties. Is equal
- to 1.
@end table
+
+
projects / lilypond.git / blobdiff