Documentation/lilyinput.pod

   1 =head1 NAME
   2
   3 LilyInput -  LilyPond input format -- Mudela 0.1
   4
   5 B<NOTICE:> this doc describes the I<new> input format, S<Mudela 0.1>.
   6
   7 =head1 DESCRIPTION
   8
   9 This document describes the the LilyPond input format, which is an
  10 effective language for definining music.  We call this language
  11 (rather arrogantly) The Musical Definition Language (S<Mudela 0.1>).
  12
  13 The first aim of Mudela is to define a piece of music,
  14 being complete from both from a musical typesetting,
  15 as from a musical performing point of view.
  16
  17 The design of Mudela has been (perfect past tense, hopefully)
  18 an ongoing process,
  19 the most important criteria being:
  20
  21 =over 4
  22
  23 =item *
  24
  25 define the (musical) message of the composer as unambiguously as possible,
  26
  27 =item *
  28
  29 be intuitive, and easily readable
  30 (compared to, say, Musi*TeX input, or MIDI :-),
  31
  32 =item *
  33
  34 be writable in ASCII with a simple texteditor, yfte(TM).
  35
  36 =back
  37
  38 Other considerations were (and will be):
  39
  40 =over 4
  41
  42 =item *
  43
  44 be able to edit the layout
  45 without danger of changing the original music (Urtekst),
  46
  47 =item *
  48
  49 allow for adding different interpretations, again,
  50 without danger of changing the original,
  51
  52 =item *
  53
  54 easy to create a conductor's score,
  55 as well as the scores for all individual instruments,
  56
  57 =item *
  58
  59 provide simple musical manipulations, such as
  60 S<(i) extracting> a slice of music from a previously defined piece,
  61 S<(ii) extracting> only the rhythm from a piece of music,
  62 S<(iii) transposing>, etc.,
  63
  64 =item *
  65
  66 easy to comprehend to both programmers and others.
  67
  68 =back
  69
  70 Musical pieces could be
  71
  72 =over 5
  73
  74 =item *
  75
  76 Mahlerian orchestral scores,
  77
  78 =item *
  79
  80 piano pieces (Schubertian, Rachmaninovian),
  81
  82 =item *
  83
  84 pop songs (lyrics and chords),
  85
  86 =item *
  87
  88 gregorian chants,
  89
  90 =item *
  91
  92 Bach multivoice organ pieces,
  93
  94 =item *
  95
  96 short excerpts to be used in musicological publications.
  97
  98 =back
  99
 100
 101 =head1 Overview
 102
 103 The Musical Definition Language (Mudela) S<version 0.1>,
 104 has a logical structure,
 105 making use of typing and naming (using identifiers),
 106 that allows for flexible input, and definition reuse.
 107
 108 =head2 Comments
 109
 110 Line comments are introduced by a C<%>
 111
 112 =head2 Keywords
 113
 114 Keywords are preceded by a backslash "\".
 115
 116 The actual musical part of Mudela that defines a melody, is known as
 117 I<simple mudela>.
 118
 119 Mudela uses the brace (C<{> and C<}>) for hierarchical structures. To
 120 aid the eye in reading, for chords we have used the C<<> and the C<>>
 121 as nesting braces.
 122
 123
 124 The general structure consists of declarations:
 125
 126         IDENTIFIER = \TYPE{
 127                 <type specific data>
 128         }
 129
 130 and instantiations:
 131
 132         \TYPE{ <type specific data> }
 133
 134 (Currently, C<\score> is the only type that can be instantiated
 135 at top level. Currently declarations can only be done at top level)
 136
 137 Most instantiations that use an IDENTIFIER are specified as follows:
 138
 139         \TYPE { IDENTIFIER [...] }
 140
 141 Some exceptions on this rule have been made to prevent inputting
 142 Mudela becoming tedious
 143
 144 =head1 Music
 145
 146 =head2 Simple mudela
 147
 148 Simple mudela is the most common type of music.  It consists of a list
 149 of notes, chords, and commands.  The below included for explanatory
 150 purposes only (i.e., for a complete and up-to-date definition, see
 151 F<lily/parser.y> and F<lily/lexer.l>):
 152
 153 Simple mudela basically is a sequence of the notes you want to
 154 enter.
 155
 156         a'4     % dutch names
 157
 158 is a A-1 pitched quaver. The ' signifies an octave change.
 159 A-1 is 440 Hz concert-pitch. C<c'> is also known as the central
 160 c. More examples:
 161
 162         a`      % 110
 163         a       % 220
 164         a'      % 440
 165         a''     % 880
 166
 167 another example:
 168
 169         as`4.*2/3
 170
 171 This is an A flat, (just below 110 Hz concert-pitch). The C<*2/3>
 172 signifies that this note is part of a triplet (3 in stead of 2). The
 173 duration is one and a half quaver times 2/3.
 174
 175 The default language for notenames is defined to be dutch,
 176
 177         % double sharp
 178         cisis disis eisis fisis gisis aisis bisis
 179         % sharps
 180         cis dis eis fis gis ais bis
 181         % naturals
 182         c d e f g a b
 183         % flats
 184         ces des es fes ges as bes
 185         % double flats
 186         ceses deses eses feses geses ases beses
 187
 188 The standard notenames also have uppercase versions, which octavate
 189 down:
 190
 191         a       % 220
 192         A       % 110
 193         'A      % 55
 194         A'      % 220
 195
 196 These notenames along with duration is enough material to construct
 197 simple melodies:
 198
 199         c4 c4 g4 g4 a4 a4 g2
 200         f4 f4 e4 e4 d4 d4 c2
 201
 202 Music is able to express more. generally speaking, the other
 203 'features' are either connected between notes (slurs, beams: spanning
 204 requests) or attached to notes (eg. accents). The former are
 205 implemented as START and STOP stop features and then attached to the note.
 206
 207         []      START/STOP a beam
 208         ()      START/STOP a slur
 209
 210
 211 example:
 212
 213         [c8 () d8 () e8 ]
 214
 215 Please note that these two parentheses do I<not> necesarrily nest, eg:
 216
 217         [c8 e8(] [)g8 c'8]
 218
 219
 220 Symbols which can be put at either side of a staff are entered as follows:
 221
 222         a-^     % marcato, direction: default
 223         a^-     % portato, direction: above note
 224         a_.     % staccato, direction: below note
 225         a^\script { "symbolindex"  . . . } % see script.ini for details.
 226
 227 Dynamics can be put after the notename:
 228
 229         a4 \dynamic { 0 } % 0 = fff, 7 = ppp
 230
 231 Mudela defines the following dynamic identifiers:
 232
 233         ppp pp p mp mf df ff fff        % df iso f, f is a notename.
 234
 235 The general form of a note is:
 236
 237         post-requests de-octavate notename octavate duration pre-requests
 238
 239 Notenames are just identifiers, and can be declared for any
 240 language appropriate (see F<dutch.ini>).
 241
 242
 243 =head2 Lyrics
 244
 245 Lyrics in Mudela resemble Simple mudela a lot,
 246 with notes substituted by text.
 247 All syllables are entered separately, separated by whitespace
 248 ("Twin-4 kle4 twin-4 kle4 ... ").
 249 Two syllables or words that compose a single duration entry
 250 are bound together using an underscore ("He_could4 not4").
 251
 252 =head2 Rhythms
 253
 254 Rhythms in Mudela are entered identical to Simple mudela.
 255 The melodic part of the information is ignored.
 256
 257 =head1 STRUCTURE
 258
 259 In concrete, a piece of Mudela has the following structure:
 260
 261         % declare pieces of music:
 262         melody = \music{ <simple mudela> }
 263         accompany = \music{ <simple mudela> }
 264
 265         % instantiate (=create tex, midi output) the score:
 266         \score{
 267                 \staff{ melody }
 268                 \staff{ accompany }
 269                 \commands{ <score global commands> }
 270                 \midi{ <midi definitions> }
 271                 \paper{ <paper and layout definitions }
 272         }
 273
 274 =head2 Examples
 275
 276 Examples are included with the LilyPond distribution. For the sake of
 277 maintenance no long examples are included in this document.
 278
 279
 280 =head2 Other
 281
 282 LilyPond first reads F<symbol.ini>, which contains declarations crucial
 283 to proper operation of LilyPond (symbol tables, note names).
 284
 285 =head1 Decisions (Sat 1997-3-15, dommelpijpje no21)
 286
 287 =over 4
 288
 289 =item *
 290
 291 \keyword, bo difference notes vs. notenames,
 292
 293 =item *
 294
 295 {} hierachical, nest.,
 296
 297 =item *
 298
 299 <> chords,
 300
 301 =item *
 302
 303 drop staff (NOT)?,
 304
 305 =item *
 306
 307 melody = \melodic{ } vs. \melodic melody = { }
 308
 309 =item *
 310
 311 lexer mode switch by types: \lyric{ }, \melodic{ }, etc.,
 312
 313 =item *
 314
 315 octaves: low 'C C c c' c'' high; 'c' == c === "c-klein", comment: a '
 316 ' a . Which ' for which a? Now using a!'`.
 317
 318 =over 4
 319
 320 =item *
 321
 322 \meter{ 2/4 },
 323
 324 =item *
 325
 326 \grouping{ 2*8 3*8 },
 327
 328 =item *
 329
 330 \skip{ 2: 2*8 3*32 },
 331
 332 =item *
 333
 334 abbrev: [c2 c2]\noplet{1/2} (wat bout [c2 c2]1/2\noplet?),
 335
 336 =item *
 337
 338 abbrev: c4=16 (heu, =?),
 339
 340 =item *
 341
 342 plet === midi-note: c4*2/3; c4*385/384,
 343
 344 =back
 345
 346 =item *
 347
 348 drop \music,
 349
 350 =item *
 351
 352 \meter compulsory in Simple mudela,
 353
 354 =item *
 355
 356 ++ concat
 357
 358 =item *
 359
 360 C<+> is  merge
 361
 362 =item *
 363
 364         \transpose{ \from c \to g \melodic{ c d e } }
 365         \transpose{ \from c \to g melody } %!?
 366
 367 =item *
 368
 369         \extract{ \from 2:3*4 \to 5 oboe }
 370
 371 =back
 372