=head1 NAME

LilyInput -  LilyPond input format -- Mudela 0.1

B<NOTICE:> this doc describes the I<new> input format, S<Mudela 0.1>.

=head1 DESCRIPTION

This document describes the the LilyPond input format, which is an
effective language for definining 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.

The design of Mudela has been (perfect past tense, hopefully)
an ongoing process, 
the most important criteria being:

=over 4

=item *

define the (musical) message of the composer as unambiguously as possible,

=item *

be intuitive, and easily readable 
(compared to, say, Musi*TeX input, or MIDI :-),

=item *

be writable in ASCII with a simple texteditor, yfte(TM).

=back

Other considerations were (and will be):

=over 4

=item *

be able to edit the layout 
without danger of changing the original music (Urtekst),

=item *

allow for adding different interpretations, again, 
without danger of changing the original,

=item *

easy to create a conductor's score, 
as well as the scores for all individual instruments,

=item *

provide simple musical manipulations, such as 
S<(i) extracting> a slice of music from a previously defined piece, 
S<(ii) extracting> only the rhythm from a piece of music, 
S<(iii) transposing>, etc.,

=item *

easy to comprehend to both programmers and others.

=back

Musical pieces could be

=over 5

=item *

Mahlerian orchestral scores,

=item *

piano pieces (Schubertian, Rachmaninovian),

=item *

pop songs (lyrics and chords),

=item *

gregorian chants,

=item *

Bach multivoice organ pieces,

=item *

short excerpts to be used in musicological publications.

=back


=head1 Overview

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

=head2 Comments

Line comments are introduced by a C<%>

=head2 Keywords

Keywords are preceded by a backslash "\".

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

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


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

=head1 Music

=head2 Simple mudela

Simple mudela is the most common type of music.  It consists of a list
of notes, chords, and commands.  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>):

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:

	as`4.*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 times 2/3. 

The default language for notenames is defined to be dutch,

	% 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
	A	% 110
	'A	% 55
	A'	% 220

These notenames along with duration is 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 parentheses do I<not> necesarrily nest, eg:

	[c8 e8(] [)g8 c'8]


Symbols which can be put at either side 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.

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.

The general form of a note is:

	post-requests de-octavate notename octavate duration pre-requests 

Notenames are just identifiers, and can be declared for any
language appropriate (see F<dutch.ini>). 


=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 Rhythms

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

=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{ melody }
		\staff{ accompany }
		\commands{ <score global commands> }
		\midi{ <midi definitions> }
		\paper{ <paper and layout definitions }
	}

=head2 Examples

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


=head2 Other

LilyPond first reads F<symbol.ini>, which contains declarations crucial
to proper operation of LilyPond (symbol tables, note names).

=head1 Decisions (Sat 1997-3-15, dommelpijpje no21)

=over 4

=item *

\keyword, bo difference notes vs. notenames,

=item *

{} hierachical, nest.,

=item *

<> chords,

=item *

drop staff (NOT)?,

=item *

melody = \melodic{ } vs. \melodic melody = { }

=item *

lexer mode switch by types: \lyric{ }, \melodic{ }, etc.,

=item *

octaves: low 'C C c c' c'' high; 'c' == c === "c-klein", comment: a '
' a . Which ' for which a? Now using a!'`.

=over 4

=item *

\meter{ 2/4 },

=item *

\grouping{ 2*8 3*8 },

=item *

\skip{ 2: 2*8 3*32 },

=item *

abbrev: [c2 c2]\noplet{1/2} (wat bout [c2 c2]1/2\noplet?),

=item *

abbrev: c4=16 (heu, =?),

=item *

plet === midi-note: c4*2/3; c4*385/384,

=back

=item *

drop \music,

=item *

\meter compulsory in Simple mudela,

=item *

++ concat

=item *

C<+> is  merge

=item *

	\transpose{ \from c \to g \melodic{ c d e } }
	\transpose{ \from c \to g melody } %!?

=item *

	\extract{ \from 2:3*4 \to 5 oboe }

=back