1 \input texinfo @c -*-texinfo-*-
3 @setfilename orchestrallily.info
4 @settitle The OrchestralLily package for Lilypond
7 @documentencoding UTF-8
18 @c *******************************************************
19 @c ** COPYRIGHT INFORMATION **
20 @c *******************************************************
23 This is the documentation of the OrchestralLily package for Lilypond, the GNU music
24 typesetting application.
26 Copyright @copyright{} 2008 Reinhold Kainhofer, @email{reinhold@@kainhofer.com}
30 @c *******************************************************
32 @c *******************************************************
36 @subtitle A Lilypond package for orchestral scores.
37 @author Reinhold Kainhofer, @email{reinhold@@kainhofer.com}
39 @c The following two commands start the copyright page.
41 @vskip 0pt plus 1filll
43 @setcontentsaftertitlepage
46 @c Output the table of contents at the beginning.
51 @c *******************************************************
53 @c *******************************************************
57 @top The OrchestralLily Package
60 @item @b{Description}: A @uref{http://www.lilypond.org/, Lilypond} package to easily generate orchestral scores and other complex scores.
61 @item @b{Author}: @uref{http://reinhold.kainhofer.com/,Reinhold Kainhofer}, @email{reinhold@@kainhofer.com}
62 @item @b{Date}: February 2008
63 @item @b{Download}: @uref{http://wiki.kainhofer.com/_media/lilypond/orchestrallily.ly,orchestrallily.ly, (Version 0.02@comma{} 2008-03-06)}, licensed under the GPL v3.0
69 * About OrchestralLily and Download::
73 * Structure of a score::
74 * What OrchestralLily does::
76 * Settings defined by OrchestralLily::
77 * Available functions::
78 * Frequently asked questions::
80 * Known limitations and missing features::
81 * OrchestralLily index::
85 @c *******************************************************
87 @c *******************************************************
89 @node About OrchestralLily and Download
90 @chapter About OrchestralLily and Download
93 @item @b{Description}: A @uref{http://www.lilypond.org/, Lilypond} package to easily generate orchestral scores and other complex scores.
94 @item @b{Author}: @uref{http://reinhold.kainhofer.com/,Reinhold Kainhofer}, @email{reinhold@@kainhofer.com}
95 @item @b{Date}: February 2008
96 @item @b{Download}: @uref{http://wiki.kainhofer.com/_media/lilypond/orchestrallily.ly,orchestrallily.ly, (Version 0.02@comma{} 2008-03-06)}, licensed under the GPL v3.0
103 Orchestral scores might have a quite complicated structure, which is cumbersome to construct manually, in particular since each movement will have the same structure. The OrchestralLily package for @uref{http://www.lilypond.org/,Lilypond} aids you by adding some more magic to lilypond's already existing magic: You only define the structure of the whole piece once, you define the music that each instrument plays in each movement, and lilypond will do the rest. In particular, OrchestralLily will
105 @item generate appropriate staves and staff groups
106 @item collate them in the proper (defined) order
107 @item add correct instrument names (if defined by the user)
108 @item add movement titles (if defined)
109 @item add a header "Movement name tacet" in an instrumental score for each movement where the instrument rests
110 @item add correct clefs/keys/other settings into each staff (if defined by the user)
113 This way, generating full scores, scores for individual instruments and for instrument groups are really simple and no additional manual work!
116 As you can imagine, if you have lots of parts and lots of instruments, the number of similar staves/scores simply multiply (e.g. for 12 parts with 23 instruments, you'll have 12*23=276 individual staves, not counting any staff groups!). If you also want to include cue notes into the instrumental scores, you'll define a separate staff or score for the full score, where you call killCues. Thus the number will automatically double!
118 As they all look really similar, why not automate their creation instead of manually writing them? That is exactly where OrchestralLily comes in.
122 @chapter A simple example
124 Assume you have a piece called "Dada" with soprano solo (including lyrics) and violoncello. You might want to create a score for soprano only, one for cello one, one including both, a cello score including soprano (but in smaller size), etc.
126 We will call the soprano staff @code{SSolo} and the cello staff @code{Vc}. First, we need to define the music and lyrics for each, as well as the score structure. These will go into one file, say @code{dada-defs.ly}:
128 @verbatiminclude dada-defs.ly
131 @comment \version "2.11.40"
132 @comment \include "orchestrallily.ly"
133 @comment \paper @{ ragged-bottom = ##t @}
134 @comment \header @{ title = "A nonsensical work" @}
136 @comment DadaPieceName = "Dada song"
137 @comment DadaPieceNameTacet = "Dada song - Tacet"
139 @comment VcInstrumentName = "Violoncello"
140 @comment VcShortInstrumentName = "Vc."
141 @comment SSoloInstrumentName = "Soprano Solo"
142 @comment SSoloShortInstrumentName = "S."
144 @comment VcClef = \clef "bass"
145 @comment DadaSettings = @{\mark\markup@{\bold "Slow."@}@}
147 @comment DadaVcMusic = \relative c @{ c4 g' c, b' @}
148 @comment DadaSSoloMusic = \relative c'' @{c2 c,8 e g c@}
149 @comment DadaSSoloLyrics = \lyricmode @{ Da, da -- da -- da -- da! @}
151 @comment \orchestralScoreStructure #'(
152 @comment ("FullScore" ParallelMusic ("Percussion" "SSolo" "Vc"))
153 @comment ("InvertedScore" StaffGroup ("Vc" "SSolo"))
157 For each scores (full score, instrumental score, etc.), we write one additional file to generate the score.
160 Notice that all variables have a similar structure: First comes "Dada", then the instrument name ("SSolo" or "Vc"), and finally an indicator ("Settings", "Clef", "Music", "Lyrics", ...). For some of the variables, the instrument or the piece name is left out (This is only important for works with multiple pieces / movements, where you want one variable used in multiple pieces). Also notice that in the full score we have also added a "Percussion" instrument, but haven't defined any music for it (because e.g. it will only play in the second movement, which we haven't written yet). OrchestralLily will then simply ignore this instrument in the "Dada" part of the work.
162 Finally, the call @code{\orchestralScoreStructure} defines a FullScore and an InvertedScore with SSolo and Vc as children. This call tells OrchestralLily how the structure of your score looks like.
164 The above definitions are all that is needed by OrchestralLily to generate all various kinds of scores!
166 @lilypond[quote,verbatim,staffsize=14,line-width=8.0\cm]
168 \include "dada-defs.ly"
171 \createScore #"Dada" #'("SSolo")
174 \createScore #"Dada" #'("Vc")
176 % the percussion score, no notes defined -> Tacet
177 \createScore #"Dada" #'("Percussion")
180 \createScore #"Dada" #'("FullScore")
183 The actual score creation is done with a call to @code{\createScore}, with the part name ("Dada" in our case) as the first argument and a list of instrument / staff group identifiers as second argument.
187 Now, suppose we want to generate a score for Vc, including the soprano staff in smaller size. This is also really simple in OrchestralLily:
189 @lilypond[quote,verbatim]
191 \include "dada-defs.ly"
193 \header { instrument = \VcInstrumentName }
195 % For the SSolo staff, use a smaller staff size!
196 DadaSSoloSettings = {
199 \override Staff.StaffSymbol #'staff-space = #(magstep -4)
202 \createScore #"Dada" #'("InvertedScore")
206 In full scores, the violoncello and contrabass staff is typically shown with a bracket (StaffGroup) of their own, and the solo staves are shown without any bracket. To achieve this, all you have to do is to define the correct score structure (including a VcB staff group, consisting only of the Vc staff):
208 @lilypond[quote,verbatim]
210 \include "dada-defs.ly"
212 \orchestralScoreStructure #'(
213 ("VcB" StaffGroup ("Vc"))
214 ("FullScore" ParallelMusic ("Percussion" "SSolo" "VcB"))
217 \createScore #"Dada" #'("FullScore")
221 Although it was not explicitly shown in this simple example, OrchestralLily of course supports also nested staff groups.
223 @node Extended example
224 @chapter Extended example: Multiple pieces
226 The whole power of OrchestralLily, however, becomes unleashed only for pieces with multiple movements/sub-parts. Let us now add a second song "Didi", with only Timpani and Soprano Solo, as well as a third song "Dodo" with all instruments playing. For this, we have to add the corresponding music to the definitions file @b{dadafull-defs.ly}, which becomes:
229 @verbatiminclude dadafull-defs.ly
231 @comment @lilyverb{@c
232 @comment \version "2.11.40"
233 @comment \include "orchestrallily.ly"
234 @comment \paper @{ ragged-bottom = ##t @}
235 @comment \header @{ title = "A useless opus" @}
237 @comment TimKey = \key c \major
238 @comment TimClef = \clef "bass"
239 @comment TimInstrumentName = "Timpani"
240 @comment TimShortInstrumentName = "Tim."
241 @comment VcClef = \clef "bass"
242 @comment VcInstrumentName = "Violoncello"
243 @comment VcShortInstrumentName = "Vc."
244 @comment SSoloInstrumentName = "Soprano Solo"
245 @comment SSoloShortInstrumentName = "S."
247 @comment DadaPieceName = "1) Dada song"
248 @comment DadaPieceNameTacet = "1) Dada song - Tacet"
249 @comment DadaSettings = @{\mark\markup@{\italic "Slow."@}@}
250 @comment DadaVcMusic = \relative c @{ c4 g' c, b' @}
251 @comment DadaSSoloMusic = \relative c'' @{c2 c,8 e g c@}
252 @comment DadaSSoloLyrics = \lyricmode @{ Da, da -- da -- da -- da! @}
254 @comment DidiPieceName = "2) Didi song"
255 @comment DidiPieceNameTacet = "2) Didi song - Tacet"
256 @comment DidiKey = \key fis \major
257 @comment DidiTimMusic = \relative c @{ g1\startTrillSpan~ | g1\stopTrillSpan @}
258 @comment DidiSSoloMusic = \relative c' @{ fis8 cis'4. fis,8 cis'4. | fis8 cis'4. fis,8 cis'4.@}
259 @comment DidiSSoloLyrics = \lyricmode @{ Di -- di, di -- di, di -- di, di -- di! @}
261 @comment DodoPieceName = "3) Dodo song"
262 @comment DodoPieceNameTacet = "3) Dodo song - Tacet"
263 @comment DodoTimMusic = \relative c' @{ c1\<\startTrillSpan~ | c1\!\stopTrillSpan\ff @}
264 @comment DodoVcMusic = \relative c @{ c1:16\< | c1:16\!\ff @}
265 @comment DodoSSoloMusic = \relative c' @{ c4 d8 e f g a b | c1\ff @}
266 @comment DodoSSoloLyrics = \lyricmode @{ Do, do, do, do, do, do, do, do... @}
269 @comment \orchestralScoreStructure #'(
270 @comment ("FullScore" ParallelMusic ("Tim" "SSolo" "VcB"))
271 @comment ("VcB" StaffGroup ("Vc"))
272 @comment ; a nested staff to highlight nested groups:
273 @comment ("NestedScore" StaffGroup ("TimGr" "Solo" "VcB"))
274 @comment ("TimGr" GrandStaff ("Tim"))
275 @comment ("Solo" ChoirStaff ("SSolo"))
279 After these definitions, we can easily generate individual instrumental scores, as well as a full score:
280 @lilypond[quote,verbatim]
282 \include "dadafull-defs.ly"
284 \header { instrument = \TimInstrumentName }
286 \createScore #"Dada" #'("Tim")
287 \createScore #"Didi" #'("Tim")
288 \createScore #"Dodo" #'("Tim")
291 @lilypond[quote,verbatim]
293 \include "dadafull-defs.ly"
295 \header { instrument = \SSoloInstrumentName }
297 \createScore #"Dada" #'("SSolo")
298 \createScore #"Didi" #'("SSolo")
299 \createScore #"Dodo" #'("SSolo")
302 @lilypond[quote,verbatim]
304 \include "dadafull-defs.ly"
306 \header { instrument = \VcInstrumentName }
308 \createScore #"Dada" #'("Vc")
309 \createScore #"Didi" #'("Vc")
310 \createScore #"Dodo" #'("Vc")
313 @lilypond[quote,verbatim]
315 \include "dadafull-defs.ly"
317 \createScore #"Dada" #'("FullScore")
318 \createScore #"Didi" #'("FullScore")
319 \createScore #"Dodo" #'("FullScore")
324 @node Structure of a score
325 @chapter Structure of a score, naming staff groups
328 @image{score_structure,,,A typical score hierarchy}
330 A full score typically consists of several levels of staves and staff groupings, which can also be understood as a hierarchy of staves. We will assign each level in this hierarchy an identifier (written in red in the example). For example, the score on the left has the tree:
332 @item "FullScore" (parallel staves/groups)
334 @item "Woodwinds" (staff group)
336 @item "Fl" (staff with two voices)
337 @item "Ob" (staff with two voices)
339 @item "Strings" (staff group)
341 @item "Violins" (grand staff)
343 @item "VI" (simple staff)
344 @item "VII" (simple staff)
346 @item "Va" (simple staff)
348 @item "Vocal" (parallel staves/groups)
350 @item "Solo" (parallel staves)
352 @item "SSolo" (simple staff)
353 @item "TSolo" (simple staff)
355 @item "Choir" (choir staff)
357 @item "S" (simple staff)
358 @item "A" (simple staff)
359 @item "T" (simple staff)
360 @item "B" (simple staff)
363 @item "VcB" (staff group)
365 @item "Vc" (simple staff)
369 So, the "FullScore" consists of parallel music of the following staves/groups: "Woodwinds", "Strings", "Vocal" and "VcB".
370 Similarly, "Choir" is a ChoirStaff and consists of the individual staves "S", "A", "T" and "B". To be able to generate such a score automatically, lilypond needs to know the structure of the tree. For this, it suffices to know the type and all children of each group, e.g. which staves/groups are direct children of "FullScore", which of "Vocal", etc. No information about the individual staves is needed yet.
373 * Hierarchies in OrchestralLily::
374 * Why giving each level a name::
377 @node Hierarchies in OrchestralLily
378 @section How to define this hierarchy in OrchestralLily
380 This structure can be easily defined in OrchestralLily by calling @code{\orchestral-score-structure} with a simple list describing the hierarchy:
382 \orchestral-score-structure #'(
383 ("FullScore" SimultaneousMusic ("Woodwinds" "Strings" "Vocal" "VcB"))
384 ("Woodwinds" StaffGroup ("Fl" "Ob"))
385 ("Fl" #t ("FlI" "FlII"))
386 ("Ob" #t ("ObI" "ObII"))
387 ("Strings" StaffGroup ("Violins" "Va"))
388 ("Violins" GrandStaff ("VI" "VII"))
389 ("Vocal" SimultaneousMusic ("Solo" "Choir"))
390 ("Solo" SimultaneousMusic ("SSolo" "TSolo"))
391 ("Choir" ChoirStaff ("S" "A" "T" "B"))
392 ("VcB" StaffGroup ("Vc"))
395 Please note the apostrophe before the list! There are no apostrophes needed in front of the staff group types (because the whole is list is already quoted!).
397 Each entry of the list describes one grouping of staves or voices and has three possible forms:
399 ("Identifier" StaffGroupType ("List" "of" "child" "identifiers")) ; Staff group of given type
400 ("Identifier" SimultaneousMusic|ParallelMusic ("List" "children" )) ; Staves connected without a bracket
401 ("Identifier" #f ("List" "of" "voices")) ; One staff with multiple voices (not yet implemented!)
402 ("Identifier" #t ("Two" "voices")) ; Staff with two part-combined voices@c
404 The first entry creates a staff group of type @code{StaffGroupType} (e.g. @code{StaffGroup}, @code{GrandStaff}, @code{PianoStaff}, @code{ChoirStaff}), the second one (i.e. giving either SimultaneousMusic or ParallelMusic as staff type) creates parallel staves connected by a simple line, but no bracket. In lilypond syntax, this is equivalent to @code{<< Staff1 Staff2 >>}.
405 The third and fourth forms are not really staff groups, but staves containing multiple voices. The third one with #f as staff type generates a staff with multiple voices (@code{\voiceOne}, @code{\voiceTwo}, etc.), possibly with lyrics, while the fourth one with #t (for combined=##t) as staff type staff with two part-combined voices (e.g. Flute 1 and Flute 2 combined in one staff for Flute). Internally, @code{\partcombine} is used for this (with all its limitations!).
407 If an identifier from the list of child identifiers is not defined in that hierarchy list, it is assumed to be a simple staff.
410 @node Why giving each level a name
411 @section The advantage of giving each level a name
413 One of the advantages of assigning each group a name is that you can now tell OrchestralLily to generate e.g. a vocal score (containing only the "Vocal" staff group). Whether you want to generate an individual instrumental score, a full score, or a score for a group of instruments, is then no difference to OrchestralLily: You simply tell OrchestralLily to generate the score for a given identifier, and you will end up with the correct PDF. If you tell OrchestralLily to build the "FullScore" score, you'll get a score with the group named "FullScore" (which happens to be the full score), if you tell it to build "Fl", you'll get a score with just one staff, namely the one for the flutes. Similarly, to generate a pure choral score, simply tell OrchestralLily to build the score for the "Choir" group.
416 @node What OrchestralLily does
417 @chapter What OrchestralLily does
420 * How a score is generated::
421 * How a staff is generated::
422 * How a staff group is generated::
425 Say you have the following structure of your score:
428 ("V" GrandStaff ("VI" "VII"))
429 ("Strings" StaffGroup ("V" "Va"))
430 ("FullScore" ParallelMusic ("Strings" "SSolo"))
433 in you score structure definition. This means you have two violins, one viola and a soprano solo.
436 @node How a score is generated
437 @section How a score is generated
440 @lilyverb{\createScore #"PieceA" #"FullScore"}
441 in your lilypond file, OrchestralLily will generate a score for you that is similar to the following hand-written score:
448 \header @{ piece = \PieceA[FullScore]PieceName @}
451 If there exists e.g. a variable @code{\PieceAStringsStaff}, it is used, otherwise the staff (group) will be generated by OrchestralLily as described below.
453 If none of the sub-staves (and their sub-staves, etc.) contains any music, OrchestralLily will instead create a title to indicate no music is to be played:
454 @lilyverb{\markup \piece-title \PieceA[FullScore]PieceNameTacet}
455 Here, piece-title is the function used by OrchestralLily to format piece headings. It simply returns the proper markup definition for the given string.
458 @node How a staff group is generated
459 @section How a staff group is generated
461 If there is no definition for @code{\PieceAStringsStaff}, it is generated (as a StaffGroup as defined in the score structure) by OrchestralLily and is equivalent to the following manual definition:
463 \context StaffGroup = "\PieceAStringsSt" \with @{
464 instrumentName = \PieceAStringsInstrumentName
465 shortInstrumentName = \PieceAStringsShortInstrumentName
472 Again, if any of the @code{PieceAVStaff} or @code{PieceAVaStaff} variable is defined, it is inserted, otherwise the corresponding staff or staff group is created automatically (unless there is no music definition for it, in which case it is simply ignored). If any of the instrument name variables is not defined, the corresponding assignment is left out (without any error or warning message!).
474 If the definition of the Strings group in the score structure were a @code{ParallelMusic} or @code{SimultaneousMusic}, the generated code would be equivalent to
481 without the possibility to have an instrument name attached.
484 @node How a staff is generated
485 @section How a staff is generated
487 If the staff for e.g. "SSolo" is not manually defined, OrchestralLily generates it in a form equivalent to
489 \context Staff = "PieceASSoloSt" \with @{
490 instrumentName = \PieceASSoloInstrumentName
491 shortInstrumentName = \PieceASSoloShortInstrumentName
493 \context Voice = "PieceASSoloVoice" <<
495 \PieceA[SSolo]Settings
500 \context Lyrics = "PieceASSoloLyrics" \lyricsto "PieceASSoloVoice" \PieceASSoloLyrics
504 If no lyrics are defined (i.e. the variable @code{\PieceASSoloLyrics} is not defined), the @code{\dynamicUp} as well as the lyrics context is left out. Similarly, if any of the variables shown above is not defined, it is simply left out without any warning or error. If no music is defined (e.g. the variable @code{\PieceASSoloMusic} is not defined), no staff will be generated and it will simply be left out in the parent group.
507 @node Suffixes in use
508 @chapter Suffixes in use
510 @multitable @columnfractions .25 .20 .20 .10 .25
511 @headitem @tab in Score @tab in Staff group @tab in Staff
512 @headitem Suffix @tab @tab @tab StaffType @tab Parallel
513 @item @code{...PieceName} @tab Title for the piece @tab - @tab - @tab -
514 @item @code{...PieceNameTacet} @tab Piece title if no music is found @tab - @tab - @tab -
515 @item @code{...Staff} @tab Used as staff/group @tab - @tab - @tab -
516 @headitem The following variables are only used if ...Staff is not defined (i.e. the staff is created by OrchestralLily):
517 @item @code{...Music} @tab - @tab - @tab - @tab used as music for the staff
518 @item @code{...Lyrics} @tab - @tab - @tab - @tab Lyrics assigned to music
519 @item @code{...Settings} @tab - @tab - @tab - @tab music expression at beginning of staff
520 @item @code{...Clef} @tab - @tab - @tab - @tab music expression at beginning of staff
521 @item @code{...Key} @tab - @tab - @tab - @tab music expression at beginning of staff
522 @item @code{...InstrumentName} @tab - @tab assigned as instr. name @tab - @tab assigned as instr. name
523 @item @code{...ShortInstrumentName} @tab - @tab assigned as instr. name @tab - @tab assigned as instr. name
524 @item @code{...MidiInstrument} @tab - @tab assigned as MIDI instr. @tab - @tab assigned as MIDI instr.
527 The order in which these variables are looked up is also relevant. If you are printing the score for piece "PieceA" and the currently processed instrument/group is "Instr", OrchestralLily will test the following variable names (in this order):
533 This particular order ensures that you can have a definition for each score-instrument combination, which overrides everything else (e.g. the definition of the music should probably use this variable). However, for piece titles, keys and so on, you can have one definition, which applies to all instruments in that piece (the third form). On the other hand, some instruments (e.g. transposing instruments) need some special settings, which should override the piece-wide settings (like the key). For this, the second form is provided.
535 In the following we will typically give the variable name in full form @code{\PieceAInstrSuffix} with the understanding that of course @code{\InstrSuffix} and @code{\PieceASuffix} will be used if the full form variable does not exist. If any part is written in square brackets [..], this indicates that this part is typically left out and instrument- or piece-wide variables are usually used in this place.
537 One word or care, though: Be careful with variables of the form @code{\InstrStaff}. If you define it, OrchestralLily will use that staff for the given instrument for each part of the whole work and never generate a staff for you!!! Similarly, if you define @code{\PieceAStaff}, all instruments in PieceA will get this staff, unless you manually define a staff for an instrument!
539 FIXME Add ...Transposition
542 @node Settings defined by OrchestralLily
543 @chapter Settings defined/changed by OrchestralLily
546 @item Proper rest combination
547 @item modern-cautionary style for auto-accidentals
548 @item FIXME lots of other things (not yet documented) in the context hierarchy. See the orchestrallily.ly file (at the end of the file)
552 @node Available functions
553 @chapter Available functions
557 * createNoCuesScore::
558 * orchestralScoreStructure::
563 * namedTransposedCueDuring::
571 @unnumberedsec createScore
573 Generates the score for the given piece and the given instrument(s). If no appropriate *Staff or *Music can be found, a header with the *PieceName (or the *PieceNameTacet) string will be printed.
574 @lilyverb{\createScore #"PieceID" #'("Instrument1" "Instrument2" ...) }
576 @item Typical call: @code{\createScore #"IIIChor" #'("T")}
580 The identifier for the piece/movement, which is part of the variable names used to generate the score
581 @item @b{Instrument list}
582 The list of instruments/staff identifiers to be shown in the score. These identifiers either indicate a staff group (as defined in the score structure list) or a single instrument (where the *Staff or *Music variables are used to create the staff).
587 @node createNoCuesScore
588 @unnumberedsec createNoCuesScore
590 Like @code{\createScore}, except that @code{\killCues} and @code{\removeWithTag 'cued} is applied to all the music/staves
591 @lilyverb{\createNoCuesScore #"PieceID" #'("Instrument1" "Instrument2" ...)}
593 @item Typical call: @code{\createNoCuesScore #"IIIChor" #'("T")}
597 @node orchestralScoreStructure
598 @unnumberedsec orchestralScoreStructure
600 @lilyverb{\orchestralScoreStructure #'( ("ID" 'StaffType ("List" "Of" "Instruments"))... ))}
601 * Typical call: @lilyverb{\orchestralScoreStructure #'(
602 ; Part-combined staves (one staff with two voices)
603 ("Fl" #t ("FlI" "FlII"))
604 ; Grouped staves (multiple staves either in a StaffGroup, or parallel without a bracket)
605 ("Str" 'StaffGroup ("V" "Va"))
606 ("Solo" 'ParallelMusic ("SSolo" "TSolo"))
607 ("Ch" 'ChoirStaff ("S" "A" "T" "B"))
608 ("Vocal" 'SimultaneousMusic ("Solo" "Ch"))
609 ; full scores, again as grouped staves, no over-all bracket
610 ("FullScore" 'ParallelMusic ("Fl" "Str" "Solo" "Ch"))
613 * Description: Defines the hierarchy tree of the score. Each staff group (or part-combined staff with two voices) is identified by an ID (the first element of each entry).
614 * Parameters: @b{Score structure} ... A list of group descriptions. Each entry describes such a group and has three possible forms:
616 ("Identifier" StaffGroupType ("List" "of" "child" "identifiers")) ; Staff group of given type
617 ("Identifier" SimultaneousMusic|ParallelMusic ("List" "children" )) ; Staves connected without a bracket
618 ("Identifier" #f ("List" "of" "voices")) ; One staff with multiple voices (not yet implemented!)
619 ("Identifier" #t ("Two" "voices")) ; Staff with two part-combined voices
621 The list can contain each identifier only once, but they do not have to form only one tree, you can define several different hierarchy trees in one list!
625 @unnumberedsec setUseBook
627 @lilyverb{\setUseBook ##t}
628 * Typical call: @code{\setUseBook ##t}
629 * Description: Declare whether the scores are called within a @code{\book} section or as top-level.
630 * Explanation: Internally, a score needs to be created differently if it should be printed inside a @code{\book} environment. Unfortunately, it is not possible in lilypond to detect the current environment, so this function is needed to explicitly declare that the following scores are inserted inside a @code{\book} environment.
632 * @b{inside book} ... @code{##t} if the following scores are inside a @code{\book} environment, @code{##f} if not (default)
633 setUseBook = #(define-music-function (parser location usebook) (boolean?)
637 @unnumberedsec setCreateMIDI
639 Set a flag to determine whether MIDI output should be generated (default: NO). If YES, then an empty @code{\midi@{@}} block is generated in the score to trigger the creation of the midi file.
640 @lilyverb{\setCreateMIDI ##t}
641 * Typical call: @code{\setCreateMidi ##t}
646 @unnumberedsec setCreatePDF
648 Set a flag to determine whether PDF output should be generated (default: YES). If no, no @code{\layout@{@}} block will be generated in the score. If create @code{MIDI == #t}, then only MIDI will be created. If create @code{MIDI == #f}, then the PDF output will still be generated (similar to the existence/non-existence of a @code{\midi} and @code{\layout} block in a score!).
649 @lilyverb{\setCreatePDF ##t}
650 * Typical call: @code{\setCreatePDF ##t}
655 @unnumberedsec namedCueDuring
657 Like @code{\cueDuring}, but also adds the instrument name of the cue instrument at the beginning of the cue notes and the original instrument name after the cue notes.
658 @lilyverb{\namedCueDuring #"QuoteName" #DIR #"cue instrument" #"original instrument" music}
659 * Typical call: @code{\namedCueDuring #"vIQuote" #UP #"V.I" #"Sop." @{ R1*3 @}}
661 * @b{quote name}, @b{direction}, @b{music} ... Parameters of @code{\cueDuring}
662 * @b{cue instrument}, @b{original instrument} ... Instrument names (strings) to be printed as cue instrument name at the beginning of the cues and as original instrument name after the cue notes
665 @node namedTransposedCueDuring
666 @unnumberedsec namedTransposedCueDuring
668 Like @code{\namedCueDuring}, but uses @code{\transposedCueDuring} instead of @code{\cueDuring}.
669 @lilyverb{\namedTransposedCueDuring #"QuoteName" #DIR #"cue instrument" #"original instrument" centralCNote music}
670 * Typical call: @code{\namedTransposedCueDuring #"vIQuote" #UP #"Piccolo" #"Sop." c' @{ R1*3 @}}
673 @node cleffedCueDuring
674 @unnumberedsec cleffedCueDuring
676 Like @code{\namedCudDuring}, but shows the cue notes with a different clef.
677 @lilyverb{\cleffedCueDuring NameOfQuote CueDirection CueInstrument CueClef OriginalInstrument OriginalClef music}
678 * Typical call: @code{\cleffedCueDuring #"vIQuote" #UP #"V.I" @{\clef "treble"@} #"Basso" @{\clef "bass"@} @{ R1*3 @}}
680 % Parameters: \cleffedCueDuring NameOfQuote CueDirection CueInstrument CueClef OriginalInstrument OriginalClef music
681 % -) NameOfQuote CueDirection music are the parameters for \cueDuring
682 % -) CueInstrument and OriginalInstrument are the displayed instrument names
683 % -) CueClef and OriginalClef are the clefs for the the cue notes and the clef of the containing voice
685 % This adds the notes from vIQuote (defined via \addQuote) to three measures, prints "V.I" at
686 % the beginning of the cue notes and "Basso" at the end. The clef is changed to treble at the
687 % beginning of the cue notes and reset to bass at the end
691 @unnumberedsec piece-title
693 @lilyverb{\piece-title pieceTitleString}
697 @node Other functions
698 @unnumberedsec Other functions
699 FIXME: not yet documented
702 @node Frequently asked questions
703 @chapter Frequently asked questions
706 * Can I use my own staff definitions?::
707 * Can I use different variable names?::
708 * Can I change the structure of the score hierarchy list?::
711 @node Can I use my own staff definitions?
712 @unnumberedsec Can I use my own staff definitions?
714 @node Can I use different variable names?
715 @unnumberedsec I don't like the variable names, can I use a different order?
717 If you don't like that the variables are generated as @code{\PieceInstrumentVarname}, you can override this behavior by redefining the scheme function @code{(namedPieceInstrObject piece instr name)}. The default implementation is:
719 #(define (namedPieceInstrObject piece instr name)
721 (fullname (string->symbol (string-append piece instr name)))
722 (instrname (string->symbol (string-append instr name)))
723 (piecename (string->symbol (string-append piece name)))
726 ((defined? fullname) (primitive-eval fullname))
727 ((defined? instrname) (primitive-eval instrname))
728 ((defined? piecename) (primitive-eval piecename))
734 Now it's up to you to write a different implementation... (e.g. use varnames of the style @code{\VarnameInstrPiece})
735 But be careful with the order of evaluation, since some large scores might depend on @code{instrname} overriding @code{piecename} (e.g. a globally-defined key for transposing instruments!).
738 @node Can I change the structure of the score hierarchy list?
739 @unnumberedsec I don't like the structure of the score hierarchy list, can I change it?
741 Sure, there is only one function that interprets the entries (factory pattern!): @code{(oly:create_staff_or_group parser piece instr)}. It looks up the @code{\PieceInstrumentStaff} variable and if that does not exist, it looks at a possible entry in the score structure descriptions and depending on its form, calls different methods to create a staff, a group, a part-combined staff or a staff with multiple voices.
743 If you redefine this function, you have complete control about the decision when to create each type of staff/group.
746 @node Version History
747 @chapter Version History
750 @item 0.01 (2008-03-02):
752 @item 0.02 (2008-03-06):
753 Added basic MIDI support (...MidiInstrument and \setCreateMIDI)
754 @item 0.03 (2008-03-??):
755 Add *TimeSignature variable, split settings for full/vocal/instrumental scores
759 @node Known limitations and missing features
760 @chapter Known limitations and missing features
763 @item FIXME @b{Staves with multiple voices} (using @code{\voiceOne}, @code{\voiceTwo}), possibly with lyrics attached, are not yet implemented. Currently, you'll still have to define those staves manually.
764 @item FIXME Support for @b{transposing instruments} is missing. You'd define the music in sounding pitch, but the displayed staff would be automatically transposed to the defined key (via a @code{\[Piece]InstrTransposition} variable). Thus, all cue notes will also be correct automatically.
765 @item FIXME Support for other staff types (DrumStaff, RhythmicStaff, TabStaff) and the corresponding voices
766 @item FIXME Add flag to generate MIDI
769 @node OrchestralLily index
770 @appendix OrchestralLily index