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 (Urtext),
  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 The below included for explanatory
 109 purposes only (i.e., for a complete and up-to-date definition, see
 110 F<lily/parser.y> and F<lily/lexer.l>):
 111
 112 =head2 Files
 113
 114 The de-facto extension of Mudela is F<.ly>. Files may be included by
 115 entering C<include> at the start of a line:
 116
 117         include "a_file.ly"
 118
 119 =head2 Comments
 120
 121 Line comments are introduced by a C<%>
 122
 123 =head2 Words
 124
 125 Keywords are preceded by a backslash "\". They contain alphabetic
 126 characters only.
 127
 128 Identifiers in their normal form consist start with a alpha character,
 129 followed by alpha-numerics. Identifiers can contain any characters
 130 (except whitespace, C<$> and C<%>), if you use this construct:
 131
 132         $Id_with###@weird92chars =
 133
 134 =head2 Nesting characters
 135
 136 Mudela uses the brace (C<{> and C<}>) for hierarchical structures. To
 137 aid the eye in reading, for chords the C<<> and the C<>> are used as
 138 nesting braces.
 139
 140 =head2 Identifiers
 141
 142 =head2 Hierarchical structures
 143
 144 The general structure consists of declarations:
 145
 146         IDENTIFIER = \TYPE{
 147                 <type specific data>
 148         }
 149
 150 and instantiations:
 151
 152         \TYPE{ <type specific data> }
 153
 154 (Currently, C<\score> is the only type that can be instantiated
 155 at top level. Currently declarations can only be done at top level)
 156
 157 Most instantiations that use an IDENTIFIER are specified as follows:
 158
 159         \TYPE { IDENTIFIER [...] }
 160
 161 Some exceptions on this rule have been made to prevent inputting
 162 Mudela becoming tedious
 163
 164
 165 =head2 Simple mudela
 166
 167 The actual musical part of Mudela that defines a melody, is known as
 168 I<simple mudela>.
 169
 170 Simple mudela is the most common type of music.  It consists of a list
 171 of notes or lyrics, chords, and commands.
 172
 173 =head2 Modes:
 174
 175 To simplify different aspects of music definition (entering the notes
 176 and manipulating them) Mudela has a number of different input "modes":
 177
 178 =over 4
 179
 180 =item Normal mode
 181
 182 At the start of parsing, Mudela assumes normal mode.
 183 In Normal mode, a word is looked up in the following order:
 184
 185         word    identifier, string
 186         \word   keyword, string
 187
 188 In normalmode, a word is assumed to start with an alphabetic
 189 character, followed by alpha-numeric characters.
 190
 191 =item Note mode
 192
 193 Note mode (and thus Simple mudela) is introduced by the keyword C<\music>.
 194 In Note mode, a word is looked up in the following order:
 195
 196         word    identifier, string
 197         \word   keyword, string
 198
 199 In Note mode a word is considered to have alphabetic characters only.
 200
 201 =item Lyric mode
 202
 203 Lyrics mode (and thus Simple mudela)  is introduced by the keyword C<\lyrics>.
 204
 205 In Lyrics mode, a word is looked up in the following order:
 206
 207         word    string
 208         \word   keyword, string
 209
 210 In Lyric mode every sequence of non-digit and non-white characters
 211 starting with an alphabetic character is considered a word.
 212
 213 =back
 214
 215 These modes are of a lexical nature. Normal and Note mode largely
 216 resemble each other, save the possibility of entering Reals, and
 217 meaning of C<_>
 218
 219 =head2 Notes
 220
 221 Simple mudela basically is a sequence of the notes you want to
 222 enter.
 223
 224         a'4     % dutch names
 225
 226 is a A-1 pitched quaver. The ' as well as the ` signify an octave change.
 227 A-1 is 440 Hz concert-pitch. C<c'> is also known as the central
 228 c. More examples:
 229
 230         `a      % 110
 231         a       % 220
 232         a'      % 440
 233         a''     % 880
 234
 235 another example:
 236
 237         `as4.*2/3
 238
 239 This is an A flat, (just below 110 Hz concert-pitch). The C<*2/3>
 240 signifies that this note is part of a triplet (3 in stead of 2). The
 241 duration is one and a half quaver (C<4.>) times 2/3.
 242
 243 The default language for notenames is defined to be dutch,
 244
 245         % double sharp
 246         cisis disis eisis fisis gisis aisis bisis
 247         % sharps
 248         cis dis eis fis gis ais bis
 249         % naturals
 250         c d e f g a b
 251         % flats
 252         ces des es fes ges as bes
 253         % double flats
 254         ceses deses eses feses geses ases beses
 255
 256 The standard notenames also have uppercase versions, which octavate
 257 down:
 258
 259         a       % 220
 260         A       % 110
 261         'A      % 55
 262         A'      % 220
 263         Cisis
 264
 265 The rest is named
 266
 267         r
 268
 269 These notenames along with duration is enough material to construct
 270 simple melodies:
 271
 272         c4 c4 g4 g4 a4 a4 g2
 273         f4 f4 e4 e4 d4 d4 c2
 274
 275 Music is able to express more. generally speaking, the other
 276 'features' are either connected between notes (slurs, beams: spanning
 277 requests) or attached to notes (eg. accents). The former are
 278 implemented as START and STOP stop features and then attached to the note.
 279
 280         []      START/STOP a beam
 281         ()      START/STOP a slur
 282
 283
 284 example:
 285
 286         [c8 () d8 () e8 ]
 287
 288 Please note that these two characters do I<not> necessarrily nest, eg:
 289
 290         [c8 e8(] [)g8 c'8]
 291
 292
 293 Symbols which can be put at either side of a staff are entered as follows:
 294
 295         a-^     % marcato, direction: default
 296         a^-     % portato, direction: above note
 297         a_.     % staccato, direction: below note
 298         a^\script { "symbolindex"  . . . } % see script.ini for details.
 299
 300 Dynamics can be put after the notename:
 301
 302         a4 \dynamic { 0 } % 0 = fff, 7 = ppp
 303
 304 Mudela defines the following dynamic identifiers:
 305
 306         ppp pp p mp mf df ff fff        % df iso f, f is a notename.
 307
 308 The general form of a note is:
 309
 310         post-requests de-octavate notename octavate duration pre-requests
 311
 312 Notenames are just identifiers, and can be declared for any
 313 language appropriate (see F<dutch.ini>).
 314
 315 =head2 Lyrics
 316
 317 Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
 318 by text.
 319
 320 All syllables are entered separately, separated by whitespace
 321
 322         Twin-4 kle4 twin-4 kle4 ...
 323
 324 Two syllables or words that compose a single
 325 duration entry are bound together using an underscore
 326
 327         He_could4 not4
 328
 329
 330
 331 =head2 Rhythms
 332
 333 Rhythms in Mudela are entered identical to Simple mudela.
 334 The melodic part of the information is ignored.
 335
 336 =head1 STRUCTURE
 337
 338 In concrete, a piece of Mudela has the following structure:
 339
 340         % declare pieces of music:
 341         melody = \music{ <simple mudela> }
 342         accompany = \music{ <simple mudela> }
 343
 344         % instantiate (=create tex, midi output) the score:
 345         \score{
 346                 \staff{ melody }
 347                 \staff{ accompany }
 348                 \commands{ <score global commands> }
 349                 \midi{ <midi definitions> }
 350                 \paper{ <paper and layout definitions }
 351         }
 352
 353 =head2 Examples
 354
 355 Examples are included with the LilyPond distribution. For the sake of
 356 maintenance no long examples are included in this document.
 357
 358
 359 =head2 Other
 360
 361 LilyPond first reads F<symbol.ini>, which contains declarations crucial
 362 to proper operation of LilyPond (symbol tables, note names).