Typo

[orchestrallily.git] / Documentation / orchestrallily.tely

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename orchestrallily.info
@settitle The OrchestralLily package for Lilypond
@c %**end of header

@documentencoding UTF-8
@documentlanguage en

@macro lilyverb{TEXT}
@quotation
@verbatim
\TEXT\
@end verbatim
@end quotation
@end macro

@c *******************************************************
@c **               COPYRIGHT INFORMATION               **
@c *******************************************************

@copying
This is the documentation of the OrchestralLily package for Lilypond, the GNU music
typesetting application.

Copyright @copyright{} 2008 Reinhold Kainhofer, @email{reinhold@@kainhofer.com}
@end copying


@c *******************************************************
@c **                     TITLEPAGE                     **
@c *******************************************************

@titlepage
@title OrchestralLily
@subtitle A Lilypond package for orchestral scores.
@author Reinhold Kainhofer, @email{reinhold@@kainhofer.com}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@setcontentsaftertitlepage
@end titlepage

@c Output the table of contents at the beginning.
@contents



@c *******************************************************
@c **                      TOP NODE                     **
@c *******************************************************

@ifnottex
@node Top
@top The OrchestralLily Package

@itemize
@item @b{Description}: A @uref{http://www.lilypond.org/, Lilypond} package to easily generate orchestral scores and other complex scores.
@item @b{Author}: @uref{http://reinhold.kainhofer.com/,Reinhold Kainhofer}, @email{reinhold@@kainhofer.com}
@item @b{Date}: February 2008
@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
@end itemize

@end ifnottex

@menu
* About OrchestralLily and Download::
* Motivation::
* Simple example::
* Extended example::
* Structure of a score::
* What OrchestralLily does::
* Suffixes in use::
* Settings defined by OrchestralLily::
* Available functions::
* Frequently asked questions::
* Version History::
* Known limitations and missing features::
* OrchestralLily index::
@end menu


@c *******************************************************
@c **                      CONTENT                      **
@c *******************************************************

@node About OrchestralLily and Download
@chapter About OrchestralLily and Download

@itemize
@item @b{Description}: A @uref{http://www.lilypond.org/, Lilypond} package to easily generate orchestral scores and other complex scores.
@item @b{Author}: @uref{http://reinhold.kainhofer.com/,Reinhold Kainhofer}, @email{reinhold@@kainhofer.com}
@item @b{Date}: February 2008
@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
@end itemize


@node Motivation
@chapter Motivation

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
@itemize
@item generate appropriate staves and staff groups
@item collate them in the proper (defined) order
@item add correct instrument names (if defined by the user)
@item add movement titles (if defined)
@item add a header "Movement name tacet" in an instrumental score for each movement where the instrument rests
@item add correct clefs/keys/other settings into each staff (if defined by the user)
@item etc.
@end itemize
This way, generating full scores, scores for individual instruments and for instrument groups are really simple and no additional manual work!


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! 

As they all look really similar, why not automate their creation instead of manually writing them? That is exactly where OrchestralLily comes in.


@node Simple example
@chapter A simple example

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.

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}:
@quotation
@verbatiminclude dada-defs.ly
@end quotation
@comment  lilyverb{@c
@comment  \version "2.11.40"
@comment  \include "orchestrallily.ly"
@comment  \paper @{ ragged-bottom = ##t @}
@comment  \header @{ title = "A nonsensical work" @}
@comment  
@comment  DadaPieceName = "Dada song"
@comment  DadaPieceNameTacet = "Dada song - Tacet"
@comment  
@comment  VcInstrumentName = "Violoncello"
@comment  VcShortInstrumentName = "Vc."
@comment  SSoloInstrumentName = "Soprano Solo"
@comment  SSoloShortInstrumentName = "S."
@comment  
@comment  VcClef = \clef "bass"
@comment  DadaSettings = @{\mark\markup@{\bold "Slow."@}@}
@comment  
@comment  DadaVcMusic = \relative c @{ c4 g' c, b' @}
@comment  DadaSSoloMusic = \relative c'' @{c2 c,8 e g c@}
@comment  DadaSSoloLyrics = \lyricmode @{ Da, da -- da -- da -- da! @}
@comment  
@comment  \orchestralScoreStructure #'(
@comment    ("FullScore" ParallelMusic ("Percussion" "SSolo" "Vc"))
@comment    ("InvertedScore" StaffGroup ("Vc" "SSolo"))
@comment  )@c
@comment  }

For each scores (full score, instrumental score, etc.), we write one additional file to generate the score.


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.

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.

The above definitions are all that is needed by OrchestralLily to generate all various kinds of scores!

@lilypond[quote,verbatim,staffsize=14,line-width=8.0\cm]
\version "2.11.40"
\include "dada-defs.ly"

% the soprano score:
\createScore #"Dada" #'("SSolo")

% the Vc score:
\createScore #"Dada" #'("Vc")

% the percussion score, no notes defined -> Tacet
\createScore #"Dada" #'("Percussion")

% the full score:
\createScore #"Dada" #'("FullScore")
@end lilypond

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.



Now, suppose we want to generate a score for Vc, including the soprano staff in smaller size. This is also really simple in OrchestralLily:

@lilypond[quote,verbatim]
\version "2.11.40"
\include "dada-defs.ly"

\header { instrument = \VcInstrumentName }

% For the SSolo staff, use a smaller staff size!
DadaSSoloSettings = {
    \DadaSettings 
    \set fontSize = #-4
    \override Staff.StaffSymbol #'staff-space = #(magstep -4)
}

\createScore #"Dada" #'("InvertedScore")
@end lilypond


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):

@lilypond[quote,verbatim]
\version "2.11.40"
\include "dada-defs.ly"

\orchestralScoreStructure #'(
  ("VcB" StaffGroup ("Vc"))
  ("FullScore" ParallelMusic ("Percussion" "SSolo" "VcB"))
)

\createScore #"Dada" #'("FullScore")
@end lilypond


Although it was not explicitly shown in this simple example, OrchestralLily of course supports also nested staff groups.

@node Extended example
@chapter Extended example: Multiple pieces

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:

@quotation
@verbatiminclude dadafull-defs.ly
@end quotation
@comment  @lilyverb{@c
@comment  \version "2.11.40"
@comment  \include "orchestrallily.ly"
@comment  \paper @{ ragged-bottom = ##t @}
@comment  \header @{ title = "A useless opus" @}
@comment  
@comment  TimKey = \key c \major
@comment  TimClef = \clef "bass"
@comment  TimInstrumentName = "Timpani"
@comment  TimShortInstrumentName = "Tim."
@comment  VcClef = \clef "bass"
@comment  VcInstrumentName = "Violoncello"
@comment  VcShortInstrumentName = "Vc."
@comment  SSoloInstrumentName = "Soprano Solo"
@comment  SSoloShortInstrumentName = "S."
@comment  
@comment  DadaPieceName = "1) Dada song"
@comment  DadaPieceNameTacet = "1) Dada song - Tacet"
@comment  DadaSettings = @{\mark\markup@{\italic "Slow."@}@}
@comment  DadaVcMusic = \relative c @{ c4 g' c, b' @}
@comment  DadaSSoloMusic = \relative c'' @{c2 c,8 e g c@}
@comment  DadaSSoloLyrics = \lyricmode @{ Da, da -- da -- da -- da! @}
@comment  
@comment  DidiPieceName = "2) Didi song"
@comment  DidiPieceNameTacet = "2) Didi song - Tacet"
@comment  DidiKey = \key fis \major
@comment  DidiTimMusic = \relative c @{ g1\startTrillSpan~ | g1\stopTrillSpan @}
@comment  DidiSSoloMusic = \relative c' @{ fis8 cis'4. fis,8 cis'4. | fis8 cis'4. fis,8 cis'4.@}
@comment  DidiSSoloLyrics = \lyricmode @{ Di -- di, di -- di, di -- di, di -- di! @}
@comment  
@comment  DodoPieceName = "3) Dodo song"
@comment  DodoPieceNameTacet = "3) Dodo song - Tacet"
@comment  DodoTimMusic = \relative c' @{ c1\<\startTrillSpan~ | c1\!\stopTrillSpan\ff @}
@comment  DodoVcMusic = \relative c @{ c1:16\< | c1:16\!\ff @}
@comment  DodoSSoloMusic = \relative c' @{ c4 d8 e f g a b | c1\ff @}
@comment  DodoSSoloLyrics = \lyricmode @{ Do, do, do, do, do, do, do, do... @}
@comment  
@comment  
@comment  \orchestralScoreStructure #'(
@comment    ("FullScore" ParallelMusic ("Tim" "SSolo" "VcB"))
@comment    ("VcB" StaffGroup ("Vc"))
@comment  ; a nested staff to highlight nested groups:
@comment    ("NestedScore" StaffGroup ("TimGr" "Solo" "VcB"))
@comment    ("TimGr" GrandStaff ("Tim"))
@comment    ("Solo" ChoirStaff ("SSolo"))
@comment  )@c
@comment  }

After these definitions, we can easily generate individual instrumental scores, as well as a full score:
@lilypond[quote,verbatim]
\version "2.11.40"
\include "dadafull-defs.ly"

\header { instrument = \TimInstrumentName }

\createScore #"Dada" #'("Tim")
\createScore #"Didi" #'("Tim")
\createScore #"Dodo" #'("Tim")
@end lilypond

@lilypond[quote,verbatim]
\version "2.11.40"
\include "dadafull-defs.ly"

\header { instrument = \SSoloInstrumentName }

\createScore #"Dada" #'("SSolo")
\createScore #"Didi" #'("SSolo")
\createScore #"Dodo" #'("SSolo")
@end lilypond

@lilypond[quote,verbatim]
\version "2.11.40"
\include "dadafull-defs.ly"

\header { instrument = \VcInstrumentName }

\createScore #"Dada" #'("Vc")
\createScore #"Didi" #'("Vc")
\createScore #"Dodo" #'("Vc")
@end lilypond

@lilypond[quote,verbatim]
\version "2.11.40"
\include "dadafull-defs.ly"

\createScore #"Dada" #'("FullScore")
\createScore #"Didi" #'("FullScore")
\createScore #"Dodo" #'("FullScore")
@end lilypond



@node Structure of a score
@chapter Structure of a score, naming staff groups

@float
@image{score_structure,,,A typical score hierarchy}
@end float
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:
@itemize
  @item "FullScore" (parallel staves/groups)
  @itemize
    @item "Woodwinds" (staff group)
    @itemize
      @item "Fl" (staff with two voices)
      @item "Ob" (staff with two voices)
    @end itemize
    @item "Strings" (staff group)
    @itemize
      @item "Violins" (grand staff)
      @itemize
        @item "VI" (simple staff)
        @item "VII" (simple staff)
      @end itemize
      @item "Va" (simple staff)
    @end itemize
    @item "Vocal" (parallel staves/groups)
    @itemize
      @item "Solo" (parallel staves)
      @itemize
        @item "SSolo" (simple staff)
        @item "TSolo" (simple staff)
      @end itemize
      @item "Choir" (choir staff)
      @itemize
        @item "S" (simple staff)
        @item "A" (simple staff)
        @item "T" (simple staff)
        @item "B" (simple staff)
      @end itemize
    @end itemize
    @item "VcB" (staff group)
    @itemize
      @item "Vc" (simple staff)
    @end itemize
  @end itemize
@end itemize
So, the "FullScore" consists of parallel music of the following staves/groups: "Woodwinds", "Strings", "Vocal" and "VcB".
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.

@menu
* Hierarchies in OrchestralLily::
* Why giving each level a name::
@end menu

@node Hierarchies in OrchestralLily
@section How to define this hierarchy in OrchestralLily

This structure can be easily defined in OrchestralLily by calling @code{\orchestral-score-structure} with a simple list describing the hierarchy:
@lilyverb{@c
\orchestral-score-structure #'(
  ("FullScore" SimultaneousMusic ("Woodwinds" "Strings" "Vocal" "VcB"))
  ("Woodwinds" StaffGroup ("Fl" "Ob"))
  ("Fl" #t ("FlI" "FlII"))
  ("Ob" #t ("ObI" "ObII"))
  ("Strings" StaffGroup ("Violins" "Va"))
  ("Violins" GrandStaff ("VI" "VII"))
  ("Vocal" SimultaneousMusic ("Solo" "Choir"))
  ("Solo" SimultaneousMusic ("SSolo" "TSolo"))
  ("Choir" ChoirStaff ("S" "A" "T" "B"))
  ("VcB" StaffGroup ("Vc"))
)@c
}
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!).

Each entry of the list describes one grouping of staves or voices and has three possible forms:
@lilyverb{@c
  ("Identifier" StaffGroupType ("List" "of" "child" "identifiers"))    ; Staff group of given type
  ("Identifier" SimultaneousMusic|ParallelMusic ("List" "children" ))  ; Staves connected without a bracket
  ("Identifier" #f ("List" "of" "voices"))                             ; One staff with multiple voices (not yet implemented!)
  ("Identifier" #t ("Two" "voices"))                                   ; Staff with two part-combined voices@c
}
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 >>}.
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!).

If an identifier from the list of child identifiers is not defined in that hierarchy list, it is assumed to be a simple staff.


@node Why giving each level a name
@section The advantage of giving each level a name

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.


@node What OrchestralLily does
@chapter What OrchestralLily does

@menu
* How a score is generated::
* How a staff is generated::
* How a staff group is generated::
@end menu 

Say you have the following structure of your score:
@lilyverb{@c
'(
  ("V" GrandStaff ("VI" "VII"))
  ("Strings" StaffGroup ("V" "Va"))
  ("FullScore" ParallelMusic ("Strings" "SSolo"))
)@c
}
in you score structure definition. This means you have two violins, one viola and a soprano solo.


@node How a score is generated
@section How a score is generated

If you call
@lilyverb{\createScore #"PieceA" #"FullScore"}
in your lilypond file, OrchestralLily will generate a score for you that is similar to the following hand-written score:
@lilyverb{@c
\score @{
  <<
    \PieceAStringsStaff
    \PieceASSoloStaff
  >>
  \header @{ piece = \PieceA[FullScore]PieceName @}
@}@c
}
If there exists e.g. a variable @code{\PieceAStringsStaff}, it is used, otherwise the staff (group) will be generated by OrchestralLily as described below.

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:
@lilyverb{\markup \piece-title \PieceA[FullScore]PieceNameTacet}
Here, piece-title is the function used by OrchestralLily to format piece headings. It simply returns the proper markup definition for the given string.


@node How a staff group is generated
@section How a staff group is generated

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:
@lilyverb{@c
\context StaffGroup = "\PieceAStringsSt" \with @{
         instrumentName = \PieceAStringsInstrumentName
         shortInstrumentName = \PieceAStringsShortInstrumentName 
@} <<
  \PieceAVStaff
  \PieceAVaStaff  
>>@c
}

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!).

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
@lilyverb{@c
<<
  \PieceAVStaff
  \PieceAVaStaff  
>>@c
}
without the possibility to have an instrument name attached.


@node How a staff is generated
@section How a staff is generated

If the staff for e.g. "SSolo" is not manually defined, OrchestralLily generates it in a form equivalent to
@lilyverb{@c
\context Staff = "PieceASSoloSt" \with @{
         instrumentName = \PieceASSoloInstrumentName
         shortInstrumentName = \PieceASSoloShortInstrumentName 
@} <<
  \context Voice = "PieceASSoloVoice" << 
    \dynamicUp
    \PieceA[SSolo]Settings
    \[PieceA]SSoloClef
    \PieceA[SSolo]Key
    \PieceASSoloMusic
  >>
  \context Lyrics = "PieceASSoloLyrics" \lyricsto "PieceASSoloVoice" \PieceASSoloLyrics
>>@c
}

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.


@node Suffixes in use
@chapter Suffixes in use

@multitable @columnfractions .25 .20 .20 .10 .25
@headitem @tab in Score  @tab in Staff group        @tab  in Staff
@headitem  Suffix @tab         @tab            @tab  StaffType  @tab  Parallel
@item @code{...PieceName}      @tab Title for the piece @tab  -  @tab  -  @tab  -
@item @code{...PieceNameTacet} @tab Piece title if no music is found @tab  -  @tab  -  @tab  -
@item @code{...Staff}          @tab Used as staff/group @tab  -  @tab  -  @tab  -
@headitem The following variables are only used if ...Staff is not defined (i.e. the staff is created by OrchestralLily):
@item @code{...Music}          @tab  -  @tab  -  @tab  -  @tab used as music for the staff
@item @code{...Lyrics}         @tab  -  @tab  -  @tab  -  @tab Lyrics assigned to music
@item @code{...Settings}       @tab  -  @tab  -  @tab  -  @tab music expression at beginning of staff
@item @code{...Clef}           @tab  -  @tab  -  @tab  -  @tab music expression at beginning of staff
@item @code{...Key}            @tab  -  @tab  -  @tab  -  @tab music expression at beginning of staff
@item @code{...InstrumentName} @tab  -  @tab assigned as instr. name @tab  -  @tab assigned as instr. name  
@item @code{...ShortInstrumentName} @tab  -  @tab assigned as instr. name @tab  -  @tab assigned as instr. name
@item @code{...MidiInstrument} @tab  -  @tab assigned as MIDI instr. @tab  -  @tab assigned as MIDI instr.
@end multitable

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):
@lilyverb{@c
  \PieceAInstrSuffix
  \InstrSuffix
  \PieceASuffix@c
}
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.

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.

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!

FIXME Add ...Transposition 


@node Settings defined by OrchestralLily
@chapter Settings defined/changed by OrchestralLily

@itemize
@item Proper rest combination
@item modern-cautionary style for auto-accidentals
@item FIXME lots of other things (not yet documented) in the context hierarchy. See the orchestrallily.ly file (at the end of the file)
@end itemize


@node Available functions
@chapter Available functions

@menu
* createScore::
* createNoCuesScore::
* orchestralScoreStructure::
* setUseBook::
* setCreateMIDI::
* setCreatePDF::
* namedCueDuring::
* namedTransposedCueDuring::
* cleffedCueDuring::
* piece-title::
* Other functions::
@end menu


@node createScore
@unnumberedsec createScore

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.
@lilyverb{\createScore #"PieceID" #'("Instrument1" "Instrument2" ...) }
@itemize
@item Typical call: @code{\createScore #"IIIChor" #'("T")}
@item Parameters: 
@table @var
@item @b{PieceID}
The identifier for the piece/movement, which is part of the variable names used to generate the score
@item @b{Instrument list}
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).
@end table
@end itemize


@node createNoCuesScore
@unnumberedsec createNoCuesScore

Like @code{\createScore}, except that @code{\killCues} and @code{\removeWithTag 'cued} is applied to all the music/staves
@lilyverb{\createNoCuesScore #"PieceID" #'("Instrument1" "Instrument2" ...)}
@itemize
@item Typical call: @code{\createNoCuesScore #"IIIChor" #'("T")}
@end itemize


@node orchestralScoreStructure
@unnumberedsec orchestralScoreStructure

@lilyverb{\orchestralScoreStructure #'( ("ID" 'StaffType ("List" "Of" "Instruments"))... ))}
  * Typical call: @lilyverb{\orchestralScoreStructure #'(
; Part-combined staves (one staff with two voices)
  ("Fl" #t ("FlI" "FlII"))
; Grouped staves (multiple staves either in a StaffGroup, or parallel without a bracket)
  ("Str" 'StaffGroup ("V" "Va"))
  ("Solo" 'ParallelMusic ("SSolo" "TSolo"))
  ("Ch" 'ChoirStaff ("S" "A" "T" "B"))
  ("Vocal" 'SimultaneousMusic ("Solo" "Ch"))
; full scores, again as grouped staves, no over-all bracket
  ("FullScore" 'ParallelMusic ("Fl" "Str" "Solo" "Ch"))
)@c
}
  * 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). 
  * Parameters: @b{Score structure} ... A list of group descriptions. Each entry describes such a group and has three possible forms:
@code{
  ("Identifier" StaffGroupType ("List" "of" "child" "identifiers"))    ; Staff group of given type
  ("Identifier" SimultaneousMusic|ParallelMusic ("List" "children" ))  ; Staves connected without a bracket
  ("Identifier" #f ("List" "of" "voices"))                             ; One staff with multiple voices (not yet implemented!)
  ("Identifier" #t ("Two" "voices"))                                   ; Staff with two part-combined voices
}
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!


@node setUseBook
@unnumberedsec setUseBook

@lilyverb{\setUseBook ##t}
  * Typical call: @code{\setUseBook ##t}
  * Description: Declare whether the scores are called within a @code{\book} section or as top-level. 
  * 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.
  * Parameters: 
    * @b{inside book} ... @code{##t} if the following scores are inside a @code{\book} environment, @code{##f} if not (default)
setUseBook = #(define-music-function (parser location usebook) (boolean?) 


@node setCreateMIDI
@unnumberedsec setCreateMIDI

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.
@lilyverb{\setCreateMIDI ##t}
  * Typical call: @code{\setCreateMidi ##t}



@node setCreatePDF
@unnumberedsec setCreatePDF

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!).
@lilyverb{\setCreatePDF ##t}
  * Typical call: @code{\setCreatePDF ##t}



@node namedCueDuring
@unnumberedsec namedCueDuring

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.
@lilyverb{\namedCueDuring #"QuoteName" #DIR #"cue instrument" #"original instrument"  music}
  * Typical call: @code{\namedCueDuring #"vIQuote" #UP #"V.I" #"Sop." @{ R1*3 @}}
  * Parameters: 
    * @b{quote name}, @b{direction}, @b{music} ... Parameters of @code{\cueDuring}
    * @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


@node namedTransposedCueDuring
@unnumberedsec namedTransposedCueDuring

Like @code{\namedCueDuring}, but uses @code{\transposedCueDuring} instead of @code{\cueDuring}.
@lilyverb{\namedTransposedCueDuring #"QuoteName" #DIR #"cue instrument" #"original instrument" centralCNote music}
  * Typical call: @code{\namedTransposedCueDuring #"vIQuote" #UP #"Piccolo" #"Sop." c' @{ R1*3 @}}


@node cleffedCueDuring
@unnumberedsec cleffedCueDuring

Like @code{\namedCudDuring}, but shows the cue notes with a different clef.
@lilyverb{\cleffedCueDuring NameOfQuote CueDirection CueInstrument CueClef OriginalInstrument OriginalClef music}
  * Typical call: @code{\cleffedCueDuring #"vIQuote" #UP #"V.I" @{\clef "treble"@} #"Basso" @{\clef "bass"@} @{ R1*3 @}}

% Parameters: \cleffedCueDuring NameOfQuote CueDirection CueInstrument CueClef OriginalInstrument OriginalClef music
%                 -) NameOfQuote CueDirection music are the parameters for \cueDuring
%                 -) CueInstrument and OriginalInstrument are the displayed instrument names
%                 -) CueClef and OriginalClef are the clefs for the the cue notes and the clef of the containing voice

%      This adds the notes from vIQuote (defined via \addQuote) to three measures, prints "V.I" at
%      the beginning of the cue notes and "Basso" at the end. The clef is changed to treble at the 
%      beginning of the cue notes and reset to bass at the end


@node piece-title
@unnumberedsec piece-title

@lilyverb{\piece-title pieceTitleString}
FIXME


@node Other functions
@unnumberedsec Other functions
FIXME: not yet documented


@node Frequently asked questions
@chapter Frequently asked questions

@menu
* Can I use my own staff definitions?::
* Can I use different variable names?::
* Can I change the structure of the score hierarchy list?::
@end menu

@node Can I use my own staff definitions?
@unnumberedsec Can I use my own staff definitions?

@node Can I use different variable names?
@unnumberedsec I don't like the variable names, can I use a different order?

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:
@lilyverb{@c
#(define (namedPieceInstrObject piece instr name)
  (let* (
         (fullname  (string->symbol (string-append piece instr name)))
         (instrname (string->symbol (string-append instr name)))
         (piecename (string->symbol (string-append piece name)))
        )
    (cond
      ((defined? fullname) (primitive-eval fullname))
      ((defined? instrname) (primitive-eval instrname))
      ((defined? piecename) (primitive-eval piecename))
      (else '())
    )
  )
)@c
}
Now it's up to you to write a different implementation... (e.g. use varnames of the style @code{\VarnameInstrPiece})
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!).


@node Can I change the structure of the score hierarchy list?
@unnumberedsec I don't like the structure of the score hierarchy list, can I change it?

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. 

If you redefine this function, you have complete control about the decision when to create each type of staff/group.


@node Version History
@chapter Version History

@table @asis
@item 0.01 (2008-03-02): 
Initial Version
@item 0.02 (2008-03-06): 
Added basic MIDI support (...MidiInstrument and \setCreateMIDI)
@item 0.03 (2008-03-??): 
Add *TimeSignature variable, split settings for full/vocal/instrumental scores
@end table


@node Known limitations and missing features
@chapter Known limitations and missing features

@itemize
@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.
@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.
@item FIXME Support for other staff types (DrumStaff, RhythmicStaff, TabStaff) and the corresponding voices
@item FIXME Add flag to generate MIDI
@end itemize

@node OrchestralLily index
@appendix OrchestralLily index

@printindex cp

@bye