[lilypond.git] / Documentation / mudela.pod

=head1 NAME

Mudela -  GNU LilyPond input format 0.1

=head1 DESCRIPTION

This document describes the the GNU LilyPond input format, which is an
effective language for defining music.  We call this language
(rather arrogantly) The Musical Definition Language (S<Mudela 0.1>).

The first aim of Mudela is to define a piece of music, 
being complete from both from a musical typesetting, 
as from a musical performing point of view.


=head1 Overview

The Musical Definition Language (Mudela) S<version 2>, has a logical
structure, making use of typing and naming (using identifiers), that
allows for flexible input, and definition reuse. See MANIFESTO for
reasons and design considerations.

The below included for explanatory purposes only (i.e., for a complete
and up-to-date definition, see F<lily/parser.y> and F<lily/lexer.l>):

As a related note, you should take a look at the examples and the init
file, as this document does not cover every aspect of mudela yet, and
may be out of date.

=head2 Files

The de-facto extension of Mudela is F<.ly>. Files may be included by
entering C<include> at the start of a line:

        \include "a_file.ly"

=head2 Comments

Line comments are introduced by a C<%>. Block comments are delimited
by C<%{> and C<%}>. They do not nest.

=head2 Versions

Occasionally, small changes in syntax across different versions of
Mudela might give syntax errors. To warn you about possible
incompatibilities, you can specify the Mudela version for which the
inputfile was written,

        \version "0.0.50";

A perl-script which tries to convert to newer versions
(F<convert-mudela>) is included in the LilyPond distribution.

=head2 Words

Keywords are preceded by a backslash "\". They contain alphabetic
characters only. 

Identifiers in their normal form consist start with a alpha character,
followed by alpha-numerics. Identifiers can contain any characters
(except whitespace, C<$> and C<%>), if you use this construct:

        $i'm_a_weird###identifier

(which is the identifier with the name
C<i'm_a_weird###identifier> ). C<$> Takes any sequence of
characters which are not whitespace, C<$> and C<%>.

        \$i'm_a_weird###escaped_word

=head2 Nesting characters

Mudela uses the brace (C<{> and C<}>) for hierarchical structures. To
aid the eye in reading, for chords the < and the > are used as
nesting braces.

=head2 Identifiers

=head2 Hierarchical structures

The general structure consists of declarations:

        IDENTIFIER = \TYPE{
                <type specific data>
        }

and instantiations:

        \TYPE{ <type specific data> }

(Currently, C<\score> is the only type that can be instantiated
at top level. Currently declarations can only be done at top level)

Most instantiations that use an IDENTIFIER are specified as follows:

        \TYPE{ IDENTIFIER [...] }

Some exceptions on this rule have been made to prevent inputting
Mudela becoming tedious


=head2 Simple mudela

The actual musical part of Mudela that defines a melody, is known as 
I<simple mudela>. 

Simple mudela is the most common type of music.  It consists of a list
of notes or lyrics, chords, and commands.

=head2 Modes:

To simplify different aspects of music definition (entering the notes
and manipulating them) Mudela has a number of different input "modes":

=over 4

=item Normal mode

At the start of parsing, Mudela assumes normal mode.
In Normal mode, a word is looked up in the following order:

        word    identifier, string
        \word   keyword, identifier, string

In normalmode, a word is assumed to start with an alphabetic
character, followed by alpha-numeric characters.

=item Note mode

Note mode (and thus Simple mudela) is introduced by the keyword C<\melodic>.
In Note mode, a word is looked up in the following order:

        word    notename, string
        \word   keyword, identifier, string

In Note mode a word is considered to have alphabetic characters only.

=item Lyric mode

Lyrics mode (and thus Simple mudela)  is introduced by the keyword C<\lyrics>.

In Lyrics mode, a word is looked up in the following order:

        word    string
        \word   keyword, identifier, string

In Lyric mode every sequence of non-digit and non-white characters
starting with an alphabetic character or the '_'is considered a word.

        a&@&@&TSI|{[    % a word
        1THtrhortho     % not a "word"
        Leise Fl\"u\ss{}teren meine Sapfe       % 4 words
        _ _ _ _         % 4 words: 4 spaces

=back

These modes are of a lexical nature. Normal and Note mode largely
resemble each other, save the possibility of entering Reals, 
meaning of C<_> and the resolution of words

=head2 Notes

Simple mudela basically is a sequence of the notes you want to
enter. 

        a'4     % dutch names

is a A-1 pitched quaver. The ' signifies an octave change.  A-1 is 440
Hz concert-pitch. C<c'> is also known as the central c. More examples:

        'a      % 110
        a       % 220
        a'      % 440
        a''     % 880

another example:

        'as4.*2/3

This is an A flat, (just below 110 Hz concert-pitch). The C<*2/3>
signifies that this note is part of a triplet (3 in stead of 2). The
duration is one and a half quaver (C<4.>) times 2/3.


Notenames are just a special kind of identifiers, and can be declared
for any language appropriate (see F<dutch.ini>).  The default language
for notenames is defined to be dutch. In dutch, the notenames are
a,b,c,d,e,f and g. Sharps are formed by adding the extension "is",
flats by adding "es"

        % double sharp
        cisis disis eisis fisis gisis aisis bisis
        % sharps
        cis dis eis fis gis ais bis
        % naturals
        c d e f g a b 
        % flats
        ces des es fes ges as bes
        % double flats
        ceses deses eses feses geses ases beses

The standard notenames also have uppercase versions, which octavate
down:

        a       % 220 concert-pitch
        A       % 110
        'A      % 55
        A'      % 220
        Cisis

Rests are named r or s

        r       % print a rest
        s       % a "space" rest, nothing is printed.

These notenames along with duration are enough material to construct
simple melodies:

        c4 c4 g4 g4 a4 a4 g2
        f4 f4 e4 e4 d4 d4 c2

Music is able to express more. generally speaking, the other
'features' are either connected between notes (slurs, beams: spanning
requests) or attached to notes (eg. accents). The former are
implemented as START and STOP stop features and then attached to the note.

        []      START/STOP a beam
        ()      START/STOP a slur


example: 

        [c8 () d8 () e8 ]

Please note that these two characters do I<not> necessarrily nest,
they should attached to the note C<[ {c4 c4} ]> will generate a parse
error for this reason. 

        [c8 e8(] [)g8 <c'8] e'8>
                                % NO nesting!
        [c8 c8 c8]2/3           % a triplet

Symbols which can be put at either side (above or below) of a staff
are entered as follows:

        a-^     % marcato, direction: default
        a^-     % portato, direction: above note
        a_.     % staccato, direction: below note
        a^\script { "symbolindex"  . . . } % see script.ini for details.
        a^\fermata      % predefined identifier

Dynamics can be put after the notename:

        a4 \dynamic { 0 } % 0 = fff, 7 = ppp

Mudela defines the following dynamic identifiers:

        ppp pp p mp mf df ff fff        % df iso f, f is a notename.

and the following abbreviations:

        \<      %start crescendo
        \>      % start decrescendo
        \!      % end crescendo/decrescendo

=head2 Text

To accompany a note with a text (eg, "marcato"), you should say: 

        c_"marcato"
        c^"marcato"
        c-"marcato"

the c- construct chooses the default up/down direction.




=head2 Defaults

If omit the duration of a, a default value is substituted. For this
default value, there are two modes:

=over 4

=item 1

Use the last duration explicitly entered

=item 2

Use the explicitly set "default duration"

=back

Thus the following inputs are  equivalent

        c4 c4 c16 c16 c16 s16 c4 c16

        \duration { "last" }
        c4 c c16 c c c c4 c16

        \duration { 4 }
        c c c16 c16 c16 c16 c c16

        \duration { 16 }
        c4 c4 c c c c c4 

If you are typing music which does not lie in the "small" and "large"
octave, you can prevent having to type C<'> all the time by using the
C<\octave> command: These two lines have the same pitch.

        c'' d'' e''     
        \octave{c''} c d e

By default the setting of C<\octave> is 0.

=head2 Lyrics

Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
by text. 

All syllables are entered separately, separated by whitespace 

        Twin-4 kle4 twin-4 kle4 ... 

Two syllables or words that compose a single
duration entry are bound together using an underscore 

        He_could4 not4

=head2  Music direction

Mudela reads left to right, but you can still stack voices and
Voice_elements which are produced in two directions: horizontal
(voice like) and vertical (chord like)

A sequence of notes (horizontal) is called simple horizontal, eg

        c4 c4 g4 g4


You can also glue two pieces of simple horizontal music together with the
concatenation operator:

        horOne = \melodic { c c g g }
        horTwo = \melodic { a a g2 }
        twinkle = \melodic { \horOne ++ \horTwo }

If you enclose simple horizontal music in braces ( { } ), then you get
horizontal music:

        { c c g g a a g2 }      % twinkle twinkle

You can start vertical music (a "chord") by enclosing a sequence of
notes with < and >. Example:

        <a cis e'>      % a-major chord

You can also put vertical music inside horizontal music:

        { c <c e> <c e g> <c e g c'> }  % 4 increasing chords

And vice versa

        < \multivoice
          {c c g g a a g2}              
          {r2  r2  c c g g a a g2} >    % a canon

The duration of a chord equals the union of the durations of each of
its elements.  The C<\multivoice> is a construct which is explained
below.


=head2 Transposition

You can transpose horizontal music in the following way:

        
        \melodic {
                \meter 2/4;
                ++
                \transpose { 
                        d               % from c to the d that's one octave down 
                        { e4 f4 }       % the horizontal music
                } ++ g4
        }

The result is, as you can see, again simple horizontal music.


=head2 Voicegroups

If more than one "voice" is in a staff, then you have the option of
putting the different voices into so called voicegroups: members of
the same voicegroup share certain characteristics, among others:

        - dynamics
        - text
        - beams and stems
        - scripts

For the actual list, see the init file F<register.ini>

Putting different musical lines in to the same voicegroup effectively
makes LilyPond try to form chords of all those lines. Putting
different musical lines in to different voicegroups effectively makes
LilyPond try to set those lines as independently as possible. 

You can set the voicegroup of a voice with the command C<\group>, e.g.,
        
        oboeI = \melodic { 
                \group "oboes"; 
                [e8 f8
                \group "+solo";
                [g16 a16 g16 fis16]
                \group "-";
                g8 f8
        }
        oboeII = \melodic { \group "oboes";
                c8 d8]
                e4
                e8 d8
        }
        ///     ...

        \staff { 
                melodicregs \melodic{ oboeI }
                \melodic { oboeII}
        }

In this example, the two oboe voices share one staff and are initially
in the voicegroup called "oboes". They will share beams, dynamics etc.
After two quavers, oboeI "pushes" its group: a new voicegroup is
created, called "oboes+solo". The C<\group "-"> command makes the
voice enter "oboes" again.

Please do note that [] are voicegroup wide; the previous input is
valid: the beam, started in oboeI, voicegroup "oboes" is also ended in
voicegroup "oboes", albeit not in oboeI but oboeII

This concept may seem contorted, but it allows you to set the separate
oboe parts without changing the C<oboeI> and C<oboeII> (assuming that
you edit the [] in the example.)

The construct

        < { .... } {......} >

makes a chord (all horizontal parts are in the same voicegroup). The construct

        < \multivoice { ....} { .... } >

creates horizontal parts which behave independently. You will have to
set voicegroup features by hand (\stem and \hshift. See examples)




=head2 Rhythms

Rhythms in Mudela are entered identical to Simple mudela.
The melodic part of the information is ignored.

=head2 Durations

A duration always starts with the duration type (1,2,4 etc), and then
any optional multipliers/dots

=head2 Meters/groupings

A meter has this form:

        \meter 3/4 ;

Rhythmic grouping is  a concept closely associated with this. For
example, in a 5/8 meter, the counts are grouped 2+3. In mudela this is
entered as

        \grouping  8*2 8*3 ;

You can start the piece with a partial measure, the command takes the
same syntax as grouping: 

        \partial 16*3 4;

Make the piece start with a partial measure [transl?]  lasting 1 3/4
quaver.

These commands are also "voice elements", and constitute simple mudela
(consisting of stuff with duration 0).

=head1 STRUCTURE

In concrete, a piece of Mudela has the following structure:

        % declare pieces of music:
        melody = \music{ <simple mudela> }
        accompany = \music{ <simple mudela> }

        % instantiate (=create tex, midi output) the score:
        \score{ 
                \staff{ melodicregs melody }
                \staff{ melodicregs accompany }
                \midi{ <midi definitions> }
                \paper{ <paper and layout definitions> }
        }

=head2 Examples

Examples are included with the GNU LilyPond distribution. For the sake of
maintenance no long examples are included in this document.


=head1 INTERNALS

This chapter deals with the internals of Mudela. In the end Mudela
converted to Voice, which contain Voice_elements which (in turn)
contain Requests. The former 2 types are basically containers (lists).
Consider the following simple mudela

        \music { c4 <e4 g4> }

After the parsing, this is converted to: (from the debug output)

        Voice { start: 0
          voice_element { dur :1/4
            Stem_req {duration { 4}}
            Note_req {notename: 0 acc: 0 oct: -1 
              duration { 4}}
            Group_change_req {}
            }
          voice_element { dur :0
            Terminate_voice_req {}
            }
          }

        Voice { start: 1/4
          voice_element { dur :1/4
            Stem_req {duration { 4}}
            Note_req {notename: 2 acc: 0 oct: -1 
              duration { 4}}
            Group_change_req {}
            }
          voice_element { dur :0
            Terminate_voice_req {}
            }
          }

        Voice { start: 1/4
          voice_element { dur :1/4
            Stem_req {duration { 4}}
            Note_req {notename: 4 acc: 0 oct: -1 
              duration { 4}}
            Group_change_req {}
            }
          voice_element { dur :0
            Terminate_voice_req {}
            }
          }


=head2 Requests

As you can see, most information is stored in the form of a request. 
In music typesetting, the user might want to cram a lot more symbols
on the paper than actually fits. To reflect this idea (the user asks
more than we can do), the container for this data is called Request.

A request is done to the C<Staff> which contains the
C<Voice_element>. The staff decides whether to to honor the request,
ignore it, or merge it with other requests. Merging of requests is
preferably done with other requests done by members of the same
voicegroups (beams, brackets, stems)

=head2 Staff

The staff is a simple container (containing Voices). The so-called
"registers" determine the characteristics of the Staff. At this time,
LilyPond supports the following personalities:

=over 4

=item melodicregs

This makes the staff into a single five line melodic staff.

=item lyricregs

This makes the staff into a staff which will only set Lyric_requests.

=back


=head1 HISTORY


This language has a number of roots. First and foremost, GNU LilyPond's
predecessor mpp was the inspiration of simple Mudela.  Secondly, the
hierarchical structure looks a lot like Rayce's (Rayce is a raytracer
that I've written as a hobby project. ), which in turn owes a lot to
POVRay.

Now, we know, musictypesetting and raytracing do not necessarily
require the same input format, and we know that a lot more ways exist
to convert music to ASCII, but we did give this language some
thoughts. As always suggestions are appreciated.