Move instrument names to separate include file

[orchestrallily.git] / Documentation / orchestrallily.tely

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

@documentencoding UTF-8
@documentlanguage en

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

@macro bs
\\
@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 @uref{http://reinhold.kainhofer.com,Reinhold Kainhofer}, @email{reinhold@@kainhofer.com}
@end copying


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

@titlepage
@title OrchestralLily
@subtitle A Lilypond package for orchestral scores.
@author @uref{http://reinhold.kainhofer.com,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 *******************************************************

@comment  @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}: June 2008
@item @b{Download}: @uref{http://wiki.kainhofer.com/_media/lilypond/orchestrallily.ly,orchestrallily.ly, (Version 0.03@comma{} 2008-06-24)}, licensed under the GPL v3.0
@item @b{Development version}:
@itemize 
@item Web-Frontend: @uref{http://repo.or.cz/w/orchestrallily.git}
@item read-only git URL: git://repo.or.cz/orchestrallily.git (use git clone URL)
@end itemize
@item @b{Documentation}: @uref{index.html,HTML (one page per section)}, @uref{orchestrallily-bigpage.html,HTML (Single page)}, @uref{orchestrallily.pdf,PDF}
@end itemize

@comment @end ifnottex

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


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

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

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

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::
* Different staff types::
* Different voice types::
* 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:
@example
\orchestral-score-structure #'(
  ("FullScore" "SimultaneousMusic" ("Woodwinds" "Strings" "Vocal" "VcB"))
  ("Woodwinds" "StaffGroup" ("Fl" "Ob"))
  ("Fl" "PartCombinedStaff" ("FlI" "FlII"))
  ("Ob" "PartCombinedStaff" ("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"))
  ; Staff types
  ("Percussion" "RhythmicStaff" ())
)
@end example
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:
@example
     ; Staff group of given type
  ("StaffID" "StaffGroupType" ("List" "of" "child" "identifiers"))
     ; Staves connected without a bracket
  ("StaffID" "SimultaneousMusic"|"ParallelMusic" ("List" "children" ))
     ; One staff with multiple voices
  ("StaffID" "ParallelVoicesStaff" ("List" "of" "voices"))
     ; Staff with two part-combined voices
  ("StaffID" "PartCombinedStaff" ("Two" "voices"))@c
     ; Non-default staff type
  ("StaffID" "StaffType" ())
  ("StaffID" "StaffType" ("ChildVoiceName"))
@end example
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 Different staff types
@section Different staff types

Lilypond supports more types than just ordinary staves: DrumStaff, FiguredBass, etc.
In OrchestralLily, the type of a staff (e.g. DrumStaff, RhythmicStaff, etc.) can
also be defined directly in the score structure by an entry like
@example
     ; Non-default staff type
  ("StaffID" "StaffType" ())
  ("StaffID" "StaffType" ("ChildVoiceName"))
@end example

If "ChildVoiceName" is given, it is used as voice name (in particular, the music
is extracted from [Piece]ChildVoiceNameMusic), otherwise, the ID of the staff
is also taken for the Voice (the music is extracted from [Piece]StaffIDMusic).

@node Different voice types
@section Different voice types

Some staves and some music definitions need different contexts than Voice, which 
is used by default. For example, music defined with @code{\\drummode} needs to
be inside a @code{DrumVoice}, @code{\figuremode} inside @code{FiguredBass}, etc.

To set the type of context used for a voice in Orchestrallily, simply call 
@code{\orchestralVoiceTypes} with an association list defining the voice type 
for each voice ID. For example:
@example
\orchestralVoiceTypes #'(
  ("Ix" "DrumVoice")
  ("Iix" "FiguredBass")
)
@end example



@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
@example
'(
  ("V" "GrandStaff" ("VI" "VII"))
  ("Strings" "StaffGroup" ("V" "Va"))
  ("FullScore" "ParallelMusic" ("Strings" "SSolo"))
)
@end example
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
@example
\createScore #"PieceA" #"FullScore"
@end example
in your lilypond file, OrchestralLily will generate a score for you that is similar to the following hand-written score:
@example
\score @{
  <<
    \PieceAStringsStaff
    \PieceASSoloStaff
  >>
  \header @{ piece = \PieceA[FullScore]PieceName @}
@}
@end example
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:
@example
\markup \piece-title \PieceA[FullScore]PieceNameTacet
@end example
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:
@example
\context StaffGroup = "\PieceAStringsSt" \with @{
         instrumentName = \PieceAStringsInstrumentName
         shortInstrumentName = \PieceAStringsShortInstrumentName 
@} <<
  \PieceAVStaff
  \PieceAVaStaff  
>>
@end example


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
@example
<<
  \PieceAVStaff
  \PieceAVaStaff  
>>
@end example
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
@example
\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
>>
@end example

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{...TimeSignature}  @tab  -  @tab  -  @tab  -  @tab music expression at beginning of staff
@item @code{...TransposeTo}    @tab  -  @tab  -  @tab  -  @tab pitch, definition position of middle c' for the piece
@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):
@example
  \PieceAInstrSuffix
  \InstrSuffix
  \PieceASuffix
@end example
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 Simple examples
@chapter Simple examples

An example says more than thousand explanations, so in this chapter, I will 
present some advanced features of OrchestralLily using simple test cases. It 
should be easy to tell how to adapt the example in your own score...

@menu
* Figured Bass::
* Transposing music::
* Using custom staff definitions::
* Title pages::
* Table of contents::
* Equally-spaced markup columns::
* Using cue notes::
* Markup using header fields::
* Default instrument names::
* Non-standard staves::
* Using your custom context definitions::
@end menu


@node Figured Bass
@section Figured Bass

Figured bass can be either inserted like a staff (i.e. a direct child of a score 
or a staff group) or attached to a given staff (i.e. like a voice). These two 
cases are handled differently:

@lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/figuredbass.ly}



@node Transposing music
@section Transposing music

OrchestralLily supports transposing staves by defining the pitches in [Piece][Instrument]TransposeFrom and [Piece][Instrument]TransposeTo. The meaning of the these pitches is exactly the same as in ''\transpose frompitch topitch music''. In one of them is not defined, middle c' is used.

@lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/transpose.ly}



@node Using custom staff definitions
@section Using custom staff definitions

By default, OrchestralLily generates the whole staff definition from the music 
definition and the other settings. However, sometimes this is not desirable, 
because you want some special settings for one particular staff. In this case, 
you can simply define the staff yourself as ''[Piece][Instr]Staff'' and 
OrchestralLily will make use of this staff definition:

@lilypondfile[quote,verbatim]{../testsuite/staff-variable.ly}


@node Title pages
@section Title pages

OrchestralLily provides a definition ''\\titlePageMarkup''for a nice title page, you only have to assign it as  ''bookTitleMarkup'' in the header block. It uses fields from the header block and formats a title page suitable for a professionally published score:

@lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/titlepage.ly}




@node Table of contents
@section Table of contents

OrchestralLily automatically appends all piece headers to the internal table 
of TOC entries, you only have to display them using ''\markuplines \table-of-contents''. Also, you can insert your own
headers using ''\createHeadline''.

@lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/auto-toc.ly}



@node Equally-spaced markup columns
@section Equally-spaced markup columns

The ''\fill-line'' markup command generates markup in columns, but unfortunately,
the columns of different markups are not aligned with each other. If you want
to insert translations to your score, you'll have to use the ''\columns'' 
command instead, defined in OrchestralLily:

@lilypondfile[quote,verbatim,line-width=15\cm]{../testsuite/markup-columns.ly}




@node Using cue notes
@section Using cue notes

TODO

@node Markup using header fields
@section Markup using header fields

By default, markup in Lilypond does not have access to header fields (unless the
markup is assigned to a header variable and called from one of the formatting
functions defined in the header). OrchestralLily provides a function 
''\markupWithHeaders'', which formats a given markup and allows access to header 
fields from this markup.

@lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/markup-header-fields.ly}



@node Default instrument names
@section Default instrument names

OrchestralLily defines a lot of instrument names and clefs for the most 
common instrument abbreviations. In order not to clutter the default output,
these are defined in the include file settings_names.ly:

@lilypondfile[quote,verbatim,line-width=12\cm]{../testsuite/default-instrument-names.ly}



@node Non-standard staves
@section Non-standard staves

OrchestralLily also supports other staff types than the default. For example,
a DrumStaff and a RhythmicStaff can easily be generated by a proper score 
structure definition. As the voice of a DrumStaff needs to be a DrumVoice, 
we also have to set this voice type once in our definitions. 

The supported staff group types are: 
@itemize
@item "GrandStaff"
@item "PianoStaff"
@item "ChoirStaff"
@item "StaffGroup"
@item "InnerChoirStaff"
@item "InnerStaffGroup"
@item "ParallelMusic" and its equivalent "SimultaneousMusic".
@end itemize

The supported staff types are: 
@itemize 
@item "Staff"
@item "DrumStaff"
@item "RhythmicStaff"
@item "TabStaff"
@item "GregorianTranscriptionStaff"
@item "MensuralStaff"
@item "VaticanaStaff"
@item "PartCombinedStaff"
@item "ParallelVoicesStaff"
@item "FiguredBass"
@end itemize

The supported voice types are: 
@itemize
@item "Voice"
@item "CueVoice" (for smaller notes)
@item "DrumVoice"
@item "FiguredBass"
@item "GregorianTranscriptionVoice"
@item "NoteNames"
@item "TabVoice"
@item "VaticanaVoice"
@end itemize

@lilypondfile[quote,verbatim,line-width=10\cm]{../testsuite/non-standard-staff-voice-types.ly}


@node Using your custom context definitions
@section Using your custom context definitions

Suppose, you want to define your own staff group type called "SquareStaffGroup", which uses a rectangle 
for the bracket, and your own staff type "ThreeStaff", which uses only three 
staff lines. Also, we want to define our own voice type "RedVoice", which prints
all note heads in red and the stems in blue.
Of course, you could simply use @code{\set} and @code{\override} with the corresponding
properties somewhere inside your music definitions, but the cleaner way is to 
define your own contexts with these settings. The further advantage is then 
that you can OrchestralLily to use these context without much additional work:

@lilypondfile[quote,verbatim]{../testsuite/custom-contexts-handlers.ly}



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

@itemize
@item Proper rest combination for staves with two voices:
@lilypond
\include "../orchestrallily.ly"
\score {
  \context Staff << { c''4 r d'' r } \\ { f'4 r r r } >>
}
@end lilypond
@item modern-cautionary style for auto-accidentals. Cautionary accidentals are shown in brackets for one bar, after that no cautionary accidental is shown any more.
@lilypond
\include "../orchestrallily.ly"
\relative c' { cis dis es fis | d d f f | c d e f }
@end lilypond
@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

\paragraph "text"
\piece-titlepage "markup"
\orchestralScoreStructure '(structure list)
\orchestralVoiceTypes '(voice type list)
(oly:register_staff_type_handler type func)
(oly:register_voice_type_handler type func)
\setUseBook #t/#f
\setCreateMIDI #t/#f
\setCreatePDF #t/#f
\createScore #"Piece" '("Instrument"...)
\createNoCuesScore #"Piece" '("Instrument"...)
\createHeadline "text of the headline"

\setCue "cueString"
\setClefCue "cueString" clef
\namedCueDuring "CueVoice" #DIR "InstrCue" "Instr" music
\namedTransposedCueDuring "CueVoice" #DIR "InstrCue" "Instr" Transposition music
\cleffedCueDuring "CueVoice" #DIR "InstrCue" ClefCue "Instr" ClefInst Transposition music

\tempoMark '(padding . padding) #"Marktext"
\shiftDynamics #x #y

Dynamic text: \ffz, \pf, \sempp, \parenf, \parenp
Dynamic spanners: \setDim, \dim, \enddim, \setDecresc, \decresc, \enddecresc, \setCresc, \cresc, \endcresc

\newOrOldClef "new" "old" (depending on (ly:get-option 'old-clefs))
\filterArticulations music (removed all articulations, dynamics, text scripts and multi-measure text events)

\when-property symbol markup
\vspace #space

\markupWithHeader markupVariable
\columns markup-list

\newInstrument "instrumentName" (set cue name with "+")
\cueText (= \setCue !!!!!)

\scoreNumber nr

Settings:
\contentsTitle (title for the TOC)
\titlePageMarkup (book title as header)
\titleHeaderMarkup (book title as title page)
\titleScoreMarkup (score title as markup)

@menu
* createScore::
* createNoCuesScore::
* orchestralScoreStructure::
* setUseBook::
* setCreateMIDI::
* setCreatePDF::
* namedCueDuring::
* namedTransposedCueDuring::
* cleffedCueDuring::
* piece-title::
* markupWithHeaders::
* 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.
@example
\createScore #"PieceID" #'("Instrument1" "Instrument2" ...)
@end example
@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
@example
\createNoCuesScore #"PieceID" #'("Instrument1" "Instrument2" ...)
@end example
@itemize
@item Typical call: @code{\createNoCuesScore #"IIIChor" #'("T")}
@end itemize


@node orchestralScoreStructure
@unnumberedsec \orchestralScoreStructure

@example
\orchestralScoreStructure #'( ("ID" 'StaffType ("List" "Of" "Instruments"))... ))
@end example
  * Typical call: 
@example
\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"))
)
@end example
  * 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

@example
\setUseBook ##t
@end example
  * 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.
@example
\setCreateMIDI ##t
@end example
  * 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!).
@example
\setCreatePDF ##t
@end example
  * 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.
@example
\namedCueDuring #"QuoteName" #DIR #"cue instrument" #"original instrument"  music
@end example
  * 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}.
@example
\namedTransposedCueDuring #"QuoteName" #DIR #"cue instrument" #"original instrument" centralCNote music
@end example
  * 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.
@example
\cleffedCueDuring NameOfQuote CueDirection CueInstrument CueClef OriginalInstrument OriginalClef music
@end example
  * 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

@example
\piece-title pieceTitleString
@end example
FIXME

@node markupWithHeaders
@unnumberedsec \markupWithHeaders


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


@node Extending OrchestralLily
@chapter Extending OrchestralLily

To produce a staff group, staff or voice of a given type as specified in the 
score structure, OrchestralLily internally uses so-called handler functions. 
In particular, each known staff or group type is assigned to a scheme function
with the signature
@example
(staff_group_handler_function parser piece name type children)
@end example
where parser is the internal parser (needed by some of the subsequently called 
functions), piece is the name of the current score part (i.e. the first 
argument given in @code{\createScore}), name. type and children are the three
entried given in the score structure. Each handler generates either a staff 
music expression, a list of staff music expressions or an empty list.

Similarly, to produce a voice object (to be used as children of a staff), 
OrchestralLily internally uses voice type handler functions, which have a 
function signature of 
@example
(voice_handler_function parser piece name type)
@end example

To register a staff/group or a voice handler with OrchestralLily, there are two functions:
@example
#(oly:register_staff_type_handler type func)
#(oly:register_voice_type_handler type func)
@end example


If you want to add your own staff group, staff type or voice type, in most cases
you can use the internal functions provided by OrchestralLily: 
If you own type can be treated exactly like any other staff, 
group or voice, only with a different context name (i.e. because all the 
settings are in the @code{\layout} section and the staff/group/voice definition
itself does not need any special settings), you can simply re-use the internal
functions @code{oly:staff_group_handler}, @code{oly:staff_handler} or 
@code{oly:voice_handler}. For example
@example
#(oly:register_staff_type_handler "MyOwnGroup" oly:staff_group_handler)
\orchestral-score-structure #'(
  ("Group" "MyOwnGroup" ("InstrI" "InstrII" "InstrIII"))
)
\createScore #"Test" #'("group")
@end example
will produce the same as 
@example
\context MyOwnGroup="TestGroupStaff" << 
    \TestInstrIStaff 
    \TestInstrIIStaff 
    \TestInstrIIIStaff
>>
@end example
(notice that the only difference to the default case is that the context is now
MyOwnGroup instead of StaffGroup).

If your staves, groups or voices need special settings or should be created 
differently, of course, you'll have to implement your own handler function. 
As a guide, you can take a look at the implementation of the built-in handlers.



@node Frequently asked questions
@chapter Frequently asked questions

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

@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:
@example
#(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 '())
    )
  )
)
@end example
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 @uref{releases/orchestrallily_0.01.ly, 0.01 (2008-03-02)}: 
Initial Version
@item @uref{releases/orchestrallily_0.02.ly, 0.02 (2008-03-06)}: 
Added basic MIDI support (...MidiInstrument and \setCreateMIDI)
@item @uref{releases/orchestrallily_0.03.ly, 0.03 (2008-06-??)}:
@itemize
@item Add *TimeSignature variable, split settings for full/vocal/instrumental scores
@item [Piece][Instrument]TransposeTo, if set, now specifies the pitch where c' should be shown in the applicable voices.
@item interpreting markup using header fields
@item Automatically add score title to TOC
@item \createHeadline to create a headline and add it to the TOC
@item Adapted cresc spanners to new syntax
@item Nice title page (full page) and nicer title header (for instrumental scores)
@item Default clefs and Instrument names for lots of common abbreviations
@item Default cue names fo lots of instruments, function to show cue name
@item Default score numbers for each instrument
@item one can also specify voice types
@item parallel voices in one staff work,
@item Group types are given as strings
@item Adding handlers for new group/staff or voice types supported
@item Support for Drum staves/voices and figured bass
@end itemize
@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}), mess up the \voiceOne and \voiceTwo setting for some weird reason.
@item FIXME Add support for MIDI instrument names
@end itemize



@node Credits
@appendix Credits

Of course, a huge project like OrchestralLily would have never been possible
without the help of many others. In particular, I'm indebted to Han-Wen 
Niewenhuis and Jan Nieuwenhuizen, the two authors of Lilypond. The folks over at
the lilypond-user and lilypond-devel mailinglist were also of great importance
and helped me solve lots of problems I ran into. A particular thanks goes to
Nicolas Sceaux, who help me enourmously with his deeps insight into the Lilypond
internals and the tricks he provided on the mailinglist and in his own Lilypond
package for operas. Of course, all the authors of snippets posted at the LSR 
(Lilypond Snippet Repository) also contributed their share to the success of
OrchestralLily.

@node OrchestralLily index
@appendix OrchestralLily index

@printindex cp

@bye