From db97775a2f171b51d7f0c8a59ceea3b228cd23a8 Mon Sep 17 00:00:00 2001 From: fred Date: Sun, 24 Mar 2002 19:35:46 +0000 Subject: [PATCH] lilypond-0.0.43 --- Documentation/lilyinput.pod | 373 +++++++++++++++++++++++++++++++----- 1 file changed, 328 insertions(+), 45 deletions(-) diff --git a/Documentation/lilyinput.pod b/Documentation/lilyinput.pod index 58a4378d4b..6fdedd2148 100644 --- a/Documentation/lilyinput.pod +++ b/Documentation/lilyinput.pod @@ -1,79 +1,362 @@ =head1 NAME -LilyInput - LilyPond input format +LilyInput - LilyPond input format -- Mudela 0.1 + +B this doc describes the I input format, S. =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). -=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 { } +=over 4 -Some types allow declarations: +=item * - IDENTIFIER = BLOCKNAME { - - } +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, +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 and F): + +=head2 Files + +The de-facto extension of Mudela is F<.ly>. Files may be included by +entering C 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{ + + } + +and instantiations: + + \TYPE{ } + +(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 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 (Rayce is a raytracer that I've -written as a hobby project. I used as a practice program for writing -(among others) C++ and Yacc. It also gave me RSI :-( ) 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 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 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). + +=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{ } + accompany = \music{ } + + % instantiate (=create tex, midi output) the score: + \score{ + \staff{ melody } + \staff{ accompany } + \commands{ } + \midi{ } + \paper{ , which contains declarations crucial +to proper operation of LilyPond (symbol tables, note names). -- 2.39.5