From: fred Date: Tue, 26 Mar 2002 22:41:33 +0000 (+0000) Subject: lilypond-1.2.13 X-Git-Tag: release/1.5.59~2054 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=8fbb76d86325265275da43d6e7effb636f632927;p=lilypond.git lilypond-1.2.13 --- diff --git a/CHANGES b/CHANGES index 762e19f241..8acd8145cb 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,22 @@ +12.jcn1 + - auto-knees, input/test/auto-knee.ly + +pl 12.rrr2 + - voltaSpannerDuration may be a rational + - .ly files corrected, Voice.dynamicDir to Voice.dynamicDirection + +pl 12.rrr1 + - key (K:) with clef, bug fix for abc2ly + - voltaSpannerDuration code added to lilypond + +pl 12.hwn1 + - junked wordwrap + - bf: use position (not pitch) for autochange + - mudela-book fixes: --dependencies, --dep-prefix + - mudela.tely more updates. Now absorbed LilyPond manpage. + - BUGS now in INSTALL.texi + +******* pl 11.uu1 - changed debug init code. diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile index 716212ddb6..d900ff88fc 100644 --- a/Documentation/GNUmakefile +++ b/Documentation/GNUmakefile @@ -6,7 +6,7 @@ NAME = documentation SUBDIRS= user metadoc bibliography pictures topdocs ntweb STEPMAKE_TEMPLATES=documentation texinfo -README_TOP_FILES=NEWS DEDICATION TODO AIMS +README_TOP_FILES=NEWS DEDICATION TODO AIMS CHANGES INFO_FILES = $(wildcard $(outdir)/$(package).info*) EXTRA_DIST_FILES = COPYRIGHT @@ -24,3 +24,4 @@ local-WWW: copy-for-me copy-for-me: $(foreach a, $(README_TOP_FILES),cp ../$(a) $(outdir)/$(a).txt && ) true + diff --git a/Documentation/topdocs/index.tely b/Documentation/topdocs/index.tely index 766b43c25a..973f35c707 100644 --- a/Documentation/topdocs/index.tely +++ b/Documentation/topdocs/index.tely @@ -43,16 +43,13 @@ simple pieces, tests and bugs. MIDI, PNG, PostScript, and Source. LilyPond handling real music. MIDI, view PNG, PostScript, and Source. @end itemize -@unnumberedsec Documentation +@unnumberedsec More information @itemize @bullet -@item @uref{Documentation/tex/out-www/tutorial.html,Tutorial} -@item @uref{Documentation/out-www/faq.html,FAQ} +@item @uref{Documentation/out-www/index.html, Documentation} @item @uref{Documentation/out-www/mail.html,Mailing Lists} -@item @uref{Documentation/out-www/index.html,All of the LilyPond documentation} -@item @uref{./docxx/index.html,The DOC++ documentation of the C++ sources.} -@item @uref{Documentation/topdocs/out-www/INSTALL.html,The installation instructions} +@item @uref{./docxx/index.html,Source code documentation} @end itemize @unnumberedsec Sites diff --git a/Documentation/user/lilypond.tely b/Documentation/user/lilypond.tely new file mode 100644 index 0000000000..1567ec748e --- /dev/null +++ b/Documentation/user/lilypond.tely @@ -0,0 +1,128 @@ +\input texinfo @c -*-texinfo-*- +@setfilename lilypond.info +@settitle LilyPond Reference Manual + + + +@titlepage +@title LilyPond +@subtitle The GNU Project Typesetter +@author Han-Wen Nienhuys, Jan Nieuwenhuizen and Adrian Mariano + + Copyright @copyright 1999 by the authors + +@vskip 0pt plus 1filll + +Permission is granted to make and distribute verbatim +copies of this manual provided the copyright notice and +this permission notice are preserved on all copies. + +Permission is granted to copy and distribute modified +versions of this manual under the conditions for +verbatim copying, provided also that the sections +entitled ``Copying'' and ``GNU General Public License'' +are included exactly as in the original, and provided +that the entire resulting derived work is distributed +under the terms of a permission notice identical to this +one. + +Permission is granted to copy and distribute +translations of this manual into another language, +under the above conditions for modified versions, +except that this permission notice may be stated in a +translation approved by the Free Software Foundation. + +@end titlepage + +@ifinfo +This file documents GNU LilyPond. + +Copyright 1999 Han-Wen Nienhuys, Jan Nieuwenhuizen and Adrian Mariano + +Permission is granted to make and distribute verbatim +copies of this manual provided the copyright notice and +this permission notice are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX +and print the results, provided the printed document +carries a copying permission notice identical to this +one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +@end ignore + +Permission is granted to copy and distribute modified +versions of this manual under the conditions for +verbatim copying, provided also that the sections +entitled ``Copying'' and ``GNU General Public License'' +are included exactly as in the original, and provided +that the entire resulting derived work is distributed +under the terms of a permission notice identical to this +one. + +Permission is granted to copy and distribute +translations of this manual into another language, +under the above conditions for modified versions, +except that this permission notice may be stated in a +translation approved by the Free Software Foundation. + +@end ifinfo + +@ignore +Should add disclaimer, abstract + +"GNU LilyPond has no connection with the music package Rosegarden, other +than the names being similar :-)" + + + +@end ignore + +@contents + +@node Top, , , (dir) +@top +@menu +* Tutorial:: a tutorial introduction to lilypond. +* Invoking LilyPond:: Operation. +* Reporting Bugs:: Where to report bugs. +* Reference Manual:: Reference Manual. +* Glossary:: A dictionary of musical terms. +* More information:: Where to turn to for more help. +* convert-mudela:: Upgrading input files. +* Index:: Unified index. +@end menu + +@macro keyindex {word} +@cindex \word\ + +@end macro + +@macro indexcode {word} +@cindex \word\ + +@end macro + + +@mbinclude tutorial.itely + + +@include invoking.itexi + +@include bugs.itexi + +@mbinclude refman.itely + +@include glossary.itexi + +@include moreinfo.itexi + +@include convert-mudela.itexi + +@node Index, , , Top +@unnumbered Index + +@printindex cp + +@bye diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely new file mode 100644 index 0000000000..786cbc2f6d --- /dev/null +++ b/Documentation/user/refman.itely @@ -0,0 +1,2976 @@ + + +@node Reference Manual, , , Top +@menu +* Overview:: Overview +* Top level:: Top level +* notenames:: notenames +* Lexical conventions:: Lexical conventions +* Other languages:: notelang +* modes:: modes +* Types:: Types +* Music expressions:: Music expressions +* Atomic music expressions:: Atomic music expressions +* Note specification:: notedesc +* barlines:: barlines +* Manual beams:: Manual beam +* tremolo:: tremolo +* Compound music expressions:: Compound music expressions +* relative:: relative +* Repeats:: Repeats +* transpose:: transpose +* Ambiguities:: Ambiguities +* Notation conversion specifics:: Notation conversion specifics +* autobeam:: autobeam +* lyricprint:: lyricprint +* Notation Contexts:: Notation Contexts +* Properties:: Changing formatting +* Notation output definitions:: Notation output definitions +* paper:: paper +* Paper variables:: papervars +* contextdefs:: contextdefs +* engravers:: engravers +* Sound output:: Sound output +* midilist:: midilist +* Pre-defined Identifiers:: Pre-defined Identifiers +@end menu + +@chapter Reference Manual + + + +@node Overview, , , Reference Manual +@section Overview + +This document@footnote{This document has been revised for +LilyPond 1.2.} describes the the GNU LilyPond input format, which is +a language for defining music. We call this language @emph{Music +Definition Language} or @emph{Mudela}, for short.@footnote{If anybody +comes up with a better name, we'd gladly take this. Gourlay already +uses a ``Musical Description Language,'' ISO standard 10743 defines a +``Standard Music Description Language.'' We're not being original +here.} + +@emph{Mudela} is a language that allows you to + +@itemize @bullet + @item create musical expressions by combining pitches, durations + @item output those musical expressions to various formats + @item give those musical expressions and output definitions names, so + you can enter them in manageable chunks. +@end itemize + +@emph{Mudela} aims to define a piece of music completely, both from +typesetting and from a performance point of view. + + + +@node Top level, , , Reference Manual +@section Top level + +@cindex top level + +This section describes what you may enter at top level. + + + +@cindex score definition + +The output is generated combining a music expression with an output +definition. A score block has the following syntax: + +@example + \score @{ @var{musicexpr} @var{outputdefs} @} +@end example + +@var{outputdefs} are zero or more output definitions. If no output +definition is supplied, the default @code{\paper} block will be added. + + + +@cindex header + +@keyindex{header} + +The syntax is + +@example + \header @{ @var{key1} = @var{val1}; + @var{key2} = @var{val2}; @dots{} @} +@end example + +A header describes the file's contents. It can also appear in a +@code{\score} block. Tools like @code{ly2dvi}@indexcode{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. + + +@node notenames, , , Reference Manual + +Note name tables can be specified using + +@example + \notenames@keyindex{notenames} + @{ @var{assignmentlist} @} +@end example + +@var{assignmentlist} is a list of definitions of the form + +@example + @var{name} = @var{pitch} +@end example + +Chord modifiers can be set analogously, with +@code{\chordmodifiers}@keyindex{chordmodifiers}. + +A @code{\paper} block at top level sets the default paper block. A +@code{\midi} block at top level works similarly. + + + +LilyPond contains a Scheme interpreter (the GUILE library) for +internal use. The following commands access the interpreter +directly. + +@example + \scm @keyindex{scm} @var{scheme} ; +@end example + +Evaluates the specified Scheme code. The result is discarded. + +@example +\scmfile@keyindex{scmfile} @var{filename}; +@end example + +Reads Scheme code from the specified file. The result is discarded. + + + +Identifier assignments may appear at top level. Semicolons are +forbidden after top level assignments. + + + +@node Lexical conventions, , , Reference Manual +@section Lexical conventions + +@cindex lexical conventions + + + +@cindex comment + +@indexcode{%} + + +A one line comment is introduced by a `@code{%}' character. +Block comments are started by `@code{%@{}' and ended by `@code{%@}}'. +They cannot be nested. + + + +@cindex keyword + +Keywords start with a backslash, followed by a number of lower case +alphabetic characters. These are all the keywords. + +@example + \accepts + \addlyrics + \alternative + \bar + \breathe + \cadenza + \chordmodifiers + \chords + \clef + \cm + \consists + \consistsend + \context + \duration + \font + \grace + \header + \in + \key + \keysignature + \lyrics + \mark + \midi + \mm + \musicalpitch + \name + \notenames + \notes + \paper + \partial + \penalty + \property + \pt + \relative + \remove + \repeat + \repetitions + \scm + \scmfile + \score + \script + \sequential + \shape + \simultaneous + \skip + \spanrequest + \tempo + \textscript + \time + \times + \translator + \transpose + \type +@end example + + + + +@cindex integer + +Formed from an optional minus sign followed by digits. Arithmetic +operations cannot be done with integers, and integers cannot be mixed +with reals. + + + +@cindex real + + +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{+}@indexcode{+}', `@code{-}@indexcode{-}', `@code{*}@indexcode{*}', and +`@code{/}@indexcode{/}', with parentheses for grouping. + +A real constant can be followed by one of the dimension +keywords: +@cindex dimensions + @code{\mm}@keyindex{mm}, +@code{\pt}@keyindex{pt}, @code{\in}@keyindex{in}, or +@code{\cm}@keyindex{cm}, for millimeters, points, inches and +centimeters, respectively. This converts the number to a real that +is the internal representation of dimensions. + + + +@cindex string + + +Begins and ends with the `@code{"}' character. To include a `@code{"}' +character in a string write `@code{\"}'. Various other backslash +sequences have special interpretations as in the C language. A +string that contains no spaces can be written without the quotes. +See section XREF-modes [FIXME] for details on unquoted strings; their +interpretation varies depending on the situation. Strings can be +concatenated with the `@code{+}' operator. + + +The tokenizer accepts the following commands. They can appear +anywhere. + +@example + \maininput@keyindex{maininput} +@end example + +This command is used in init files to signal that the user file must +be read. This command cannot be used in a user file. + +@example + \include@keyindex{include} @var{file} +@end example + +Include @var{file}. The argument @var{file} 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, + +@example + \version@keyindex{version} @var{string} ; +@end example + +Specify the version of LilyPond that a file was written for. The +argument is a version string in quotes, for example @code{"1.2.0"}. +This is used to detect invalid input, and to aid +@code{convert-mudela}, a tool that automatically upgrades input files. + + + +@cindex other languages + +@node Other languages, , , Reference Manual + +Note name definitions have been provided in various languages. +Simply include the language specific init file. For example: +`@code{\include "english.ly"}'. The available language files and the +names they define are: + +@quotation + +@example + Note Names sharp flat +nederlands.ly c d e f g a bes b -is -es +english.ly c d e f g a bf b -s/-sharp -f/-flat +deutsch.ly c d e f g a b h -is -es +norsk.ly c d e f g a b h -iss/-is -ess/-es +svenska.ly c d e f g a b h -iss -ess +italiano.ly do re mi fa sol la sid si -d -b +catalan.ly do re mi fa sol la sid si -d/-s -b +@end example + +@end quotation + +Pitch names can be redefined using the +@code{\notenames}@keyindex{notenames} command, see +subsection XREF-notenames [FIXME]. + + + +@cindex lexical modes + +@cindex modes + +@node modes, , , Reference Manual + +To simplify entering notes, lyrics, and chords, @emph{Mudela} 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. + +@table @samp + @item Normal mode. +@cindex mode!normal + + At the start of parsing, @emph{Mudela} 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 Note mode. +@cindex mode!note + + Note mode is introduced by the keyword + @code{\notes}@keyindex{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. + + Since combinations of numbers and dots are used for indicating + durations, it is not possible to enter real numbers in this mode. + + @item Chord mode. +@cindex mode!chord + + Chord mode is introduced by the keyword + @code{\chords}@keyindex{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. + + @item Lyrics mode. +@cindex mode!lyric + + Lyrics mode is introduced by the keyword + @code{\lyrics}@keyindex{lyrics}. This mode has rules that make it + easy to include punctuation and diacritical marks in words. 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{^}'.@footnote{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 indeed is + ludicrous. This will remain so until the authors of LilyPond + acquire a deeper understanding of character encoding, or someone + else steps up to fix this.} + + 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 if + you thought the closing brace was going to terminate Lyrics + mode.@footnote{LilyPond will issue a warning, though.} Any + `@code{_}' characters which appear in an unquoted word are + converted to spaces. 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. + + + @quotation + +@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 + + @end quotation + + Since combinations of numbers and dots are used for indicating + durations, you can not enter real numbers in this mode. +@end table + +It is possible to create words that break the rules by prefixing them +with the dollar sign `@code{$}@indexcode{$}'. Regardless of the context, a +word beginning with `@code{$}' extends until the next white space +character. Such words can contain numbers (even in Note mode), or +other forbidden characters. The dollar sign can be used to create +and access identifiers that could not otherwise be used.@footnote{Use +of `@code{$}' hampers readability and portability to future LilyPond +versions, thus the use of the dollar sign is discouraged.} + + + +@node Types, , , Reference Manual +@section Types + +@cindex types and identifiers + +@emph{Mudela} has a limited set of types: + +@itemize @bullet + @item integers + @item reals + @item strings + @item music expressions + @item durations of notes and rests (specified with + @code{\notenames}@keyindex{notenames}) + @item note name tables + @item context definitions, part of output definitions. See + section XREF-contextdefs [FIXME] for more information + @item output definitions (like @code{\paper}@keyindex{paper} blocks + and @code{\midi}@keyindex{midi} blocks) + @item score definitions (@code{\score}@keyindex{score} blocks) +@end itemize + +Type is a syntactical property: @emph{Mudela} has no real type system, +so there is no support for generic expressions, functions, or user +defined types. For the same reason, it is not possible to mix reals +and integers in arithmetic expressions, and ``type +errors'' +@cindex type error + (e.g., using a string identifier to +initialize a @code{\paper}@keyindex{paper} block) will yield a ``parse +error''. + +Identifiers allow objects to be assigned to names. To assign an +identifier, you use `@var{name}=@var{value}' and to refer to an +identifier, you preceed its name with a backslash: +`@code{\}@var{name}'. Identifier assignments must appear at top level +in the @emph{Mudela} file. Semicolons are forbidden after assignments +appearing at top level but they are obligatory after assignments +appearing in the @code{\paper} block, see Section XREF-paper [FIXME]. + +@var{value} is any of the types listed above. + +An identifier can be created with any string for its name, but you +will only be able to refer to identifiers whose names begin with a +letter, being entirely alphanumeric. It is impossible to refer to an +identifier whose name is the same as the name of a keyword. + +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. + +@example + foo = \foo * 2.0 +@end example + +When an identifier is referenced, the information it points to is +copied. Therefore it only makes sense to put identifiers for +translators, output definitions, and @code{\score}@keyindex{score} +blocks as the first item in a block. For this reason, if you +reference a @code{\foo} variable in a @code{\foo} block, it must be the +first item in the list following @code{\foo}.@footnote{@code{\paper@{\one +\two@}} does not make sense, because the information of @code{\two} +would overwrite the information of @code{\one}, thereby making the +reference to the first identifier useless.} + + + +@node Music expressions, , , Reference Manual +@section Music expressions + +@cindex music expressions + +Music in @emph{Mudela} 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 XREF-atomicmusic [FIXME]. Compound music expressions are +discussed in subsection XREF-compoundmusic [FIXME]. + + + +@node Atomic music expressions, , , Reference Manual +@section Atomic music expressions + + + + +@cindex pitch + +@cindex duration + + +The syntax for pitch specification is + + +@example + \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @} +@end example + +@var{octave} is specified by an integer, zero for the octave +containing middle C. @var{note} is a number from 0 to 7, with 0 +corresponding to C and 7 corresponding to B. The shift is zero for a +natural, negative to add flats, or positive to add sharps. + +In Note and Chord mode, pitches may be designated by names. See +section XREF-notelang [FIXME] for pitch names in different languages. + +The syntax for duration specification is + +@example + \duration@keyindex{duration} + @{ @var{length} @var{dotcount} @} +@end example + +@var{length} is the negative logarithm (base 2) of the duration: +1 is a half note, 2 is a quarter note, 3 is an eighth +note, etc. The number of dots after the note is given by +@var{dotcount}. + +In Note, Chord, and Lyrics mode, durations may be designated by +numbers and dots. See Section XREF-notelang [FIXME] for details. + + +@node Note specification, , , Reference Manual + +@cindex note specification + +@cindex pitches + +@cindex entering notes + +A note specification has the form + +@example + @var{pitch}[@var{octavespec}][!][?][@var{duration}] +@end example + +The pitch of the note is specified by the note's name. + + +The default names are the Dutch note names. The notes are specified +by the letters `@code{c}' through `@code{b}', where `@code{c}' is an +octave below middle C and the letters span the octave above that C. +In Dutchcindex(notenames!Dutch), a sharp is formed by adding +`@code{-is}' to the end of a pitch name. A flat is formed by adding +`@code{-es}'. Double sharps and double flats are obtained by adding +`@code{-isis}' or `@code{-eses}'. `@code{aes}' and `@code{ees}' are +contracted to `@code{as}' and `@code{es}' in Dutch, but both forms will +be accepted. + +LilyPond has predefined sets of notenames for various languages. See +section XREF-notelang [FIXME] for details. + + +The optional octave specification takes the form of a series of +single quote (`@code{'}@indexcode{'}') characters or a series of comma +(`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one +octave; each @code{,} lowers the pitch by an octave. + +@mudela[fragment,verbatim,center] + c' d' e' f' g' a' b' c'' +@end mudela + +@mudela[fragment,verbatim,center] + cis' dis' eis' fis' gis' ais' bis' +@end mudela + +@mudela[fragment,verbatim,center] + ces' des' es' fes' ges' as' bes' +@end mudela + +@mudela[fragment,verbatim,center] + cisis' eisis' gisis' aisis' beses' +@end mudela + +@mudela[fragment,verbatim,center] + ceses' eses' geses' ases' beses' +@end mudela + +Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond +will determine what accidentals to typeset depending on the key and +context. A reminder accidental +@cindex reminder accidental + can be +forced by adding an exclamation mark `@code{!}' after the pitch. A +cautionary accidental, +@cindex cautionary accidental + i.e., an +accidental within parentheses can be obtained by adding the question +mark `@code{?}@indexcode{?}' after the pitch. + +@mudela[fragment,verbatim,center] + cis' d' e' cis' c'? d' e' c'! +@end mudela + + +@cindex duration + +Durations are entered as their reciprocal values. For notes longer +than a whole note, use identifiers. + +@quotation + +@example +c'\longa c'\breve +c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 +@end example + +@end quotation + +@quotation + +@mudela[] +\score { + \notes \relative c'' { + a\longa a\breve + a1 a2 a4 a8 a16 a32 a64 a64 + } + \paper { + loose_column_distance = 2.5 * \interline; + linewidth = -1.0; + \translator { + \type "Score_engraver"; + \name "Score"; + \consists "Note_heads_engraver"; + \consists "Stem_engraver"; + \consists "Rhythmic_column_engraver"; + } + } +} +@end mudela +@end quotation + +@quotation + +@example +r\longa r\breve +r1 r2 r4 r8 r16 r32 r64 r64 +@end example + +@end quotation + +@quotation + +@mudela[] +\score { + \notes \relative c'' { + r\longa r\breve + r1 r2 r4 r8 r16 r32 r64 r64 + } + \paper { + loose_column_distance = 2.5 * \interline; + linewidth = -1.0; + \translator { + \type "Score_engraver"; + \name "Score"; + \consists "Rest_engraver"; + \consists "Stem_engraver"; + \consists "Rhythmic_column_engraver"; + } + } +} +@end mudela +@end quotation + +If the duration is omitted then it is set equal to the previous +duration. If there is no previous duration, a quarter note is +assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}') +to obtain dotted note lengths. + +@mudela[fragment,verbatim,center] + a'4. b'4. +@end mudela + +You can alter the length of duration by writing +`@code{*}@var{fraction}' after it. This will not affect the +appearance of note heads or rests. + + +Rests are entered like notes, with note name `@code{r}@indexcode{r}', +or `@code{R}@indexcode{R}'. There is also a note name `@code{s}@indexcode{s}', +which produces a space of the specified duration. +`@code{R}' is specifically meant for entering parts: the @code{R} rest +can expand to fill a score with rests, or it can be printed as a +single multimeasure rest. + + +@cindex lyrics expressions + +Syllables are entered like notes, with pitches replaced by text. For +example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each +with quarter note duration. Note that the hyphen has no special +meaning for lyrics, and does not introduce special symbols. See +section XREF-modes [FIXME] for a description of what is interpreted as +lyrics. + +Spaces can be introduced into a lyric either by using quotes +(`@code{"}') or by using an underscore without quotes: `@code{He_could4 +not4}'. All unquoted underscores are converted to spaces. Printing +lyrics is discussed in section XREF-lyricprint [FIXME]. + + + +@cindex properties + +@example + \property@keyindex{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 + +@example + \translator@keyindex{translator} + @var{contexttype} = @var{name} +@end example + +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. + +Usually this is used to switch staffs in Piano music, e.g. + +@example + \translator Staff = top @var{Music} +@end example + + + +@cindex commands + +Commands are music expressions that have no duration. + + +@example + + @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;} +@end example + +Change the key signature. @var{type} should be +@code{\major}@keyindex{major} or @code{\minor}@keyindex{minor} to get +@var{pitch}-major or @var{pitch}-minor, respectively. The second +argument is optional; the default is major keys. The @var{\context} +argument can also be given as an integer, which tells the number of +semitones that should be added to the pitch given in the subsequent +@code{\key}@keyindex{key} commands to get the corresponding major key, +e.g., @code{\minor}@keyindex{minor} is defined as 3. The standard +mode names @code{\ionian}@keyindex{ionian}, +@code{\locrian}@keyindex{locrian}, @code{\aeolian}@keyindex{aeolian}, +@code{\mixolydian}@keyindex{mixolydian}, @code{\lydian}@keyindex{lydian}, +@code{\phrygian}@keyindex{phrygian}, and @code{\dorian}@keyindex{dorian} +are also defined. + +@example + + @code{\keysignature}@keyindex{keysignature} @var{pitchseq} @code{;} +@end example + +Specify an arbitrary key signature. The pitches from @var{pitch} will +be printed in the key signature in the order that they appear on the +list. + + +@example + \mark@keyindex{mark} @var{unsigned}; + \mark @var{string}; +@end example + +Prints a mark over or under (depending on the +@code{markDirection}@indexcode{markDirection} property) the staff. You must add +@code{Mark_engraver}@indexcode{Mark_engraver} to either the Score or Staff context for +this to work. + +@node barlines, , , Reference Manual + +@example + \bar@keyindex{bar} @var{bartype}; +@end example + +This is a request to print a special bar symbol. It replaces the +regular bar symbol with a special +symbol. The argument @var{bartype} is a string which specifies the +kind of bar to print. Options are @code{":|"} +@cindex "|A@@@code{:|} +, +@code{"|:"} +@cindex "|B@@@code{|:} +, @code{":|:"} +@cindex "|C@@@code{:|:} +, +@code{"||"} +@cindex "|D@@@code{||} +, @code{"|."} +@cindex "|E@@@code{|.} +, +@code{".|"} +@cindex "|F@@@code{.|} +, and @code{".|."} +@cindex "|G@@@code{.|.} +. +These produce, respectively, a right repeat, a left repeat, a double +repeat, a double bar, a start bar, an end bar, and a thick double +bar. If @var{bartype} is set to @code{"empty"} then nothing is +printed, but a line break is allowed at that spot. + +You are encouraged to use @code{\repeat} for repetitions. +See section XREF-sec-repeats [FIXME]. + + + +@example + \cadenza@keyindex{cadenza} @var{togglevalue} @code{;} +@end example + +Music expression that toggles the automatic generation of bar lines. +If @var{togglevalue} is 1, bar line generation is turned off. If +@var{togglevalue} is 0, a bar line is immediately printed and +automatic bar generation is turned on. + +@example + + \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;} +@end example + +Change the time signature. The default time signature is 4/4. +The time signature is used to generate bar lines. + +@example + + \tempo@keyindex{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. + +@example + + \partial@keyindex{partial} @var{duration} @code{;} +@end example + +@cindex anacrusis + +@cindex upstep + +This creates an incomplete measure (anacrusis, upbeat) at the start of +the music, e.g., `@code{\partial 8*2;}' creates a starting measure +lasting two eighth notes. + +@example + + @code{|}@indexcode{|} +@cindex bar check + +@end example + +@cindex shorten measures + +@cindex upstep + +`@code{|}' is a barcheck. Whenever a barcheck is encountered during +interpretation, a warning message is issued if it doesn't fall at a +measure boundary. This can help you finding errors in the input. +The beginning of the measure will be relocated, so this can also +be used to shorten measures. + + +@example + + \penalty@keyindex{penalty} @var{int} @code{;} +@end example + +Discourage or encourage line breaks. See identifiers +@code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in +section [on identifiers] [FIXME]. + +@example + + \clef@keyindex{clef} @var{clefname} @code{;} +@end example + +Music expression that sets the current clef. The argument is a +string which specifies the name of the clef. Several clef names are +supported. If `@code{_8}' or `@code{^8}' is added to the end of a clef +name, then the clef lowered or raised an octave will be generated. +Here are the supported clef names with middle C shown in each +clef: + +@quotation + +@mudela[] +\score { + \notes { + \cadenza 1; + %\property Voice.textStyle = typewriter + \clef subbass; c'4-"\kern -5mm subbass" + \clef bass; c'4^"\kern -2mm bass" + \clef baritone; c'4_"\kern -5mm baritone" + \clef varbaritone; c'4^"\kern -6mm varbaritone" + \clef tenor; c'4_"\kern -3mm tenor" + \clef "G_8"; c'4^"\kern -2mm G\\_8" + } + \paper { + linewidth = 4.5 \in; + } +} +@end mudela +@end quotation + +@quotation + +@mudela[] +\score { + \notes { + \cadenza 1; + \clef alto; c'4_"\kern -2mm alto" + \clef mezzosoprano; c'4^"\kern -9mm mezzosoprano" + \clef soprano; c'4_"\kern -6mm soprano" + \clef treble; c'4^"\kern -4mm treble" + \clef french; c'4_"\kern -4mm french" + } + \paper { + linewidth = 4.5 \in; + } +} +@end mudela +@end quotation + +The three clef symbols can also be obtained using the names `@code{G}', +`@code{C}' or `@code{F}', optionally followed by an integer which +indicates at which note line the clef is located. An as example, the +@code{mezzosoprano} clef can also be given as `@code{C2}'. + +@example + + \skip@keyindex{skip} @var{duration} @code{;} +@end example + +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 space rest `@code{s}'. + + +@cindex beams + +@node Manual beams, , , Reference Manual + +A beam is specified by surrounding the beamed notes with brackets +`@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'. + +@mudela[fragment,verbatim,center] + [a'8 a'] [a'16 a' a' a'] +@end mudela + +Some more elaborate constructions: + +@mudela[fragment,verbatim,center] + [a'16 c'' ] + \times 2/3 { [e'8 f' g'] } +@end mudela + +Beaming can be generated automatically; see section XREF-autobeam [FIXME]. + +To place tremolo marks +@cindex tremolo beams + between two notes, begin +with `@code{[:}@var{length}' and end with `@code{]}'. Tremolo marks +will appear instead of beams. Putting more than two notes in such a +construction will produce odd effects. To create tremolo beams on a +single note, simply attach `@code{:}@var{length}' to the note itself +(see also section XREF-tremolo [FIXME]). + +@mudela[fragment,verbatim,center] + [:16 e'1 g'] [:8 e'4 f'] +@end mudela + +@mudela[fragment,verbatim,center] + c'4:32 [:16 c'8 d'8] +@end mudela + + +@cindex --@@@code{-}@code{-} + +@indexcode{__} + +@cindex extender + +@cindex hyphen + +The syntax for an extender mark is `@code{__}'. This syntax can only +be used within lyrics mode. The syntax for a spanning hyphen (i.e., +a hyphen that will be printed between two lyric syllables) is +`@code{-}@code{-}'. + + +@cindex ties + +A tie connects two adjacent note heads of the same pitch. When used +with chords, it connects all of the note heads whose pitches match. +Ties are indicated using the tilde symbol `@code{~}@indexcode{~}'. +If you try to tie together chords which have no common pitches, a +warning message will appear and no ties will be created. + +@mudela[fragment,verbatim,center] + e' ~ e' ~ +@end mudela + + + +[TODO: explain Requests] + + +@cindex articulations + +@cindex scripts + +@cindex ornaments + +A variety of symbols can appear above and below notes to indicate +different characteristics of the performance. These symbols can be +added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols +are defined in @file{script.ly} and @file{script.scm}. Symbols can be +forced to appear above or below the note by writing +`@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}' +respectively. Here is a chart showing symbols above notes, with the +name of the corresponding symbol appearing underneath. + +@mudela[] + + \score { + < \notes { + c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata + c''-\stopped c''-\staccato c''-\tenuto c''-\upbow + c''-\downbow c''^\lheel c''-\rheel c''^\ltoe + c''-\rtoe c''-\turn c''-\open c''-\flageolet + c''-\reverseturn c''-\trill c''-\prall c''-\mordent + c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall + c''-\thumb c''-\segno c''-\coda + } + \context Lyrics \lyrics { + accent__ marcato__ staccatissimo__ fermata + stopped__ staccato__ tenuto__ upbow + downbow__ lheel__ rheel__ ltoe + rtoe__ turn__ open__ flageolet + reverseturn__ trill__ prall__ mordent + prallprall__ prallmordent__ uprall__ downprall + thumb__ segno__ coda + } + > + \paper { + linewidth = 5.875\in; + indent = 0.0; + } + } + +@end mudela + +In addition, it is possible to place arbitrary strings of text or +TeX above or below notes by using a string instead of an +identifier: `@code{c^"text"}'. Fingerings +@cindex fingering + can be +placed by simply using digits. All of these note ornaments appear in +the printed output but have no effect on the MIDI rendering of the +music. + +To save typing, fingering instructions (digits 0 to 9 are +supported) and single characters shorthands exist for a few +common symbols + +@mudela[] + + \score { + \notes { + \property Voice.textStyle = typewriter + c''4-._"c-." s4 + c''4--_"c-{}-" s4 + c''4-+_"c-+" s4 + c''4-|_"c-|" s4 + c''4->_"c->" s4 + c''4-^_"c-\\^{ }" s4 + c''4-1_"c-1" s4 + c''4-2_"c-2" s4 + c''4-3_"c-3" s4 + c''4-4_"c-4" s4 + } + \paper { + linewidth = 5.875 \in; + indent = 0.0; + } + } + +@end mudela + +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}@keyindex{ppp}, +@code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp}, +@code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff}, +@code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff}, +@code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf}, +@code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp}, +@code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and +@code{\rfz}@keyindex{rfz}. + + +@example + + \textscript@keyindex{textscript} @var{text} @var{style} +@end example + +Defines a text to be printed over or under a note. @var{style} is a +string that may be one of @code{roman}, @code{italic}, @code{typewriter}, +@code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}. + +You can attach a general textscript request using this syntax: + +@quotation + +@example +c4-\textscript "6" "finger" +c4-\textscript "foo" "normal" +@end example + +@end quotation + +This is equivalent to `@code{c4-6 c4-"foo"}'. + + +@cindex scripts + +@example + + \script@keyindex{script} @var{alias} +@end example + +Prints a symbol above or below a note. The argument is a string +which points into the script-alias table defined in @file{script.scm}. +The scheme definitions specify whether the symbol follows notes into +the staff, dependence of symbol placement on staff direction, and a +priority for placing several symbols over one note. Usually the +@code{\script}@keyindex{script} keyword is not used directly. Various +helpful identifier definitions appear in @file{script.ly}. + + +@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: + +@mudela[fragment,verbatim,center] + f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 +@end mudela + + +@cindex crescendo + +A crescendo mark is started with @code{\cr}@keyindex{cr} and terminated +with @code{\rc}@keyindex{rc}. A decrescendo mark is started with +@code{\decr}@keyindex{decr} and terminated with +@code{\rced}@keyindex{rced}. There are also shorthands for these +marks. A crescendo can be started with @code{\<}@keyindex{<} and a +decrescendo can be started with @code{\>}@keyindex{>}. Either one can +be terminated with @code{\!}@keyindex{"!}. 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. + +@mudela[fragment,verbatim,center] + c'' \< \! c'' d'' \decr e'' \rced + < f''1 { s4 \< \! s2 \> \! s4 } > +@end mudela + + +@example + + \spanrequest@keyindex{spanrequest} @var{startstop} @var{type} +@end example + +Define a spanning request. The @var{startstop} parameter is either -1 +(@code{\start}@keyindex{start}) or 1 (@code{\stop}@keyindex{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 + +@mudela[fragment,verbatim,center] + c'4-\spanrequest \start "slur" + c'4-\spanrequest \stop "slur" +@end mudela + +The slur syntax with parentheses is a shorthand for this. + + + +@cindex tremolo marks + +@node tremolo, , , Reference Manual + +Tremolo marks can be printed on a single note by adding +`@code{:}[@var{length}]' after the note. The length must be at +least 8. A @var{length} value of 8 gives one line across +the note stem. If the length is omitted, then the last value is +used, or the value of the @code{abbrev}@indexcode{abbrev} property if there was +no last value. + +@mudela[verbatim,fragment,center] + c'2:8 c':32 +@end mudela + + + +@node Compound music expressions, , , Reference Manual +@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: + +@mudela[fragment,verbatim,center] + \notes \context Staff { + \cadenza 1; + + <{a b c'}{c' d' e'}> + } +@end mudela + +@cindex context selection +@keyindex{context} + +@example + \context + @var{contexttype} [= @var{contextname}] @var{musicexpr} +@end example + +Interpret @var{musicexpr} within a context of type @var{contexttype}. +If the context does not exist, it will be created. The new context +can optionally be given a name. See +section XREF-contextselection [FIXME] and XREF-contextdefs [FIXME] for more +information on interpretation contexts. + + + +@cindex input modes + +@cindex mode switch + +Mode switching keywords form compound music expressions: @code{\notes} +@keyindex{notes} @var{musicexpr}, @code{\chords} @keyindex{chords} +@var{musicexpr}, and @code{\lyrics} @keyindex{lyrics} @var{musicexpr}. +These expressions do not add anything to the meaning of their +arguments. They are just a way to indicate that the arguments should +be parsed in indicated mode. See section XREF-modes [FIXME] for more +information on modes. + +More information on context selection can be found in +section XREF-contextselection [FIXME]. + + + +@cindex sequential music + + + +@example + + \sequential@keyindex{sequential} + @code{@{} @var{musicexprlist} @code{@}} +@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: + +@example + + @code{@{} @var{musicexprlist} @code{@}} +@end example + + + +@cindex simultaneous music + +@indexcode{<} +@indexcode{>} + +@example + + \simultaneous@keyindex{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: + +@example + + @code{<} @var{musicexprlist} @code{>} +@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. + +@mudela[verbatim,center] + \score { + \notes + \paper { + linewidth = -1.; + } + } +@end mudela + +This happens because the chord is interpreted by a score context. +Each time a note is encountered a default Voice context (along with a +Staff context) is created. The solution is to explicitly instantiate +a Voice context: + +@mudela[verbatim,center] + \score { + \notes\context Voice + \paper { + linewidth = -1.; + } + } +@end mudela + + + +@cindex relative pitch specification + +@node relative, , , Reference Manual + +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. + +@example + + \relative@keyindex{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}. + +Entering scales is straightforward in relative mode. + +@mudela[fragment,verbatim,center] + \relative c' { + c d e f g a b c c, + } +@end mudela + +And octave changing marks are used for intervals greater than a fourth. + +@mudela[fragment,verbatim,center] + \relative c'' { + c g c f, c' a, e'' } +@end mudela + +If the preceding item is a chord, the first note of the chord is used +to determine the first note of the next chord. But other notes +within the second chord are determined by looking at the immediately +preceding note. + +@mudela[fragment,verbatim,center] + \relative c' { + c + + + } +@end mudela + +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}@keyindex{notes} keyword (which is not +shown here). + +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}. + +It is strongly recommended to use relative pitch mode: less work, +less error-prone, and more readable. + + + +Chord names are a way to generate simultaneous music expressions that +correspond with traditional chord names. It can only be used in +Chord mode (see section XREF-modes [FIXME]). + +@example + + @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}]. +@end example + +@var{tonic} should be the tonic note of the chord, and @var{duration} +is the chord duration in the usual notation. There are two kinds of +modifiers. One type is @emph{chord additions}, which are obtained by +listing intervals separated by dots. An interval is written by its +number with an optional `@code{+}' or `@code{-}' to indicate raising or +lowering by half a step. Chord additions has two effects: It adds +the specified interval and all lower odd numbered intervals to the +chord, and it may lower or raise the specified interval. Intervals +must be separated by a dot (`@code{.}'). + +@quotation + +@mudela[fragment,verbatim] +\transpose c'' { + \chords { + c1 c-3- c-7 c-8 + c-9 c-9-.5+.7+ c-3-.5- c-4.6.8 + } +} + +@end mudela +@end quotation + +The second type of modifier that may appear after the `@code{-}' is a +named modifier. Named modifiers are listed in the file +@file{chord-modifiers.ly}. The available modifiers are `@code{m}' and +`@code{min}' which lower the 3rd half a step, `@code{aug}@indexcode{aug}' which +raises the 5th, `@code{dim}@indexcode{dim}' which lowers the 5th, +`@code{maj}@indexcode{maj}' which adds a raised 7th, and `@code{sus}@indexcode{sus}' +which replaces the 5th with a 4th. + +@quotation + +@mudela[fragment,verbatim] +\transpose c'' { + \chords { + c1-m c-min7 c-maj c-aug c-dim c-sus + } +} + +@end mudela +@end quotation + + +Chord subtractions are used to eliminate notes from a chord. The +notes to be subtracted are listed after a `@code{^}' character, +separated by dots. + +@mudela[fragment,verbatim,center] + \transpose c'' { + \chords { + c1^3 c-7^5.3 c-8^7 + } + } +@end mudela + +Chord inversions can be specified by appending `@code{/}@indexcode{/}' and +the name of a single note to a chord. This has the effect of +lowering the specified note by an octave so it becomes the lowest +note in the chord. If the specified note is not in the chord, a +warning will be printed. + +@mudela[fragment,verbatim,center] + \transpose c''' { + \chords { + c1 c/e c/g c-7/e + } + } + +@end mudela + +Throughout these examples, chords have been shifted around the staff +using @code{\transpose}. + +You should not combine @code{\relative} with named chords. + + + +@cindex tuplets + +Tuplets are made out of a music expression by multiplying their +duration with a fraction. + +@example + + \times@keyindex{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: + +@mudela[fragment,verbatim,center] + g'4 \times 2/3 {c'4 c' c'} d'4 d'4 +@end mudela + + + +@cindex grace notes + +@example + + \grace@keyindex{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}@indexcode{graceAlignPosition}. + +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{stemStyle}@indexcode{stemStyle} property. + +@quotation + +@mudela[fragment,verbatim] +\relative c'' { + \grace c8 c4 \grace { [c16 c16] } c4 + \grace { \property Grace.stemStyle = "" c16 } c4 +} + +@end mudela +@end quotation + +At present, nesting @code{\grace}@keyindex{grace} notes, e.g. + +@example + + @code{\grace @{ \grace c32 c16 @} c4} +@end example + +may result in run-time errors of LilyPond. 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. + + + +@cindex repeats + +@node Repeats, , , Reference Manual + +In order to specify repeats, use the @code{\repeat}@keyindex{repeat} +keyword. Since repeats look and sound differently when played or +printed, there are a few different variants of repeats. + +@table @samp + @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 useful for + lyrics. +@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 + +@example + + \alternative@keyindex{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: + +@quotation + +@mudela[fragment,verbatim] + c'1 + \repeat volta 2 { c'4 d' e' f' } + \repeat volta 2 { f' e' d' c' } + +@end mudela +@end quotation + +With alternative endings: + +@quotation + +@mudela[fragment,verbatim] + c'1 + \repeat volta 2 {c'4 d' e' f'} + \alternative { {d'2 d'} {f' f} } + +@end mudela +@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 + +@mudela[fragment,verbatim] + c'1 + \repeat fold 2 {c'4 d' e' f'} + \alternative { {d'2 d'} {f' f} } + +@end mudela +@end quotation + +@quotation + +@mudela[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 } } + } +} + +@end mudela +@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 + +@mudela[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 mudela +@end quotation + +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. + + + +@cindex transposition of pitches + +@node transpose, , , Reference Manual + +A music expression can be transposed with +@code{\transpose}@keyindex{transpose}. The syntax is + +@example + + \transpose @var{pitch} @var{musicexpr} +@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. + +@quotation + +@mudela[fragment,verbatim] +\context Staff { + \clef "F"; + { \key e; c d e f } + \clef "G"; + \transpose des'' { \key e; c d e f } + \transpose cis'' { \key e; c d e f } +} + +@end mudela +@end quotation + +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}. + + + +@cindex automatic lyric durations + +If you have lyrics that are set to a melody, you can import the +rhythm of that melody into the lyrics using @code{\addlyrics}. +@keyindex{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}. + +If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the +context of @var{musicexpr1}, no lyrics will be put on slurred or tied +notes. + +@quotation + +@mudela[verbatim,fragment] +\addlyrics +\transpose c'' { + \property Voice.automaticMelismata = "1" + c8 () cis d8. e16 f2 +} +\context Lyrics \lyrics { + do4 re mi fa } + +@end mudela +@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 + +@mudela[verbatim,fragment] +\addlyrics +\transpose c'' { + c8 () cis d8. e16 f2 +} +\context Lyrics \lyrics +< { do4 re mi fa } + { do8 re mi fa } > + +@end mudela +@end quotation + +It is valid (but probably not very useful) to use notes instead of +lyrics for @var{musicexpr2}. + + + + +@node Ambiguities, , , Reference Manual +@section Ambiguities + +@cindex ambiguities + +The grammar contains a number of ambiguities.@footnote{The authors +hope to resolve them at a later time.} + +@itemize @bullet + @item The assignment + + @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 + + @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 + + @quotation + +@example +\repeat @dots{} +\repeat @dots{} +\alternative +@end example + + @end quotation + + 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. + + @item (an as yet unidentified ambiguity :-) +@end itemize + + + +@node Notation conversion specifics, , , Reference Manual +@section Notation conversion specifics + + + +@cindex automatic beam generation + +@node autobeam, , , Reference Manual + +By default, LilyPond will generate beams automatically. This feature +can be disabled by setting the @code{Voice.noAutoBeaming}@indexcode{Voice.noAutoBeaming} +property to 1. It can be overridden for specific cases by +specifying explicit beams as described in +section XREF-manualbeam [FIXME]. + +A large number of Voice properties are used to decide how to generate +beams. Their default values appear in @file{auto-beam-settings.ly}. +In general, beams can begin anywhere, but their ending location is +significant. Beams can end on a beat, or at durations specified by +the @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} property. To end beams every +quarter note, for example, you could set +@code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} equal to `@code{"1/4"}'. To end beams +at every three eighth notes you would set it to `@code{"3/8"}'. The +same syntax can be used to specify beam starting points using +@code{Voice.beamAutoBegin}@indexcode{Voice.beamAutoBegin}. + +To allow different settings for different time signatures, these +property names can start with `@code{time}@var{N}@code{_}@var{M}' to +restrict the definition to `@var{N}@code{/}@var{M}' time. For example, +to specify beams ending only for 6/8 time you would use the +property @code{Voice.time6_8beamAutoEnd}. To allow different endings +for notes of different durations, the duration can be tacked onto the +end of the property. To specify beam endings for beams that contain +32nd notes, you would use @code{Voice.beamAutoEnd_32}. + + + +@cindex chord names + +@cindex chords + +@cindex printing!chord names + +For displaying printed chord names, use the @code{ChordNames}@indexcode{ChordNames} +and @code{ChordNameVoice}@indexcode{ChordNameVoice} contexts. The chords may be entered +either using the notation described above, or directly using +simultaneous music. + +@quotation + +@mudela[fragment,verbatim] +< + \context ChordNames { + \chords{a b c} \notes{ } + } + \context Staff \notes { + a b c' d' e' + } +> + +@end mudela +@end quotation + +LilyPond examines chords specified as lists of notes to determine a +name to give the chord. By default, LilyPond will not try to +identify chord inversions: + +@mudela[fragment,verbatim,center] + < + \context ChordNameVoice \notes { + + } + \context Thread \notes { + + } + > +@end mudela + +If you want inversions to be recognized, you must set the property +@code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}: + +@mudela[fragment,verbatim,center] + < + \property Score.chordInversion = 1 + \context ChordNameVoice \notes { + + } + \context Thread \notes { + + } + > +@end mudela + + + +@cindex lyrics + +@cindex printing!lyrics + +@node lyricprint, , , Reference Manual + +Lyric syllables must be interpreted within a @code{Lyrics} context + +@cindex context!Lyrics + for printing them. + +Here is a full example: + +@quotation + +@mudela[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 mudela +@end quotation + +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{_}'). + +@quotation + +@mudela[verbatim] +\score { + < + \notes \relative c'' { + a4 () b () c () d | c () d () b () a | c () d () b () a + } + \context Lyrics \lyrics { + foo1 __ | bar2. __ _4 | baz1 __ + } + > +} + +@end mudela +@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 + +@mudela[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 mudela +@end quotation + + + +@node Notation Contexts, , , Reference Manual +@section Notation Contexts + +@cindex notation contexts + +Notation contexts are objects that only exist during a run of +LilyPond. During the interpretation phase of LilyPond, the Music +expression contained in a @code{\score} block is interpreted in time +order. This is the order in which humans read, play, and write +music. + +A context is an object that holds the reading state of the +expression; it contains information like + +@itemize @bullet + @item What notes are playing at this point? + @item What symbols will be printed at this point? + @item In what style will they printed? + @item What is the current key signature, time signature, point within + the measure, etc.? +@end itemize + +Contexts are grouped hierarchically: A @code{Voice} context is +contained in a @code{Staff} context (because a staff can contain +multiple voices at any point), a @code{Staff} context is contained in +a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because +these can all contain multiple staffs). + +Contexts associated with sheet music output are called @emph{notation +contexts}, those for sound output are called playing contexts. + +Contexts are created either manually or automatically. Initially, +the top level music expression is interpreted by the top level +context (the @code{Score} context). When a atomic music expression +(i.e. a note, a rest, @code{\bar}, or @code{\time} commands), a nested +set of contexts is created that can process these atomic expressions, +as in this example: + +@example + + @example +\score @{ \notes < c4 > @} +@end example + +@end example + +The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score} +context. When the note `@code{c4}' itself is interpreted, a set of +contexts is needed that will accept notes. The default for this is a +@code{Voice} context, contained in a @code{Staff} context. Creation of +these contexts results in the staff being printed. + + +@cindex context + +You can also create contexts manually, and you probably have to do so +if you want to typeset complicated multiple part material. If a +`@code{\context} @var{name} @var{musicexpr}' expression is encountered +during the interpretation phase, the @var{musicexpr} argument will be +interpreted with a context of type @var{name}. If you specify a name, +the specific context with that name is searched. + +If a context of the specified type and name can not be found, a new +one is created. For example, + +@quotation + +@mudela[verbatim] +\score { + \notes \relative c'' { + c4 f + } +} + +@end mudela +@end quotation + +In this example, the @code{c} and @code{d} are printed on the +default staff. For the @code{e}, a context Staff called +`@code{another}' is specified; since that does not exist, a new +context is created. Within @code{another}, a (default) Voice context +is created for the @code{e4}. When all music referring to a +context is finished, the context is ended as well. So after the +third quarter, @code{another} is removed. + +Almost all music expressions inherit their interpretation context +from their parent. In other words, suppose that the syntax for a +music expression is + +@example + + \keyword @var{musicexpr1} @var{musicexpr2} @dots{} +@end example + +When the interpretation of this music expression starts, the context +for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total +expression. + +Lastly, you may wonder, why this: + +@quotation + +@example +\score @{ + \notes \relative c'' @{ + c4 d4 e4 + @} +@} +@end example + +@end quotation + +doesn't result in this: + +@mudela[] + + \score { + \notes \relative c'' { + + } + } + +@end mudela + +For the @code{c4}, a default @code{Staff} (with a contained +@code{Voice}) context is created. After the @code{c4} ends, no +music refers to this default staff, so it would be ended, with the +result shown. To prevent this inconvenient behavior, the context to +which the sequential music refers is adjusted during the +interpretation. So after the @code{c4} ends, the context of the +sequential music is also the default @code{Voice} context. +The @code{d4} gets interpreted in the same context +as @code{c4}. + + + +These are the contexts supplied with the package. They are defined +in the initialization file @file{ly/engraver.ly}. + +@table @samp + @item @code{Grace}@indexcode{Grace} + The context for handling grace notes. It is instantiated + automatically when you use @code{\grace}. Basically, it is an + `embedded' miniature of the Score context. Since this context + needs special interaction with the rest of LilyPond, you should + not explicitly instantiate it. + + @item @code{LyricVoice}@indexcode{LyricVoice} + Corresponds to a voice with lyrics. Handles the printing of a + single line of lyrics. + + @item @code{Thread}@indexcode{Thread} + Handles note heads, and is contained in the Voice context. You + have to instantiate this explicitly if you want to adjust the + style of individual note heads. + + @item @code{Voice}@indexcode{Voice} + Corresponds to a voice on a staff. This context handles the + conversion of dynamic signs, stems, beams, super- and subscripts, + slurs, ties, and rests. + + You have to instantiate this explicitly if you want to have + multiple voices on the same staff. + + @item @code{ChordNamesVoice}@indexcode{ChordNamesVoice} + A voice with chord names. Handles printing of a line of chord + names. + + @item @code{ChordNames}@indexcode{ChordNames} + Typesets chord names. Can contain @code{ChordNamesVoice} + contexts. + + @item @code{Lyrics}@indexcode{Lyrics} + Typesets lyrics. It can contain @code{LyricVoice} contexts. + + @item @code{Staff}@indexcode{Staff} + Handles clefs, bar lines, keys, accidentals. It can contain + @code{Voice} contexts. + + @item @code{RhythmicStaff}@indexcode{RhythmicStaff} + A context like @code{Staff} but for printing rhythms. Pitches are + ignored; the notes are printed on one line. It can contain + @code{Voice} contexts. + + @item @code{GrandStaff}@indexcode{GrandStaff} + Contains @code{Staff} or @code{RhythmicStaff} contexts. It adds a + brace on the left side, grouping the staffs together. The bar + lines of the contained staffs are connected vertically. It can + contain @code{Staff} contexts. + + @item @code{PianoStaff}@indexcode{PianoStaff} + Just like @code{GrandStaff} but with @code{minVerticalAlign} set + equal to @code{maxVerticalAlign} so that interstaff beaming and + slurring can be used. + + @item @code{StaffGroup}@indexcode{StaffGroup} + Contains @code{Staff} or @code{RhythmicStaff} contexts. Adds a + bracket on the left side, grouping the staffs together. The bar + lines of the contained staffs are connected vertically. It can + contain @code{Staff}, @code{RhythmicStaff}, @code{GrandStaff}, or + @code{Lyrics} contexts. + + @item @code{ChoirStaff}@indexcode{ChoirStaff} + Identical to @code{StaffGroup} except that the contained staffs + are not connected vertically. + + @item @code{Score}@indexcode{Score} + This is the top level notation context. No other context can + contain a @code{Score} context. This context handles the + administration of time signatures. It also makes sure that items + such as clefs, time signatures, and key-signatures are aligned + across staffs. It can contain @code{Lyrics}, @code{Staff}, + @code{RhythmicStaff}, @code{GrandStaff}, @code{StaffGroup}, and + @code{ChoirStaff} contexts. + + You cannot explicitly instantiate a Score context (since it is + not contained in any other context). It is instantiated + automatically when an output definition (a @code{\score} or + @code{\paper} block) is processed. +@end table + + + +Properties that are set in one context are inherited by all of the +contained contexts. This means that a property valid for the +@code{Voice} context can be set in the @code{Score} context (for +example) and thus take effect in all @code{Voice} contexts. + +Properties can be preset within the @code{\translator} block +corresponding to the appropriate context. In this case, the syntax +is + +@example + + @var{propname} @code{=} @var{value} +@end example + +This assignment happens before interpretation starts, so a +@code{\property} expression will override any predefined settings. + +The @code{\property} expression will create any property you specify. +There is no guarantee that a property will be used. So if you spell +a property name wrong, there will be no error message. + +The property settings are used during the interpretation phase. They +are read by the LilyPond modules where interpretation contexts are +built of. These modules are called @emph{translators}. Translators for +notation are called @emph{engravers}, and translators for sound are +called @emph{performers}. + +The precise result of a property is determined by the implementation +of the translator that reads them. Therefore, the result of a +property can vary, since it is implementation and configuration +dependent. + +In order to fully find out what properties are used, you must +currently search the source code for calls to @code{get_property}. +The rest of the section is devoted to an (incomplete) overview of +available properties. + +@mbinclude properties.itely + +@node Notation output definitions, , , Reference Manual +@section Notation output definitions + +@cindex output + +@cindex notation output + +@cindex output definition + +@node paper, , , Reference Manual + +The most important output definition is the @code{\paper} block, for +music notation. The syntax is + +@example + + @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}} +@end example + +where each of the items is one of + +@itemize @bullet + @item An assignment. The assignment must be terminated by a + semicolon. See section XREF-papervars [FIXME] for information on + paper variables. + + @item A context definition. See section XREF-contextdefs [FIXME] for + more information on context definitions. + + @item A margin shape declaration. The syntax is + + @example + + \shape @var{indent1}@code{,} @var{width1}@code{,} + @var{indent2}@code{,} @var{width2} @dots{} @code{;} + @end example + + @keyindex{shape} + + 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. + + @item A font declaration. Its syntax is + + @example + + @var{fontsize} @code{=} \font@keyindex{font} @var{fontname} + @end example + + @var{fontsize} is an integer describing the font to be used. + 0 is the default font. @var{fontname} is the basename of + a font (usually a member of the Feta family). +@end itemize + + + +@cindex changing font size and paper size + +The Feta font provides musical symbols at six different sizes. These +fonts are 11 point, 13 point, 16 point, 20 point, +23 point, and 26 point. The point size of a font is the +height of the five lines in a staff when displayed in the font. + +Definitions for these sizes are the files @file{paperSZ.ly}, where +@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include +any of these files, the identifiers @code{paper_eleven}, +@code{paper_thirteen}, @code{paper_sixteen}, @code{paper_twenty}, +@code{paper_twentythree}, and @code{paper_twentysix} are defined +respectively. The default @code{\paper} block is also set. + +To change the paper size, you must first set the +@code{papersize}@indexcode{papersize} variable at top level. Set it to the strings +@code{a4}, @code{letter}, or @code{legal}. After this specification, +you must set the font as described above. If you want the default +font, then use the 20 point font. The new paper size will not +take effect if the font is not loaded and selected afterwards. Paper +size selection works by loading a file named after the paper size you +select. + + + +@cindex paper variables + +@node Paper variables, , , Reference Manual + +There is a large number of paper variables that are used to control +details of the layout. These variables control the defaults for the +entire score. Usually, they do not have to be changed; they are by +default set to values that depend on the font size in use. The +values are used by the graphic objects while formatting the score; +they are therefore implementation dependent. Most variables are +accompanied by documentation in the initalization file +@file{params.ly} or @file{paperSZ.ly}, where @code{SZ} is the staff +height in points. + +Nevertheless, here are some variables you may want to use or change: + +@table @samp + @item @code{indent}@indexcode{indent} + The indentation of the first line of music. + + @item @code{interline}@indexcode{interline} + The distance between two staff lines, calculated from the center + of the lines. You should use either this or @code{rulethickness} + as a unit for distances you modify. + + @item @code{linewidth}@indexcode{linewidth} + Sets the width of the lines. If set to -1.0, a single + unjustified line is produced. + + @item @code{output}@indexcode{output} + Specifies an alternate name for the the output @file{s}. + A @file{.tex}, @file{.midi} or @file{.ps} extension will be + added to the string you specify. + + @item @code{rulethickness}@indexcode{rulethickness} + Determines the thickness of staff and bar lines. +@end table + + +@node contextdefs, , , Reference Manual + +@cindex context definition + +A notation contexts is defined by the following information + +@enumerate i + @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 @samp + @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver} + The standard cooperation engraver. + + @item @code{Score_engraver}@indexcode{Score_engraver} + This is cooperation module that should be in the top level context. + + @item @code{Grace_engraver_group}@indexcode{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. + Section XREF-engravers [FIXME] contains an overview of the engravers + available. 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 the context to create by + default. + + @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 + +@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 @samp + @item @code{StaffContext}@indexcode{StaffContext} + Default Staff context. + + @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext} + Default RhythmicStaff context. + + @item @code{VoiceContext}@indexcode{VoiceContext} + Default Voice context. + + @item @code{ScoreContext}@indexcode{ScoreContext} + Default Score context. + + @item @code{ScoreWithNumbers}@indexcode{ScoreWithNumbers} + Score context with numbering at the Score level. + + @item @code{BarNumberingStaffContext}@indexcode{BarNumberingStaffContext} + Staff context with numbering at the Staff level. + + @item @code{HaraKiriStaffContext}@indexcode{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 Samourai.} + + @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext} + + @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext} +@end table + +Using these pre-defined values, you can remove or add items to the +translator: + +@quotation + +@example +\paper @{ + \translator @{ + \StaffContext + \remove Some_engraver; + \consists Different_engraver; + @} +@} +@end example + +@end quotation + + + +@node engravers, , , Reference Manual + +The engravers for paper output are: + +[incomplete, FIXME] + +@table @samp + @item @code{Bar_engraver}@indexcode{Bar_engraver} + Engraves bar lines. Normally in @code{Staff} and + @code{RhythmicStaff}. + + @item @code{Bar_number_engraver}@indexcode{Bar_number_engraver} + Engrave bar numbers. These numbers appear at the start of each + line. Not normally in any translator. Can be added to + @code{Score} for score-wide numbering or to @code{Staff} for + numbering on each staff. + + @item @code{Beam_engraver}@indexcode{Beam_engraver} + Handles beam requests by engraving beams. Normally appears in + the @code{Voice} translator. If omitted, then notes will be + printed with flags instead of beams. + + @item @code{Beam_req_swallow_translator} + @indexcode{Beam_req_swallow_translator} + Swallows beam requests. In @code{LyricVoice}. + + @item @code{Chord_name_engraver}@indexcode{Chord_name_engraver} + Engraves chord names. Normally in @code{ChordNameVoice} . + + @item @code{Chord_tremolo_engraver}@indexcode{Chord_tremolo_engraver} + + @item @code{Clef_engraver}@indexcode{Clef_engraver} + Engraves the clef symbol. Normally in @code{Staff}. + + @item @code{Collision_engraver}@indexcode{Collision_engraver} + + @item @code{Dot_column_engraver}@indexcode{Dot_column_engraver} + Engraves dots on dotted notes shifted to the right of the note. + Normally in @code{Voice}. If omitted, then dots appear on top of + the notes. + + @item @code{Dynamic_engraver}@indexcode{Dynamic_engraver} + Engraves dynamics symbols. Normally in @code{Voice}. + + @item @code{Font_size_engraver}@indexcode{Font_size_engraver} + + @item @code{Key_engraver}@indexcode{Key_engraver} + Engraves the key signature. Normally in @code{Staff}. + + @item @code{Local_key_engraver}@indexcode{Local_key_engraver} + + @item @code{Lyric_engraver}@indexcode{Lyric_engraver} + Engraves lyrics. Normally in @code{LyricVoice}. + + @item @code{Multi_measure_rest_engraver} + @indexcode{Multi_measure_rest_engraver} + Engraves multi-measure rests that are produced with @code{R}. + Normally in @code{Voice}. + + @item @code{Piano_bar_engraver}@indexcode{Piano_bar_engraver} + + @item @code{Pitch_squash_engraver}@indexcode{Pitch_squash_engraver} + Treat all pitches as middle C. Used in @code{RhythmicStaff}. + Note that the notes move, but the locations of accidentals stay + the same. + + @item @code{Priority_horizontal_align_engraver} + @indexcode{Priority_horizontal_align_engraver} + + @item @code{Repeat_engraver}@indexcode{Repeat_engraver} + Handles repeats? In @code{Staff} and @code{RhythmicStaff}. + + @item @code{Rest_collision_engraver}@indexcode{Rest_collision_engraver} + Handles collisions of rests. In @code{Staff}. + + @item @code{Rest_engraver}@indexcode{Rest_engraver} + Engraves rests. Normally in @code{Voice}. + + @item @code{Rhythmic_column_engraver}@indexcode{Rhythmic_column_engraver} + + @item @code{Score_priority_engraver}@indexcode{Score_priority_engraver} + + @item @code{Script_engraver}@indexcode{Script_engraver} + Handles note ornaments generated by @code{\script}. Normally in + @code{Voice}. + + @item @code{Separating_line_group_engraver} + @indexcode{Separating_line_group_engraver} + + @item @code{Skip_req_swallow_translator} + @indexcode{Skip_req_swallow_translator} + + @item @code{Slur_engraver}@indexcode{Slur_engraver} + Engraves slurs. Normally in @code{Voice}. + + @item @code{Span_bar_engraver}@indexcode{Span_bar_engraver} + Engraves lines across multiple staffs. Normally in + @code{Staffgroup} and @code{GrandStaff}. Removing this from + @code{StaffGroup} gives the definition of @code{ChoirStaff}. + + @item @code{Span_score_bar_engraver}@indexcode{Span_score_bar_engraver} + + @item @code{Staff_group_bar_engraver}@indexcode{Staff_group_bar_engraver} + + @item @code{Staff_margin_engraver}@indexcode{Staff_margin_engraver} + Prints the name of the instrument (specified by + @code{Staff.instrument} and @code{Staff.instr}) at the left of the + staff. + + @item @code{Staff_sym_engraver}@indexcode{Staff_sym_engraver} + + @item @code{Stem_engraver}@indexcode{Stem_engraver} + Engraves stems. Normally in @code{Voice}. + + @item @code{Ties_engraver}@indexcode{Ties_engraver} + Engraves ties. Normally in @code{Voice}. + + @item @code{Time_signature_engraver}@indexcode{Time_signature_engraver} + Engraves the time signature. Normally in @code{Staff} and + @code{RhythmicStaff}. + + @item @code{Timing_engraver}@indexcode{Timing_engraver} + Responsible for synchronizing timing information from staffs. + Normally in @code{Score}. In order to create polyrhythmic music, + this engraver should be removed from @code{Score} and placed in + @code{Staff}. + + @item @code{Tuplet_engraver}@indexcode{Tuplet_engraver} + Engraves tuplet brackets? In @code{Staff}. + + @item @code{Vertical_align_engraver}@indexcode{Vertical_align_engraver} +@end table + + + +@node Sound output, , , Reference Manual +@section Sound output + + + +The MIDI block is analogous to the paper block, but it is simpler. +The @code{\midi} block can contain: +@cindex MIDI block + +@itemize @bullet + @item a @code{\tempo} definition + @item context definitions +@end itemize + +Assignments in the @code{\midi} block are not allowed. + + + +@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}. + + + +@cindex MIDI instrument names + +@node midilist, , , Reference Manual + +The MIDI instrument name is set by the +@code{Staff.midiInstrument}@indexcode{Staff.midiInstrument} property or, +if that property is not set, the +@code{Staff.instrument}@indexcode{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. + + +@quotation + +@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 + +@end quotation + + +@cindex MIDI types and performers + +The types available for MIDI translators are: + +@table @samp + @item @code{Performer_group_performer}@indexcode{Performer_group_performer} + @item @code{Score_performer}@indexcode{Score_performer} + @item @code{Staff_performer}@indexcode{Staff_performer} +@end table + +The performers for MIDI translators are: + +@table @samp + @item @code{Key_performer}@indexcode{Key_performer} + @item @code{Time_signature_performer}@indexcode{Time_signature_performer} + @item @code{Note_performer}@indexcode{Note_performer} + @item @code{Lyric_performer}@indexcode{Lyric_performer} + @item @code{Swallow_performer}@indexcode{Swallow_performer} +@end table + + + +@node Pre-defined Identifiers, , , Reference Manual + +@section 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}. + +@table @samp + @item @code{\break}@keyindex{break} + Force a line break in music by using a large argument for the + keyword @code{\penalty}. + + @item @code{\center}@keyindex{center} + Used for setting direction properties. Equals 0. + + @item @code{\down}@keyindex{down} + Used for setting direction setting properties. Is equal + to -1. + + @item @code{\free}@keyindex{free} + Used for setting direction setting properties. Is equal + to 0. + + @item @code{\left}@keyindex{left} + Used for setting text alignment property. Is equal to -1. + + @item @code{\nobreak}@keyindex{nobreak} + Prevent a line break in music by using a large negative argument + for the keyword @code{\penalty}. + + @item @code{\none}@keyindex{none} + Used for setting @code{Score.beamslopedamping} and + @code{Score.beamquantisation} properties. Is equal to 0. + + @item @code{\normal}@keyindex{normal} + Used for setting @code{Score.beamslopedamping} and + @code{Score.beamquantisation} properties. Is equal to 1. + + @item @code{\normalkey}@keyindex{normalkey} + Select normal key signatures where each octave has the same key + signature. This sets the @code{Staff.keyoctaviation} property. + + @item @code{\right}@keyindex{right} + Used for setting text alignment property. Is set to 1. + + @item @code{\shiftoff}@keyindex{shiftoff} + Disable horizontal shifting of note heads that collide. Sets the + @code{Voice.horizontalNoteShift} property. + + @item @code{\shifton}@keyindex{shifton} + Enable note heads that collide with other note heads to be + shifted horiztonally. Sets the @code{Voice.horizontalNoteShift} + property. + + @item @code{\slurboth}@keyindex{slurboth} + Allow slurs to be above or below notes. This sets the + @code{Voice.slurVerticalDirection} property. + + @item @code{\slurdown}@keyindex{slurdown} + Force slurs to be below notes. This sets the + @code{Voice.slurVerticalDirection} property. + + @item @code{\slurup}@keyindex{slurup} + Force slurs to be above notes. This sets the + @code{Voice.slurVerticalDirection} property. + + @item @code{\specialkey}@keyindex{specialkey} + Allow key signatures do differ in different octaves. This sets + the @code{Staff.keyoctaviation} property. + + @item @code{\stemboth}@keyindex{stemboth} + Allow stems, beams, and slurs to point either upwards or + downwards, decided automatically by LilyPond. This sets the + @code{Voice.verticalDirection} property. + + @item @code{\stemdown}@keyindex{stemdown} + Force stems, beams, and slurs to point down. This sets the + @code{Voice.verticalDirection} property. + + @item @code{\stemup}@keyindex{stemup} + Force stems, beams and slurs to point up. This sets the + @code{Voice.verticalDirection} property. + + @item @code{\traditional}@keyindex{traditional} + Used for setting the @code{Score.beamquantisation} property. Is + equal to 2. + + @item @code{\up}@keyindex{up} + Used for setting various direction properties. Is equal + to 1. +@end table diff --git a/input/test/auto-knee.ly b/input/test/auto-knee.ly new file mode 100644 index 0000000000..e6541ec2ef --- /dev/null +++ b/input/test/auto-knee.ly @@ -0,0 +1,26 @@ + +\score { + \notes \context PianoStaff < + \context Staff = "up" { + \autochange Staff \relative c' { + [c8 e'] [c' c,,] + \stemdown + c'8 c c g, + g8 d' d d + \stemup + b8 c d e + } + } + \context Staff = "down" { + \clef bass; + s1*2 + } + > + \paper{ + \translator{ + \StaffContext + autoKneeGap = "13.0"; + autoInterstaffKneeGap = "4.0"; + } + } +} diff --git a/lily/auto-beam-engraver.cc b/lily/auto-beam-engraver.cc index e72ffb29ab..28fc85fa65 100644 --- a/lily/auto-beam-engraver.cc +++ b/lily/auto-beam-engraver.cc @@ -203,8 +203,16 @@ Auto_beam_engraver::create_beam_p () /* urg, copied from Beam_engraver */ Scalar prop = get_property ("beamslopedamping", 0); if (prop.isnum_b ()) - beam_p->set_elt_property (damping_scm_sym, gh_int2scm( prop)); + beam_p->set_elt_property (damping_scm_sym, gh_int2scm(prop)); + prop = get_property ("autoKneeGap", 0); + if (prop.isnum_b ()) + beam_p->set_elt_property (auto_knee_gap_scm_sym, gh_int2scm(prop)); + + prop = get_property ("autoInterstaffKneeGap", 0); + if (prop.isnum_b ()) + beam_p->set_elt_property (auto_interstaff_knee_gap_scm_sym, gh_int2scm( prop)); + prop = get_property ("beamquantisation", 0); if (prop.isnum_b ()) beam_p->quantisation_ = (Beam::Quantisation)(int)prop; diff --git a/lily/beam-engraver.cc b/lily/beam-engraver.cc index d0a965e33a..b34d329d94 100644 --- a/lily/beam-engraver.cc +++ b/lily/beam-engraver.cc @@ -98,11 +98,19 @@ Beam_engraver::do_process_requests () beam_info_p_ = new Beaming_info_list; - + /* urg, must copy to Auto_beam_engraver too */ Scalar prop = get_property ("beamslopedamping", 0); if (prop.isnum_b ()) beam_p_->set_elt_property (damping_scm_sym, gh_int2scm( prop)); + prop = get_property ("autoKneeGap", 0); + if (prop.isnum_b ()) + beam_p_->set_elt_property (auto_knee_gap_scm_sym, gh_int2scm( prop)); + + prop = get_property ("autoInterstaffKneeGap", 0); + if (prop.isnum_b ()) + beam_p_->set_elt_property (auto_interstaff_knee_gap_scm_sym, gh_int2scm( prop)); + prop = get_property ("beamquantisation", 0); if (prop.isnum_b ()) beam_p_->quantisation_ = (Beam::Quantisation)(int)prop; diff --git a/lily/beam.cc b/lily/beam.cc index bb688749dd..92a92050a2 100644 --- a/lily/beam.cc +++ b/lily/beam.cc @@ -120,13 +120,73 @@ Beam::center () const si.stem_l_->staff_line_leading_f ()/2); } +/* + Simplistic auto-knees; only consider vertical gap between two + adjacent chords + */ +bool +Beam::auto_knee (SCM gap, bool interstaff_b) +{ + bool knee = false; + int knee_y = 0; + Real internote_f = stems_[0]->staff_line_leading_f ()/2; + if (gap != SCM_BOOL_F) + { + int auto_gap_i = gh_scm2int (SCM_CDR (gap)); + for (int i=1; i < stems_.size (); i++) + { + bool is_b = (bool)(sinfo_[i].interstaff_f_ - sinfo_[i-1].interstaff_f_); + int l_y = (int)(stems_[i-1]->chord_start_f () / internote_f) + + (int)sinfo_[i-1].interstaff_f_; + int r_y = (int)(stems_[i]->chord_start_f () / internote_f) + + (int)sinfo_[i].interstaff_f_; + int gap_i = r_y - l_y; + + /* + Forced stem directions are ignored. If you don't want auto-knees, + don't set, or unset autoKneeGap/autoInterstaffKneeGap. + */ + if ((abs (gap_i) >= auto_gap_i) && (!interstaff_b || is_b)) + { + knee_y = (r_y + l_y) / 2; + knee = true; + break; + } + } + } + if (knee) + { + for (int i=0; i < stems_.size (); i++) + { + int y = (int)(stems_[i]->chord_start_f () / internote_f) + + (int)sinfo_[i].interstaff_f_; + stems_[i]->dir_ = y < knee_y ? UP : DOWN; + stems_[i]->set_elt_property (dir_forced_scm_sym, SCM_BOOL_T); + } + } + return knee; +} + +bool +Beam::auto_knees () +{ + if (auto_knee (get_elt_property (auto_interstaff_knee_gap_scm_sym), true)) + return true; + + return auto_knee (get_elt_property (auto_knee_gap_scm_sym), false); +} + + void Beam::do_pre_processing () { + /* + urg: it seems that info on whether beam (voice) dir was forced + is being junked here? + */ if (!dir_) dir_ = get_default_dir (); - set_direction (dir_); } @@ -146,7 +206,25 @@ Beam::do_post_processing () { warning (_ ("beam with less than two stems")); set_elt_property (transparent_scm_sym, SCM_BOOL_T); - return ; + return; + } + set_steminfo (); + if (auto_knees ()) + { + /* + if auto-knee did its work, most probably stem directions + have changed, so we must recalculate all. + */ + dir_ = get_default_dir (); + set_direction (dir_); + + /* auto-knees used to only work for slope = 0 + anyway, should be able to set slope per beam + set_elt_property (damping_scm_sym, gh_int2scm(1000)); + */ + + sinfo_.clear (); + set_steminfo (); } calculate_slope (); set_stemlens (); @@ -323,6 +401,7 @@ Beam::set_steminfo () return; assert (multiple_i_); + int total_count_i = 0; int forced_count_i = 0; for (int i=0; i < stems_.size (); i++) @@ -374,7 +453,6 @@ Beam::set_steminfo () void Beam::calculate_slope () { - set_steminfo (); if (!sinfo_.size ()) slope_f_ = left_y_ = 0; else if (sinfo_[0].idealy_f_ == sinfo_.top ().idealy_f_) diff --git a/lily/include/beam.hh b/lily/include/beam.hh index 39f9b3b99b..145bbddce0 100644 --- a/lily/include/beam.hh +++ b/lily/include/beam.hh @@ -69,6 +69,8 @@ protected: Direction get_default_dir () const; void set_direction (Direction); void set_steminfo (); + bool auto_knee (SCM gap, bool interstaff_b); + bool auto_knees (); virtual void do_pre_processing (); virtual void do_post_processing (); diff --git a/lily/include/ly-symbols.hh b/lily/include/ly-symbols.hh index 0d929dd23e..521fa3d06e 100644 --- a/lily/include/ly-symbols.hh +++ b/lily/include/ly-symbols.hh @@ -18,6 +18,8 @@ DECLARE_LY_SYMBOL(alt_symbol); DECLARE_LY_SYMBOL(at_line_start); +DECLARE_LY_SYMBOL(auto_interstaff_knee_gap); +DECLARE_LY_SYMBOL(auto_knee_gap); DECLARE_LY_SYMBOL(bar_size); DECLARE_LY_SYMBOL(beam); DECLARE_LY_SYMBOL(beam_thickness);