From a2069422b6c7bbac1c3d88cec0c2f48b95f0dab7 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Tue, 30 May 2006 07:33:30 +0000 Subject: [PATCH] Various small additions and editing, plus Spanish glossary update from Francisco Vila. --- ChangeLog | 10 + Documentation/user/advanced-notation.itely | 56 +++- Documentation/user/instrument-notation.itely | 114 ++++++-- Documentation/user/music-glossary.tely | 93 ++++--- Documentation/user/notation-appendices.itely | 3 + .../user/programming-interface.itely | 263 ------------------ THANKS | 2 + 7 files changed, 204 insertions(+), 337 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6408308491..b34b733241 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2006-05-30 Graham Percival + + * Documentation/user/ various: minor additions from mailist and + editing. + +2006-05-30 Paco + + * Documentation/user/music-glossary.tely: numerous corrections and + some new translations. + 2006-05-29 Han-Wen Nienhuys * BackportmeStart. diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely index e9a2bc2209..8d3186dc1b 100644 --- a/Documentation/user/advanced-notation.itely +++ b/Documentation/user/advanced-notation.itely @@ -836,6 +836,30 @@ You may use @code{format-mark-barnumbers}, @code{format-mark-box-barnumbers}, and @code{format-mark-circle-barnumbers} to get bar numbers instead of incremented numbers or letters. +The horizontal location of rehearsal marks can be adjusted by +setting @code{break-align-symbol} + +@lilypond[fragment,quote,ragged-right,verbatim,relative] +c1 +\key cis \major +\clef alto +\override Score.RehearsalMark #'break-align-symbol = #'key-signature +\mark "on-key" +cis +\key ces \major +\override Score.RehearsalMark #'break-align-symbol = #'clef +\clef treble +\mark "on clef" +ces +@end lilypond + +@code{break-align-symbol} may also accept the following values: +@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos}, +@code{staff-bar}, @code{left-edge}, @code{key-cancellation}, +@code{key-signature}, and @code{time-signature}. Setting +@code{break-align-symbol} will only have an effect if the symbol +appears at that point in the music. + @seealso @@ -862,6 +886,23 @@ Bar numbers are printed by default at the start of the line. The number itself is stored in the @code{currentBarNumber} property, which is normally updated automatically for every measure. +@lilypond[verbatim,ragged-right,quote,fragment,relative] +\repeat unfold 4 {c4 c c c} \break +\set Score.currentBarNumber = #50 +\repeat unfold 4 {c4 c c c} +@end lilypond + +Bar numbers may only be printed at bar lines; to print a bar +number at the beginning of a piece, an empty bar line must +be added + +@lilypond[verbatim,ragged-right,quote,fragment,relative] +\set Score.currentBarNumber = #50 +\bar "" +\repeat unfold 4 {c4 c c c} \break +\repeat unfold 4 {c4 c c c} +@end lilypond + Bar numbers can be typeset at regular intervals instead of at the beginning of each line. This is illustrated in the following example, whose source is available as @@ -869,17 +910,6 @@ whose source is available as @lilypondfile[ragged-right,quote]{bar-number-regular-interval.ly} -Bar numbers can be manually changed by setting the -@code{Staff.currentBarNumber} property - -@lilypond[verbatim,ragged-right,quote] -\relative c' { - \repeat unfold 4 {c4 c c c} \break - \set Score.currentBarNumber = #50 - \repeat unfold 4 {c4 c c c} -} -@end lilypond - Bar numbers can be removed entirely by removing the Bar number engraver from the score. @@ -1344,6 +1374,8 @@ staff. See @inputfileref{input/@/test,ossia@/.ly} for an example. @node Quoting other voices @subsection Quoting other voices +@cindex cues + With quotations, fragments of other parts can be inserted into a part directly. Before a part can be quoted, it must be marked especially as quotable. This is done with the @code{\addquote} command. @@ -1440,6 +1472,8 @@ Program reference: @internalsref{QuoteMusic}. @node Formatting cue notes @subsection Formatting cue notes +@cindex cues, formatting + The previous section deals with inserting notes from another voice. There is a more advanced music function called @code{\cueDuring}, which makes formatting cue notes easier. diff --git a/Documentation/user/instrument-notation.itely b/Documentation/user/instrument-notation.itely index 2e1819daf6..30f112dcc4 100644 --- a/Documentation/user/instrument-notation.itely +++ b/Documentation/user/instrument-notation.itely @@ -829,6 +829,23 @@ 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{^}. +To define indentifiers containing lyrics, the function @code{lyricmode} +must be used. + +@example +verseOne = \lyricmode @{ Joy to the world the Lord is come @} +\score @{ + << + \new Voice = "one" \relative c'' @{ + \autoBeamOff + \time 2/4 + c4 b8. a16 g4. f8 e4 d c2 + @} + \addlyrics @{ \verseOne @} + >> +@} +@end example + @seealso @@ -889,8 +906,8 @@ melody and the lyrics with the @code{\lyricsto} expression @end example This aligns the lyrics to the -notes of the @internalsref{Voice} context called @var{name}, which has -to exist. Therefore, normally the @code{Voice} is specified first, and +notes of the @internalsref{Voice} context called @var{name}, which must +already exist. Therefore normally the @code{Voice} is specified first, and then the lyrics are specified with @code{\lyricsto}. The command @code{\lyricsto} switches to @code{\lyricmode} mode automatically, so the @code{\lyricmode} keyword may be omitted. @@ -905,7 +922,7 @@ The following example uses different commands for entering lyrics. c4 b8. a16 g4. f8 e4 d c2 } \new Lyrics \lyricmode { Joy4 to8. the16 world!4. the8 Lord4 is come.2 } - \new Lyrics \lyricmode { Joy to the earth! the Sav -- our reigns. } + \new Lyrics \lyricmode { Joy to the earth! the Sa -- viour reigns. } \new Lyrics \lyricsto "one" { No more let sins and sor -- rows grow. } >> @end lilypond @@ -913,28 +930,6 @@ The following example uses different commands for entering lyrics. The second stanza is not properly aligned because the durations were not specified. A solution for that would be to use @code{\lyricsto}. - - - - - -To define indentifiers containing lyrics, the function @code{lyricmode} -must be used. - -@example -verseOne = \lyricmode @{ Joy to the world the Lord is come @} -\score @{ - << - \new Voice = "one" \relative c'' @{ - \autoBeamOff - \time 2/4 - c4 b8. a16 g4. f8 e4 d c2 - @} - \addlyrics @{ \verseOne @} - >> -@} -@end example - The @code{\addlyrics} command is actually just a convenient way to write a more complicated LilyPond structure that sets up the lyrics. @@ -1093,6 +1088,7 @@ differing ways. Such variations can still be captured with * Divisi lyrics:: * Switching the melody associated with a lyrics line:: * Specifying melismata within the lyrics:: +* Lyrics independent of notes:: @end menu @node Lyrics to multiple notes of a melisma @@ -1293,7 +1289,7 @@ melisma. In this case, you can also have ties and slurs in the melody, if you set @code{melismaBusyProperties}, as is done in the example above. -@lilypond[relative=1,verbatim,fragment] +@lilypond[relative=1,verbatim,fragment,quote] { \set melismaBusyProperties = #'() c d( e) f f( e) e e @@ -1303,6 +1299,35 @@ set @code{melismaBusyProperties}, as is done in the example above. @end lilypond +@node Lyrics independent of notes +@subsubsection Lyrics independent of notes + +In some complex vocal music, it may be desirable to place +lyrics completely independently of notes. Music defined +inside @code{lyricrhythm} disappears into the +@code{Devnull} context, but the rhythms can still be used +to place the lyrics. + +@lilypond[quote,verbatim,ragged-right] +voice = { + c''2 + \tag #'music { c''2 } + \tag #'lyricrhythm { c''4. c''8 } + d''1 +} + +lyr = \lyricmode { I like my cat! } + +<< + \new Staff \keepWithTag #'music \voice + \new Devnull="nowhere" \keepWithTag #'lyricrhythm \voice + \new Lyrics \lyricsto "nowhere" \lyr + \new Staff { c'8 c' c' c' c' c' c' c' + c' c' c' c' c' c' c' c' } +>> +@end lilypond + + @node Spacing lyrics @subsection Spacing lyrics @@ -1564,6 +1589,7 @@ also be used to show the rhythms of melodies. * Showing melody rhythms:: * Entering percussion:: * Percussion staves:: +* Ghost notes:: @end menu @@ -1830,6 +1856,42 @@ Because general MIDI does not contain rim shots, the sidestick is used for this purpose instead. +@c FIXME: check name -gp +@node Ghost notes +@subsection Ghost notes + +Ghost notes for drums and percussion may be created using the +@code{\parenthesize} command detailed in @ref{Parentheses}. However, +the default @code{\drummode} does +not include the @code{Parenthesis_engraver} plugin which allows +this. You +must add the plugin explicitly in the context definition as +detailed in @ref{Changing context properties on the fly}. + +@lilypond[quote,ragged-right,verbatim,fragment] +\new DrumStaff \with { + \consists "Parenthesis_engraver" +} << + \context DrumVoice = "1" { s1 *2 } + \context DrumVoice = "2" { s1 *2 } + \drummode { + << + { + hh8[ hh] hh16 + < \parenthesize sn > hh < \parenthesize + sn > hh8 hh + } \\ { + bd4 r4 bd8 bd r8 bd + } + >> + } +>> +@end lilypond + +@noindent +Also note that you must add chords (@code{< >} brackets) +around each @code{\parenthesize} statement. + @node Guitar @section Guitar diff --git a/Documentation/user/music-glossary.tely b/Documentation/user/music-glossary.tely index c039976145..5a809089dd 100644 --- a/Documentation/user/music-glossary.tely +++ b/Documentation/user/music-glossary.tely @@ -466,7 +466,7 @@ accidental. @node accelerando @section accelerando -ES: acelerando, +ES: accelerando, I: accelerando, F: accelerando, en accélérant, D: accelerando, schneller werden, @@ -560,7 +560,7 @@ C clef setting middle C on the middle line of the staff @node ambit @section ambit -ES: ambitus, +ES: ámbito, I: ambitus, F: ambitus, D: ambitus, @@ -576,6 +576,7 @@ the pitch range that a musical instrument is capable of playing. @node ancient minor scale @section ancient minor scale +ES: escala menor antigua I: scala minore naturale, F: forme du mode mineur ancien, troisème mode, mode hellénique D: reines Moll, @@ -700,7 +701,7 @@ FI: arpeggio, murtosointu. @node ascending interval @section ascending interval -ES: Intervalo ascendente, +ES: intervalo ascendente, I: intervallo ascendente, F: intervalle ascendant, D: steigendes Intervall, @@ -728,6 +729,7 @@ FI: ylinouseva intervalli. @node autograph @section autograph +ES: manuscrito, I: autografo, F: manuscrit, D: Autograph, Handschrift, @@ -767,7 +769,7 @@ ES: compás, @aref{measure}. @node bar line @section bar line -ES: ?, +ES: barra, línea divisoria, I: stanghetta, barra (di divisione), F: barre (de mesure), D: Taktstrich, @@ -826,6 +828,7 @@ A clef setting with middle C on the first top ledger line. @node bass @section bass +ES: bajo, I: basso, F: basse, D: Bass, @@ -842,6 +845,7 @@ an abbreviation for double bass. @node beam @section beam +ES: barra I: coda, F: barre, D: Balken, @@ -866,7 +870,7 @@ The number of beams determines the note value of the connected notes. @node beat @section beat -ES: tiempo, +ES: tiempo, parte (de compás) I: tempi, F: temps, D: Takt, Taktschlag, Zeit (im Takt), @@ -940,6 +944,7 @@ trumpet, trombone, french horn, and tube. @node breath mark @section breath mark +ES: respiración, I: respiro, F: respiration, D: Atemzeichen, Trennungszeichen, @@ -952,7 +957,7 @@ Indication of where to breathe in vocal and wind instrument parts. @node breve @section breve -ES: breve, +ES: cuadrada, breve, I: breve, F: brève, D: Brevis, @@ -984,7 +989,7 @@ FI: C, c. @node C clef @section C clef -ES: Clave de do, +ES: clave de do, I: chiave di do, F: clé d'ut, D: C-Schlüssel, @@ -1221,6 +1226,7 @@ pitch contained in the cluster would be notated as an ordinary note. @node comma @section comma +ES: coma, comma I: comma, F: comma, D: Komma, @@ -1256,6 +1262,7 @@ Intervals larger than an octave. @node complement @section complement +ES: intervalo invertido I: rivolto, F: intervalle complémentaire, D: Komplementärintervall, @@ -1417,7 +1424,7 @@ abbreviation ``cresc.''. @node cue-notes @section cue-notes -ES: notas guia, +ES: notas guía, I: notine, F: petites notes précédent l'entrée d'in instrument, réplique, D: Stichnoten, @@ -1467,7 +1474,7 @@ of the 20th century @node D @section D -ES: Re, +ES: re, I: re, F: ré, D: D, d, @@ -1783,7 +1790,7 @@ Opposite of @aref{conjunct movement}. @node dissonant interval @section dissonant interval -ES: intervalo disonante, disonancias, +ES: intervalo disonante, disonancia, I: intervallo dissonante, dissonanza, F: dissonance, D: Dissonanz, @@ -1797,6 +1804,7 @@ FI: dissonanssi, dissonoiva intervalli, riitasointi. @node dominant ninth chord @section dominant ninth chord +ES: acorde de novena de dominante, I: accordo di nona di dominante, F: accord de neuvième dominante, D: Domi@-nant@-nonen@-akkord, @@ -1895,6 +1903,7 @@ FI: kaksoisappogiatura, kaksoisetuhele. @node double bar line @section double bar line +ES: doble barra, I: doppia barra, F: double barre, D: Doppelstrich, @@ -1908,7 +1917,7 @@ Indicates the end of a section within a movement. @node double dotted note @section double dotted note -ES: nota con dos puntillos, +ES: nota con doble puntillo, I: nota doppiamente puntata, F: note doublement pointée, D: doppelt punktierte Note, @@ -2064,7 +2073,7 @@ FI: kahdeksasosatauko. @node engraving @section engraving -ES: Grabar +ES: grabar, I: incisione, F: gravure, D: Notenstechen, Notendruck @@ -2111,7 +2120,7 @@ but equal pitch. @node equal temperament @section equal temperament -ES: ?, +ES: temperamento igual, I: temperamento equabile, F: tempérament égal, D: gleichschwebende Stimmung, @@ -2126,7 +2135,7 @@ Tuning system dividing the octave into 12 equal @aref{semitone}s @node expression mark @section expression mark -ES: ?, +ES: expresión, I: segno d'espressione, F: signe d'expression, indication de nuance, D: Vortragszeichen, @@ -2154,7 +2163,7 @@ FI: F, f. @node F clef @section F clef -ES: Clave de Fa, +ES: clave de fa, I: chiave di fa, F: clé de fa, D: F-Schlüssel, @@ -2385,7 +2394,7 @@ FI: G, g. @node G clef @section G clef -ES: Clave de sol, +ES: clave de sol, I: chiave di sol, F: clé de sol, D: G-Schlüssel, Violinschlüssel, @@ -2443,7 +2452,7 @@ Letting the pitch slide fluently from one note to the other. @node grace notes @section grace notes -ES: ?, +ES: mordente, I: abbellimenti, F: fioriture, D: Verzierungen, Vorschläge, Vor@-schlags@-noten, @@ -2458,6 +2467,7 @@ counted in the rhythm of the bar. @aref{appoggiatura}. @node grand staff @section grand staff +ES: sistema de piano, I: accolatura, F: accolade, D: Akkolade, @@ -2507,7 +2517,7 @@ FI: puolinuotti. @node half rest @section half rest -ES: ?, +ES: silencio de blanca, I: pausa di minima, F: demi-pause, UK: minim rest, @@ -2723,6 +2733,7 @@ The difference between an interval and an octave. @node just intonation @section just intonation +ES: entonación justa, I: intonazione giusta, F: intonation juste, D: reine Stimmung, @@ -2753,7 +2764,7 @@ there are 12@w{ }keys, one on@w{ }c, one on c-sharp, etc. @node key signature @section key signature -ES: armadura de clave, +ES: armadura (de la clave), I: armatura di chiave, F: armure, armature [de la clé], D: Vorzeichen, Tonart, @@ -2818,7 +2829,7 @@ A ledger line is an extension of the staff. @node legato @section legato -ES: ligado, +ES: legato, I: legato, F: legato, lié, D: legato, @@ -2862,7 +2873,7 @@ unlike (b) @emph{leggiero} or @emph{non-legato}, (c) @emph{portato}, and @node lilypond @section lilypond -ES: estanque de lilas, +ES: estanque de nenúfares, I: stagno del giglio, F: étang de lis, UK: lily pond, @@ -2877,6 +2888,8 @@ A pond with lilies floating in it, also the name of a music typesetter. @node ligature @section ligature +ES: ligadura + A ligature is a coherent graphical symbol that represents at least two distinct notes. Ligatures originally appeared in the manuscripts of Gregorian chant notation roughly since the 9th century to denote @@ -2940,7 +2953,7 @@ Note value: double length of @aref{breve}. @node lyrics @section lyrics -ES: ., +ES: letra (de la canción), I: ., F: ., D: Liedtext, @@ -2980,6 +2993,7 @@ FI: duuri. @node meantone temperament @section meantone temperament +ES: afinación mesotónica, I: accordatura mesotonica, F: tempérament mésotonique, D: mitteltönige Stimmung, @@ -3031,6 +3045,7 @@ harmony}, @aref{relative key}. @node melisma @section melisma +ES: melisma, NL: melisma, FI: melisma, laulettavan tavun sävelkuvio. @@ -3359,7 +3374,7 @@ and hears a tone. @node note head @section note head -ES: oval, +ES: cabeza, I: testa, testina, capocchia, F: t@^ete de la note, D: Notenkopf, @@ -3378,7 +3393,7 @@ instrument. @node note value @section note value -ES: valor, +ES: valor (duración), I: valore, durata, F: durée, valeur (d'une note), D: Notenwert, @@ -3764,7 +3779,7 @@ FI: neljännesosatauko. @node quintuplet @section quintuplet -ES: quintillo, +ES: cinquillo, I: quintina, F: quintolet, D: Quintole, @@ -3884,7 +3899,7 @@ no common metrical unit (beat). @node ritardando @section ritardando -ES: retardando, +ES: ritardando, I: ritardando, F: ritardando, D: Ritardando, langsamer werden, @@ -4032,6 +4047,7 @@ FI: septimi. @node sextuplet @section sextuplet +ES: seisillo, I: sestina, F: sextolet, D: Sextole, @@ -4084,7 +4100,7 @@ FI: kuudestoistaosanuotti. @node sixteenth rest @section sixteenth rest -ES: silencia de semicorchea, +ES: silencio de semicorchea, I: pausa di semicroma, F: quart de soupir, UK: semiquaver rest, @@ -4128,7 +4144,7 @@ FI: kuudeskymmenesneljäsosanuotti. @node sixty-fourth rest @section sixty-fourth rest -ES: silencia de semifusa, +ES: silencio de semifusa, I: pausa di semibiscroma, F: seizième de soupir, UK: hemidemisemiquaver rest, @@ -4143,7 +4159,7 @@ FI: kuudeskymmenesneljäsosatauko. @node slur @section slur -ES: ligadura, +ES: ligadura (de expresión), I: legatura (di portamento or espressiva), F: liaison, coulé, D: Bogen, Legatobogen, Phrasierungsbogen, @@ -4159,6 +4175,7 @@ breath in singing. @node solmization @section solmization +ES: solmisación, I: solmisazione, F: solmisation, D: Solmisation, @@ -4235,7 +4252,7 @@ The highest female voice. @node staccato @section staccato -ES: staccato, +ES: picado (staccato), I: staccato, F: staccato, piqué, détaché, D: Staccato, @@ -4353,7 +4370,7 @@ The fourth @aref{scale degree}. @aref{functional harmony}. @node submediant @section submediant -ES: superdominante, +ES: submediante, I: sopratonica, F: sous-médiante, D: Submediante, @@ -4423,7 +4440,7 @@ A symphony may be defined as a @aref{sonata} for orchestra. @node syncopation @section syncopation -ES: sincopado, +ES: síncopa, I: sincope, F: syncope, D: Synkope, @@ -4451,6 +4468,7 @@ the underlaying (normal) pulse and the actual (abnormal) rhythm. @node syntonic comma @section syntonic comma +ES: coma sintónica, I: comma sintonico (o didimico), F: comma syntonique, D: syntonisches Komma, @@ -4466,6 +4484,7 @@ tuning (@aref{Pythagorean comma}), equal to 22@w{ }cents. @node system @section system +ES: sistema, I: accollatura, F: système, D: Notensystem, @@ -4680,7 +4699,7 @@ FI: tahtiosoitus. @node tone @section tone -ES: sonido, +ES: tono, I: suono, F: ton, D: Ton, @@ -4696,7 +4715,7 @@ Music from the 20th century may be based on atonal sounds. @node tonic @section tonic -ES: tonica, +ES: tónica, I: tonica, F: tonique, D: Tonika, @@ -4760,7 +4779,7 @@ FI: diskanttiavain. @node tremolo @section tremolo -ES: tremolo, +ES: trémolo, I: tremolo, F: trémolo, D: Tremolo, @@ -4874,7 +4893,7 @@ second). @node turn @section turn -ES: grupo, +ES: grupeto, I: gruppetto, F: grupetto, D: Doppelschlag, @@ -5066,7 +5085,7 @@ symphony orchestra are flute, oboe, clarinet, saxophone, and bassoon. @item @tab brevis @tab brevis - @tab breve + @tab cuadrada @item diff --git a/Documentation/user/notation-appendices.itely b/Documentation/user/notation-appendices.itely index 3efa17df7f..9ad1949cad 100644 --- a/Documentation/user/notation-appendices.itely +++ b/Documentation/user/notation-appendices.itely @@ -178,6 +178,9 @@ Where N is in the range 0-100. @node The Feta font @appendixsec The Feta font +@cindex Feta font +@cindex Font, Feta + The following symbols are available in the Emmentaler font and may be accessed directly using text markup such as @code{g^\markup @{ \musicglyph #"scripts.segno" @}}, see @ref{Text markup}. diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely index 55d8d145fb..e282f754f1 100644 --- a/Documentation/user/programming-interface.itely +++ b/Documentation/user/programming-interface.itely @@ -12,7 +12,6 @@ not familiar with Scheme, you may wish to read our * Building complicated functions:: * Markup programmer interface:: * Contexts for programmers:: -* OLD STUFF:: @end menu @@ -1132,265 +1131,3 @@ note-heads on the center-line: (set! (ly:grob-property grob 'transparent) #t))) @end example - -@node OLD STUFF -@section OLD STUFF - -This stuff is slated for deletion or merger into the earlier sections. - -@menu -* Extending music syntax:: -* Manipulating music expressions:: -* Using LilyPond syntax inside Scheme:: -@end menu - - -@node Extending music syntax -@subsection Extending music syntax - -@c TODO: rewrite example. -@c The use of FUNC as example argument is rather confusing. - -The syntax of composite music expressions, like @code{\repeat}, -@code{\transpose}, and @code{\context} follows the general form of - -@example -\@code{keyword} @var{non-music-arguments} @var{music-arguments} -@end example - -Such syntax can also be defined as user code. To do this it is -necessary to create a @emph{music function}. This is a specially marked -Scheme function. For example, the music function @code{\applyMusic} applies -a user-defined function to a music expression. Its syntax is - -@example -\applyMusic #@var{func} @var{music} -@end example - -A music function is created with @code{ly:make-music-function}, - -@example -(ly:make-music-function -@end example - -@code{\applyMusic} takes a Scheme function and a Music expression as -arguments. This is encoded in its parameter list, - -@example -(list procedure? ly:music?) -@end example - -The function itself takes another argument: an Input location -object. That object is used to provide error messages with file names -and line numbers. The definition is the second argument of -@code{ly:make-music-function}. The body simply calls the function - -@example -(lambda (where func music) - (func music)) -@end example - -The above Scheme code only defines the functionality. The tag -@code{\applyMusic} is selected by defining - -@example -applyMusic = #(ly:make-music-function - (list procedure? ly:music?) - (lambda (parser location func music) - (func music))) -@end example - -A @code{define-music-function} macro is introduced on top of -@code{ly:make-music-function} to ease the definition of music -functions: - -@example -applyMusic = #(define-music-function (parser location func music) - (procedure? ly:music?) - (func music)) -@end example - -Examples of the use of @code{\applyMusic} are in the next section. - -@seealso -@file{ly/@/music@/-functions@/-init@/.ly}. - - -@node Manipulating music expressions -@subsection Manipulating music expressions - -Music objects and their properties can be accessed and manipulated -directly through the @code{\applyMusic} mechanism. -The syntax for @code{\applyMusic} is - -@example -\applyMusic #@var{func} @var{music} -@end example - -@noindent -This means that the Scheme function @var{func} is called with -@var{music} as its argument. The return value of @var{func} is the -result of the entire expression. @var{func} may read and write music -properties using the functions @code{ly:music-property} and -@code{ly:music-set-property!}. - -An example is a function that reverses the order of elements in -its argument, -@lilypond[quote,verbatim,ragged-right] -#(define (rev-music-1 m) - (ly:music-set-property! m 'elements - (reverse (ly:music-property m 'elements))) - m) - -\applyMusic #rev-music-1 { c'4 d'4 } -@end lilypond - -The use of such a function is very limited. The effect of this -function is void when applied to an argument that does not have -multiple children. The following function application has no effect - -@example -\applyMusic #rev-music-1 \grace @{ c4 d4 @} -@end example - -@noindent -In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which -has no @code{elements}, only a single @code{element}. Every generally -applicable function for @code{\applyMusic} must -- like music expressions -themselves -- be recursive. - -The following example is such a recursive function: It first extracts -the @code{elements} of an expression, reverses them and puts them -back. Then it recurses, both on @code{elements} and @code{element} -children. - -@example -#(define (reverse-music music) - (let* ((elements (ly:music-property music 'elements)) - (child (ly:music-property music 'element)) - (reversed (reverse elements))) - - ; set children - (ly:music-set-property! music 'elements reversed) - - ; recurse - (if (ly:music? child) (reverse-music child)) - (map reverse-music reversed) - - music)) -@end example - -A slightly more elaborate example is in -@inputfileref{input/@/test,reverse@/-music@/.ly}. - -Some of the input syntax is also implemented as recursive music -functions. For example, the syntax for polyphony -@example -<> -@end example - -@noindent -is actually implemented as a recursive function that replaces the -above by the internal equivalent of -@example -<< \context Voice = "1" @{ \voiceOne a @} - \context Voice = "2" @{ \voiceTwo b @} >> -@end example - -Other applications of @code{\applyMusic} are writing out repeats -automatically (@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}), -saving keystrokes (@inputfileref{input/@/test,music@/-box@/.ly}) and -exporting LilyPond input to other formats -@c no @inputfileref{} here -(eg. @file{input/@/no@/-notation/@/to@/-xml@/.ly}). - -@seealso - -@file{scm/@/music@/-functions@/.scm}, @file{scm/@/music@/-types@/.scm}, -@inputfileref{input/@/test,add@/-staccato@/.ly}, -@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}, and -@inputfileref{input/@/test,music@/-box@/.ly}. - - -@node Using LilyPond syntax inside Scheme -@subsection Using LilyPond syntax inside Scheme - -Creating music expressions in Scheme can be tedious, as they are -heavily nested and the resulting Scheme code is large. For some -simple tasks this can be avoided by using common LilyPond syntax inside -Scheme, with the dedicated @code{#@{ ... #@}} syntax. - -The following two expressions give equivalent music expressions: -@example -mynotes = @{ \override Stem #'thickness = #4 - @{ c'8 d' @} @} - -#(define mynotes #@{ \override Stem #'thickness = #4 - @{ c'8 d' @} #@}) -@end example - -The content of @code{#@{ ... #@}} is enclosed in an implicit @code{@{ -... @}} block, which is parsed. The resulting music expression, a -@code{SequentialMusic} music object, is then returned and usable in Scheme. - -Arbitrary Scheme forms, including variables, can be used in @code{#@{ ... #@}} -expressions with the @code{$} character (@code{$$} can be used to -produce a single @code{$} character). This makes the creation of simple -functions straightforward. In the following example, a function -setting the TextScript's padding is defined: - -@lilypond[quote,verbatim,ragged-right] -#(use-modules (ice-9 optargs)) -#(define* (textpad padding #:optional once?) - (ly:export ; this is necessary for using the expression - ; directly inside a block - (if once? - #{ \once \override TextScript #'padding = #$padding #} - #{ \override TextScript #'padding = #$padding #}))) - - { - c'^"1" - #(textpad 3.0 #t) % only once - c'^"2" - c'^"3" - #(textpad 5.0) - c'^"4" - c'^"5" - } -@end lilypond - -Here, the variable @code{padding} is a number; music expression -variables may also be used in a similar fashion, as in the following -example: - -@lilypond[quote,verbatim,ragged-right] -#(define (with-padding padding) - (lambda (music) - #{ \override TextScript #'padding = #$padding - $music - \revert TextScript #'padding #})) - -{ - c'^"1" - \applyMusic #(with-padding 3) { c'^"2" c'^"3" } - c'^"4" -} -@end lilypond - -The function created by @code{(with-padding 3)} adds @code{\override} and -@code{\revert} statements around the music given as an argument, and returns -this new expression. Thus, this example is equivalent to: - -@example -@{ - c'^"1" - @{ \override TextScript #'padding = #3 - @{ c'^"2" c'^"3"@} - \revert TextScript #'padding - @} - c'^"4" -@} -@end example - - - diff --git a/THANKS b/THANKS index adfd10fdb0..72aa057e83 100644 --- a/THANKS +++ b/THANKS @@ -41,12 +41,14 @@ BUG HUNTERS/SUGGESTIONS Albert Frantz Aurèle Duda +Bernie Arai Cameron Horsburgh Claude Routhier Christopher Ellis Christian Hitz Colin Wilding David Rogers +Francisco Vila J. Leung Harald Wellmann Karl Hammar -- 2.39.5