=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
+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>).
+[If anybody comes up with a better name, we'd gladly take this Gourlay
+already uses Musical Description Language, GSharp Score Definition
+Language. We're not being original here]
+
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. 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>):
-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
+files, 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"
+ \include "a_file.ly"
=head2 Comments
-Line comments are introduced by a C<%>
+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
+Keywords are preceded by a backslash: '\'. They contain alphabetic
characters only.
Identifiers in their normal form consist start with a alpha character,
aid the eye in reading, for chords the < and the > are used as
nesting braces.
+=head2 Constants
+
+Please note that -.5 is no Real.
+
+ "I am a string"
+ -1.2e3 % a real
+ 12 % an int
+
+
+
=head2 Identifiers
=head2 Hierarchical structures
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.
+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, 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
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.
+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' % 220
Cisis
-The rest is named
+Rests are named r or s
- r
+ r % print a rest
+ s % a "space" rest, nothing is printed.
These notenames along with duration are enough material to construct
simple melodies:
[c8 () d8 () e8 ]
-Please note that these two characters do I<not> necessarrily nest, eg:
+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!
+ [2/3 c8 c8 c8]1/1 % a triplet
+
+
+=head2 Slurs and Ties
+
+Ties connect the noteheads of adjecent notes. They are entered as follows:
+
+ a4 ~ a4
- [c8 e8(] [)g8 c'8]
+Slurs connect whole chords, and try to avoid crossing stems. They are
+entered as follows:
+ a4( )a4
-Symbols which can be put at either side of a staff are entered as follows:
+=head2 Scripts
+
+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:
\> % start decrescendo
\! % end crescendo/decrescendo
-=head2 General
+=head2 Text
+
+To accompany a note with a text (eg, "marcato"), you should say:
-The general form of a note is:
+ c_"marcato"
+ c^"marcato"
+ c-"marcato"
- post-requests de-octavate notename octavate duration pre-requests
+the c- construct chooses the default up/down direction.
-Notenames are just identifiers, and can be declared for any
-language appropriate (see F<dutch.ini>).
=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 start horizontal music by enclosing a sequence of notes with { and }
+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 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.
+
+=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.
A meter has this form:
- \meter { 3/4 }
+ \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 }
+ \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
% instantiate (=create tex, midi output) the score:
\score{
- \staff{ melody }
- \staff{ accompany }
- \commands{ <score global commands> }
+ \staff{ melodicregs melody }
+ \staff{ melodicregs accompany }
\midi{ <midi definitions> }
- \paper{ <paper and layout definitions }
+ \paper{ <paper and layout definitions> }
}
=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 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 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 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