=head1 NAME
-LilyInput - LilyPond input format
+LilyInput - LilyPond input format -- Mudela 0.1
+
+B<NOTICE:> this doc describes the I<new> input format, S<Mudela 0.1>.
=head1 DESCRIPTION
-This page globally documents the the LilyPond input format, mudela.
-To get a better impression, please study some examples.
+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>).
-=head2 Overview
+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.
-General format of a construct:
+The design of Mudela has been (perfect past tense, hopefully)
+an ongoing process,
+the most important criteria being:
- BLOCKNAME { <info to go with this block> }
+=over 4
-Some types allow declarations:
+=item *
- IDENTIFIER = BLOCKNAME {
- <info to go with this block>
- }
+define the (musical) message of the composer as unambiguously as possible,
- ..
+=item *
- BLOCKNAME {
- IDENTIFIER
- ...
- }
+be intuitive, and easily readable
+(compared to, say, Musi*TeX input, or MIDI :-),
+=item *
+
+be writable in ASCII with a simple texteditor, yfte(TM).
-In musicmode, eg,
+=back
- ''!c8.-"text"_v
+Other considerations were (and will be):
-and in lyricmode, eg,
+=over 4
- Twin- kle, twin- kle lit- tle star,2
+=item *
-a lot of characters parse differently
-than in "command" mode, eg,
+be able to edit the layout
+without danger of changing the original music (Urtext),
- identifier = score { .. }
+=item *
-So you have to signal this to the tokenizer. This is done with
-'$'. '$' is a delimiter, which used by the tokenizer only. The same
-goes for lyrics, it has a '@' delimiter.
+allow for adding different interpretations, again,
+without danger of changing the original,
=item *
-musicmode: The brace still is used to group grammatical groups.
+
+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 *
-musicmode: "word" are preceded by a '\' (backslash)
-This means you can write some stuff in a zillion ways:
+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 *
-=item 1.
- $\var = \blockname { ... } $
+short excerpts to be used in musicological publications.
-=item 2.
- var = blockname { $ ... $ }
+=back
-=item 3.
- var = $ $ $\blockname { ... $ }
+
+=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.
+
+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>):
+
+=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
-Not really crystallized; you can use '#' or '%' as line comment
+Line comments are introduced by a C<%>
-=head2 other
+=head2 Words
-LilyPond first reads 'symbol.ini', which contains declarations crucial
-to proper operation of LilyPond (symbol tables, note names).
+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:
+
+ $Id_with###@weird92chars =
+
+=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
+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, string
-This language looks a lot like Rayce's which in turn owes a lot to the
-POVRay raytracer. Now, I know, musictypesetting and Raytracing do not
-necessarily require the same input format, but I was just to lazy to
-make up a new and/or better input format. Suggestions appreciated.
+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>.
+In Note mode, a word is looked up in the following order:
+
+ word identifier, string
+ \word keyword, 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, 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<_>
+
+=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 ' 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:
+
+ `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.
+
+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
+ Cisis
+
+The rest is named
+
+ r
+
+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 characters do I<not> necessarrily 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).
projects / lilypond.git / blobdiff