From af51453530b95aee167fe02ee3f4cb0c8dcd1fe2 Mon Sep 17 00:00:00 2001 From: Jan Nieuwenhuizen Date: Wed, 31 Jan 2001 17:16:52 +0100 Subject: [PATCH] patch::: 1.3.126.jcn3 1.3.126.jcn2 ============ * Grand Refman restructuring, featuring outline mode. * Fixed missing menus and cross references. --- CHANGES | 7 + Documentation/user/internals.itely | 42 +- Documentation/user/macros.itexi | 31 + Documentation/user/properties.itely | 27 - Documentation/user/refman.itely | 4061 +++++++++-------- Documentation/user/tricks.itely | 55 +- VERSION | 2 +- input/bugs/arpeggio-collision.ly | 43 - input/bugs/auto-beam-tuplets.ly | 16 +- input/bugs/auto-beam.ly | 9 +- input/bugs/barline.ly | 8 +- input/bugs/broken-tuplet.ly | 16 + input/bugs/coda-kludge.ly | 58 - input/bugs/die-staff.ly | 6 +- input/bugs/different-time.ly | 6 +- input/bugs/dots.ly | 8 +- input/bugs/dynamic-switch.ly | 3 - input/bugs/empty.ly | 16 - input/bugs/no-bars.ly | 20 - input/bugs/prefatory-spacing.ly | 9 +- input/bugs/slur-dx.ly | 8 +- input/bugs/spanners.ly | 11 - input/bugs/steep-beam.ly | 6 +- input/bugs/text-kerning.ly | 2 + input/bugs/ties.ly | 8 +- input/bugs/volta.ly | 44 - input/bugs/voltastart.ly | 132 - input/regression/allfontstyle.ly | 17 + input/regression/arpeggio-collision.ly | 47 + input/regression/volta-broken-left-edge.ly | 136 + input/test/allfontstyle.ly | 17 - lily/all-font-metrics.cc | 4 - lily/include/spring.hh | 4 + lily/spacing-spanner.cc | 3 +- lily/tuplet-spanner.cc | 6 +- ly/generic-paper.ly | 2 - ly/midi.ly | 3 - ly/script.ly | 4 - make/mutopia-targets.make | 5 + .../J.S.Bach/Solo-Cello-Suites/GNUmakefile | 3 + scm/basic-properties.scm | 2 + scm/lily.scm | 1 + scm/paper.scm | 9 - scm/translator-description.scm | 3 +- scm/translator-property-description.scm | 8 +- 45 files changed, 2656 insertions(+), 2272 deletions(-) create mode 100644 input/bugs/broken-tuplet.ly create mode 100644 input/regression/allfontstyle.ly create mode 100644 input/regression/arpeggio-collision.ly create mode 100644 input/regression/volta-broken-left-edge.ly diff --git a/CHANGES b/CHANGES index 331585b72d..dcdd1c8539 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,10 @@ +1.3.126.jcn2 +============ + +* Grand Refman restructuring, featuring outline mode. + +* Fixed missing menus and cross references. + 1.3.126.jcn1 ============ diff --git a/Documentation/user/internals.itely b/Documentation/user/internals.itely index 18fd638dca..aaf03d8da6 100644 --- a/Documentation/user/internals.itely +++ b/Documentation/user/internals.itely @@ -1,15 +1,27 @@ +@c -*-texinfo-*- +@c Note: +@c +@c A menu is needed before every deeper *section nesting of @nodes +@c Run M-x texinfo-all-menus-update +@c to automagically fill in these menus +@c before saving changes + + @node Internals @chapter Internals @menu -* Conversion stages:: Lilypond is a multi-pass program. -* Moment:: -* Grobs:: Graphical object -* Engraver:: -* Music_iterator:: -* Music:: -* Molecules:: Molecules are stand-alone descriptions of output -* Font metrics:: Font metrics +* Conversion stages:: Lilypond is a multi-pass program. +* Moment:: +* Grobs:: Graphical object +* Duration:: +* Pitch data type:: +* Engraver:: +* Music_iterator:: +* Music:: +* Molecules:: Molecules are stand-alone descriptions of output +* Font metrics:: Font metrics +* Miscellaneous Scheme functions:: @end menu @node Conversion stages @@ -101,12 +113,12 @@ them involve Grobs in some form, this section explains some details of how grobs work. @menu -* What is a grob?:: -* Callbacks:: -* Setting grob properties:: -* Items and Spanners:: -* Pointer substitution:: -* Grob Scheme functions:: +* What is a grob?:: +* Callbacks:: +* Setting grob properties:: +* Items and Spanners:: +* Pointer substitution:: +* Grob Scheme functions:: @end menu @node What is a grob? @@ -359,6 +371,8 @@ will return @code{'()} (end-of-list) if @var{g} doesn't have @var{sym} set. @node Duration @section Duration +@menu +@end menu @defun make-duration length dotcount @var{length} is the negative logarithm (base 2) of the duration: diff --git a/Documentation/user/macros.itexi b/Documentation/user/macros.itexi index 2fdd232704..9ef47bbbec 100644 --- a/Documentation/user/macros.itexi +++ b/Documentation/user/macros.itexi @@ -19,3 +19,34 @@ @end macro @end ifnotinfo + + +@ignore + +@c Huh, do outline mode and texinfo really fight eachother? +@c Outline can only use spaces to indent topic headers +@c (or bullets, but then topics can't start with `@c'). +@c Texinfo can't have spaces in macro names. + +@macro c_ {word} +\word\ +@node \word\ +@section \word\ +@end macro + +@macro c__ {word} +\word\ +@node \word\ +@subsection \word\ +@end macro + +@macro c___ {word} +\word\ +@node \word\ +@unnumberedsubsubsection \word\ +@end macro + +@end ignore + +@macro c_ {word} +@end macro diff --git a/Documentation/user/properties.itely b/Documentation/user/properties.itely index 97ba731a41..e69de29bb2 100644 --- a/Documentation/user/properties.itely +++ b/Documentation/user/properties.itely @@ -1,27 +0,0 @@ -@node Properties -@section Properties - -Properties are Scheme values. Most of them are in the generated documentation, but some MIDI properties are not. Here is their documentation - -@macro propertytype{t} - (\t\) -@end macro - - -@table @samp -@cindex @code{midiInstrument} - @item @code{midiInstrument} @propertytype{string} - Sets the instrument for MIDI output. If this property is not set - then LilyPond will use the @code{instrument} property. This must - be set to one of the strings on the list of MIDI instruments that - appears in section @ref{midilist}. If you use a string which - is not listed, LilyPond will silently substitute piano. -@cindex @code{transposing} - - @item @code{transposing} @propertytype{integer} - Transpose the MIDI output. Set this property to the number of - half-steps to transpose by. - -@end table - - diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely index 3806e59c09..ea338517a1 100644 --- a/Documentation/user/refman.itely +++ b/Documentation/user/refman.itely @@ -1,53 +1,34 @@ -@c -*-texinfo-*- - +@c Note: +@c +@c A menu is needed before every deeper *section nesting of @nodes +@c Run M-x texinfo-all-menus-update +@c to automagically fill in these menus +@c before saving changes + +@c_{Reference Manual} @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 -* Assignments:: Assignments -* 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 -* Point and click:: Quik edit using Point and Click -* Interpretation contexts:(lilypond-internals)LilyPond interpretation contexts. -* Engravers:(lilypond-internals)LilyPond engravers. -* Backend:(lilypond-internals)LilyPond backend. +* Overview:: +* Music constructs:: +* Modifying music:: +* Note entry:: +* Note specification:: +* Music notation:: +* Lyrics entry:: +* Chord entry:: +* Page layout:: +* Sound:: +* Music entry:: +* Engravers:: +* Lexer innards:: +* Unsorted:: @end menu - - +@c_ {Overview} @node Overview @section Overview - -[todo: pedals] - This document describes the the GNU LilyPond input format This format represents a piece of music in an elegant way, but contains enough information for @@ -71,8 +52,6 @@ symbols and their placement is @emph{generated} from a high-level musical description. In other words, LilyPond would be best described by `music compiler' or `music to notation compiler'. - - LilyPond input can be classified into three types: @itemize @bullet @item musical expressions: a musical expression is some combination of @@ -84,482 +63,605 @@ expressions into performances (MIDI) or graphics (eg. PostScript). can enter and edit them in manageable chunks. @end itemize -@node Top level -@section Top level -This section describes what you may enter at top level. +@c_ {Music constructs} +@node Music constructs +@section Music constructs +@cindex Music constructs +@menu +* Music expressions:: +* Sequential music:: +* Simultanious music:: +* Compound music expressions:: +* Grace music:: +* Explicit atomic music:: +@end menu +@c_ {Music expressions} +@node Music expressions +@subsection Music expressions -@unnumberedsubsec Score definition -@cindex score definition +@cindex music expressions -The output is generated combining a music expression with an output -definition. A score block has the following syntax: +Music in LilyPond is entered as a music expression. Notes, rests, +lyric syllables are music expressions (the atomic +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: + +@example +\sequential @{ c4 d4 @} +@end example + +The meaning of this compound expression is to play the @code{c} +first, and then the @code{d} (as opposed to playing them +simultaneously, for instance). + +Atomic music expression are discussed in +subsection @ref{Atomic music expressions}. Compound music expressions are +discussed in subsection @ref{Compound music expressions}. + + +@c_ {Sequential music} +@node Sequential music +@subsection Sequential music +@cindex Sequential music +@cindex @code{\sequential} +@cindex sequential music @example - \score @{ @var{musicexpr} @var{outputdefs} @} + \sequential @code{@{} @var{musicexprlist} @code{@}} @end example -@var{outputdefs} are zero or more output definitions. If no output -definition is supplied, the default @code{\paper} block will be added. +This means that list should be played or written in sequence, i.e., +the second after the first, the third after the second. The duration +of sequential music is the the sum of the durations of the elements. +There is a shorthand, which leaves out the keyword: -@unnumberedsubsec Header definition -@cindex headers +@example +@cindex @code{<} +@cindex @code{>} -@cindex @code{\header} + @code{@{} @var{musicexprlist} @code{@}} +@end example -The syntax is +@c_ {Simultanious music} +@node Simultanious music +@subsection Simultanious music +@cindex Simultanious music +@cindex @code{\simultaneous} @example - \header @{ @var{key1} = @var{val1}; -@cindex @code{ly2dvi} - @var{key2} = @var{val2}; @dots{} @} + \simultaneous @code{@{} @var{musicexprlist} @code{@}} @end example +It constructs a music expression where all of its arguments start at +the same moment. The duration is the maximum of the durations of the +elements. The following shorthand is a common idiom: -A header describes the file's contents. It can also appear in a -@code{\score} block. Tools like @code{ly2dvi} can use this -information for generating titles. Key values that are used by -@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument, -metre, arranger, piece and tagline. - -It is customary to put the @code{\header} at the top of the file. +@example + @code{<} @var{musicexprlist} @code{>} +@end example -@unnumberedsubsec Default output +If you try to use a chord as the first thing in your score, you might +get multiple staffs instead of a chord. -A @code{\midi} or @code{\paper} block at top-level sets the default -paper block for all scores that lack an explicit paper block. +@lilypond[verbatim,center] + \score { + \notes + \paper { + linewidth = -1.; + } + } +@end lilypond -@unnumberedsubsec Scheme statements +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: -Scheme statements maybe issued to produce interesting side-effects. +@lilypond[verbatim,center] + \score { + \notes\context Voice + \paper { + linewidth = -1.; + } + } +@end lilypond +@c_ {Compound music expressions} +@node Compound music expressions +@subsection Compound music expressions -@node Pitch names -@section Pitch names +@cindex Compound music expressions +Music expressions are compound data structures. You can nest music +expressions any way you like. This simple example shows how three +chords can be expressed in two different ways: -@unnumberedsubsec Pitch name definition -@cindex pitch names +@lilypond[fragment,verbatim,center] + \notes \context Staff { + + < { a b c' } { c' d' e' } > + } -@cindex note names -@cindex chord modifier names +@end lilypond -Note names and chord modifiers can be customised for nationalities. -languages and conventions. The syntax is as follows. -@cindex @code{\pitchnames} -@cindex @code{\chordmodifiers} +@cindex @code{\context} +@cindex context selection @example - \pitchnames @var{scheme-alist} - \chordmodifiers @var{scheme-alist} + \context @var{contexttype} [= @var{contextname}] @var{musicexpr} @end example -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. +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. -@unnumberedsubsec Assignments -@cindex assignments -@cindex @code{#} -Identifier assignments may appear at top level. @ref{Assignments} +@c_ {Grace music} <-> Grace notes +@node Grace music +@subsection Grace music +@cindex Grace music +@cindex @code{\grace} +@cindex ornaments +@cindex grace notes +@cindex @code{graceAlignPosition} +@example + \grace @var{musicexpr} +@end example -@node Lexical conventions -@section Lexical conventions +A grace note expression has duration 0; the next real note is +assumed to be the main note. -@cindex lexical conventions +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 +@code{graceAlignPosition}. +@cindex @code{flagStyle} +When grace music is interpreted, a score-within-a-score is set up: +@var{musicexpr} has its own time bookkeeping, and you could (for +example) have a separate time signature within grace notes. While in +this score-within-a-score, you can create notes, beams, slurs, etc. +Unbeamed eighth notes and shorter by default have a slash through the +stem. This behavior can be controlled with the +@code{flagStyle} property. -@unnumberedsubsec Comments +@quotation +@lilypond[fragment,verbatim] +\relative c'' { + \grace c8 c4 \grace { [c16 c16] } c4 + \grace { \property Grace.flagStyle = "" c16 } c4 +} -@cindex comment -@cindex @code{%} +@end lilypond +@end quotation +@cindex @code{\grace} +At present, nesting @code{\grace} notes is not supported. The following +may cause run-time errors: +@example + @code{\grace @{ \grace c32 c16 @} c4} +@end example +Since the meaning of such a construct is unclear, we don't consider +this a loss. Similarly, juxtaposing two @code{\grace} sections is +syntactically valid, but makes no sense and may cause runtime errors. -A one line comment is introduced by a @code{%} character. -Block comments are started by @code{%@{} and ended by `@code{%@}}'. -They cannot be nested. +Ending a staff or score with grace notes may also generate a run-time +error, since there will be no main note to attach the grace notes to. -@unnumberedsubsec Scheme +The present implementation is not robust and generally kludgy. We expect +it to change after LilyPond 1.4 +@c_ {Explicit atomic music} +@node Explicit atomic music +@subsection Explicit atomic music +@cindex Explicit atomic music -@cindex Scheme -@cindex GUILE -@cindex Scheme, in-line code +@cindex pitch +The syntax for pitch specification is -LilyPond contains a Scheme interpreter (the GUILE library) for -internal use. In some places Scheme expressions also form valid syntax: -whereever it is allowed, -@example - #@var{scheme} -@end example -evaluates the specified Scheme code. If this is used at toplevel, then -the result is discarded. Example: +@cindex @code{\pitch} @example - \property Staff.TestObject \override #'foobar = #(+ 1 2) + \pitch @var{scmpitch} @end example -@code{\override} expects two Scheme expressions, so there are two Scheme -expressions. The first one is a symbol (@code{foobar}), the second one -an integer (namely, 3). - -Scheme is a full-blown programming language, and a full discussion is -outside the scope of this document. Interested readers are referred to -the website @uref{http://www.schemers.org/} for more information on -Scheme. - -@unnumberedsubsec Keywords -@cindex keyword +@var{scmpitch} is a pitch scheme object, see @ref{Pitch}. +In Note and Chord mode, pitches may be designated by names. See +section @ref{Other languages} for pitch names in different languages. -Keywords start with a backslash, followed by a number of lower case -alphabetic characters. These are all the keywords. +@cindex duration +@cindex @code{\duration} +The syntax for duration specification is @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 pitch -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 + \duration @var{scmduration} @end example -@unnumberedsubsec Integers +In Note, Chord, and Lyrics mode, durations may be designated by +numbers and dots. -@cindex integers -@cindex @code{+} -@cindex @code{-} -@cindex @code{*} -@cindex @code{/} -Formed from an optional minus sign followed by digits. Arithmetic -operations cannot be done with integers, and integers cannot be mixed -with reals. -@unnumberedsubsec Reals -@cindex real numbers +@c_ {Modifying music} +@node Modifying music +@section Modifying music +@cindex Modifying music +@menu +* Relative:: +* Transpose:: +* Repeat:: +* Times :: +* Apply:: +* Transform:: +@end menu +@c_ {Relative} +@node Relative +@subsection Relative +@cindex Relative +@cindex relative octave 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 +note's octave is `the relative octave' mode. +@cindex @code{\relative} +@example + \relative @var{startpitch} @var{musicexpr} +@end example +The octave of notes that appear in @var{musicexpr} are calculated as +follows: If no octave changing marks are used, the basic interval +between this and the last note is always taken to be a fourth or +less.@footnote{The interval is determined without regarding +accidentals. A @code{fisis} following a @code{ceses} will be put above +the @code{ceses}.} The octave changing marks @code{'} and @code{,} +can then be added to raise or lower the pitch by an extra octave. +Upon entering relative mode, an absolute starting pitch must be +specified that will act as the predecessor of the first note of +@var{musicexpr}. -Formed from an optional minus sign and a sequence of digits followed -by a @emph{required} decimal point and an optional exponent such as -@code{-1.2e3}. Reals can be built up using the usual operations: -`@code{+}', `@code{-}', `@code{*}', and -`@code{/}', with parentheses for grouping. +Entering scales is straightforward in relative mode. -@cindex @code{\mm}, -@cindex @code{\in} -@cindex @code{\cm} -@cindex @code{\pt} -@cindex dimensions +@lilypond[fragment,verbatim,center] + \relative c' { + c d e f g a b c c, + } +@end lilypond -A real constant can be followed by one of the dimension keywords: -@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters, -points, inches and centimeters, respectively. This converts the number -to a real that is the internal representation of dimensions. +And octave changing marks are used for intervals greater than a fourth. +@lilypond[fragment,verbatim,center] + \relative c'' { + c g c f, c' a, e'' } +@end lilypond -@unnumberedsubsec Strings -@cindex string -@cindex concatenate +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. -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 -@ref{Lexical modes} for details on unquoted strings; their interpretation varies -depending on the situation. Strings can be concatenated with the -@code{+} operator. +@lilypond[fragment,verbatim,center] + \relative c' { + c + + + } +@end lilypond +@cindex @code{\notes} -The tokenizer accepts the following commands. They have no grammatical -function, hence they can appear anywhere in the input. +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 +be a surrounding @code{\notes} keyword (which is not +shown here). -@unnumberedsubsec Main input +The relative conversion will not affect @code{\transpose} or +@code{\relative} sections in its argument. If you want to use +relative within transposed music, you must place an additional +@code{\relative} inside the @code{\transpose}. -@cindex @code{\maininput} +It is strongly recommended to use relative pitch mode: less work, +less error-prone, and more readable. -The @code{\maininput} command is used in init files to signal that the -user file must be read. This command cannot be used in a user file. +@c_ {Transpose} +@node Transpose +@subsection Transpose +@cindex Transpose +@cindex transposition of pitches +@cindex @code{\transpose} -@unnumberedsubsec File inclusion -@cindex @code{\include} +A music expression can be transposed with @code{\transpose}. The syntax +is @example - \include @var{filename} + \transpose @var{pitch} @var{musicexpr} @end example -Include @var{filename}. The argument @var{filename} may be a quoted string (an -unquoted string will not work here!) or a string identifier. The full -filename including the @file{.ly} extension must be given, - -@unnumberedsubsec Version information -@cindex @code{\version} -@example - \version @var{string} ; -@end example +This means that middle C in @var{musicexpr} is transposed to +@var{pitch}. -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-ly} a tool that automatically upgrades input files. See -See @ref{convert-ly} for more information on @code{convert-ly}. +@code{\transpose} distinguishes between enharmonic pitches: both +@code{\transpose cis'} or @code{\transpose des'} will transpose up half +a tone. The first version will print sharps and the second version +will print flats. -@cindex convert-ly +@quotation +@lilypond[fragment,verbatim] +\context Staff { + \clef "F"; + { \key e \major; c d e f } + \clef "G"; + \transpose des'' { \key e \major; c d e f } + \transpose cis'' { \key e \major; c d e f } +} +@end lilypond +@end quotation -@node Lexical modes -@section Lexical modes -@cindex Lexical modes -@cindex modes +If you want to use both @code{\transpose} and @code{\relative}, then +you must use @code{\transpose} first. @code{\relative} will have no +effect music that appears inside a @code{\transpose}. +@c_ {Repeat} +@node Repeat +@subsection Repeat +@cindex Repeat +@cindex repeats -To simplify entering notes, lyrics, and chords, 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 -a keyword or as an identifier. The behavior of the modes differs in -two ways: Different modes treat unquoted words differently, and -different modes have different rules for deciding what is a word. +@ref{Volta} +[TODO: document #'repeatCommands.] -@table @asis -@item Normal mode. -@cindex normal mode - -At the start of parsing, 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. +@cindex @code{\repeat} -@item Note mode. -@cindex note mode +In order to specify repeats, use the @code{\repeat} +keyword. Since repeats look and sound differently when played or +printed, there are a few different variants of repeats. -@cindex @code{\notes} -Note mode is introduced by the keyword -@code{\notes}. In Note mode, words can only -contain alphabetic characters. If @code{word} is encountered, -LilyPond first checks for a notename of @code{word}. If no -notename is found, then @code{word} is treated as a string. +@table @asis +@item unfolded +Repeated music is fully written (played) out. Useful for MIDI +output. -Since combinations of numbers and dots are used for indicating -durations, it is not possible to enter real numbers in this mode. +@item volta +This is the normal notation: Repeats are not written out, but +alternative endings (voltas) are printed, left to right. -@item Chord mode. -@cindex chord mode +@item folded +Alternative endings are written stacked. Which is unfortunately not +practical for anything right now. -Chord mode is introduced by the keyword -@code{\chords}. It is similar to Note mode, but -words are also looked up in a chord modifier table (containing -@code{maj}, @code{dim}, etc). +@item tremolo +Make tremolo beams. +@end table -Since combinations of numbers and dots are used for indicating -durations, you can not enter real numbers in this mode. Dashes -and carets are used to indicate chord additions and subtractions, -so scripts can not be entered in Chord mode. +The syntax for repeats is -@item Lyrics mode. -@cindex lyric mode -@cindex @code{\lyrics} +@example + \repeat @var{variant} @var{repeatcount} @var{repeatbody} +@end example -Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has -rules that make it easy to include punctuation and diacritical marks in -words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{} -format or a standard encoding without needing quotes. The precise -definition of this mode is ludicrous, and this will remain so until the -authors of LilyPond acquire a deeper understanding of character -encoding, or someone else steps up to fix this. +If you have alternative endings, you may add -A word in Lyrics mode begins with: an alphabetic character, @code{_}, -@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A} -through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^}, -any 8-bit character with ASCII code over 127, or a two-character -combination of a backslash followed by one of @code{`}, @code{'}, -@code{"}, or @code{^}. +@cindex @code{\alternative} +@example + \alternative @code{@{} @var{alternative1} + @var{alternative2} + @var{alternative3} @dots{} @code{@}} +@end example -Subsequent characters of a word can be any character that is not a digit -and not white space. One important consequence of this is that a word -can end with `@code{@}}', which may be confusing. However, LilyPond will -issue a warning. Any @code{_} character which appears in an unquoted -word is converted to a space. This provides a mechanism for introducing -spaces into words without using quotes. Quoted words can also be used -in Lyrics mode to specify words that cannot be written with the above -rules. Here are some examples. Not all of these words are printable by -@TeX{}. +where each @var{alternative} is a Music expression. -@example -Ah! % a word -2B_||_!2B % not a word because it starts with a digit -``Hello'' % not a word because it starts with ` -_ _ _ _ % 4 words, each one a space -@end example +Normal notation repeats are used like this: -Since combinations of numbers and dots are used for indicating -durations, you can not enter real numbers in this mode. -@end table +@quotation -[todo: include short table showing differences] +@lilypond[fragment,verbatim] + c'1 + \repeat volta 2 { c'4 d' e' f' } + \repeat volta 2 { f' e' d' c' } -@node Types -@section Types +@end lilypond +@end quotation -@cindex Identifiers +With alternative endings: -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, +@quotation -@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 -@item Moment (rational number) -@end itemize +@lilypond[fragment,verbatim] + c'1 + \repeat volta 2 {c'4 d' e' f'} + \alternative { {d'2 d'} {f' f} } -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. +@end lilypond +@end quotation -@itemize @bullet -@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 +Folded repeats look like this:@footnote{Folded repeats offer little +more over simultaneous music. However, it is to be expected that +more functionality -- especially for the MIDI backend -- will be +implemented.} -@node Assignments -@unnumberedsubsec Assignments +@quotation -Identifiers allow objects to be assigned to names during the parse -stage. To assign an identifier, you use @var{name}@code{=}@var{value} -and to refer to an identifier, you preceed its name with a backslash: -`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of -the input-types listed above. Identifier assignments can appear at top -level in the LilyPond file, but also in @code{\paper} blocks. +@lilypond[fragment,verbatim] + c'1 + \repeat fold 2 {c'4 d' e' f'} + \alternative { {d'2 d'} {f' f} } -Semicolons are forbidden after top level assignments, but mandatory in -other places. The rules about semicolons and assignments are very -confusing, but when LilyPond input evolves more towards Scheme, we hope -that this problem will grow smaller. +@end lilypond +@end quotation -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. +@quotation -The right hand side of an identifier assignment is parsed completely -before the assignment is done, so it is allowed to redefine an -identifier in terms of its old value, e.g. +@lilypond[fragment,verbatim] +\context Staff { + \relative c' { + \partial 4; + \repeat volta 2 { e | c2 d2 | e2 f2 | } + \alternative { { g4 g g } { a | a a a a | b1 } } + } +} -@example -foo = \foo * 2.0 -@end example +@end lilypond +@end quotation -When an identifier is referenced, the information it points to is -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 -@} +If you don't give enough alternatives for all of the repeats, then +the first alternative is assumed to be repeated often enough to equal +the specified number of repeats. -\paper @{ -\paperIdent % correct -foo = 1.0 -@} -@end example +@quotation +@lilypond[fragment,verbatim] +\context Staff { + \relative c' { + \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | } + \alternative { { g4 g g } + {\partial 1; e4 e e } + {\partial 1; a a a a | b1 } } + } +} +@end lilypond +@end quotation + +As you can see, LilyPond doesn't remember the timing information, nor +are slurs or ties repeated. We hope to fix this after 1.4. +It is possible to nest @code{\repeat}. This is not entirely +supported: the notes will come be in the right places, but the repeat +bars will not. -@node Music expressions -@section Music expressions +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. -@cindex music expressions +@lilypond[verbatim,center] +\score { + \context Voice \notes\relative c' { + \repeat "tremolo" 8 { c16 d16 } + \repeat "tremolo" 4 { c16 d16 } + \repeat "tremolo" 2 { c16 d16 } + } + \paper { + linewidth = 40*\staffspace; + } +} +@end lilypond +@cindex @code{__} -Music in LilyPond is entered as a music expression. Notes, rests, -lyric syllables are music expressions (the atomic -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: +@lilypond[fragment,verbatim,center] -@example -\sequential @{ c4 d4 @} -@end example + c'4:32 +@end lilypond -The meaning of this compound expression is to play the @code{c} -first, and then the @code{d} (as opposed to playing them -simultaneously, for instance). +@c_ {Times} +@node Times +@subsection Times +@cindex Times +@ref{Tuplets} +Tuplets are made out of a music expression by multiplying their +duration with a fraction. -Atomic music expression are discussed in -subsection @ref{Atomic music expressions}. Compound music expressions are -discussed in subsection @ref{Compound music expressions}. +@cindex @code{\times} +@example + \times @var{fraction} @var{musicexpr} +@end example + +The duration of @var{musicexpr} will be multiplied by the fraction. +In print, the fraction's denominator will be printed over the notes, +optionally with a bracket. The most common tuplet is the triplet in +which 3 notes have the length of 2, so the notes are 2/3 of +their written length: +@lilypond[fragment,verbatim,center] + g'4 \times 2/3 {c'4 c' c'} d'4 d'4 +@end lilypond -@node Atomic music expressions -@section Atomic music expressions +@c_ {Apply} +@node Apply +@subsection Apply +@cindex Apply +Apply allows a Scheme-function to operate directly on the internal +representation of music. +@example + \apply #@var{func} @var{music} +@end example +The function takes two arguments, being a function and an musical +argument for that function. The function should return a music +expression. +This example replaces the text string of a script. It also shows a dump +of the music it processes. +@lilypond[verbatim] +#(define (testfunc x) + (if (eq? (ly-get-mus-property x 'text) "foo") + (ly-set-mus-property x 'text "bar")) + ;; recurse + (ly-set-mus-property x 'elements + (map testfunc (ly-get-mus-property x 'elements))) + (display x) + x +) +\score { \notes + \apply #testfunc { c4_"foo" } +} +@end lilypond +For more information on what is possible, see the @ref{Tricks} and the +automatically generated documentation. +@c_ {Transform} +@node Transform +@subsection Transform +@cindex Transform -@cindex pitch -The syntax for pitch specification is +@c_ {Note entry} +@node Note entry +@section Note entry +@cindex Note entry -@cindex @code{\pitch} -@example - \pitch @var{scmpitch} -@end example +@menu +* Notes mode:: +* Pitch names:: +@end menu -@var{scmpitch} is a pitch scheme object, see @ref{Pitch}. +@c_ {Notes mode} +@node Notes mode +@subsection Notes mode -In Note and Chord mode, pitches may be designated by names. See -section @ref{Other languages} for pitch names in different languages. +@cindex note mode -@cindex duration -@cindex @code{\duration} +@cindex @code{\notes} +Note mode is introduced by the keyword +@code{\notes}. In Note mode, words can only +contain alphabetic characters. If @code{word} is encountered, +LilyPond first checks for a notename of @code{word}. If no +notename is found, then @code{word} is treated as a string. -The syntax for duration specification is -@example - \duration @var{scmduration} -@end example +Since combinations of numbers and dots are used for indicating +durations, it is not possible to enter real numbers in this mode. -In Note, Chord, and Lyrics mode, durations may be designated by -numbers and dots. +@cindex Notes mode +@c_ {Pitch names} +@node Pitch names +@subsection Pitch names +@cindex Pitch names @node Note specification @section Note specification @cindex Note specification @cindex pitches - @cindex entering notes A note specification has the form @@ -648,7 +750,28 @@ question mark `@code{?}' after the pitch. @end lilypond -@cindex duration +@c_ {Rests} +@menu +* Rests:: +* Durations:: +* Multi measure rests:: +* Skip:: +@end menu + +@node Rests +@subsection Rests +@cindex Rests + +Rests are entered like notes, with note name `@code{r}'. +There is also a note name +`@code{s}', which produces a space of the specified +duration. + + +@c_ {Durations} +@node Durations +@subsection Durations +@cindex Durations Durations are entered as their reciprocal values. For notes longer than a whole note, use identifiers. @@ -695,10 +818,6 @@ entered. At the start of parsing there is no previous duration, so then a quarter note is assumed. The duration can be followed by a dot (`@code{.}') to obtain dotted note lengths. -Rests are entered like notes, with note name `@code{r}'. -There is also a note name -`@code{s}', which produces a space of the specified -duration. @lilypond[fragment,verbatim,center] @@ -710,7 +829,10 @@ duration. 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. -@unnumberedsubsec Multi measure rests +@c_ {Multi measure rests} +@node Multi measure rests +@subsection Multi measure rests +@cindex Multi measure rests @cindex @code{R} @@ -728,97 +850,59 @@ automatically adds the appropriate number. Note that there is currently no way to condense multiple rests into a single multimeasure rest. +@c_ {Skip} +@node Skip +@subsection Skip +@cindex Skip -@unnumberedsubsec Lyrics -@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 @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 @ref{lyricprint}. +@example + \skip @var{duration} @code{;} +@end example +@cindex @code{\skip} -[explain automatic phrasing] +Skips the amount of time specified by @var{duration}. If no other +music is played, a gap will be left for the skipped time with no +notes printed. It works in Note Mode or Lyrics Mode. In Note mode, +this has the same effect as the spacer rest. -@cindex properties -@unnumberedsubsec Translation property -@cindex @code{\property} -@example - \property @var{contextname}.@var{propname} = @var{value} -@end example -Sets the @var{propname} property of the context @var{contextname} to -the specified @var{value}. All three arguments are strings. -Depending on the context, it may be necessary to quote the strings or -to leave space on both sides of the dot. -@cindex translator switches -@unnumberedsubsec Translator switches -@cindex @code{\translator} -@example - \translator @var{contexttype} = @var{name} -@end example +@c_ {Music notation} +@node Music notation +@section Music notation +@cindex Music notation +@menu +* Key:: +* Clef:: +* Time signature:: +* Spanners:: +* Ornaments:: +* Bar check:: +@end menu -A music expression indicating that the context which is a direct -child of the a context of type @var{contexttype} should be shifted to -a context of type @var{contexttype} and the specified name. +@c_ {Key} +@node Key +@subsection Key +@cindex Key -Usually this is used to switch staffs in Piano music, e.g. +@cindex @code{\key} @example - \translator Staff = top @var{Music} + @code{\key} @var{pitch} @var{type} @code{;} @end example - - -@cindex output properties -@unnumberedsubsec Output properties - -These allow you to tweak what is happening in the back-end -directly. If you want to control every detail of the output -formatting, this is the feature to use. The downside to this is that -you need to know exactly how the backend works. Example: - - -@lilypond[fragment,verbatim] -\relative c'' { c4 - \context Staff \outputproperty - #(make-type-checker 'note-head-interface) - #'extra-offset = #'(5.0 . 7.5) - } -@end lilypond - -This selects all note heads occurring at current staff level, and sets -the @code{extra-offset} of those heads to @code{(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 implementation of the backend, -which we change regularly and unscrupulously. - -@unnumberedsubsec Key signature -@cindex @code{\key} - -@example - @code{\key} @var{pitch} @var{type} @code{;} -@end example -@cindex @code{\minor} -@cindex @code{\major} -@cindex @code{\minor} -@cindex @code{\ionian} -@cindex @code{\locrian} -@cindex @code{\aeolian} -@cindex @code{\mixolydian} -@cindex @code{\lydian} -@cindex @code{\phrygian} -@cindex @code{\dorian} +@cindex @code{\minor} +@cindex @code{\major} +@cindex @code{\minor} +@cindex @code{\ionian} +@cindex @code{\locrian} +@cindex @code{\aeolian} +@cindex @code{\mixolydian} +@cindex @code{\lydian} +@cindex @code{\phrygian} +@cindex @code{\dorian} Change the key signature. @var{type} should be @code{\major} or @code{\minor} to get @var{pitch}-major or @var{pitch}-minor, @@ -830,43 +914,40 @@ major key, e.g., @code{\minor} is defined as 3. The standard mode names @code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian}, @code{\phrygian}, and @code{\dorian} are also defined. -@unnumberedsubsec Rehearsal marks -@cindex rehearsal marks -@cindex mark -@cindex @code{\mark} -@example - \mark @var{unsigned}; -@cindex @code{Mark_engraver} - \mark @var{string}; -@end example - -Prints a mark over or under the staff. -@unnumberedsubsec barlines +@c_ {Clef} +@node Clef +@subsection Clef +@cindex Clef -@cindex @code{\bar} -@cindex measure lines -@cindex repeat bars +@c_ {Clef changes} +@subsubsection Clef changes +@cindex @code{\clef} @example - \bar @var{bartype}; + \clef @var{clefname} @code{;} @end example -This is a short-cut for doing +Short-cut for + @example - \property Score.whichBar = @var{bartype} + \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 -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}. +Supported clef-names include + +[todo] -[FIXME] -@unnumberedsubsec Time signature +@c_ {Time signature} +@node Time signature +@subsection Time signature +@cindex Time signature @cindex meter -@cindex time signature @cindex @code{\time} + @example \time @var{numerator}@code{/}@var{denominator} @code{;} @end example @@ -878,18 +959,10 @@ A short-cut for doing See the documentation of @code{timeSignatureFraction} -@unnumberedsubsec Tempo -@cindex beats per minute -@cindex metronome marking -@cindex @code{\tempo} -@example - \tempo @var{duration} = @var{perminute} @code{;} -@end example - -Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests -output with 76 quarter notes per minute. -@unnumberedsubsec Partial measures +@c_ {Partial} +@subsubsection Partial +@cindex Partial @cindex anacrusis @cindex upstep @cindex partial measure @@ -909,69 +982,94 @@ Short cut for See the documentation of @code{measurePosition}. -@unnumberedsubsec Bar check - -@cindex bar check -@cindex @code{barCheckNoSynchronize} -@cindex @code{|} - - -Bar checks help you find errors in the input: Whenever one is -encountered during interpretation, a warning message is issued if it -doesn't fall at a measure boundary. Depending on the value of -@code{barCheckNoSynchronize}, the beginning of the measure will be -relocated, so this can also be used to shorten measures. -A bar check is entered using the bar symbol, @code{|} -This can help you finding errors in the input. +@c_ {Spanners} +@node Spanners +@subsection Spanners +@cindex Spanners -@unnumberedsubsec Line break penalty. -@cindex @code{\penalty} +@menu +* Beam:: +* Slur:: +* Tie:: +* Tuplet:: +* Volta:: +* Crescendo and Decrescendo:: +* Text spanner:: +* Ottava:: +* Span requests:: +@end menu +@c_ {Beam} +@node Beam +@subsubsection Beam +@cindex Beam +@c_ {Automatic beams} +@unnumberedsubsubsec Automatic beams -@example - \penalty @var{int} @code{;} -@end example +@cindex automatic beam generation +@cindex autobeam -Discourage or encourage line breaks. See @ref{Page layout}. +@cindex @code{Voice.noAutoBeaming} -@unnumberedsubsec Clef change -@cindex @code{\clef} -@example - \clef @var{clefname} @code{;} -@end example +By default, LilyPond will generate beams automatically. This feature +can be disabled by setting the @code{Voice.noAutoBeaming} property to +true. It can be overridden for specific cases by specifying explicit +beams. -Short-cut for +@cindex @code{Voice.autoBeamSettings} +@cindex @code{(end * * * *)} +@cindex @code{(begin * * * *)} +A large number of Voice properties are used to decide how to generate +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}. +To end beams every quarter note, for example, you could set the property +@code{(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 * * * *)}, eg: +@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} +\property Voice.autoBeamSettings \override + #'(end * * * *) = #(make-moment 1 4) +\property Voice.autoBeamSettings \override + #'(begin * * * *) = #(make-moment 1 8) @end example +@end quotation -Supported clef-names include +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 * *)}. -[todo] +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. -@unnumberedsubsec Skip -@example - \skip @var{duration} @code{;} -@end example -@cindex @code{\skip} +For example, to specify beam endings for beams that contain 32nd notes, +you would use @code{(end * * 1 32)}. -Skips the amount of time specified by @var{duration}. If no other -music is played, a gap will be left for the skipped time with no -notes printed. It works in Note Mode or Lyrics Mode. In Note mode, -this has the same effect as the spacer rest. -@node Manual beams -@unnumberedsubsec Manual beams +@c_ {Manual beams} +@cindex Automatic beams +@unnumberedsubsubsec Manual beams @cindex beams, manual @cindex @code{]} @cindex @code{[} +FIXME +Beaming can be generated automatically; see section @ref{Automatic Beaming}. + A beam is specified by surrounding the beamed notes with brackets `@code{[}' and `@code{]}'. @@ -981,25 +1079,44 @@ A beam is specified by surrounding the beamed notes with brackets \times 2/3 { [e'8 f' g'] } @end lilypond -Beaming can be generated automatically; see section @ref{Automatic Beaming}. @cindex @code{-}@code{-} -@unnumberedsubsec Lyric extender -@cindex extender -@cindex lyric extender -@cindex hyphen -The syntax for an extender mark is @code{__}. This syntax can only -be used within lyrics mode. +@c_ {Adjusting beams} +@unnumberedsubsubsec Adjusting beams +@cindex Adjusting beams -@unnumberedsubsec Lyric hyphens -The syntax for a spanning hyphen (i.e., a hyphen that will be printed -between two lyric syllables) is `@code{-}@code{-}'. +@c_ {Slur} + +@node Slur +@subsubsection Slur +@cindex Slur + +@cindex slur + +Slurs connects chords and try to avoid crossing stems. A slur is +started with @code{(} and stopped with @code{)}. The +starting @code{(} appears to the right of the first note in +the slur. The terminal @code{)} appears to the left of the +first note in the slur. This makes it possible to put a note in +slurs from both sides: + +@lilypond[fragment,verbatim,center] + f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 +@end lilypond -@unnumberedsubsec Ties + +@c_ {Adjusting slurs} +@unnumberedsubsubsec Adjusting slurs +@c_ {Tie} +@cindex Adusting slurs +@node Tie +@subsubsection Tie + +@cindex Tie @cindex ties @cindex @code{~} @@ -1015,7 +1132,143 @@ warning message will appear and no ties will be created. [sparseTies] -@unnumberedsubsec Articulation + +@c_ {Tuplet} +@node Tuplet +@subsubsection Tuplet +@cindex Tuplet + +See @ref{Times}. + +@c_ {Volta} +@node Volta +@subsubsection Volta +@cindex Volta + +See @ref{Repeat}. + +@c_ {Crescendo and Decrescendo} +@node Crescendo and Decrescendo +@subsubsection Crescendo and Decrescendo +@cindex Crescendo and Decrescendo +@cindex crescendo +@cindex @code{\cr} +@cindex @code{\rc} +@cindex @code{\decr} +@cindex @code{\rced} +@cindex @code{\<} +@cindex @code{\>} +@cindex @code{\"!} + + + +A crescendo mark is started with @code{\cr} and terminated with +@code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is +started with @code{\decr} and terminated with @code{\rced}. There are +also shorthands for these marks. A crescendo can be started with +@code{\<} and a decrescendo can be started with @code{\>}. Either one +can be terminated with @code{\!}. Note that @code{\!} must go before +the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go +after the last note. Because these marks are bound to notes, if you +want to get several marks during one note, you must use spacer notes. + +@lilypond[fragment,verbatim,center] + c'' \< \! c'' d'' \decr e'' \rced + < f''1 { s4 \< \! s2 \> \! s4 } > +@end lilypond + +[todo: text cr] + + +@c_ {Text spanner} +@node Text spanner +@subsubsection Text spanner +@cindex Text spanner + +Have crescendo set a text spanner instead of hairpin + +@lilypond[fragment,relative,verbatim] + \context Voice { + \property Voice.crescendoText = "cresc." + \property Voice.crescendoSpanner = #'dashed-line + a''2\mf\< a a \!a + } +@end lilypond + +@c_ {Ottava} +@node Ottava +@subsubsection Ottava +@cindex Ottava +@unnumberedsubsubsec Ottava + +@lilypond[fragment,relative,verbatim] + a'''' b c a + \property Voice.TextSpanner \set #'type = #'dotted-line + \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5) + \property Voice.TextSpanner \set #'edge-text = #'("8va " . "") + \property Staff.centralCPosition = #-13 + a\spanrequest \start "text" b c a \spanrequest \stop "text" +@end lilypond + + + +@c_ {Text crescendo and decrescendo} +@unnumberedsubsubsec Text crescendo and decrescendo + +TODO + +@c_ {Span requests} +@node Span requests +@subsubsection Span requests +@cindex Span requests + +@cindex @code{\spanrequest} + +@example + \spanrequest @var{startstop} @var{type} +@end example +@cindex @code{\start} +@cindex @code{\stop} + +Define a spanning request. The @var{startstop} parameter is either -1 +(@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that +describes what should be started. Supported types are @code{crescendo}, +@code{decrescendo}, @code{beam}, @code{slur}. This is an internal +command. Users should use the shorthands which are defined in the +initialization file @file{spanners.ly}. + +You can attach a (general) span request to a note using + +@lilypond[fragment,verbatim,center] + c'4-\spanrequest \start "slur" + c'4-\spanrequest \stop "slur" +@end lilypond + +The slur syntax with parentheses is a shorthand for this. + + +@c_ {Ornaments} +@node Ornaments +@subsection Ornaments +@cindex Ornaments +@menu +* Articulation:: +* Text scripts:: +* Grace notes:: +* Stem tremolo:: +* Arpeggio:: +* Glissando :: +* Dynamics:: +* Bar lines:: +* Breath marks:: +* Rehearsal marks:: +@end menu + +@c_ {Articulation} +@node Articulation +@subsubsection Articulation +@cindex Articulation + @cindex articulations @cindex scripts @cindex ornaments @@ -1062,7 +1315,12 @@ name of the corresponding symbol appearing underneath. @end lilypond -@unnumberedsubsec Text scripts +@c_ {Text scripts} +@node Text scripts +@subsubsection Text scripts +@cindex Text scripts + +FIXME: markup In addition, it is possible to place arbitrary strings of text or @TeX{} above or below notes by using a string instead of an @@ -1071,7 +1329,9 @@ 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. -@cindex fingering +@c_ {Fingerings} +@unnumberedsubsubsec Fingerings +@cindex Fingerings To save typing, fingering instructions (digits 0 to 9 are supported) and single characters shorthands exist for a few @@ -1143,105 +1403,17 @@ helpful identifier definitions appear in @file{script.ly}. -@unnumberedsubsec Dynamics - -@cindex @code{\ppp} -@cindex @code{\pp} -@cindex @code{\p} -@cindex @code{\mp} -@cindex @code{\mf} -@cindex @code{\f} -@cindex @code{\ff} -@cindex @code{\fff} -@cindex @code{\ffff} -@cindex @code{\fp} -@cindex @code{\sf} -@cindex @code{\sff} -@cindex @code{\sp} -@cindex @code{\spp} -@cindex @code{\sfz} -@cindex @code{\rfz} -@cindex crescendo -@cindex @code{\cr} -@cindex @code{\rc} -@cindex @code{\decr} -@cindex @code{\rced} -@cindex @code{\<} -@cindex @code{\>} -@cindex @code{\"!} - -Dynamic marks are specified by using an identifier after a note: -@code{c4-\ff} (the dash is optional for dynamics: `@code{c4 \ff})'. -The available dynamic marks are: -@code{\ppp}, -@code{\pp}, @code{\p}, @code{\mp}, -@code{\mf}, @code{\f}, @code{\ff}, -@code{\fff}, @code{\fff}, -@code{\fp}, @code{\sf}, -@code{\sff}, @code{\sp}, -@code{\spp}, @code{\sfz}, and -@code{\rfz}. - - -A crescendo mark is started with @code{\cr} and terminated with -@code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is -started with @code{\decr} and terminated with @code{\rced}. There are -also shorthands for these marks. A crescendo can be started with -@code{\<} and a decrescendo can be started with @code{\>}. Either one -can be terminated with @code{\!}. Note that @code{\!} must go before -the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go -after the last note. Because these marks are bound to notes, if you -want to get several marks during one note, you must use spacer notes. - -@lilypond[fragment,verbatim,center] - c'' \< \! c'' d'' \decr e'' \rced - < f''1 { s4 \< \! s2 \> \! s4 } > -@end lilypond - -[todo: text cr] - -@unnumberedsubsec Slurs -@cindex slur - -Slurs connects chords and try to avoid crossing stems. A slur is -started with @code{(} and stopped with @code{)}. The -starting @code{(} appears to the right of the first note in -the slur. The terminal @code{)} appears to the left of the -first note in the slur. This makes it possible to put a note in -slurs from both sides: - -@lilypond[fragment,verbatim,center] - f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 -@end lilypond - - -@unnumberedsubsec Spanners -@cindex @code{\spanrequest} - -@example - \spanrequest @var{startstop} @var{type} -@end example -@cindex @code{\start} -@cindex @code{\stop} - -Define a spanning request. The @var{startstop} parameter is either -1 -(@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that -describes what should be started. Supported types are @code{crescendo}, -@code{decrescendo}, @code{beam}, @code{slur}. This is an internal -command. Users should use the shorthands which are defined in the -initialization file @file{spanners.ly}. - -You can attach a (general) span request to a note using -@lilypond[fragment,verbatim,center] - c'4-\spanrequest \start "slur" - c'4-\spanrequest \stop "slur" -@end lilypond +@c_ {Grace notes} +@node Grace notes +@subsubsection Grace notes +@cindex Grace notes -The slur syntax with parentheses is a shorthand for this. +See @ref{Grace music}. +@c_ {Stem tremolo} @node Stem tremolo -@section Stem tremolo +@subsubsection Stem tremolo @cindex tremolo marks @cindex @code{tremoloFlags} @@ -1258,8 +1430,11 @@ no last value. c'2:8 c':32 @end lilypond -@section Arpeggio -@cindex argepeggio + +@c_ {Arpeggio} +@node Arpeggio +@subsubsection Arpeggio +@cindex Arpeggio @cindex broken arpeggio @cindex @code{\arpeggio} @@ -1293,8 +1468,12 @@ extended arpeggio sign is printed. @end lilypond @end quotation -@section Glissando -@cindex glissando + +@c_ {Glissando} +@node Glissando +@subsubsection Glissando +@cindex Glissando + @cindex @code{\glissando} A @rgrob{Glissando} line can be requested by issuing a @@ -1312,7 +1491,8 @@ A @rgrob{Glissando} line can be requested by issuing a Printing of the additional text @samp{gliss.} must be done manually. -@subsection Follow Thread +@c_ {Follow Thread} +@subsubsection Follow Thread @cindex follow thread @cindex staff switching @cindex cross staff @@ -1337,186 +1517,388 @@ switches to another staff. This is enabled if the property @end lilypond @end quotation -@node Compound music expressions -@section Compound music expressions - -@cindex compound music expressions - -Music expressions are compound data structures. You can nest music -expressions any way you like. This simple example shows how three -chords can be expressed in two different ways: - -@lilypond[fragment,verbatim,center] - \notes \context Staff { - - < { a b c' } { c' d' e' } > - } -@end lilypond - -@cindex @code{\context} -@cindex context selection -@example - \context @var{contexttype} [= @var{contextname}] @var{musicexpr} -@end example +@c_ {Dynamics} +@node Dynamics +@subsubsection Dynamics +@cindex Dynamics -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. +@unnumberedsubsec Dynamics -@cindex input modes +@cindex @code{\ppp} +@cindex @code{\pp} +@cindex @code{\p} +@cindex @code{\mp} +@cindex @code{\mf} +@cindex @code{\f} +@cindex @code{\ff} +@cindex @code{\fff} +@cindex @code{\ffff} +@cindex @code{\fp} +@cindex @code{\sf} +@cindex @code{\sff} +@cindex @code{\sp} +@cindex @code{\spp} +@cindex @code{\sfz} +@cindex @code{\rfz} -@cindex mode switch +Dynamic marks are specified by using an identifier after a note: +@code{c4-\ff} (the dash is optional for dynamics: `@code{c4 \ff})'. +The available dynamic marks are: +@code{\ppp}, +@code{\pp}, @code{\p}, @code{\mp}, +@code{\mf}, @code{\f}, @code{\ff}, +@code{\fff}, @code{\fff}, +@code{\fp}, @code{\sf}, +@code{\sff}, @code{\sp}, +@code{\spp}, @code{\sfz}, and +@code{\rfz}. -@cindex @code{\notes} -@cindex @code{\chords} -@cindex @code{\lyrics} +See also @ref{Crescendo and Decrescendo} -Mode switching keywords form compound music expressions: @code{\notes} -@var{musicexpr}, @code{\chords} @var{musicexpr}, -and @code{\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 @ref{Lexical modes} for more information on modes. -[to lexer modes?] +@c_ {Bar lines} +@node Bar lines +@subsubsection Bar lines +@cindex Bar lines -@unnumberedsubsec Sequential music -@cindex @code{\sequential} -@cindex sequential music +@cindex @code{\bar} +@cindex measure lines +@cindex repeat bars @example - \sequential @code{@{} @var{musicexprlist} @code{@}} + \bar @var{bartype}; @end example -This means that list should be played or written in sequence, i.e., -the second after the first, the third after the second. The duration -of sequential music is the the sum of the durations of the elements. -There is a shorthand, which leaves out the keyword: - +This is a short-cut for doing @example -@cindex @code{<} -@cindex @code{>} - - @code{@{} @var{musicexprlist} @code{@}} + \property Score.whichBar = @var{bartype} @end example +You are encouraged to use @code{\repeat} for repetitions. See +@ref{Repeat}, @ref{Volta}, and the documentation of @code{whichBar} in +@ref{(lilypond-internals)LilyPond context properties}. -@unnumberedsubsec Simultaneous music -@cindex simultaneous music -@cindex @code{\simultaneous} +[FIXME] -@example - \simultaneous @code{@{} @var{musicexprlist} @code{@}} -@end example +@c_ {Breath marks} +@node Breath marks +@subsubsection Breath marks +@cindex Breath marks -It constructs a music expression where all of its arguments start at -the same moment. The duration is the maximum of the durations of the -elements. The following shorthand is a common idiom: +@c_ {Rehearsal marks} +@node Rehearsal marks +@subsubsection Rehearsal marks +@cindex Rehearsal marks +@cindex mark +@cindex @code{\mark} @example - @code{<} @var{musicexprlist} @code{>} + \mark @var{unsigned}; +@cindex @code{Mark_engraver} + \mark @var{string}; @end example -If you try to use a chord as the first thing in your score, you might -get multiple staffs instead of a chord. - -@lilypond[verbatim,center] - \score { - \notes - \paper { - linewidth = -1.; - } - } -@end lilypond +Prints a mark over or under the staff. -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: -@lilypond[verbatim,center] - \score { - \notes\context Voice - \paper { - linewidth = -1.; - } - } -@end lilypond +@c_ {Bar check} +@node Bar check +@subsection Bar check +@cindex Bar check +@cindex bar check +@cindex @code{barCheckNoSynchronize} +@cindex @code{|} +Bar checks help you find errors in the input: Whenever one is +encountered during interpretation, a warning message is issued if it +doesn't fall at a measure boundary. Depending on the value of +@code{barCheckNoSynchronize}, the beginning of the measure will be +relocated, so this can also be used to shorten measures. -@node Relative octaves -@section Relative octaves -@cindex relative octave specification +A bar check is entered using the bar symbol, @code{|} -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 -note's octave is `the relative octave' mode. +This can help you finding errors in the input. -@cindex @code{\relative} -@example - \relative @var{startpitch} @var{musicexpr} -@end example -The octave of notes that appear in @var{musicexpr} are calculated as -follows: If no octave changing marks are used, the basic interval -between this and the last note is always taken to be a fourth or -less.@footnote{The interval is determined without regarding -accidentals. A @code{fisis} following a @code{ceses} will be put above -the @code{ceses}.} The octave changing marks @code{'} and @code{,} -can then be added to raise or lower the pitch by an extra octave. -Upon entering relative mode, an absolute starting pitch must be -specified that will act as the predecessor of the first note of -@var{musicexpr}. +@c_ {Lyrics entry} +@node Lyrics entry +@section Lyrics entry +@cindex Lyrics entry -Entering scales is straightforward in relative mode. +@menu +* Lyrics mode:: +* Printing lyrics:: +* Lyric hyphen:: +* Lyric extender:: +* Addlyrics:: +@end menu -@lilypond[fragment,verbatim,center] - \relative c' { - c d e f g a b c c, - } -@end lilypond +@c_ {Lyrics mode} +@node Lyrics mode +@subsection Lyrics mode +@cindex Lyrics mode -And octave changing marks are used for intervals greater than a fourth. +@cindex lyric mode +@cindex @code{\lyrics} + +Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has +rules that make it easy to include punctuation and diacritical marks in +words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{} +format or a standard encoding without needing quotes. The precise +definition of this mode is ludicrous, and this will remain so until the +authors of LilyPond acquire a deeper understanding of character +encoding, or someone else steps up to fix this. + +A word in Lyrics mode begins with: an alphabetic character, @code{_}, +@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A} +through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^}, +any 8-bit character with ASCII code over 127, or a two-character +combination of a backslash followed by one of @code{`}, @code{'}, +@code{"}, or @code{^}. + +Subsequent characters of a word can be any character that is not a digit +and not white space. One important consequence of this is that a word +can end with `@code{@}}', which may be confusing. However, LilyPond will +issue a warning. Any @code{_} character which appears in an unquoted +word is converted to a space. This provides a mechanism for introducing +spaces into words without using quotes. Quoted words can also be used +in Lyrics mode to specify words that cannot be written with the above +rules. Here are some examples. Not all of these words are printable by +@TeX{}. + +@example +Ah! % a word +2B_||_!2B % not a word because it starts with a digit +``Hello'' % not a word because it starts with ` +_ _ _ _ % 4 words, each one a space +@end example + +Since combinations of numbers and dots are used for indicating +durations, you can not enter real numbers in this mode. + +[todo: include short table showing differences] + +@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 @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 @ref{lyricprint}. + + +@c_ {Printing Lyrics} +@node Printing lyrics +@subsection lyricprint +@cindex lyrics + + +@cindex printing!lyrics + + +Lyric syllables must be interpreted within a @code{Lyrics} context + +@cindex context!Lyrics + for printing them. + +Here is a full example: + +@quotation +@lilypond[verbatim] +\score { + < + \notes \transpose c'' { + c d e c | c d e c | + e f g2 | e4 f g2 \bar "|."; + } + \context Lyrics \lyrics { + Va-4 der Ja- cob Va- der Ja- cob + Slaapt gij nog?2 Slaapt4 gij nog?2 + } + > +} -@lilypond[fragment,verbatim,center] - \relative c'' { - c g c f, c' a, e'' } @end lilypond +@end quotation -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. +You may want a continuous line after the syllables to show melismata. +To achieve this effect, add a @code{__} lyric as a separate word +after the lyric to be extended. This will create an extender, a line +that extends over the entire duration of the lyric. This line will +run all the way to the start of the next lyric, so you may want to +shorten it by using a blank lyric (using @code{_}). -@lilypond[fragment,verbatim,center] - \relative c' { - c - - - } -@end lilypond -@cindex @code{\notes} +@quotation -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 -be a surrounding @code{\notes} keyword (which is not -shown here). +@lilypond[verbatim] +\score { + < + \notes \relative c'' { + a4 () b () c () d | c () d () b () a | c () d () b () a + } + \context Lyrics \lyrics { + foo1 __ | bar2. __ _4 | baz1 __ + } + > +} -The relative conversion will not affect @code{\transpose} or -@code{\relative} sections in its argument. If you want to use -relative within transposed music, you must place an additional -@code{\relative} inside the @code{\transpose}. +@end lilypond +@end quotation + + +If you want to have hyphens centered between syllables (rather than +attached to the end of the first syllable) you can use the special +`@code{-}@code{-}' lyric as a separate word between syllables. This +will result in a hyphen which length varies depending on the space +between syllables, and which will be centered between the syllables. +For example: + +@quotation + +@lilypond[verbatim] +\score { + < + \notes \transpose c'' { + c d e c | c d e c | + e f g2 | e4 f g2 \bar "|."; + } + \context Lyrics \lyrics { + Va4 -- der Ja -- cob | Va -- der Ja -- cob | + Slaapt gij nog?2 | Slaapt4 gij nog?2 + } + > +} + +@end lilypond +@end quotation + + + + +@c_ {Lyric hyphen} +@node Lyric hyphen +@subsection Lyric hyphen +@cindex Lyric hyphen + +The syntax for a spanning hyphen (i.e., a hyphen that will be printed +between two lyric syllables) is `@code{-}@code{-}'. + +@c_ {Lyric extender} +@node Lyric extender +@subsection Lyric extender +@cindex Lyric extender +@cindex extender +@cindex lyric extender +@cindex hyphen + +The syntax for an extender mark is @code{__}. This syntax can only +be used within lyrics mode. + + + + +@c_ {Addlyrics} +@node Addlyrics +@subsection Addlyrics +@cindex Addlyrics + + +[explain automatic phrasing] +@cindex automatic lyric durations +@cindex @code{\addlyrics} + +If you have lyrics that are set to a melody, you can import the rhythm +of that melody into the lyrics using @code{\addlyrics}. The syntax for +this is +@example + \addlyrics @var{musicexpr1 musicexpr2} +@end example + +This means that both @var{musicexpr1} and @var{musicexpr2} are +interpreted, but that every non-command atomic music expression +(``every syllable'') in @var{musicexpr2} is interpreted using timing +of @var{musicexpr1}. +@cindex @code{automaticMelismata} + +If the property @code{automaticMelismata} is set in the +context of @var{musicexpr1}, no lyrics will be put on slurred or tied +notes. + +@quotation +@lilypond[verbatim,fragment] +\addlyrics +\transpose c'' { + \property Voice.automaticMelismata = ##t + c8 () cis d8. e16 f2 +} +\context Lyrics \lyrics { + do4 re mi fa } +@end lilypond +@end quotation + +You should use a single rhythm melody, and single rhythm lyrics (a +constant duration is the obvious choice). If you do not, you will get +undesired effects when using multiple stanzas: + +@quotation +@lilypond[verbatim,fragment] +\addlyrics +\transpose c'' { + c8 () cis d8. e16 f2 +} +\context Lyrics \lyrics +< { do4 re mi fa } + { do8 re mi fa } > + +@end lilypond +@end quotation + +It is valid (but probably not very useful) to use notes instead of +lyrics for @var{musicexpr2}. -It is strongly recommended to use relative pitch mode: less work, -less error-prone, and more readable. + +@c_ {Chord entry} +@node Chord entry +@section Chord entry +@cindex Chord entry + +@menu +* Chords mode:: +* Entering named chords:: +* Printing named chords:: +@end menu + +@c_ {Chords mode} +@node Chords mode +@subsection Chords mode +@cindex Chords mode + +Chord mode is introduced by the keyword +@code{\chords}. It is similar to Note mode, but +words are also looked up in a chord modifier table (containing +@code{maj}, @code{dim}, etc). + +Since combinations of numbers and dots are used for indicating +durations, you can not enter real numbers in this mode. Dashes +and carets are used to indicate chord additions and subtractions, +so scripts can not be entered in Chord mode. + +@c_ {Entering named chords} @node Entering named chords -@unnumberedsubsec named chords +@subsection Entering named chords +@cindex Chords names Chord names are a way to generate simultaneous music expressions that correspond with traditional chord names. It can only be used in @@ -1629,765 +2011,843 @@ See @ref{Chord names}. You should not combine @code{\relative} with named chords. [FIXME] +@c_ {Printing named chords} +@node Printing named chords +@subsection Printing named chords -@unnumberedsubsec Tuplets -@cindex tuplets +@cindex chord names +@cindex chords -Tuplets are made out of a music expression by multiplying their -duration with a fraction. +@cindex printing!chord names +@cindex @code{ChordNames} +@cindex @code{ChordNameVoice} -@cindex @code{\times} -@example - \times @var{fraction} @var{musicexpr} -@end example +For displaying printed chord names, use the @code{ChordNames} and +@code{ChordNameVoice} contexts. The chords may be entered either using +the notation described above, or directly using simultaneous music. -The duration of @var{musicexpr} will be multiplied by the fraction. -In print, the fraction's denominator will be printed over the notes, -optionally with a bracket. The most common tuplet is the triplet in -which 3 notes have the length of 2, so the notes are 2/3 of -their written length: - -@lilypond[fragment,verbatim,center] - g'4 \times 2/3 {c'4 c' c'} d'4 d'4 +@quotation +@lilypond[verbatim] +scheme = \notes { + \chords {a1 b c} +} +\score { + \notes< + \context ChordNamesVoice \scheme + \context Staff \transpose c'' \scheme + > + \paper { linewidth = -1.; } +} @end lilypond -@cindex @code{\grace} - - -@unnumberedsubsec Grace notes - -@cindex ornaments -@cindex grace notes -@cindex @code{graceAlignPosition} - -@example - \grace @var{musicexpr} -@end example - -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 -@code{graceAlignPosition}. -@cindex @code{flagStyle} +@end quotation -When grace music is interpreted, a score-within-a-score is set up: -@var{musicexpr} has its own time bookkeeping, and you could (for -example) have a separate time signature within grace notes. While in -this score-within-a-score, you can create notes, beams, slurs, etc. -Unbeamed eighth notes and shorter by default have a slash through the -stem. This behavior can be controlled with the -@code{flagStyle} property. +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[fragment,verbatim] -\relative c'' { - \grace c8 c4 \grace { [c16 c16] } c4 - \grace { \property Grace.flagStyle = "" c16 } c4 +@lilypond[verbatim] +scheme = \chords { + c1:m \break c:m c:m c:m d } +\score { + \notes < + \context ChordNames \scheme + \context Staff \transpose c'' \scheme + > + \paper{ + linewidth = 40 * \staffspace; + \translator { + \ChordNamesContext + chordChanges = ##t + } + } +} @end lilypond @end quotation -@cindex @code{\grace} - -At present, nesting @code{\grace} notes is not supported. The following -may cause run-time errors: -@example - @code{\grace @{ \grace c32 c16 @} c4} -@end example -Since the meaning of such a construct is unclear, we don't consider -this a loss. Similarly, juxtaposing two @code{\grace} sections is -syntactically valid, but makes no sense and may cause runtime errors. - -Ending a staff or score with grace notes may also generate a run-time -error, since there will be no main note to attach the grace notes to. - -The present implementation is not robust and generally kludgy. We expect -it to change after LilyPond 1.4 - - -@node Repeats -@section Repeats -@cindex repeats - -@cindex @code{\repeat} - -In order to specify repeats, use the @code{\repeat} -keyword. Since repeats look and sound differently when played or -printed, there are a few different variants of repeats. - -@table @asis -@item unfolded -Repeated music is fully written (played) out. Useful for MIDI -output. - -@item volta -This is the normal notation: Repeats are not written out, but -alternative endings (voltas) are printed, left to right. - -@item folded -Alternative endings are written stacked. Which is unfortunately not -practical for anything right now. - -@item tremolo -Make tremolo beams. -@end table - -The syntax for repeats is - -@example - \repeat @var{variant} @var{repeatcount} @var{repeatbody} -@end example -If you have alternative endings, you may add - -@cindex @code{\alternative} -@example - \alternative @code{@{} @var{alternative1} - @var{alternative2} - @var{alternative3} @dots{} @code{@}} -@end example -where each @var{alternative} is a Music expression. -Normal notation repeats are used like this: +LilyPond examines chords specified as lists of notes to determine a +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: @quotation +@lilypond[verbatim,center] +scheme = \notes { + + + +} -@lilypond[fragment,verbatim] - c'1 - \repeat volta 2 { c'4 d' e' f' } - \repeat volta 2 { f' e' d' c' } - +\score { + < + \context ChordNamesVoice \scheme + \context Staff \scheme + > + \paper { linewidth = -1.; } +} @end lilypond @end quotation -With alternative endings: +To specify chord inversions, append @code{/}. To specify an +added bass note, append @code{/+ + \paper { linewidth = -1.; } +} @end lilypond @end quotation -Folded repeats look like this:@footnote{Folded repeats offer little -more over simultaneous music. However, it is to be expected that -more functionality -- especially for the MIDI backend -- will be -implemented.} - -@quotation - -@lilypond[fragment,verbatim] - c'1 - \repeat fold 2 {c'4 d' e' f'} - \alternative { {d'2 d'} {f' f} } - -@end lilypond -@end quotation +The chord names that LilyPond should print are fully customizable. The +code to print chord names is written in Scheme. It 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 property @code{ChordName.style} +to @code{american}: @quotation +@lilypond[verbatim] +\include "english.ly" -@lilypond[fragment,verbatim] -\context Staff { - \relative c' { - \partial 4; - \repeat volta 2 { e | c2 d2 | e2 f2 | } - \alternative { { g4 g g } { a | a a a a | b1 } } - } +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 } -@end lilypond -@end quotation - -If you don't give enough alternatives for all of the repeats, then -the first alternative is assumed to be repeated often enough to equal -the specified number of repeats. - -@quotation -@lilypond[fragment,verbatim] -\context Staff { - \relative c' { - \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | } - \alternative { { g4 g g } - {\partial 1; e4 e e } - {\partial 1; a a a a | b1 } } +\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 -As you can see, LilyPond doesn't remember the timing information, nor -are slurs or ties repeated. We hope to fix this after 1.4. - -It is possible to nest @code{\repeat}. This is not entirely -supported: the notes will come be in the right places, but the repeat -bars will not. +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 -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. + % 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 -@lilypond[verbatim,center] -\score { - \context Voice \notes\relative c' { - \repeat "tremolo" 8 { c16 d16 } - \repeat "tremolo" 4 { c16 d16 } - \repeat "tremolo" 2 { c16 d16 } - } + % 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 { - linewidth = 40*\staffspace; - } + \translator { + \ChordNamesContext + ChordName \override #'word-space = #1 + ChordName \override #'style = #'jazz + } + } } @end lilypond -@cindex @code{__} +@end quotation -@lilypond[fragment,verbatim,center] - c'4:32 -@end lilypond +@c_ {Page layout} +@node Page layout +@section Page layout +@cindex Page layout +@menu +* Paper block:: +* Paper variables:: +* Font Size:: +* Paper size:: +* Line break:: +* Page break:: +@end menu +@c_ {Paper block} +@node Paper block +@subsection Paper block +@cindex Paper block -@node transpose -@section Transposition -@cindex transposition of pitches -@cindex @code{\transpose} +The most important output definition is the @code{\paper} block, for +music notation. The syntax is -A music expression can be transposed with @code{\transpose}. The syntax -is @example - \transpose @var{pitch} @var{musicexpr} + @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}} @end example -This means that middle C in @var{musicexpr} is transposed to -@var{pitch}. - -@code{\transpose} distinguishes between enharmonic pitches: both -@code{\transpose cis'} or @code{\transpose des'} will transpose up half -a tone. The first version will print sharps and the second version -will print flats. +where each of the items is one of -@quotation -@lilypond[fragment,verbatim] -\context Staff { - \clef "F"; - { \key e \major; c d e f } - \clef "G"; - \transpose des'' { \key e \major; c d e f } - \transpose cis'' { \key e \major; c d e f } -} +@itemize @bullet + @item An assignment. The assignment must be terminated by a + semicolon. -@end lilypond -@end quotation + @item A context definition. See section @ref{contextdefs} for + more information on context definitions. -If you want to use both @code{\transpose} and @code{\relative}, then -you must use @code{\transpose} first. @code{\relative} will have no -effect music that appears inside a @code{\transpose}. +@ignore -@unnumberedsubsec Adding melodies to lyrics -@cindex automatic lyric durations -@cindex @code{\addlyrics} + FIXME -If you have lyrics that are set to a melody, you can import the rhythm -of that melody into the lyrics using @code{\addlyrics}. The syntax for -this is -@example - \addlyrics @var{musicexpr1 musicexpr2} -@end example -This means that both @var{musicexpr1} and @var{musicexpr2} are -interpreted, but that every non-command atomic music expression -(``every syllable'') in @var{musicexpr2} is interpreted using timing -of @var{musicexpr1}. -@cindex @code{automaticMelismata} + @item + + A margin shape declaration. The syntax is +@cindex @code{\shape} + @example -If the property @code{automaticMelismata} is set in the -context of @var{musicexpr1}, no lyrics will be put on slurred or tied -notes. + \shape @var{indent1}@code{,} @var{width1}@code{,} + @var{indent2}@code{,} @var{width2} @dots{} @code{;} + @end example -@quotation -@lilypond[verbatim,fragment] -\addlyrics -\transpose c'' { - \property Voice.automaticMelismata = ##t - c8 () cis d8. e16 f2 -} -\context Lyrics \lyrics { - do4 re mi fa } -@end lilypond -@end quotation + -You should use a single rhythm melody, and single rhythm lyrics (a -constant duration is the obvious choice). If you do not, you will get -undesired effects when using multiple stanzas: + Each pair of @var{indent} and @var{width} values is a dimension + specifying how far to indent and how wide to make the line. + The indentation and width of successive lines are specified by + the successive pairs of dimensions. The last pair of + dimensions will define the characeristics of all lines beyond + those explicitly specified. +@end ignore -@quotation -@lilypond[verbatim,fragment] -\addlyrics -\transpose c'' { - c8 () cis d8. e16 f2 -} -\context Lyrics \lyrics -< { do4 re mi fa } - { do8 re mi fa } > + @item \stylesheet declaration. Its syntax is + @example + \stylesheet @var{alist} + @end example -@end lilypond -@end quotation + See @file{font.scm} for details of @var{alist}. +@end itemize -It is valid (but probably not very useful) to use notes instead of -lyrics for @var{musicexpr2}. +@c_ {Paper variables} +@node Paper variables +@subsection Paper variables +@cindex Paper variables -@node Transforming music -@unnumberedsubsec Apply -@unnumberedsubsec Transforming music +The paper block has some variables you may want to use or change: -Apply allows a Scheme-function to operate directly on the internal -representation of music. -@example - \apply #@var{func} @var{music} -@end example -The function takes two arguments, being a function and an musical -argument for that function. The function should return a music -expression. +@table @code +@cindex @code{indent} + @item @code{indent} + The indentation of the first line of music. +@cindex @code{staffspace} -This example replaces the text string of a script. It also shows a dump -of the music it processes. -@lilypond[verbatim] -#(define (testfunc x) - (if (eq? (ly-get-mus-property x 'text) "foo") - (ly-set-mus-property x 'text "bar")) - ;; recurse - (ly-set-mus-property x 'elements - (map testfunc (ly-get-mus-property x 'elements))) - (display x) - x -) -\score { \notes - \apply #testfunc { c4_"foo" } -} -@end lilypond + @item @code{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. + +@cindex @code{linewidth} + @item @code{linewidth} + Sets the width of the lines. If set to -1.0, a single + 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 +@cindex @code{textheight} -For more information on what is possible, see the @ref{Tricks} and the -automatically generated documentation. + @item @code{textheight} + Sets the total height of the music on each page. Only used by + ly2dvi. +@cindex @code{interscoreline} + @item @code{interscoreline} + Sets the spacing between the score lines. Defaults to 16 pt. +@cindex @code{interscorelinefill} -@node Ambiguities -@section Ambiguities -@cindex ambiguities -@cindex grammar + @item @code{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. +@cindex @code{stafflinethickness} + @item @code{stafflinethickness} + Determines the thickness of staff lines, and also acts as a scaling + parameter for other line thicknesses. +@end table -The grammar contains a number of ambiguities. We hope to resolve them at -some time. -@itemize @bullet - @item The assignment +@c_ {Font size} +@node Font Size +@subsection Font size +@cindex font size - @example -foo = bar -@end example +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. - can be interpreted as making a string identifier @code{\foo} - containing @code{"bar"}, or a music identifier @code{\foo} - containing the syllable `bar'. +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. - @item The assignment +The font definitions are generated using a Scheme function. For more +details, see the file @file{font.scm}. - @example -foo = -6 -@end example - can be interpreted as making an integer identifier - containing -6, or a Request identifier containing the - fingering `6' (with neutral direction). - @item If you do a nested repeat like +@c_ {Paper size} +@node Paper size +@subsection Paper size +@cindex Paper size - @quotation +@cindex paper size +@cindex page size +@cindex @code{papersize} -@example -\repeat @dots{} -\repeat @dots{} -\alternative -@end example +To change the paper size, you must first set the +@code{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. - @end quotation +@example + papersize = "a4" + \include "paper16.ly" - then it is ambiguous to which @code{\repeat} the - @code{\alternative} belongs. This is the classic if-then-else - dilemma. It may be solved by using braces. + \score @{ + ... + \paper @{ \paperSixteen @} + @} +@end example - @item (an as yet unidentified ambiguity :-) -@end itemize +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 Automatic Beaming -@section Automatic Beaming -@cindex automatic beam generation -@cindex autobeam -@cindex @code{Voice.noAutoBeaming} -By default, LilyPond will generate beams automatically. This feature -can be disabled by setting the @code{Voice.noAutoBeaming} property to -true. It can be overridden for specific cases by specifying explicit -beams. -@cindex @code{Voice.autoBeamSettings} -@cindex @code{(end * * * *)} -@cindex @code{(begin * * * *)} -A large number of Voice properties are used to decide how to generate -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}. -To end beams every quarter note, for example, you could set the property -@code{(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 * * * *)}, eg: -@quotation +@c_ {Line break} +@node Line break +@subsection Line break +@cindex Line break + + +@cindex @code{\penalty} + @example -\property Voice.autoBeamSettings \override - #'(end * * * *) = #(make-moment 1 4) -\property Voice.autoBeamSettings \override - #'(begin * * * *) = #(make-moment 1 8) + \penalty @var{int} @code{;} @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 * *)}. +Discourage or encourage line breaks. See @ref{Page layout}. -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)}. -@node Printing named chords -@section Printing named chords -@cindex chord names -@cindex chords +@cindex line breaks +@cindex breaking lines -@cindex printing!chord names -@cindex @code{ChordNames} -@cindex @code{ChordNameVoice} +Line breaks are normally computed automatically. They are chosen such +that the resulting spacing has low variation, and looks neither cramped +nor loose. -For displaying printed chord names, use the @code{ChordNames} and -@code{ChordNameVoice} contexts. The chords may be entered either using -the notation described above, or directly using simultaneous music. +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 "";}. -@quotation -@lilypond[verbatim] -scheme = \notes { - \chords {a1 b c} -} -\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 -} -\score { - \notes < - \context ChordNames \scheme - \context Staff \transpose c'' \scheme - > - \paper{ - linewidth = 40 * \staffspace; - \translator { - \ChordNamesContext - chordChanges = ##t - } - } -} -@end lilypond -@end quotation +@c_ {Page break} +@node Page break +@subsection Page break +@cindex Page break +Not implemented, but see @ref{Tricks} -LilyPond examines chords specified as lists of notes to determine a -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: +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} -@quotation -@lilypond[verbatim,center] -scheme = \notes { - - - -} -\score { - < - \context ChordNamesVoice \scheme - \context Staff \scheme - > - \paper { linewidth = -1.; } -} -@end lilypond -@end quotation +@cindex page breaks +@cindex breaking pages -To specify chord inversions, append @code{/}. To specify an -added bass note, append @code{/+ - \paper { linewidth = -1.; } -} -@end lilypond -@end quotation -The chord names that LilyPond should print are fully customizable. The -code to print chord names is written in Scheme. It 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 property @code{ChordName.style} -to @code{american}: -@quotation -@lilypond[verbatim] -\include "english.ly" +@c_ {Sound} +@node Sound +@section Sound +@cindex Sound +@menu +* MIDI block:: +* MIDI instrument names:: +* Tempo:: +@end menu -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 -} +@c_ {MIDI block} +@node MIDI block +@subsection MIDI block +@cindex MIDI block -\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 +The MIDI block is analogous to the paper block, but it is somewhat +simpler. The @code{\midi} block can contain: +@cindex MIDI block - % 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 +@itemize @bullet + @item a @code{\tempo} definition + @item context definitions +@end itemize - % 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) +Assignments in the @code{\midi} block are not allowed. - % 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 +@cindex context definition +Context definitions follow precisely the same syntax as within the +\paper block. Translation modules for sound are called performers. +The contexts for MIDI output are defined in @file{ly/performer.ly}. -@node Printing lyrics -@section lyricprint -@cindex lyrics -@cindex printing!lyrics +@c_ {MIDI instrument names} +@node MIDI instrument names +@subsection MIDI instrument names +@cindex instrument names +@cindex @code{Staff.midiInstrument} +@cindex @code{Staff.instrument} +The MIDI instrument name is set by the @code{Staff.midiInstrument} +property or, if that property is not set, the @code{Staff.instrument} +property. The instrument name should be chosen from the following list. +If the selected string does not exactly match, then LilyPond uses the +default piano. -Lyric syllables must be interpreted within a @code{Lyrics} context +[FIXME: to appendix ] -@cindex context!Lyrics - for printing them. -Here is a full example: +@example +"acoustic grand" "contrabass" "lead 7 (fifths)" +"bright acoustic" "tremolo strings" "lead 8 (bass+lead)" +"electric grand" "pizzicato strings" "pad 1 (new age)" +"honky-tonk" "orchestral strings" "pad 2 (warm)" +"electric piano 1" "timpani" "pad 3 (polysynth)" +"electric piano 2" "string ensemble 1" "pad 4 (choir)" +"harpsichord" "string ensemble 2" "pad 5 (bowed)" +"clav" "synthstrings 1" "pad 6 (metallic)" +"celesta" "synthstrings 2" "pad 7 (halo)" +"glockenspiel" "choir aahs" "pad 8 (sweep)" +"music box" "voice oohs" "fx 1 (rain)" +"vibraphone" "synth voice" "fx 2 (soundtrack)" +"marimba" "orchestra hit" "fx 3 (crystal)" +"xylophone" "trumpet" "fx 4 (atmosphere)" +"tubular bells" "trombone" "fx 5 (brightness)" +"dulcimer" "tuba" "fx 6 (goblins)" +"drawbar organ" "muted trumpet" "fx 7 (echoes)" +"percussive organ" "french horn" "fx 8 (sci-fi)" +"rock organ" "brass section" "sitar" +"church organ" "synthbrass 1" "banjo" +"reed organ" "synthbrass 2" "shamisen" +"accordion" "soprano sax" "koto" +"harmonica" "alto sax" "kalimba" +"concertina" "tenor sax" "bagpipe" +"acoustic guitar (nylon)" "baritone sax" "fiddle" +"acoustic guitar (steel)" "oboe" "shanai" +"electric guitar (jazz)" "english horn" "tinkle bell" +"electric guitar (clean)" "bassoon" "agogo" +"electric guitar (muted)" "clarinet" "steel drums" +"overdriven guitar" "piccolo" "woodblock" +"distorted guitar" "flute" "taiko drum" +"guitar harmonics" "recorder" "melodic tom" +"acoustic bass" "pan flute" "synth drum" +"electric bass (finger)" "blown bottle" "reverse cymbal" +"electric bass (pick)" "skakuhachi" "guitar fret noise" +"fretless bass" "whistle" "breath noise" +"slap bass 1" "ocarina" "seashore" +"slap bass 2" "lead 1 (square)" "bird tweet" +"synth bass 1" "lead 2 (sawtooth)" "telephone ring" +"synth bass 2" "lead 3 (calliope)" "helicopter" +"violin" "lead 4 (chiff)" "applause" +"viola" "lead 5 (charang)" "gunshot" +"cello" "lead 6 (voice)" +@end example + + + + + +@c_ {Tempo} +@node Tempo +@subsection Tempo +@cindex Tempo +@cindex beats per minute +@cindex metronome marking + +@cindex @code{\tempo} +@example + \tempo @var{duration} = @var{perminute} @code{;} +@end example + +Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests +output with 76 quarter notes per minute. + + + + + +@c_ {Music entry} +@node Music entry +@section Music entry +@cindex Music entry +@menu +* Pre-defined Identifiers:: +* Point and click:: +@end menu + +@c_ {Music entry} +@node Pre-defined Identifiers +@subsection Pre-defined Identifiers +@cindex 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} and @file{ly/property.ly}. + +@table @code +@cindex @code{\break} + @item @code{\break} + Force a line break in music by using a large argument for the + keyword @code{\penalty}. + +@cindex @code{\nobreak} + @item @code{\nobreak} + Prevent a line break in music by using a large negative argument + for the keyword @code{\penalty}. + +@cindex @code{\shiftOff} + @item @code{\shiftOff} + Disable horizontal shifting of note heads that collide. + +@cindex @code{\shiftOn} + @item @code{\shiftOn} + Enable note heads that collide with other note heads to be + shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn} +set different shift values. + +@cindex @code{\stemBoth} + @item @code{\stemBoth} + Allow stems, beams, and slurs to point either upwards or + downwards, decided automatically by LilyPond. + +@cindex @code{\stemDown} + @item @code{\stemDown} + Force stems, beams, and slurs to point down. + +@cindex @code{\stemUp} + @item @code{\stemUp} + Force stems, beams and slurs to point up. + +@end table + + +@c_ {Point and click} +@node Point and click +@subsection Point and click + +[todo] + +@c_ {Engravers} +@node Engravers +@section Engravers +@cindex engravers +@menu +* Context definitions:: +* Notation Contexts:: +@end menu + +@c_ {Context definitions} +@node Context definitions +@subsection Context definitions + +@cindex context definition +@cindex translator definition +@cindex engraver hacking + + +A notation contexts is defined by the following information + +@enumerate 1 + @item A name. + + @item The LilyPond modules that do the actual conversion of music to + notation. Each module is a so-called + @emph{engraver} +@cindex engraver +. + + @item How these modules should cooperate, i.e. which ``cooperation + module'' should be used. This cooperation module is a special + type of engraver. + + @item What other contexts the context can contain, + + @item What properties are defined. +@end enumerate + +A context definition has this syntax: + +@example + + \translator @code{@{} + @var{translatorinit} @var{translatormodifierlist} + @code{@}} +@end example + +@var{translatorinit} can be an identifier or of the form + +@example + + \type @var{typename} @code{;} +@end example + +@var{typename} is one of + +@table @code +@cindex @code{Engraver_group_engraver} + @item @code{Engraver_group_engraver} + The standard cooperation engraver. +@cindex @code{Score_engraver} + + @item @code{Score_engraver} + This is cooperation module that should be in the top level context. +@cindex @code{Grace_engraver_group} + + @item @code{Grace_engraver_group} + This is a special cooperation module (resembling + @code{Score_engraver}) that is used to created an embedded + `miniscore'. +@end table + +@var{translatormodifierlist} is a list of items where each item is +one of + +@itemize @bullet + @item @code{\consists} @var{engravername} @code{;} + Add @var{engravername} to the list of modules in this context. + The order of engravers added with @code{\consists} is + significant. + + @item @code{\consistsend} @var{engravername} @code{;} + Analogous to @code{\consists}, but makes sure that + @var{engravername} is always added to the end of the list of + engravers. + + Some engraver types need to be at the end of the list; this + insures they are put there, and stay there, if a user adds or + removes engravers. This command is usually not needed for + end-users. + + @item @code{\accepts} @var{contextname} @code{;} + Add @var{contextname} to the list of context this context can + 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. + + @item @code{\name} @var{contextname} @code{;} + This sets name of the context, e.g. @code{Staff}, @code{Voice}. If + the name is not specified, the translator won't do anything. + + @item @var{propname} @code{=} @var{value} @code{;} + A property assignment. It is allowed to use reals for + @var{value}. +@end itemize + +In the @code{\paper} block, it is also possible to define translator +identifiers. Like other block identifiers, the identifier can only +be used as the very first item of a translator. In order to define +such an identifier outside of @code{\score}, you must do @quotation -@lilypond[verbatim] -\score { - < - \notes \transpose c'' { - c d e c | c d e c | - e f g2 | e4 f g2 \bar "|."; - } - \context Lyrics \lyrics { - Va-4 der Ja- cob Va- der Ja- cob - Slaapt gij nog?2 Slaapt4 gij nog?2 - } - > -} -@end lilypond -@end quotation +@example +\paper @{ + foo = \translator @{ @dots{} @} +@} +\score @{ + \notes @{ + @dots{} + @} + \paper @{ + \translator @{ \foo @dots{} @} + @} +@} +@end example + +@end quotation + + +@cindex paper types, engravers, and pre-defined translators + +Some pre-defined identifiers can simplify modification of +translators. The pre-defined identifiers are: + +@table @code +@cindex @code{StaffContext} + @item @code{StaffContext} + Default Staff context. +@cindex @code{RhythmicStaffContext} + + @item @code{RhythmicStaffContext} + Default RhythmicStaff context. +@cindex @code{VoiceContext} + + @item @code{VoiceContext} + Default Voice context. +@cindex @code{ScoreContext} + + @item @code{ScoreContext} + Default Score context. +@cindex @code{ScoreWithNumbers} -You may want a continuous line after the syllables to show melismata. -To achieve this effect, add a @code{__} lyric as a separate word -after the lyric to be extended. This will create an extender, a line -that extends over the entire duration of the lyric. This line will -run all the way to the start of the next lyric, so you may want to -shorten it by using a blank lyric (using @code{_}). + @item @code{ScoreWithNumbers} + Score context with numbering at the Score level. +@cindex @code{BarNumberingStaffContext} -@quotation + @item @code{BarNumberingStaffContext} + Staff context with numbering at the Staff level. +@cindex @code{HaraKiriStaffContext} -@lilypond[verbatim] -\score { - < - \notes \relative c'' { - a4 () b () c () d | c () d () b () a | c () d () b () a - } - \context Lyrics \lyrics { - foo1 __ | bar2. __ _4 | baz1 __ - } - > -} + @item @code{HaraKiriStaffContext} + Staff context that does not print if it only contains rests. + Useful for orchestral scores.@footnote{Harakiri, also called + Seppuku, is the ritual suicide of the Japanese Samourai warriors.} +@cindex @code{OrchestralPartStaffContext} -@end lilypond -@end quotation + @item @code{OrchestralPartStaffContext} +@cindex @code{OrchestralScoreContext} - -If you want to have hyphens centered between syllables (rather than -attached to the end of the first syllable) you can use the special -`@code{-}@code{-}' lyric as a separate word between syllables. This -will result in a hyphen which length varies depending on the space -between syllables, and which will be centered between the syllables. -For example: + @item @code{OrchestralScoreContext} +@end table + +Using these pre-defined values, you can remove or add items to the +translator: @quotation -@lilypond[verbatim] -\score { - < - \notes \transpose c'' { - c d e c | c d e c | - e f g2 | e4 f g2 \bar "|."; - } - \context Lyrics \lyrics { - Va4 -- der Ja -- cob | Va -- der Ja -- cob | - Slaapt gij nog?2 | Slaapt4 gij nog?2 - } - > -} +@example +\paper @{ + \translator @{ + \StaffContext + \remove Some_engraver; + \consists Different_engraver; + @} +@} +@end example -@end lilypond @end quotation + +@c_ {Notation Contexts} @node Notation Contexts -@section Notation Contexts +@subsection Notation Contexts @cindex notation contexts @@ -2539,513 +2999,554 @@ notation are called @emph{engravers}, and translators for sound are called @emph{performers}. -@mbinclude properties.itely -@node Page layout -@section Page layout +@c_ {Lexer innards} +@node Lexer innards +@section Lexer innards +@cindex Lexer innards +@menu +* Top level:: +* Identifiers:: +* Assignments:: +* Lexical details:: +* Lexical modes:: +* Ambiguities:: +@end menu -@subsection Paper block +@c_ {Top level} +@node Top level +@subsection Top level +@cindex Top level -The most important output definition is the @code{\paper} block, for -music notation. The syntax is +This section describes what you may enter at top level. + + +@unnumberedsubsec Score definition +@cindex score definition + +The output is generated combining a music expression with an output +definition. A score block has the following syntax: @example - @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}} + \score @{ @var{musicexpr} @var{outputdefs} @} @end example -where each of the items is one of +@var{outputdefs} are zero or more output definitions. If no output +definition is supplied, the default @code{\paper} block will be added. -@itemize @bullet - @item An assignment. The assignment must be terminated by a - semicolon. - @item A context definition. See section @ref{contextdefs} for - more information on context definitions. +@c_ {Score} +@subsubsection Score +@cindex Score -@ignore +@c_ {Paper} +@subsubsection Paper +@cindex Paper - FIXME +@c_ {Midi} +@subsubsection Midi +@cindex Midi +@c_ {Header} +@subsubsection Header +@cindex Header +@cindex @code{\header} - @item - - A margin shape declaration. The syntax is -@cindex @code{\shape} - @example +The syntax is - \shape @var{indent1}@code{,} @var{width1}@code{,} - @var{indent2}@code{,} @var{width2} @dots{} @code{;} - @end example +@example + \header @{ @var{key1} = @var{val1}; +@cindex @code{ly2dvi} + @var{key2} = @var{val2}; @dots{} @} +@end example - - Each pair of @var{indent} and @var{width} values is a dimension - specifying how far to indent and how wide to make the line. - The indentation and width of successive lines are specified by - the successive pairs of dimensions. The last pair of - dimensions will define the characeristics of all lines beyond - those explicitly specified. -@end ignore +A header describes the file's contents. It can also appear in a +@code{\score} block. Tools like @code{ly2dvi} can use this +information for generating titles. Key values that are used by +@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument, +metre, arranger, piece and tagline. - @item \stylesheet declaration. Its syntax is - @example - \stylesheet @var{alist} - @end example +It is customary to put the @code{\header} at the top of the file. - See @file{font.scm} for details of @var{alist}. +@subsubsection Default output + +A @code{\midi} or @code{\paper} block at top-level sets the default + +paper block for all scores that lack an explicit paper block. + +@c_ {Identifiers} +@node Identifiers +@subsection Identifiers +@cindex 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, + +@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 +@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. -@subsection Paper variables +@itemize @bullet +@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 -The paper block has some variables you may want to use or change: -@table @code -@cindex @code{indent} - @item @code{indent} - The indentation of the first line of music. -@cindex @code{staffspace} +@c_ {Assignments} +@node Assignments +@subsection Assignments +@cindex Assignments - @item @code{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. - -@cindex @code{linewidth} - @item @code{linewidth} - Sets the width of the lines. If set to -1.0, a single - 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 -@cindex @code{textheight} +Identifiers allow objects to be assigned to names during the parse +stage. To assign an identifier, you use @var{name}@code{=}@var{value} +and to refer to an identifier, you preceed its name with a backslash: +`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of +the input-types listed above. Identifier assignments can appear at top +level in the LilyPond file, but also in @code{\paper} blocks. - @item @code{textheight} - Sets the total height of the music on each page. Only used by - ly2dvi. -@cindex @code{interscoreline} +Semicolons are forbidden after top level assignments, but mandatory in +other places. The rules about semicolons and assignments are very +confusing, but when LilyPond input evolves more towards Scheme, we hope +that this problem will grow smaller. - @item @code{interscoreline} - Sets the spacing between the score lines. Defaults to 16 pt. -@cindex @code{interscorelinefill} +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. - @item @code{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. -@cindex @code{stafflinethickness} +The right hand side of an identifier assignment is parsed completely +before the assignment is done, so it is allowed to redefine an +identifier in terms of its old value, e.g. - @item @code{stafflinethickness} - Determines the thickness of staff lines, and also acts as a scaling - parameter for other line thicknesses. -@end table +@example +foo = \foo * 2.0 +@end example + +When an identifier is referenced, the information it points to is +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 + + + +@c_ {Lexical details} +@node Lexical details +@subsection Lexical details +@cindex Lexical details +@menu +@end menu + +@c_ {Comments} +@subsubsection Comments +@cindex Comments +@cindex @code{%} -@subsection Line breaks -@cindex line breaks -@cindex breaking lines +A one line comment is introduced by a @code{%} character. +Block comments are started by @code{%@{} and ended by `@code{%@}}'. +They cannot be nested. -Line breaks are normally computed automatically. They are chosen such -that the resulting spacing has low variation, and looks neither cramped -nor loose. +@c_ {Direct Scheme} +@subsubsection Direct Scheme +@cindex Scheme +@cindex GUILE +@cindex Scheme, in-line code -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 "";}. +LilyPond contains a Scheme interpreter (the GUILE library) for +internal use. In some places Scheme expressions also form valid syntax: +whereever it is allowed, +@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 #'foobar = #(+ 1 2) +@end example -@subsection Page breaks +@code{\override} expects two Scheme expressions, so there are two Scheme +expressions. The first one is a symbol (@code{foobar}), the second one +an integer (namely, 3). -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} +Scheme is a full-blown programming language, and a full discussion is +outside the scope of this document. Interested readers are referred to +the website @uref{http://www.schemers.org/} for more information on +Scheme. -@cindex page breaks -@cindex breaking pages +@c_ {Keywords} +@subsubsection Keywords +@cindex Keywords -@subsection Font size +Keywords start with a backslash, followed by a number of lower case +alphabetic characters. These are all the keywords. -@cindex font size +@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 pitch +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 -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. +@c_ {Integers} +@subsubsection Integers -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. +@cindex integers +@cindex @code{+} +@cindex @code{-} +@cindex @code{*} +@cindex @code{/} -The font definitions are generated using a Scheme function. For more -details, see the file @file{font.scm}. +Formed from an optional minus sign followed by digits. Arithmetic +operations cannot be done with integers, and integers cannot be mixed +with reals. -@subsection Paper size +@c_ {Reals} +@subsubsection Reals +@cindex real numbers -@cindex paper size -@cindex page size -@cindex @code{papersize} -To change the paper size, you must first set the -@code{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}) +Formed from an optional minus sign and a sequence of digits followed +by a @emph{required} decimal point and an optional exponent such as +@code{-1.2e3}. Reals can be built up using the usual operations: +`@code{+}', `@code{-}', `@code{*}', and +`@code{/}', with parentheses for grouping. -@node Context definitions -@section Context definitions +@cindex @code{\mm}, +@cindex @code{\in} +@cindex @code{\cm} +@cindex @code{\pt} +@cindex dimensions -@cindex context definition -@cindex translator definition -@cindex engraver hacking +A real constant can be followed by one of the dimension keywords: +@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters, +points, inches and centimeters, respectively. This converts the number +to a real that is the internal representation of dimensions. -A notation contexts is defined by the following information +@c_ {Strings} +@subsubsection Strings +@cindex string +@cindex concatenate -@enumerate 1 - @item A name. +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 +@ref{Lexical modes} for details on unquoted strings; their interpretation varies +depending on the situation. Strings can be concatenated with the +@code{+} operator. - @item The LilyPond modules that do the actual conversion of music to - notation. Each module is a so-called - @emph{engraver} -@cindex engraver -. +The tokenizer accepts the following commands. They have no grammatical +function, hence they can appear anywhere in the input. - @item How these modules should cooperate, i.e. which ``cooperation - module'' should be used. This cooperation module is a special - type of engraver. - @item What other contexts the context can contain, +@c_ {Main input} +@subsubsection Main input +@cindex Main input - @item What properties are defined. -@end enumerate +@cindex @code{\maininput} -A context definition has this syntax: +The @code{\maininput} command is used in init files to signal that the +user file must be read. This command cannot be used in a user file. -@example +@c_ {File inclusion} +@subsubsection Main input +@cindex Main input - \translator @code{@{} - @var{translatorinit} @var{translatormodifierlist} - @code{@}} +@subsubsection File inclusion +@cindex @code{\include} +@example + \include @var{filename} @end example -@var{translatorinit} can be an identifier or of the form +Include @var{filename}. The argument @var{filename} may be a quoted string (an +unquoted string will not work here!) or a string identifier. The full +filename including the @file{.ly} extension must be given, +@subsubsection Version information +@cindex @code{\version} @example - - \type @var{typename} @code{;} + \version @var{string} ; @end example -@var{typename} is one of - -@table @code -@cindex @code{Engraver_group_engraver} - @item @code{Engraver_group_engraver} - The standard cooperation engraver. -@cindex @code{Score_engraver} +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-ly} a tool that automatically upgrades input files. See +See @ref{convert-ly} for more information on @code{convert-ly}. - @item @code{Score_engraver} - This is cooperation module that should be in the top level context. -@cindex @code{Grace_engraver_group} +@cindex convert-ly - @item @code{Grace_engraver_group} - This is a special cooperation module (resembling - @code{Score_engraver}) that is used to created an embedded - `miniscore'. -@end table -@var{translatormodifierlist} is a list of items where each item is -one of -@itemize @bullet - @item @code{\consists} @var{engravername} @code{;} - Add @var{engravername} to the list of modules in this context. - The order of engravers added with @code{\consists} is - significant. - - @item @code{\consistsend} @var{engravername} @code{;} - Analogous to @code{\consists}, but makes sure that - @var{engravername} is always added to the end of the list of - engravers. - Some engraver types need to be at the end of the list; this - insures they are put there, and stay there, if a user adds or - removes engravers. This command is usually not needed for - end-users. - - @item @code{\accepts} @var{contextname} @code{;} - Add @var{contextname} to the list of context this context can - contain. The first listed context is the context to create by - default. +@c_ {Pitch names} +@subsubsection Pitch names +@cindex Lexical modes +@cindex pitch names - @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. - - @item @code{\name} @var{contextname} @code{;} - This sets name of the context, e.g. @code{Staff}, @code{Voice}. If - the name is not specified, the translator won't do anything. +@cindex note names +@cindex chord modifier names - @item @var{propname} @code{=} @var{value} @code{;} - A property assignment. It is allowed to use reals for - @var{value}. -@end itemize +Note names and chord modifiers can be customised for nationalities. +languages and conventions. The syntax is as follows. +@cindex @code{\pitchnames} +@cindex @code{\chordmodifiers} -In the @code{\paper} block, it is also possible to define translator -identifiers. Like other block identifiers, the identifier can only -be used as the very first item of a translator. In order to define -such an identifier outside of @code{\score}, you must do +@example + \pitchnames @var{scheme-alist} + \chordmodifiers @var{scheme-alist} +@end example -@quotation +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. -@example -\paper @{ - foo = \translator @{ @dots{} @} -@} -\score @{ - \notes @{ - @dots{} - @} - \paper @{ - \translator @{ \foo @dots{} @} - @} -@} -@end example +@c_ {Assignments} +@subsubsection Assignments +@cindex assignments +@cindex @code{#} -@end quotation +Identifier assignments may appear at top level. @ref{Assignments} -@cindex paper types, engravers, and pre-defined translators -Some pre-defined identifiers can simplify modification of -translators. The pre-defined identifiers are: +@c_ {Direct scheme} +@subsubsection Direct scheme +@cindex Direct scheme -@table @code -@cindex @code{StaffContext} - @item @code{StaffContext} - Default Staff context. -@cindex @code{RhythmicStaffContext} +Scheme statements maybe issued to produce interesting side-effects. - @item @code{RhythmicStaffContext} - Default RhythmicStaff context. -@cindex @code{VoiceContext} - @item @code{VoiceContext} - Default Voice context. -@cindex @code{ScoreContext} +@c_ {Lexical modes} +@node Lexical modes +@subsection Lexical modes +@cindex Lexical modes - @item @code{ScoreContext} - Default Score context. -@cindex @code{ScoreWithNumbers} +@cindex Lexical modes +@cindex modes - @item @code{ScoreWithNumbers} - Score context with numbering at the Score level. -@cindex @code{BarNumberingStaffContext} +To simplify entering notes, lyrics, and chords, 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 +a keyword or as an identifier. The behavior of the modes differs in +two ways: Different modes treat unquoted words differently, and +different modes have different rules for deciding what is a word. - @item @code{BarNumberingStaffContext} - Staff context with numbering at the Staff level. -@cindex @code{HaraKiriStaffContext} +@table @asis +@item Normal mode. +@cindex normal mode + +At the start of parsing, 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. - @item @code{HaraKiriStaffContext} - Staff context that does not print if it only contains rests. - Useful for orchestral scores.@footnote{Harakiri, also called - Seppuku, is the ritual suicide of the Japanese Samourai warriors.} -@cindex @code{OrchestralPartStaffContext} +@item Note mode +See @ref{Note entry}. - @item @code{OrchestralPartStaffContext} -@cindex @code{OrchestralScoreContext} +@item Lyrics mode +See @ref{Lyrics entry}. - @item @code{OrchestralScoreContext} +@item Chord mode +See @ref{Chord entry}. @end table -Using these pre-defined values, you can remove or add items to the -translator: +@cindex input modes -@quotation +@cindex mode switch -@example -\paper @{ - \translator @{ - \StaffContext - \remove Some_engraver; - \consists Different_engraver; - @} -@} -@end example +@cindex @code{\notes} +@cindex @code{\chords} +@cindex @code{\lyrics} -@end quotation +Mode switching keywords form compound music expressions: @code{\notes} +@var{musicexpr}, @code{\chords} @var{musicexpr}, +and @code{\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 @ref{Lexical modes} for more information on modes. - -@node Sound output -@section Sound output +@c_ {Ambiguities} +@node Ambiguities +@subsection Ambiguities +@cindex ambiguities +@cindex grammar -The MIDI block is analogous to the paper block, but it is somewhat -simpler. The @code{\midi} block can contain: -@cindex MIDI block + +The grammar contains a number of ambiguities. We hope to resolve them at +some time. @itemize @bullet - @item a @code{\tempo} definition - @item context definitions -@end itemize + @item The assignment -Assignments in the @code{\midi} block are not allowed. + @example +foo = bar +@end example + can be interpreted as making a string identifier @code{\foo} + containing @code{"bar"}, or a music identifier @code{\foo} + containing the syllable `bar'. + @item The assignment -@cindex context definition + @example +foo = -6 +@end example -Context definitions follow precisely the same syntax as within the -\paper block. Translation modules for sound are called performers. -The contexts for MIDI output are defined in @file{ly/performer.ly}. + can be interpreted as making an integer identifier + containing -6, or a Request identifier containing the + fingering `6' (with neutral direction). + @item If you do a nested repeat like + @quotation -@node midilist -@section MIDI instrument names -@cindex instrument names -@cindex @code{Staff.midiInstrument} -@cindex @code{Staff.instrument} +@example +\repeat @dots{} +\repeat @dots{} +\alternative +@end example -The MIDI instrument name is set by the @code{Staff.midiInstrument} -property or, if that property is not set, the @code{Staff.instrument} -property. The instrument name should be chosen from the following list. -If the selected string does not exactly match, then LilyPond uses the -default piano. + @end quotation -[FIXME: to appendix ] + then it is ambiguous to which @code{\repeat} the + @code{\alternative} belongs. This is the classic if-then-else + dilemma. It may be solved by using braces. -@c @quotation + @item (an as yet unidentified ambiguity :-) +@end itemize -@example -"acoustic grand" "contrabass" "lead 7 (fifths)" -"bright acoustic" "tremolo strings" "lead 8 (bass+lead)" -"electric grand" "pizzicato strings" "pad 1 (new age)" -"honky-tonk" "orchestral strings" "pad 2 (warm)" -"electric piano 1" "timpani" "pad 3 (polysynth)" -"electric piano 2" "string ensemble 1" "pad 4 (choir)" -"harpsichord" "string ensemble 2" "pad 5 (bowed)" -"clav" "synthstrings 1" "pad 6 (metallic)" -"celesta" "synthstrings 2" "pad 7 (halo)" -"glockenspiel" "choir aahs" "pad 8 (sweep)" -"music box" "voice oohs" "fx 1 (rain)" -"vibraphone" "synth voice" "fx 2 (soundtrack)" -"marimba" "orchestra hit" "fx 3 (crystal)" -"xylophone" "trumpet" "fx 4 (atmosphere)" -"tubular bells" "trombone" "fx 5 (brightness)" -"dulcimer" "tuba" "fx 6 (goblins)" -"drawbar organ" "muted trumpet" "fx 7 (echoes)" -"percussive organ" "french horn" "fx 8 (sci-fi)" -"rock organ" "brass section" "sitar" -"church organ" "synthbrass 1" "banjo" -"reed organ" "synthbrass 2" "shamisen" -"accordion" "soprano sax" "koto" -"harmonica" "alto sax" "kalimba" -"concertina" "tenor sax" "bagpipe" -"acoustic guitar (nylon)" "baritone sax" "fiddle" -"acoustic guitar (steel)" "oboe" "shanai" -"electric guitar (jazz)" "english horn" "tinkle bell" -"electric guitar (clean)" "bassoon" "agogo" -"electric guitar (muted)" "clarinet" "steel drums" -"overdriven guitar" "piccolo" "woodblock" -"distorted guitar" "flute" "taiko drum" -"guitar harmonics" "recorder" "melodic tom" -"acoustic bass" "pan flute" "synth drum" -"electric bass (finger)" "blown bottle" "reverse cymbal" -"electric bass (pick)" "skakuhachi" "guitar fret noise" -"fretless bass" "whistle" "breath noise" -"slap bass 1" "ocarina" "seashore" -"slap bass 2" "lead 1 (square)" "bird tweet" -"synth bass 1" "lead 2 (sawtooth)" "telephone ring" -"synth bass 2" "lead 3 (calliope)" "helicopter" -"violin" "lead 4 (chiff)" "applause" -"viola" "lead 5 (charang)" "gunshot" -"cello" "lead 6 (voice)" -@end example -@c @end quotation -@node Pre-defined Identifiers -@section Pre-defined Identifiers +@c_ {Unsorted} +@node Unsorted +@section Unsorted -@cindex pre-defined identifiers +[mucho todo] +Translation? -Various identifiers are defined in the initialization files to -provide shorthands for some settings. Most of them are in -@file{ly/declarations.ly} and @file{ly/property.ly}. +@cindex properties +@unnumberedsubsec Translation property -@table @code -@cindex @code{\break} - @item @code{\break} - Force a line break in music by using a large argument for the - keyword @code{\penalty}. +@cindex @code{\property} +@example + \property @var{contextname}.@var{propname} = @var{value} +@end example -@cindex @code{\nobreak} - @item @code{\nobreak} - Prevent a line break in music by using a large negative argument - for the keyword @code{\penalty}. +Sets the @var{propname} property of the context @var{contextname} to +the specified @var{value}. All three arguments are strings. +Depending on the context, it may be necessary to quote the strings or +to leave space on both sides of the dot. -@cindex @code{\shiftOff} - @item @code{\shiftOff} - Disable horizontal shifting of note heads that collide. +@cindex translator switches +@unnumberedsubsec Translator switches -@cindex @code{\shiftOn} - @item @code{\shiftOn} - Enable note heads that collide with other note heads to be - shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn} -set different shift values. +@cindex @code{\translator} +@example + \translator @var{contexttype} = @var{name} +@end example -@cindex @code{\stemBoth} - @item @code{\stemBoth} - Allow stems, beams, and slurs to point either upwards or - downwards, decided automatically by LilyPond. +A music expression indicating that the context which is a direct +child of the a context of type @var{contexttype} should be shifted to +a context of type @var{contexttype} and the specified name. -@cindex @code{\stemDown} - @item @code{\stemDown} - Force stems, beams, and slurs to point down. +Usually this is used to switch staffs in Piano music, e.g. -@cindex @code{\stemUp} - @item @code{\stemUp} - Force stems, beams and slurs to point up. +@example + \translator Staff = top @var{Music} +@end example -@end table +@cindex output properties +@unnumberedsubsec Output properties +These allow you to tweak what is happening in the back-end +directly. If you want to control every detail of the output +formatting, this is the feature to use. The downside to this is that +you need to know exactly how the backend works. Example: -@node Point and click -@section Point and click -[todo] +@lilypond[fragment,verbatim] +\relative c'' { c4 + \context Staff \outputproperty + #(make-type-checker 'note-head-interface) + #'extra-offset = #'(5.0 . 7.5) + } +@end lilypond + +This selects all note heads occurring at current staff level, and sets +the @code{extra-offset} of those heads to @code{(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 implementation of the backend, +which we change regularly and unscrupulously. + +@c_{Local emacs vars} +@c Local variables: +@c mode: texinfo +@c minor-mode: font-lock +@c minor-mode: outline +@c xoutline-layout: (0 : -1 -1 0) +@c outline-layout: (-1 : 0) +@c outline-primary-bullet: "{" +@c outline-stylish-prefixes: nil +@c outline-override-protect: t +@c End: diff --git a/Documentation/user/tricks.itely b/Documentation/user/tricks.itely index 5e1ac3a3cf..f1525f530f 100644 --- a/Documentation/user/tricks.itely +++ b/Documentation/user/tricks.itely @@ -1,4 +1,11 @@ @c -*-texinfo-*- +@c Note: +@c +@c A menu is needed before every deeper *section nesting of @nodes +@c Run M-x texinfo-all-menus-update +@c to automagically fill in these menus +@c before saving changes + @ignore TODO @@ -28,17 +35,17 @@ yes: \property Staff.VoltaBracket = #'((meta . ((interfaces . ())))) @chapter Tricks @menu -* Manual beam settings:: Manual beam settings -* Slur attachments:: Slur attachments -* Text spanner:: Text spanner -* Engraver hacking:: Engraver hacking -* Part combiner:: Part combiner -* Markup text:: Markup text -* Apply hacking:: Apply hacking -* Output property:: Output property -* Embedded TeX:: Embedded TeX -* Embedded PostScript:: Embedded PostScript +* Manual beam settings:: Manual beam settings +* Slur attachments:: Slur attachments +* Engraver hacking:: Engraver hacking +* Part combiner:: Part combiner +* Markup text:: Markup text +* Output property:: Output property +* Apply hacking:: Apply hacking +* Embedded TeX:: Embedded TeX +* Embedded PostScript:: Embedded PostScript @c * Index:: Checking Feature index +* Index:: Checking Feature index @end menu @@ -290,34 +297,6 @@ increasing the @code{beautiful} value: @end quotation -@node Text spanner -@section Text spanner - - - -Have crescendo set a text spanner instead of hairpin - -@lilypond[fragment,relative,verbatim] - \context Voice { - \property Voice.crescendoText = "cresc." - \property Voice.crescendoSpanner = #'dashed-line - a''2\mf\< a a \!a - } -@end lilypond - -@subsection Ottava - -@lilypond[fragment,relative,verbatim] - a'''' b c a - \property Voice.TextSpanner \set #'type = #'dotted-line - \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5) - \property Voice.TextSpanner \set #'edge-text = #'("8va " . "") - \property Staff.centralCPosition = #-13 - a\spanrequest \start "text" b c a \spanrequest \stop "text" -@end lilypond - - - @node Engraver hacking @section Engraver hacking diff --git a/VERSION b/VERSION index ddbba8d68d..3b10972f02 100644 --- a/VERSION +++ b/VERSION @@ -2,7 +2,7 @@ PACKAGE_NAME=LilyPond MAJOR_VERSION=1 MINOR_VERSION=3 PATCH_LEVEL=126 -MY_PATCH_LEVEL=jcn2 +MY_PATCH_LEVEL=jcn3 # use the above to send patches: MY_PATCH_LEVEL is always empty for a # released version. diff --git a/input/bugs/arpeggio-collision.ly b/input/bugs/arpeggio-collision.ly index 996f19a696..e69de29bb2 100644 --- a/input/bugs/arpeggio-collision.ly +++ b/input/bugs/arpeggio-collision.ly @@ -1,43 +0,0 @@ - -hairyChord = \context Staff \notes\relative c' < - \context Voice=one { - \property Voice.Stem \push #'direction = #1 - \property Voice.NoteColumn \push #'horizontal-shift = #0 - e4\arpeggio - } - - \context Voice=two { - \property Voice.Stem \push #'direction = #1 - \property Voice.NoteColumn \push #'horizontal-shift = #1 - cis\arpeggio - } - - \context Voice=three { - \property Voice.Stem \push #'direction = #1 - \property Voice.NoteColumn \push #'horizontal-shift = #2 - ais\arpeggio - } - - \context Voice=four { - \property Voice.Stem \push #'direction = #-1 - \property Voice.NoteColumn \push #'horizontal-shift = #-1 - fis\arpeggio - } -> - - -\score{ - \notes \transpose c'' { - \context Voice < fis''-\arpeggio g d a > - \context Voice < fis,-\arpeggio g d a > - \context Voice < fis''-\arpeggio g d a > - \hairyChord - } - \paper { - linewidth = -1.; - \translator{ - \StaffContext - connectArpeggios = ##t - } - } -} diff --git a/input/bugs/auto-beam-tuplets.ly b/input/bugs/auto-beam-tuplets.ly index 3af118fafb..203e14a472 100644 --- a/input/bugs/auto-beam-tuplets.ly +++ b/input/bugs/auto-beam-tuplets.ly @@ -1,10 +1,10 @@ -\score { \notes { - \property Voice.tupletSpannerDuration = #(make-moment 1 4) - \property Voice.tupletNumberVisibility = #'if-no-beam - \property Voice.tupletBracketVisibility = #'if-no-beam - % Gm7 / F | A7 / Dm | +\header { texidoc = "tuplet-spanner should not put visible brackets on +beams even if they're auto generated."; } + +\score { \notes \relative c' { + \property Voice.tupletSpannerDuration = #(make-moment 1 4) + \property Voice.TupletBracket \override #'tuplet-bracket-visibility = #'if-no-beam \times 2/3 { - [f,8 bes, d] [g d bes,] [f, a, c] [f c a,] | e, a, cis e cis a, d, f, a, d a, f, | - % Db | - des, aes, des f des aes, des, aes, des f des aes, | } + [f8 f f ][f8 f f ] f f f f f f + } }} diff --git a/input/bugs/auto-beam.ly b/input/bugs/auto-beam.ly index 5acc702a01..a816ff774a 100644 --- a/input/bugs/auto-beam.ly +++ b/input/bugs/auto-beam.ly @@ -1,6 +1,7 @@ -% bug or feature? -\score { \notes { c8 c8 - % needed to force auto-beam: - % c4 +\header { +texidoc ="Auto beam can not be put on the final notes of a score "; +} +\score { \notes { + c8 c8 }} diff --git a/input/bugs/barline.ly b/input/bugs/barline.ly index 97ac88ac61..5ce93268bb 100644 --- a/input/bugs/barline.ly +++ b/input/bugs/barline.ly @@ -1,13 +1,10 @@ \header { - title = "The river is flowing"; - composer = "Traditonal (?)"; +texidoc= "Staffs that end half way a system should end at the bar line."; } melody = \notes \relative c' { \partial 8; g8 | - - \bar "|.";\clef bass; } @@ -15,7 +12,7 @@ melody = \notes \relative c' { accompaniment =\chords \sequential { r8 - c2:min f:min 7 + r2 r2 } \score { @@ -25,5 +22,4 @@ accompaniment =\chords \sequential { \melody } } \paper { } - \midi { } } diff --git a/input/bugs/broken-tuplet.ly b/input/bugs/broken-tuplet.ly new file mode 100644 index 0000000000..56dc693f7e --- /dev/null +++ b/input/bugs/broken-tuplet.ly @@ -0,0 +1,16 @@ +\header { + +texidoc ="tuplet bracket doesn't behave properly at line break. Not a real problem."; +} + +\score{ + \notes\relative c''< + { % broken cresc dumps core + c2 c4*2/3 \times 2/3 { c( c c } + c4 c c c + } > + \paper{ + indent = 0.; + linewidth=30.\mm; + } +} diff --git a/input/bugs/coda-kludge.ly b/input/bugs/coda-kludge.ly index 193f1eaa3e..e69de29bb2 100644 --- a/input/bugs/coda-kludge.ly +++ b/input/bugs/coda-kludge.ly @@ -1,58 +0,0 @@ -% The volta texts should read: 1-4 and 5 -% Not 1 and 2 -% (see 1.2.17) - -%{ -Hi, - I want to write some music that has the structure: - - Intro - \repeat 4 { Chorus [first-ending] verse } - fifth-ending final - - The obvious: - - \repeat 4 { Chorus \alternative{{first-ending}{}} verse} - \alternative{{}{fifth-ending}} - final - - doesn't work. - - And the (logically correct but ugly) - - \repeat 4 {Chorus} - \alternative {{first-ending verse}{fifth ending}} - final - - is very ugly, because the volta bracket keeps going for so - long. - - Peter C -%} - -\score{ - < - \context Staff \notes\relative c''{ - c c c c - % coda-klugde: let volta span only one bar - \property Staff.voltaSpannerDuration = #(make-moment 1 1) - \repeat "volta" 5 { d d d d } - \alternative { { e e e e f f f f } - { g g g g } } - } - \context Lyrics \lyrics{ - intro1 - \repeat fold 5 {} - \alternative { - { chorus1 one verse1 } - { chorus1 two verse1 } - { chorus1 three verse } - { chorus1 four verse } - } - five1 - } - > -} - - -%\version "1.0.16"; diff --git a/input/bugs/die-staff.ly b/input/bugs/die-staff.ly index f28bc52fe6..2bd1925c09 100644 --- a/input/bugs/die-staff.ly +++ b/input/bugs/die-staff.ly @@ -1,6 +1,8 @@ - +\header { +texidoc = "a staff should really die, if no one's referencing it." +} \score { - { + { \context Staff = q { \notes { a' b' c' d' } } diff --git a/input/bugs/different-time.ly b/input/bugs/different-time.ly index 4b23edc614..8f329c68d8 100644 --- a/input/bugs/different-time.ly +++ b/input/bugs/different-time.ly @@ -1,5 +1,7 @@ -% -% irregular spacing. +\header { +texidoc =" Spacing for one staff in polymetric music should +be not hampered by a staff in another time signature."; +} \score{ \context PianoStaff < diff --git a/input/bugs/dots.ly b/input/bugs/dots.ly index 6dfd11ae45..9fed6eeec1 100644 --- a/input/bugs/dots.ly +++ b/input/bugs/dots.ly @@ -1,3 +1,9 @@ +\header { + texidoc = "Dots should remain close to the heads they belong to, but should not overlap."; +} + + \score { -\notes\context Voice { } + \notes + \context Voice { } } diff --git a/input/bugs/dynamic-switch.ly b/input/bugs/dynamic-switch.ly index 3fc9f7e299..0c2a69f763 100644 --- a/input/bugs/dynamic-switch.ly +++ b/input/bugs/dynamic-switch.ly @@ -15,9 +15,6 @@ \paper{ linewidth=140.\mm; } - \midi{ - - } } diff --git a/input/bugs/empty.ly b/input/bugs/empty.ly index 187ca07d31..e69de29bb2 100644 --- a/input/bugs/empty.ly +++ b/input/bugs/empty.ly @@ -1,16 +0,0 @@ -% -% empty bars? -% -\score{ -\context Staff \notes\relative c''{ -\property Staff.defaultBarType = #"" -c1 c -\property Staff.defaultBarType = #"empty" -c1 c -} -\paper{ -} -\midi{ -\tempo 1 = 60; -} -} diff --git a/input/bugs/no-bars.ly b/input/bugs/no-bars.ly index 0ab9bf606a..e69de29bb2 100644 --- a/input/bugs/no-bars.ly +++ b/input/bugs/no-bars.ly @@ -1,20 +0,0 @@ -\header{ -texidoc=" -defaultBarType is cheched by Timing_translator, but has no effect? -"; -} - -\score { - \notes \relative c'' { - a b c d - d c b a - } - \paper { - \translator { - \StaffContext - defaultBarType = #"" - \remove "Time_signature_engraver"; - linewidth = -1.; - } - } -} diff --git a/input/bugs/prefatory-spacing.ly b/input/bugs/prefatory-spacing.ly index 23da618be9..b9526768ad 100644 --- a/input/bugs/prefatory-spacing.ly +++ b/input/bugs/prefatory-spacing.ly @@ -1,10 +1,13 @@ -% the space after clef/key is stretched too much. +\header { texidoc= "Spacing after clef/key should be stretched +equidistantly for large stretching, but should stay clear of prefatory +matter for small stretching. Support in the spacing engine for +separate spring constants for stretching/shrinking is needed"; +} -foo = \notes\relative c'' { \key as \major; d } +foo = \notes\relative c'' { \key as \major; f } \score { < \foo - \context NoteNames \foo > } diff --git a/input/bugs/slur-dx.ly b/input/bugs/slur-dx.ly index 02cfbf9413..b565cc0b96 100644 --- a/input/bugs/slur-dx.ly +++ b/input/bugs/slur-dx.ly @@ -1,9 +1,9 @@ \header{ texidoc=" -Arg, right ending of slur is too far right. I did make a better -test .ly for this, but can't seem to find it now. -"; -} + Right ending of slur is too far right. + + [I did make a better test .ly for this, but can't seem to find it +now.] "; } \score { \notes \relative c'' { diff --git a/input/bugs/spanners.ly b/input/bugs/spanners.ly index bc9692d281..e69de29bb2 100644 --- a/input/bugs/spanners.ly +++ b/input/bugs/spanners.ly @@ -1,11 +0,0 @@ -% spanners start at line start -\score{ - \notes\relative c''{ - % broken cresc dumps core - c2\< c4 \times 2/3 { c( c c } - c4 c )\!c c - } - \paper{ - linewidth=30.\mm; - } -} diff --git a/input/bugs/steep-beam.ly b/input/bugs/steep-beam.ly index 0a62020c2f..6a719c43c1 100644 --- a/input/bugs/steep-beam.ly +++ b/input/bugs/steep-beam.ly @@ -1,5 +1,5 @@ - - -% 1st beam should prob. be horizontal. +\header { +texidoc ="1st beam should prob. be horizontal."; +} \score { \notes <{ [ r8 g''16 des'] [r8 c16 a] }>} diff --git a/input/bugs/text-kerning.ly b/input/bugs/text-kerning.ly index b40afe216e..21bf734277 100644 --- a/input/bugs/text-kerning.ly +++ b/input/bugs/text-kerning.ly @@ -1,4 +1,6 @@ +\header { +texidoc= "LilyPond doesn't kern text, but TeX does, leading to skewed results: the VAVAVAVA takes less space than LilyPond thinks it does."; } \score { \notes \relative c'' < \context Voice { diff --git a/input/bugs/ties.ly b/input/bugs/ties.ly index 96ad58757b..d00f255e4a 100644 --- a/input/bugs/ties.ly +++ b/input/bugs/ties.ly @@ -1,20 +1,20 @@ \header { texidoc="Positioning of last ties is incorrect; ties between 2-1 and 1-1 - durations differ. Direction is incorrect."; + durations differ."; } \score { \context Staff < \context Voice = a \notes\relative c'' { - \stemUp + \voiceOne r2 a2~a1~a } \context Voice = y \notes\relative c' { - \stemDown + \voiceTwo r2 a2~a1~a } > \paper { linewidth = 100 * \staffspace; } -} \ No newline at end of file +} diff --git a/input/bugs/volta.ly b/input/bugs/volta.ly index fe545aa978..e69de29bb2 100644 --- a/input/bugs/volta.ly +++ b/input/bugs/volta.ly @@ -1,44 +0,0 @@ - -% left start of broken volta bracket. - -voice4 = \notes { -\clef bass; - \property Staff.instrument = "Bass" - \property Staff.instr = "B" - \time 4/4; f,2 ( ) f,8 r8 f8 e8 -\repeat volta 2 -{ - d8. d16 e8. f16 f8 c8 c16 c8. -} -\alternative -{ - { f,2 ( ) f,8 r8 f8 e8 ( \break } - { ) f,2. r8 c16 c16 | - } -} -} -voicedefault = \notes { - \property Staff.timeSignatureStyle="C" - \time 4/4; \key f \major; - \tempo 4 = 200; -} -\score{ - \notes < - - - \context Staff="4" - { - \$voicedefault - \$voice4 - } - - > - \paper { - font_normal = 12.; - \translator { - \StaffContext - \consists Instrument_name_engraver; - } - } -} - diff --git a/input/bugs/voltastart.ly b/input/bugs/voltastart.ly index 599c2450c8..e69de29bb2 100644 --- a/input/bugs/voltastart.ly +++ b/input/bugs/voltastart.ly @@ -1,132 +0,0 @@ -%{ - - -I recently discovered that although the following patch seemed to fix -the original complaint that it causes other problems (the following -tests were done in 1.3.116. - -I have attached a file which has several break-volta interactions. - -With the test file and unmodified 1.3.116 I see the following: - -Bar 3 - 1st volta spanner centered on first note - prefer it to start - closer to key signature (can live with this) -Bar 6 - 1st volta continuation - perfect -Bar 9 - 2nd volta spanner starts on left edge of key signature - prefer - it to start right of key signature -Bar 12 1st volta starts between first two slurred notes in measure - - this is not acceptable -Bar 17 like above with hairpin. -Bar 23 like above (I had expected this to be OK) -Bar 20 2nd volta continuation perfect - -With the test file and 1.3.116 modified as below I see the following: - -Bar 3 Perfect -Bar 6 1st volta continuation starts with staff - oops -Bar 9 2nd volta starts on papers left margin - OOPS! -Bar 12 Perfect -Bar 17 Perfect -Bar 20 2nd volta continuation starts with staff - oops -Bar 23 Perfect - -%} - -voice1 = \notes { - \clef bass; - \property Staff.instrument = "Bass" - \property Staff.instr = "B" - \key f \minor; - \time 4/4; - f,2 ( ) f,8 r8 f8 e8 - \repeat volta 2 - { - d8. d16 e8. f16 f8 c8 c16 c8. \break - } - \alternative - { - { - f,2 ( ) f,8 r8 f8 e8 - f,2 ( ) f,8 r8 f8 e8 - g1 \break - f,2 ( ) f,8 r8 f8 e8 - f,2 ( ) f,8 r8 f8 e8 - g1 \break - } - { - f,2. r8 c16 c16 | - } - } -} -voice2 = \notes { - \repeat volta 2 - { - bes8 bes8 c'8 c'8 a4 r8 g16 f16 | - d'8. c'16 c'8. d'16 c'8 c'8 f16 g8. | - \break - } - \alternative - { - { a2 ( ) a8 r8 a8 bes8 } - { a2. r8 g16 f16 | - d'8. c'16 c'8. d'16 c'8 c'8 c'16 c'8. | - } - } -} -voice3 = \notes { - \repeat volta 2 - { - bes8 bes8 c'8 c'8 a4 r8 g16 f16 | - d'8. c'16 c'8. d'16 c'8 c'8 f16 g8. | - \break - } - \alternative - { - { a2 \> a8 r8 a8 \! bes8 - } - { a2. r8 g16 f16 | - d'8. c'16 c'8. d'16 c'8 c'8 c'16 c'8. | \break - d'8. c'16 c'8. d'16 c'8 c'8 c'16 c'8. | - } - } -} -voice4 = \notes { - \repeat volta 2 - { - bes8 bes8 c'8 c'8 a4 r8 g16 f16 | - d'8. c'16 c'8. d'16 c'8 c'8 f16 g8. | \break - } - \alternative - { - { - a2 a8 r8 a8 bes8 - - } - { - a2. r8 g16 f16 | - d'8. c'16 c'8. d'16 c'8 c'8 c'16 c'8. | - } - } -} -\score{ - \notes < - - - \context Staff="4" - { - \$voice1 - \$voice2 - \break - \$voice3 - \$voice4 - } - - > - \paper { - font_normal = 12.; - \translator { - \StaffContext - \consists Instrument_name_engraver; - } - } -} diff --git a/input/regression/allfontstyle.ly b/input/regression/allfontstyle.ly new file mode 100644 index 0000000000..8c48cd1780 --- /dev/null +++ b/input/regression/allfontstyle.ly @@ -0,0 +1,17 @@ + + + +\score { \notes + \relative c'' \context Staff { + \emptyText + \repeat volta 2 { \time 4/4; c4^"cuivr\\'e"_\fermata } + \alternative { + { \property Voice.textStyle = "italic" d-4_"cantabile" } + { e } } \grace { c16 } + \property Voice.textStyle = "large" + f4-\ff^""^"Largo" \mark "B"; g + } + \paper { linewidth = -1.0; + \translator { \BarNumberingStaffContext} + } +} diff --git a/input/regression/arpeggio-collision.ly b/input/regression/arpeggio-collision.ly new file mode 100644 index 0000000000..d7d9907af4 --- /dev/null +++ b/input/regression/arpeggio-collision.ly @@ -0,0 +1,47 @@ +\header = { +texidoc = "arpeggio stays clear of accidentals and flipped note heads. +Since Arpeggio engraver is Voice, it does nothing for voice collisions." +}; + +hairyChord = \context Staff \notes\relative c' < + \context Voice=one { + \property Voice.Stem \override #'direction = #1 + \property Voice.NoteColumn \override #'horizontal-shift = #0 + e4-\arpeggio + } + + \context Voice=two { + \property Voice.Stem \override #'direction = #1 + \property Voice.NoteColumn \override #'horizontal-shift = #1 + cis-\arpeggio + } + + \context Voice=three { + \property Voice.Stem \override #'direction = #1 + \property Voice.NoteColumn \override #'horizontal-shift = #2 + ais-\arpeggio + } + + \context Voice=four { + \property Voice.Stem \override #'direction = #-1 + \property Voice.NoteColumn \override #'horizontal-shift = #-1 + fis-\arpeggio + } +> + + +\score{ + \notes \transpose c'' { + \context Voice < fis''-\arpeggio g d a > + \context Voice < fis,-\arpeggio g d a > + \context Voice < fis''-\arpeggio g d a > + \hairyChord + } + \paper { + linewidth = -1.; + \translator{ + \StaffContext + connectArpeggios = ##t + } + } +} diff --git a/input/regression/volta-broken-left-edge.ly b/input/regression/volta-broken-left-edge.ly new file mode 100644 index 0000000000..28400c43e0 --- /dev/null +++ b/input/regression/volta-broken-left-edge.ly @@ -0,0 +1,136 @@ +\header { +texidoc ="Broken volta spanners behave correctly at left edge in all cases." +}; + +%{ + + +I recently discovered that although the following patch seemed to fix +the original complaint that it causes other problems (the following +tests were done in 1.3.116. + +I have attached a file which has several break-volta interactions. + +With the test file and unmodified 1.3.116 I see the following: + +Bar 3 - 1st volta spanner centered on first note - prefer it to start + closer to key signature (can live with this) +Bar 6 - 1st volta continuation - perfect +Bar 9 - 2nd volta spanner starts on left edge of key signature - prefer + it to start right of key signature +Bar 12 1st volta starts between first two slurred notes in measure - + this is not acceptable +Bar 17 like above with hairpin. +Bar 23 like above (I had expected this to be OK) +Bar 20 2nd volta continuation perfect + +With the test file and 1.3.116 modified as below I see the following: + +Bar 3 Perfect +Bar 6 1st volta continuation starts with staff - oops +Bar 9 2nd volta starts on papers left margin - OOPS! +Bar 12 Perfect +Bar 17 Perfect +Bar 20 2nd volta continuation starts with staff - oops +Bar 23 Perfect + +%} + +voice1 = \notes { + \clef bass; + \property Staff.instrument = "Bass" + \property Staff.instr = "B" + \key f \minor; + \time 4/4; + f,2 ( ) f,8 r8 f8 e8 + \repeat volta 2 + { + d8. d16 e8. f16 f8 c8 c16 c8. \break + } + \alternative + { + { + f,2 ( ) f,8 r8 f8 e8 + f,2 ( ) f,8 r8 f8 e8 + g1 \break + f,2 ( ) f,8 r8 f8 e8 + f,2 ( ) f,8 r8 f8 e8 + g1 \break + } + { + f,2. r8 c16 c16 | + } + } +} +voice2 = \notes { + \repeat volta 2 + { + bes8 bes8 c'8 c'8 a4 r8 g16 f16 | + d'8. c'16 c'8. d'16 c'8 c'8 f16 g8. | + \break + } + \alternative + { + { a2 ( ) a8 r8 a8 bes8 } + { a2. r8 g16 f16 | + d'8. c'16 c'8. d'16 c'8 c'8 c'16 c'8. | + } + } +} +voice3 = \notes { + \repeat volta 2 + { + bes8 bes8 c'8 c'8 a4 r8 g16 f16 | + d'8. c'16 c'8. d'16 c'8 c'8 f16 g8. | + \break + } + \alternative + { + { a2 \> a8 r8 a8 \! bes8 + } + { a2. r8 g16 f16 | + d'8. c'16 c'8. d'16 c'8 c'8 c'16 c'8. | \break + d'8. c'16 c'8. d'16 c'8 c'8 c'16 c'8. | + } + } +} +voice4 = \notes { + \repeat volta 2 + { + bes8 bes8 c'8 c'8 a4 r8 g16 f16 | + d'8. c'16 c'8. d'16 c'8 c'8 f16 g8. | \break + } + \alternative + { + { + a2 a8 r8 a8 bes8 + + } + { + a2. r8 g16 f16 | + d'8. c'16 c'8. d'16 c'8 c'8 c'16 c'8. | + } + } +} +\score{ + \notes < + + + \context Staff="4" + { + \$voice1 + \$voice2 + \break + \$voice3 + \$voice4 + } + + > + \paper { + font_normal = 12.; + \translator { + \StaffContext + \consists Instrument_name_engraver; + } + } +} diff --git a/input/test/allfontstyle.ly b/input/test/allfontstyle.ly index 8c48cd1780..e69de29bb2 100644 --- a/input/test/allfontstyle.ly +++ b/input/test/allfontstyle.ly @@ -1,17 +0,0 @@ - - - -\score { \notes - \relative c'' \context Staff { - \emptyText - \repeat volta 2 { \time 4/4; c4^"cuivr\\'e"_\fermata } - \alternative { - { \property Voice.textStyle = "italic" d-4_"cantabile" } - { e } } \grace { c16 } - \property Voice.textStyle = "large" - f4-\ff^""^"Largo" \mark "B"; g - } - \paper { linewidth = -1.0; - \translator { \BarNumberingStaffContext} - } -} diff --git a/lily/all-font-metrics.cc b/lily/all-font-metrics.cc index 0ebc486c67..0c22c59b6c 100644 --- a/lily/all-font-metrics.cc +++ b/lily/all-font-metrics.cc @@ -18,10 +18,6 @@ #include "scm-hash.hh" #include "kpath.hh" - - - - const char * default_font_sz_ = "cmr10"; All_font_metrics::All_font_metrics (String path) diff --git a/lily/include/spring.hh b/lily/include/spring.hh index 4a49085e80..aaa7fb5b5a 100644 --- a/lily/include/spring.hh +++ b/lily/include/spring.hh @@ -16,6 +16,10 @@ struct Column_spring { Paper_column *other_l_; Real distance_f_; + + /* + TODO: make 2 strengths: one for stretching, and one for shrinking. + */ Real strength_f_; Column_spring (); diff --git a/lily/spacing-spanner.cc b/lily/spacing-spanner.cc index 3cd903f731..41f2a7bbd5 100644 --- a/lily/spacing-spanner.cc +++ b/lily/spacing-spanner.cc @@ -130,7 +130,8 @@ Spacing_spanner::do_measure (Grob*me, Link_array cols) spacing in the measure. */ SCM sfac =lc->get_grob_property ("space-factor"); - if (Item::breakable_b (lc) || lc->original_l_) + if (gh_number_p (lc->get_grob_property ("column-space-strength")) + && (Item::breakable_b (lc) || lc->original_l_)) { s.strength_f_ = gh_scm2double (lc->get_grob_property ("column-space-strength")); diff --git a/lily/tuplet-spanner.cc b/lily/tuplet-spanner.cc index b17a053a55..2b2ddd8ae1 100644 --- a/lily/tuplet-spanner.cc +++ b/lily/tuplet-spanner.cc @@ -30,11 +30,9 @@ Tuplet_spanner::set_interface (Grob*me) } /* - TODO. - */ - + TODO: use stem->beam fields to find Beams. Autobeams aren't found + through the engraver mechanism. */ MAKE_SCHEME_CALLBACK(Tuplet_spanner,brew_molecule,1); - SCM Tuplet_spanner::brew_molecule (SCM smob) { diff --git a/ly/generic-paper.ly b/ly/generic-paper.ly index 3e3f28c450..d846d86800 100644 --- a/ly/generic-paper.ly +++ b/ly/generic-paper.ly @@ -1,6 +1,4 @@ -#(eval-string (ly-gulp-file "paper.scm")) - \paper { texsetting = ""; pssetting = ""; diff --git a/ly/midi.ly b/ly/midi.ly index f367eafe59..c95aae830f 100644 --- a/ly/midi.ly +++ b/ly/midi.ly @@ -1,6 +1,3 @@ - -#(eval-string (ly-gulp-file "midi.scm")) - \midi { \tempo 4=60; \include "performer.ly" diff --git a/ly/script.ly b/ly/script.ly index 2ebe362fc5..a48626f78a 100644 --- a/ly/script.ly +++ b/ly/script.ly @@ -1,9 +1,5 @@ -#(eval-string (ly-gulp-file "script.scm")) - -#default-script-alist - "dash-hat" = "marcato" "dash-plus" = "stopped" "dash-dash" = "tenuto" diff --git a/make/mutopia-targets.make b/make/mutopia-targets.make index 4a759813c5..806ff65c6b 100644 --- a/make/mutopia-targets.make +++ b/make/mutopia-targets.make @@ -14,3 +14,8 @@ convert-ly: local-convert-ly local-convert-ly: $(PYTHON) $(script-dir)/convert-ly.py -e *ly + +tar: + mkdir -p $(outdir)/$(tarball) + cp -p *.ly $(outdir)/$(tarball) + cd $(outdir) && tar czf $(tarball).tar.gz $(tarball) diff --git a/mutopia/J.S.Bach/Solo-Cello-Suites/GNUmakefile b/mutopia/J.S.Bach/Solo-Cello-Suites/GNUmakefile index 18e9385e3f..167992e09e 100644 --- a/mutopia/J.S.Bach/Solo-Cello-Suites/GNUmakefile +++ b/mutopia/J.S.Bach/Solo-Cello-Suites/GNUmakefile @@ -8,3 +8,6 @@ examples=scsii-cello LOCALSTEPMAKE_TEMPLATES=mutopia include $(depth)/make/stepmake.make + +tarball=solo-cello-suite-ii + diff --git a/scm/basic-properties.scm b/scm/basic-properties.scm index 3910b82dfd..9975d25cd7 100644 --- a/scm/basic-properties.scm +++ b/scm/basic-properties.scm @@ -53,6 +53,8 @@ ;; See [Wanske] page 126 -- 134, [Ross] pg 143 -- 147 ;; +;; documentme: difference between extra-space and minimum-space + ;; (Measured in staff space) (define default-break-align-space-alist '( diff --git a/scm/lily.scm b/scm/lily.scm index 6228a482e0..dcc2b805ff 100644 --- a/scm/lily.scm +++ b/scm/lily.scm @@ -78,4 +78,5 @@ "basic-properties.scm" "chord-name.scm" "grob-description.scm" + "script.scm" "midi.scm" ))) diff --git a/scm/paper.scm b/scm/paper.scm index 5712e0a15a..e69de29bb2 100644 --- a/scm/paper.scm +++ b/scm/paper.scm @@ -1,9 +0,0 @@ -;;; paper.scm -- scm paper variables and functions -;;; -;;; source file of the GNU LilyPond music typesetter -;;; -;;; (c) 1999--2000 Jan Nieuwenhuizen - -;;; All dimensions are measured in staff-spaces - - diff --git a/scm/translator-description.scm b/scm/translator-description.scm index 559aa0bfa0..f91d5a0b99 100644 --- a/scm/translator-description.scm +++ b/scm/translator-description.scm @@ -230,8 +230,7 @@ put on top of all staffs, and appears only at left side of the staff." and generate the appropriate chordname." '(ChordName) '( - chordInversion - drarnChords + chordChanges ))) diff --git a/scm/translator-property-description.scm b/scm/translator-property-description.scm index 1fb2c7f9e0..e62eb8adc8 100644 --- a/scm/translator-property-description.scm +++ b/scm/translator-property-description.scm @@ -121,7 +121,11 @@ every barline. ") (translator-property-description 'currentCommandColumn ly-grob? "Grob that is X-parent to all current breakable (clef, key signature, etc.) items.") (translator-property-description 'currentMusicalColumn ly-grob? "Grob that is X-parent to all non-breakable items (note heads, lyrics, etc.).") -(translator-property-description 'defaultBarType string? "Sets the default type of bar line. Available bar types: [FIXME] +(translator-property-description 'defaultBarType string? "Sets the default type of bar line. Available bar types: [FIXME]; + +This variable is typically read at Score level, so overriding +Staff.defaultBarType will have no effect. + ") (translator-property-description 'drarnChords boolean? "") (translator-property-description 'explicitClefVisibility procedure? "visibility-lambda function for clef changes.") @@ -259,7 +263,7 @@ settings. pair of numbers, signifying the time signature. For example #'(4 . 4) is a 4/4time signature.") (translator-property-description 'timing boolean? " Keep administration of measure length, position, bar number, etc? Switch off for cadenzas.") -(translator-property-description 'transposing integer? "Number of semi tones that MIDI output must be transposed.") +(translator-property-description 'transposing integer? "Transpose the MIDI output. Set this property to the number of half-steps to transpose by.") (translator-property-description 'tremoloFlags integer? "Number of tremolo flags to add if none is specified.") (translator-property-description 'tupletInvisible boolean? " If set to true, tuplet bracket creation is switched off -- 2.39.2