@c - Add some words about Guile. /MB
@c - Fix indexing (keyindex) so it doesn't add line breaks /MB
-@node Reference Manual, , , Top
+@c ugh: because of @include, we need to fill in these nodes
+
+@node Reference Manual, , , top
@chapter Reference Manual
@menu
* transpose:: transpose
* Ambiguities:: Ambiguities
* Notation conversion specifics:: Notation conversion specifics
-* autobeam:: autobeam
+* Automatic Beaming:: Automatic Beaming
+* Chord Names:: Chord Names
* lyricprint:: lyricprint
* Notation Contexts:: Notation Contexts
* Properties:: Changing formatting
-@node Overview, , , Reference Manual
+@node Overview
@section Overview
This document@footnote{This document has been revised for LilyPond 1.2.}
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.
It is customary to put the @code{\header} at the top of the file.
+@node Pitch names
+@section Pitch names
-@node Pitch names, , , Reference Manual
+@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.
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}.
-
+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.
-
-
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
@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.
LilyPond contains a Scheme interpreter (the GUILE library) for
internal use. The interpreter is accessed by the pound sign:
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
+
Whereever the syntax allows Scheme expressions, you may enter one as
@example
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-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:
Pitch names can be redefined using the @code{\pitchnames} command, see
@ref{Pitch names}.
-@cindex Lexical Modes
-
+@node Lexical modes
+@section Lexical modes
+@cindex Lexical modes
@cindex modes
-@node Lexical modes, , , Reference Manual
To simplify entering notes, lyrics, and chords, @emph{Lilypond} has three
special input modes on top of the default mode. In each mode, words
[todo: include short table showign differences]
-@node Types, , , Reference Manual
+@node Types
@section Types
@cindex Identifiers
@end example
-@node Music expressions, , , Reference Manual
+@node Music expressions
@section Music expressions
@cindex 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 @ref{Other languages} for pitch names in different languages.
+section
+ @c @ref{Other languages} FIXME
+ for pitch names in different languages.
The syntax for duration specification is
numbers and dots.
-@node Note specification, , , Reference Manual
-
-@cindex note specification
+@node Note specification
+@section Note specification
+@cindex Note specification
@cindex pitches
LilyPond has predefined sets of notenames for various languages. See
@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
ceses' eses' geses' ases' beses'
@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.
@lilypond[fragment,verbatim,center]
cis' d' e' cis' c'? d' e' c'!
@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};
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{]}'.
\times 2/3 { [e'8 f' g'] }
@end lilypond
-Beaming can be generated automatically; see section @ref{autobeam}.
+Beaming can be generated automatically; see section @ref{Automatic Beaming}.
To place tremolo marks between notes, use @code{\repeat} with tremolo
e' ~ e' <c' e' g'> ~ <c' e' g'>
@end lilypond
-
-
-[TODO: explain Requests]
-
-
@cindex articulations
@cindex scripts
@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
\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
This is equivalent to `@code{c4-6 c4-"foo"}'.
-
@cindex scripts
@example
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
-@node Compound music expressions, , , Reference Manual
+@node Compound music expressions
@section Compound music expressions
@cindex compound music expressions
-@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
+@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
-@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
-@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
-
-[FIXME: UPDATEME]
+@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.
+@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
+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
-@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
+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{Voice.beamAutoBegin}@indexcode{Voice.beamAutoBegin}.
+@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, 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 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
-@lilypond[fragment,verbatim]
-<
- \context ChordNames {
- \chords{a b c} \notes{<d f g> <e g b>}
- }
- \context Staff \notes {
- a b c' d' e'
- }
->
+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 {
+% \property ChordNames.chordChanges = ##t
+ c1:m \break c:m c:m c:m d
+}
+
+\score {
+ \notes <
+ \context ChordNamesVoice \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper{
+ linewidth = 40 * \staffspace;
+ }
+}
@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:
-@lilypond[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
>
+ \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}:
-@lilypond[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
+ >
+ \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
-
@lilypond[verbatim]
\score {
<
-@node Notation Contexts, , , Reference Manual
+@node Notation Contexts
@section Notation Contexts
@cindex notation contexts
@mbinclude properties.itely
-@node Page layout, , , Reference Manual
+@node Page layout
+@section Page layout
@subsection Paper block
@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
will set the paper variables @code{hsize} and @code{vsize} (used by
@code{ly2dvi})
-@node contextdefs, , , Reference Manual
+@node contextdefs
+@section contextdefs
@cindex context definition
@cindex translator definition
@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 somewhat
@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,
-@node Pre-defined Identifiers, , , Reference Manual
+@node Pre-defined Identifiers
@section Pre-defined Identifiers
Allow stems, beams, and slurs to point either upwards or
downwards, decided automatically by LilyPond.
- @item @code{\stemdown}@keyindex{stemdown}
+ @item @code{\stemDown}@keyindex{stemDown}
Force stems, beams, and slurs to point down.
@item @code{\stemUp}@keyindex{stemUp}
projects / lilypond.git / commitdiff