--- /dev/null
+% -*-latex-*-
+\documentclass{article}
+\usepackage{a4wide}
+\title{GNU LilyPond input format 0.1}
+\author{Han-Wen Nienhuys}
+
+\begin{document}
+\maketitle
+\def\interexample{\par Produces the following:\par}
+\def\preexample{\par\medskip}
+\def\postexample{\par\medskip}
+\def\file#1{{\texttt{#1}}}
+
+\section{Introduction}
+
+This document describes the the GNU LilyPond input format, which is an
+effective language for defining music. We call this language
+(rather arrogantly) The Musical Definition Language (Mudela 0.1).
+
+[If anybody comes up with a better name, we'd gladly take
+this. Gourlay already uses Musical Description Language, GSharp Score
+Definition Language. We're not being original here]
+
+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.
+
+
+The Musical Definition Language (Mudela) version 2, has a logical
+structure, making use of typing and naming (using identifiers), that
+allows for flexible input, and definition reuse. See MANIFESTO for
+reasons and design considerations.
+
+The below included for explanatory purposes only (i.e., for a complete
+and up-to-date definition, see \file{lily/parser.y} and
+\file{lily/lexer.l}):
+
+As a related note, you should take a look at the examples and the init
+files, as this document does not cover every aspect of mudela yet, and
+may be out of date.
+
+
+\subsection{Files}
+
+The de-facto extension of Mudela is \file{.ly}. Files may be included by
+entering \verb+include+ at the start of a line:
+
+\begin{verbatim}
+\include "a_file.ly"
+\end{verbatim}
+
+
+\subsection{Comments}
+
+Line comments are introduced by a \verb+%+. Block comments are delimited
+by \verb+%{+ and \verb+%}+. They do not nest.
+
+\subsection{Versions}
+
+Occasionally, small changes in syntax across different versions of
+Mudela might give syntax errors. To warn you about possible
+incompatibilities, you can specify the Mudela version for which the
+inputfile was written,
+\begin{verbatim}
+\version "0.0.50";
+\end{verbatim}
+
+A perl-script which tries to convert to newer versions
+(\file{convert-mudela}) is included in the LilyPond distribution.
+
+\subsection{Words}
+
+Keywords are preceded by a backslash: \verb+\+. They contain
+alphabetic characters only.
+
+Identifiers in their normal form consist start with a backslash, a
+alpha character, followed by alpha-numerics. Identifiers can contain
+any characters (except whitespace, \verb+$+ and \verb+%+), if you use this
+construct:
+
+\begin{verbatim}
+\$i'm_a_weird!!!identifier
+\end{verbatim}
+
+(which is the identifier with the name
+\verb+i'm_a_weird!!!identifier+). \verb+$+ Takes any sequence of
+characters which are not whitespace, \verb+$+ and \verb+%+.
+\verb+$i'm_a_weird!!!string+
+
+\subsection{Nesting characters}
+
+Mudela uses the brace (\verb+{+ and \verb+}+) for most hierarchical
+structures. For chords the \verb+<+ and the \verb+>+ are used as
+nesting braces.
+
+\subsection{Constants}
+
+Please note that -.5 is not a Real.
+
+\begin{verbatim}
+"I am a string"
+-1.2e3 % a real
+12 % an int
+\end{verbatim}
+
+
+\subsection{Identifiers}
+
+When assigning identifiers you use
+
+\begin{verbatim}
+string = ...
+\oldidentifier = ..
+\end{verbatim}
+
+When using identifiers they have to be escaped:
+
+\begin{verbatim}
+oboe = \melodic { ... }
+\score{ \melodic { \oboe }}
+\end{verbatim}
+\subsection{Hierarchical structures}
+
+The general structure consists of declarations:
+\begin{verbatim}
+IDENTIFIER = \TYPE{
+ <type specific data>
+}
+\end{verbatim}
+and instantiations:
+
+\begin{verbatim}
+\TYPE{ <type specific data> }
+\end{verbatim}
+
+(Currently, \verb+\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:
+
+\begin{verbatim}
+\TYPE{ IDENTIFIER [...] }
+\end{verbatim}
+
+Some exceptions on this rule have been made to prevent inputting
+Mudela becoming tedious
+
+
+\subsection{Modes:}
+
+To simplify different aspects of music definition (entering the notes
+and manipulating them) Mudela has a number of different input "modes":
+
+\begin{description}
+
+
+\item[Normal mode]
+
+At the start of parsing, Mudela assumes normal mode.
+In Normal mode, a word is looked up in the following order:
+\begin{verbatim}
+word string
+\word keyword, identifier
+\end{verbatim}
+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 \verb+\melodic+. In Note mode, a word is looked up in
+ the following order:
+
+\begin{verbatim}
+word notename, string
+\word keyword, identifier
+\end{verbatim}
+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 \verb+\lyrics+.
+
+In Lyrics mode, a word is looked up in the following order:
+
+\begin{verbatim}
+word string
+\word keyword, identifier
+\end{verbatim}
+
+In Lyric mode every sequence of non-digit and non-white characters
+starting with an alphabetic character or the \_ is considered a word.
+
+\begin{verbatim}
+a&@&@&TSI|{[ % a word
+1THtrhortho % not a "word"
+Leise Fl\"u\ss{}teren meine Sapfe % 4 words
+_ _ _ _ % 4 words: 4 spaces
+\end{verbatim}
+\end{description}
+
+These modes are of a lexical nature. Normal and Note mode largely
+resemble each other, save the possibility of entering Reals,
+meaning of \verb+_+ and the resolution of words
+
+\subsection{Notes}
+
+You enter a note by giving the name and the reciprocal of the duration:
+
+\begin[fragment,verbatim]{mudela}
+a'4 % dutch names
+\end{mudela}
+
+is a A-1 pitched quaver. The ' signifies an octave change. A-1 is 440
+Hz concert-pitch. \verb+c'+ is also known as the central c. More examples:
+
+\begin[fragment,verbatim]{mudela}
+'a % 110
+ a % 220
+ A % 110, uppercase octavates down
+ a' % 440
+a'' % 880
+'as4.*2/3
+\end{mudela}
+
+The last one is an A flat, (just below 110 Hz concert-pitch). The \verb+*2/3+
+signifies that this note is part of a triplet (3 in stead of 2). The
+duration is one and a half quaver (\verb+4.+) times 2/3.
+
+Notenames are just a special kind of identifiers, and can be declared
+for any language appropriate (see \file{dutch.ini}). The default language
+for notenames is defined to be dutch. In dutch, the notenames are
+a,b,c,d,e,f and g. Sharps are formed by adding the extension "is",
+flats by adding ``es''
+
+\begin{verbatim}
+% 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
+\end{verbatim}
+
+Rests are named r or s
+\begin{verbatim}
+r % print a rest
+s % a "space" rest, nothing is printed.
+\end{verbatim}
+
+These notenames along with duration are enough material to construct
+simple melodies:
+
+\begin[verbatim,fragment]{mudela}
+\octave c';
+c4 c4 g4 g4 a4 a4 g2
+f4 f4 e4 e4 d4 d4 c2
+\end{mudela}
+
+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.
+
+\begin{verbatim}
+[] START/STOP a beam
+() START/STOP a slur
+\end{verbatim}
+
+example:
+\begin[verbatim,fragment]{mudela}
+ \octave c';
+ [c8 () d8 () e8
+ e8(] [)g8 <c'8] e'8> % NO nesting!
+ [2/3 c8 c8 c8]1/1 % a triplet
+\end{mudela}
+
+Please note that these two characters do \emph{not} necessarrily nest,
+they should attached to the note \verb+[ <c4 c4>]+ will generate a parse
+error for this reason.
+
+\subsection{Slurs and Ties}
+
+Ties connect the noteheads of adjecent notes. They are entered as follows:
+
+\begin[fragment]{mudela}
+a4 ~ a4
+\end{mudela}
+
+Slurs connect whole chords, and try to avoid crossing stems. They are
+entered as follows:
+\begin{verbatim}
+
+\begin[fragment]{mudela}
+a4( )a4
+\end{mudela}
+
+\subsection{Scripts}
+
+Symbols which can be put at either side (above or below) of a staff
+are entered as follows:
+\begin[fragment]{mudela}
+a-^ % marcato, direction: default
+ a^- % portato, direction: above note
+ a_. % staccato, direction: below note
+ a^\fermata % predefined identifier
+ c_"marcato" % add a text
+ c^"marcato"
+c-"marcato"
+\end{mudela}
+
+If you want to define your own scripts refer to \file{script.ini} for
+details.
+
+
+Dynamics can be put after the notename:
+\begin{verbatim}
+a4 \dynamic { 0 } % 0 = fff, 7 = ppp
+\end{verbatim}
+
+Mudela defines the following dynamic identifiers:
+
+\begin{verbatim}
+ppp pp p mp mf df ff fff % df iso f, f is a notename.
+\end{verbatim}
+and the following abbreviations:
+\begin{verbatim}
+\< %start crescendo
+\> % start decrescendo
+\! % end crescendo/decrescendo
+\end{verbatim}
+
+\subsection{Defaults}
+
+If omit the duration of a note, a default value is substituted. For
+this default value mudela uses the last duration explicitly entered.
+
+Thus the following inputs are equivalent
+\begin{verbatim}
+c4 c4 c16 c16 c16 s16 c4 c16
+c4 c c16 c c c c4 c16
+\end{verbatim}
+
+If you are typing music which does not lie in the "small" and "large"
+octave, you can prevent having to type \verb+'+ all the time by using the
+\verb+\octave+ command: These two lines have the same pitch.
+\begin{verbatim}
+c'' d'' e'' c d e c d e
+
+\octave c''; c d e ''c ''d ''e \octave c; c d e
+\end{verbatim}
+
+By default the setting of \verb+\octave+ is 0.
+
+\subsection{Lyrics}
+
+Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
+by text.
+
+All syllables are entered separately, separated by whitespace
+\begin{verbatim}
+Twin-4 kle4 twin-4 kle4 ...
+\end{verbatim}
+
+Two syllables or words that compose a single
+duration entry are bound together using an underscore
+\begin{verbatim}
+He_could4 not4
+\end{verbatim}
+
+\subsection{ Music direction}
+
+Mudela reads left to right, but you can still stack voices and
+Voice\_elements which are produced in two directions: horizontal
+(voice like) and vertical (chord like)
+
+A note is a prime example of a Music-element is the note:
+\begin{verbatim}
+c4
+\end{verbatim}
+
+If you enclose a sequence of Music-elements in braces ( { } ), then you form
+another kind of Music-element (Voice) with those pieces
+\begin{verbatim}
+ { c c g g a a g2 } % twinkle twinkle
+ { { c c g g} { a a g2 } }
+
+ horOne = \melodic { c c g g }
+ horTwo = \melodic { a a g2 }
+ twinkle = \melodic { \horOne \horTwo }
+\end{verbatim}
+
+You can stack Music-elements by enclosing a sequence Music-elements of
+notes with < and >. Example:
+\begin{verbatim}
+<a cis e'> % a-major chord
+\end{verbatim}
+You can also put vertical music inside horizontal music:
+\begin{verbatim}
+{ c <c e> <c e g> <c e g c'> } % 4 increasing chords
+\end{verbatim}
+And vice versa
+\begin{verbatim}
+< \multi 2;
+ {c c g g a a g2}
+ {r2 r2 c c g g a a g2} > % a canon
+\end{verbatim}
+
+The duration of a chord equals the union of the durations of each of
+its elements. The \verb+\multi 2+ is a construct which is explained
+below.
+
+You can also create a Music-element by transposing a Music-element:
+\begin{verbatim}
+\transpose
+ d % from c to the d that's one octave down
+ { e4 f4 } % the horizontal music
+
+\end{verbatim}
+
+\subsection{Voicegroups}
+
+If more than one "voice" is in a staff, then you have the option of
+putting the different voices into so called voicegroups: members of
+the same voicegroup share certain characteristics, among others:
+
+ - dynamics
+ - text
+ - beams and stems
+ - scripts
+
+For the actual list, see the init file \file{register.ini}
+
+Putting different musical lines in to the same voicegroup effectively
+makes LilyPond try to form chords of all those lines. Putting
+different musical lines in to different voicegroups effectively makes
+LilyPond try to set those lines as independently as possible.
+
+You can set the voicegroup of a voice with the command \verb+\group+, e.g.,
+\begin{verbatim}
+ oboeI = \melodic {
+ \group "oboes";
+ [e8 f8
+ \group "+solo";
+ [g16 a16 g16 fis16]
+ \group "-";
+ g8 f8
+ }
+ oboeII = \melodic { \group "oboes";
+ c8 d8]
+ e4
+ e8 d8
+ }
+ /// ...
+
+ \staff {
+ melodicregs \melodic{ oboeI }
+ \melodic { oboeII}
+}
+\end{verbatim}
+In this example, the two oboe voices share one staff and are initially
+in the voicegroup called "oboes". They will share beams, dynamics etc.
+After two quavers, oboeI "pushes" its group: a new voicegroup is
+created, called "oboes+solo". The \verb+\group "-"+ command makes the
+voice enter "oboes" again.
+
+Please do note that [] are voicegroup wide; the previous input is
+valid: the beam, started in oboeI, voicegroup "oboes" is also ended in
+voicegroup "oboes", albeit not in oboeI but oboeII
+
+This concept may seem contorted, but it allows you to set the separate
+oboe parts without changing the \verb+oboeI+ and \verb+oboeII+ (assuming that
+you edit the [] in the example.)
+
+The construct
+\begin{verbatim}
+< { .... } {......} >
+\end{verbatim}
+makes a chord (all horizontal parts are in the same voicegroup). The construct
+\begin{verbatim}
+< \multi 2; { ....} { .... } >
+\end{verbatim}
+creates horizontal parts which behave independently. You will have to
+set voicegroup features by hand (\verb+\stem+ and \verb+\hshift+. See examples)
+
+The construct
+\begin{verbatim}
+< \multi 3; { ....} { .... } >
+\end{verbatim}
+creates a chord with each part in a different staff
+
+
+\subsection{Durations}
+
+A duration always starts with the duration type (1,2,4 etc), and then
+any optional multipliers/dots
+
+\subsection{Meters/groupings}
+
+A meter has this form:
+\begin{verbatim}
+\meter 3/4 ;
+\end{verbatim}
+
+Rhythmic grouping is a concept closely associated with this. For
+example, in a 5/8 meter, the counts are grouped 2+3. In mudela this is
+entered as
+\begin{verbatim}
+\grouping 8*2 8*3 ;
+\end{verbatim}
+You can start the piece with a partial measure, the command takes the
+same syntax as grouping:
+\begin{verbatim}
+\partial 16*3 4;
+\end{verbatim}
+
+Make the piece start with a partial measure [transl?] lasting 1 3/4
+quaver.
+
+These commands are also "voice elements", and constitute simple mudela
+(consisting of stuff with duration 0).
+
+\section{STRUCTURE}
+
+In concrete, a piece of Mudela has the following structure:
+\begin{verbatim}
+% declare pieces of music:
+ melody = \music{ <simple mudela> }
+ accompany = \music{ <simple mudela> }
+
+ % instantiate (=create tex, midi output) the score:
+ \score{
+ \melodic <
+ \multi 3;
+ \melody
+ \accompany
+ >
+ \midi{ <midi definitions> }
+ \paper{ <paper and layout definitions> }
+}
+\end{verbatim}
+
+\subsection{Examples}
+
+Examples are included with the GNU LilyPond distribution. For the sake of
+maintenance no long examples are included in this document.
+
+
+\section{HISTORY}
+
+This language has a number of roots. First and foremost, GNU LilyPond's
+predecessor mpp was the inspiration of simple Mudela. Secondly, the
+hierarchical structure looks a lot like Rayce's (Rayce is a raytracer
+that I've written as a hobby project. ), which in turn owes a lot to
+POVRay.
+
+Now, we know, musictypesetting and raytracing do not necessarily
+require the same input format, and we know that a lot more ways exist
+to convert music to ASCII, but we did give this language some
+thoughts. As always suggestions are appreciated.
+
+\end{document}
+
projects / lilypond.git / commitdiff