=head1 NAME
-Mudela - LilyPond input format 0.1
+Mudela - GNU LilyPond input format 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 2>).
+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.
-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 (Urtext),
-
-=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 2>,
-has a logical structure,
-making use of typing and naming (using identifiers),
-that allows for flexible input, and definition reuse.
+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.
-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>):
+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.
=head2 Files
Line comments are introduced by a C<%>
+=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";
+
=head2 Words
Keywords are preceded by a backslash "\". They contain alphabetic
followed by alpha-numerics. Identifiers can contain any characters
(except whitespace, C<$> and C<%>), if you use this construct:
- $Id_with###@weird92chars =
+ $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 C<<> and the C<>> are used as
+aid the eye in reading, for chords the < and the > are used as
nesting braces.
=head2 Identifiers
Most instantiations that use an IDENTIFIER are specified as follows:
- \TYPE { IDENTIFIER [...] }
+ \TYPE{ IDENTIFIER [...] }
Some exceptions on this rule have been made to prevent inputting
Mudela becoming tedious
In Normal mode, a word is looked up in the following order:
word identifier, string
- \word keyword, 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<\music>.
+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 identifier, string
- \word keyword, string
+ word notename, string
+ \word keyword, identifier, string
In Note mode a word is considered to have alphabetic characters only.
In Lyrics mode, a word is looked up in the following order:
word string
- \word keyword, string
+ \word keyword, identifier, string
In Lyric mode every sequence of non-digit and non-white characters
starting with an alphabetic character is considered a word.
=back
These modes are of a lexical nature. Normal and Note mode largely
-resemble each other, save the possibility of entering Reals, and
-meaning of C<_>
+resemble each other, save the possibility of entering Reals,
+meaning of C<_> and the resolution of words
=head2 Notes
a'4 % dutch names
-is a A-1 pitched quaver. The ' as well as the ' signify an octave change.
-A-1 is 440 Hz concert-pitch. C<c'> is also known as the central
-c. More examples:
+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
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.
-The default language for notenames is defined to be dutch,
+
+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
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:
ppp pp p mp mf df ff fff % df iso f, f is a notename.
-The general form of a note is:
+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.
+
- 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 Defaults
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 notes have the same pitch.
+C<\octave> command: These two lines have the same pitch.
- c'' \octave{2} c
+ c'' d'' e''
+ \octave{c''} c d e
By default the setting of C<\octave> is 0.
=head2 Music direction
-Mudela reads left to right, but LilyPond can stack voices and
+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)
You can also put vertical music inside horizontal music:
- { c < c e > <c e g> <c e g c'> } % 4 increasing chords
+ { c <c e> <c e g> <c e g c'> } % 4 increasing chords
And vice versa
its elements. The C<\multivoice> is a construct which is explained
below.
+You can also glue two horizontal pieces music together with
+concatenation operator:
+
+ \horOne = \melodic { c c g g }
+ \horTwo = \melodic { a a g2 }
+ \twinkle = \melodic { \horOne ++ \horTwo }
+
+=head2 Transposition
+
+You can transpose horizontal music in the following way:
+
+ \transpose { d % from c to d that's one octave up.
+ { e4 f4 } % the horizontal music
+ }
+
=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 }
+
+
+
=head1 STRUCTURE
In concrete, a piece of Mudela has the following structure:
=head2 Examples
-Examples are included with the LilyPond distribution. For the sake of
+Examples are included with the GNU LilyPond distribution. For the sake of
maintenance no long examples are included in this document.
-=head2 Requests
+=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 Voice
-=head2 Voice_element
+=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.
-=head2 Voice groups
+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 Other
-LilyPond first reads F<symbol.ini>, which contains declarations crucial
-to proper operation of LilyPond (symbol tables, note names).
=head1 HISTORY
-This language has a number of roots. First and foremost, LilyPond's
+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
projects / lilypond.git / blobdiff