=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).
+
+=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 *
-In musicmode, eg,
+Mahlerian orchestral scores,
- ''!c8.-"text"_v
+=item *
-and in lyricmode, eg,
+piano pieces (Schubertian, Rachmaninovian),
- Twin- kle, twin- kle lit- tle star,2
+=item *
-a lot of characters parse differently
-than in "command" mode, eg,
+pop songs (lyrics and chords),
- 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.
+gregorian chants,
=item *
-musicmode: The brace still is used to group grammatical groups.
+
+Bach multivoice organ pieces,
=item *
-musicmode: "word" are preceded by a '\' (backslash)
-This means you can write some stuff in a zillion ways:
+short excerpts to be used in musicological publications.
+
+=back
-=item 1.
- $\var = \blockname { ... } $
-=item 2.
- var = blockname { $ ... $ }
+=head1 Overview
-=item 3.
- var = $ $ $\blockname { ... $ }
+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
-Not really crystallized; you can use '#' or '%' as line comment
+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.
-=head2 other
+The general form of a note is:
-LilyPond first reads 'symbol.ini', which contains declarations crucial
+ 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).
-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.
+=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
+
projects / lilypond.git / blobdiff