3 % this document should be run through the mudela-book script after lilypond
4 % has been installed. The rules have been precooked into the
5 % Documentation/Rules.make file; do
7 % make out/introduction.dvi
11 % mudela-book --outdir=out/ --outname=introduction.mudtex introduction.doc
12 % latex '\nonstopmode \input out/introduction.mudtex'
14 % Hoi Tim, hier staan wat 'enge' commando's (die dingen met een '\'
15 % zoals \documentclass en \def\mudela...).
16 % Daar moet je je niets van aantrekken, ga gewoon naar Introduction
19 \documentclass{report}
22 \author{Jan Nieuwenhuizen \& Han-Wen Nienhuys}
25 \def\file#1{\verb+#1+}
27 % ugh: trick to get examples not generate par
29 \def\mudelapaperlinewidth{-28.452756}%
30 \def\mudelapaperindent{28.452756}%
31 \def\mudelapaperrulethickness{0.400000}%
32 \def\mudelapaperbarsize{16.000000}%
33 \def\mudelapaperinterline{4.000000}%
34 \def\mudelapapernotewidth{5.930000}%
35 \def\mudelapaperwholewidth{8.640000}%
36 \def\mudelapaperunitspace{22.000000}%
37 \def\mudelapaperbasicspace{4.000000}%
38 \def\mudelapapergeometric{0.000000}%
39 \def\mudelapaperarithmetic_basicspace{2.000000}%
40 \def\mudelapaperarithmetic_multiplier{4.800000}%
41 \def\mudelapaperinterbeam{3.140000}%
42 \def\mudelapapergourlay_energybound{100000.000000}%
43 \def\mudelapapergourlay_maxmeasures{14.000000}%
45 % \def\exampleheight{2\mudelapaperbarsize pt}
46 \def\exampleheight{2cm}
48 % ful of pars, needs the above
52 \def\musixsixteendefs{}
55 \def\turnOnPostScript{}
63 %\def\interexample{\hskip15mm$\Longrightarrow$\hskip15mm}
64 %\def\interexample{\hbox to10mm{\hfill\hbox to0pt{\hss\vbox to\exampleheight{\vss$\Longrightarrow$\vss}\hss}\hfill}}
67 \def\postexample{\par\medskip}
69 \def\file#1{{\texttt{#1}}}
70 \setcounter{secnumdepth}{-1}
74 \emph{\Large ***Under construction***}
76 \section{Introduction}
78 This chapter is a gentle introduction to using LilyPond to typeset
81 LilyPond is a so called ``batch'' program. This means, that you use a
82 texteditor (such as emacs or vi) to create an input file. When you
83 are done editing your input file, you run LilyPond. If Lily
84 finds any errors in your input file she\footnote{ If computer programs
85 could have gender, we're sure that LilyPond is a female computer
86 program, so we will refer to the program as a she. This gender-bending
87 is not to tease you, dear reader. We do it in real life as well. In
88 the past two years LilyPond has become sort of a baby daughter to us,
89 keeping us awake at night, but also providing lots of joy. We hope
90 you do not mind our little aberration from computer-manual tradition.
92 % The name LilyPond is actually sort of a girl's name. Can you guess which
95 } complain. If everything is well, than she'll generate a file that
96 you can process further to view or print it.
98 Using LilyPond to print or view some music is a procedure with four
99 steps. To get you started we'll run down the full procedure for you
104 Fire up your favourite editor (if you know none, try \texttt{joe silly.ly}),
105 and key in the following text:
109 \type Staff = aStaff \melodic { g'2 e'4 }
110 \type Lyrics = yell \lyric { Air2 ball!4 }
115 Save your file as \file{silly.ly}. The input files for LilyPond have
116 the default extension \file{.ly}.
119 Run LilyPond on your newly created file: enter \verb+lilypond silly+.
120 LilyPond will then print all kinds of mumbo jumbo that can safely
121 ignored. You might see something like this:
123 GNU LilyPond 0.1.55/FlowerLib 1.1.39
124 Parsing ... [/home/hanwen/musix/spacer/init/lily-init.ly[/home/hanwen/
126 ... stuff left out here ...
128 Documentation/silly.ly]
129 Interpreting music ...[1] (time: 0.04 seconds)
130 Preprocessing elements...
131 Calculating column positions ... [2]
132 Approximated: 1 lines, (with an average of 4.0 columns)
134 warning: Can not solve this casting problem exactly; revert to Word_wrap
135 [2]Time: 0.00 seconds
137 Postprocessing elements...
138 TeX output to silly.tex ...
140 All has gone well; there were some warning but no errors. The
141 output is a \file{TeX}\footnote{%
142 \file{TeX} is usually spelled as
143 \TeX. It is batch program for typesetting text, developed by the
144 famous programmer and scientist Donald Knuth to typeset his famous The
145 Art of Computer Programming bookseries. As you can see \TeX\ can be
146 adapted to do a lot more. In fact, the document that you are
147 reading was also done with \TeX.} file, and it is called
150 To do something useful with the output you have to run \TeX\ on it
151 first. type \verb+tex silly+. The output should resemble this:
153 This is TeX, Version 3.14159 (C version 6.1)
155 Babel <v3.6h> and hyphenation patterns for american, dutch, loaded.
156 (/home/hanwen/lib/texmf/tex/lilypond/lilyponddefs.tex
157 (/home/hanwen/lib/texmf/tex/lilypond/dyndefs.tex)
158 (/home/hanwen/lib/texmf/tex/lilypond/fetdefs.tex
159 (/home/hanwen/lib/texmf/tex/lilypond/feta20.tex)
160 (/home/hanwen/lib/texmf/tex/lilypond/lily-ps-defs.tex))) [1] )
161 Output written on silly.dvi (1 page, 3084 bytes).
162 Transcript written on silly.log.
164 The human translation is ``everything went OK, the result is one
165 page long, and I put it in \file{silly.dvi}''.
167 \item The \file{silly.dvi} file is a description of how a piece of
168 text looks when it is printed. You can view it, or print it. If you
169 are using a Unix system equipped with X-Windows, issue the command
170 \file{xdvi silly} to view the result. If this is not the case,
171 consult your local \TeX\ guru on printing and viewing DVI files. What
172 is in your window should look like this:
176 \type Staff = aStaff \melodic { g'2 e'4 }
177 \type Lyrics = yell \lyric { Air2 ball!4 }
183 The remainder of this document is not about \TeX, and mostly not even
184 about LilyPond. What you entered into your text editor in step~1. and
185 fed to LilyPond is a special kind of file composed of notenames,
186 special words and punctation. The remainder of this document explains
187 how to combine these elements to express a piece of music in the
188 language that LilyPond understands. So we try to explain how to use
189 LilyPond, and not how LilyPond works; the input language of LilyPond
190 is the subject of the document. For want of a better name we call
191 this language Mudela (short for Music Description Language).
193 This document does not cover all of Mudela. Due to technical details,
194 the precise working of Mudela is coupled to the innards of LilyPond.
195 If you really want to know all the details, your best bet would be to
196 get the sources to LilyPond and read the parser and scanner
197 source\footnote{ They are in \file{lilypond-x.y.z/lily/parser.y},
198 \file{lilypond-x.y.z/lily/lexer.l}. Of course, it would be even
199 better if you would improve LilyPond and send the resulting diffs to
200 us. But that would a really different ballpark (And we
201 haven't started with the programming guide yet.)}
203 In the following sections the basic elements of Mudela are presented.
204 We don't want to bore you too much with details, so we will leave-out
205 some red tape that's needed for a valid piece of Mudela: to be
206 precise, we will write \verb+X Y Z+, when we really mean
213 Usually, we will also print the resulting fragment of music on the
214 right just as it was produced by LilyPond.
216 For the remainder we will assume that you can carry out steps 1 to 4
217 from the above instruction. We will also assume that you know how
218 music notation works, and that you are familiar with terms such as
219 ``note'', ``clef'', ``slur'' etc.
221 \section{Music copying versus music definition}
223 If you have done music copying before, then using LilyPond may seem
224 awkward to you in the beginning. The purpose of LilyPond is usually
225 explained by the term ``music typesetter.''
227 This may give the impression that the program lets you control
228 precisely how the music is formatted. This is not the case: not only
229 does the program print musical symbols, LilyPond also tries to make
230 esthetic decisions---to be precise, we programmed her to do what we
231 find pretty. You do not have complete control over what is happening.
232 On the other hand, good engraving is a very complex trade, so it is a
233 Good Thing that you do not have to worry about what is happening.
235 Secondly, LilyPond operates on musical definitions. This really is
236 something different from graphical definitions. If you copy music by
237 hand from a printed score, you don't have to know what the score
238 means; you just copy the symbols. With LilyPond such a thing is not
239 possible: we expect you to enter the meaning of the score, not the
240 score itself. If put more concretely: you do not enter ``black
241 notehead without flag, fourth staff line'', but ``a quarter note,
242 pitch $d^2$''. LilyPond will figure out from the musical info what
243 kind of graphic presentation is needed.
245 This has some drawbacks: most notably, it is difficult to enter sheet
246 music that you cannot read. On the other hand, any piece of music
247 that you enter can be played and transposed automatically.
250 \section{When you know the notes to print\ldots}
252 The basic building block of music is the note. You can have LilyPond
253 print a note by specifying its pitch and the duration. The pitch of
254 the central C, also know as c$^1$ is written as \verb+c'+. A quarter
255 note duration is written as \verb+4+. So, to print quarter note with
256 central C pitch, you enter the following
257 \begin[fragment,verbatim,center]{mudela}
260 The pitch \verb+c'+ actually consists of two parts: one for the note
261 name, and one part for the octave. The number of apostrophes
262 specifies the octave to use, and the letter which note name to use.
263 The note names simply are the letters \verb+a+ to \verb+g+.
265 The duration of a note is specified as a number: a whole note is
266 denoted by 1, the half note by 2, the quarter by 4, and so on. Here
267 are some random notes to show how it works
268 \begin[fragment,verbatim]{mudela}
269 'c8 c8 c'16 c''16 d''64 b'64 c1 c'4 d'4 e'4 f'4 g'4 a'4
272 This gives us already enough material to make simple songs:
273 \begin[fragment,verbatim]{mudela}
276 g''8 a''8 g''8 f''8 e''4 c''4
280 There is only one part about pitches that we haven't told you:
281 chromatically altered pitches. The names ``a'' to ``g'' for typing
282 pitches are convenient: they are short, pronounceable and they
283 resemble the normal vocabulary for pitches. Enter flats and sharps.
284 In english there is no standard terse word for C sharp or C flat. For
285 this reason, we implemented a different, non-english convention for
286 entering altered pitches, see table~\ref{notename-tab}: one makes a note sharp by adding the suffix
287 --is to the name, one makes the a note flat by adding the suffix
288 --es. For a double sharp you simply add another --is suffix.
290 \begin{table}\caption{Note names}\label{notename-tab}
294 c double flat &ceses\\
298 c double sharp &cisis\\
302 Variations on this convention\footnote{LilyPond actually defaults to
303 dutch notenames, with aes, aeses, ees and eeses added} are used in a
304 number of germanic languages, notably dutch, german, swedish,
305 norwegian. If you are not comfortable with these names, you can make
306 your own names. Check out the example initialisation files. A number
307 of languages are included.
309 \section{Hairy rhythms}
311 \section{Handy input}
313 % \subsection{Durations}
315 However, having only quarter notes may get a bit dull.
316 Durations are entered as their reciproce values
317 % a1 a2 a4 a a8 a a16 a a32 a a64 a a a a
318 \begin[fragment,verbatim,center]{mudela}
319 a1 a2 a4 a a8 a a16 a32 a64
321 note that you only have to specify
322 the duration when it changes:
323 Lily assumes a note has the same duration as the previous one.
325 Now we can already write a little tune
326 \begin[fragment,verbatim,center]{mudela}
327 c d e c | c d e c | e f g2
329 As you'll probably have guessed,
330 the vertical bar (pipe) \verb+|+ may be used to mark
333 In the scale shown above
334 we left-out the last c note of the next octave.
335 Postfixing the pitch with a quote \verb+'+
336 produces a note by one octave higher
337 \begin[fragment,verbatim,center]{mudela}
341 Prefixing the pitch with a quote \verb+'+
342 produces a note by one octave lower
343 \begin[fragment,verbatim,center]{mudela}
347 \section{Slurs and Ties}
349 A tie connects two adjacent noteheads
351 \begin[fragment,verbatim,center]{mudela}
355 Whereas a slur rather connects `chords',
356 and tries to avoid crossing stems
358 \begin[fragment,verbatim,center]{mudela}
362 And of course, such a (legato) slur can span several notes
363 \begin[fragment,verbatim,center]{mudela}
367 \section{Beams and Plets}
370 \begin[fragment,verbatim,center]{mudela}
374 Here's a beamed triplet
375 \begin[fragment,verbatim,center]{mudela}
379 a triplet without a beam
380 \begin[fragment,verbatim,center]{mudela}
385 \begin[fragment,verbatim,center]{mudela}
390 \begin[fragment,verbatim,center]{mudela}
394 \begin[fragment,verbatim,center]{mudela}
400 Lily has predefined sets of notenames
401 for various languages%
402 \footnote{These are Dutch, English, German, Italian and Swedish.
403 Simply include the language specific init file \file{<language.ly>}.}.
404 The default set are the ones we like best are the Dutch notenames.
406 A sharp is formed by adding \verb+is+
407 \begin[fragment,verbatim,center]{mudela}
408 cis dis eis fis gis ais bis
411 and a flat is formed by adding \verb+es+%
412 %\footnote{Exceptions: \verb+es+ and \verb+as+.}
413 \footnote{Exceptions: {\tt es} and {\tt as}.}
414 \begin[fragment,verbatim,center]{mudela}
415 ces des es fes ges as bes
418 With the obvious names for double sharps
419 \begin[fragment,verbatim,center]{mudela}
420 cisis disis eisis fisis gisis aisis bisis
424 \begin[fragment,verbatim,center]{mudela}
425 ceses deses eses feses geses ases beses
429 There are two special `notenames', the rest
430 \begin[fragment,verbatim,center]{mudela}
435 \begin[fragment,verbatim,center]{mudela}
436 a2 s-"diminuendo" | a
442 \begin[fragment,verbatim,center]{mudela}
447 \begin[fragment,verbatim,center]{mudela}
448 \clef "violin"; f' e' \clef "alto"; d' c'
451 \begin[fragment,verbatim,center]{mudela}
455 \begin[fragment,verbatim,center]{mudela}
457 'g 'a 'b cis d e fis g'
459 Note how Mudela allows you to
460 convey a musical message
461 rather than forces you to produce a list of typesetting commands.
462 If the music a \verb+cis+, you type a \verb+cis+.
463 Depending on the key and context of the note
464 Lily will determine what accidentals to typeset.
466 A reminder accidental can be forced by
467 using an exclamation mark \verb+!+
468 on a pitch a reminder accidental
469 \begin[fragment,verbatim,center]{mudela}
470 cis d e cis | c! d e c |
473 \begin[fragment,verbatim,center]{mudela}
475 \bar "|:"; c c \bar ":|:"; c c \bar ":|"; c c \bar "|.";
478 \section{Chords and Voices}
480 Here's a simple chord
481 \begin[fragment,verbatim,center]{mudela}
486 \begin[fragment,verbatim,center]{mudela}
495 \begin[fragment,verbatim,center]{mudela}
497 { \voiceone c g c g }
498 { \voicetwo 'c2 'g2 }
503 \section{A complete example}
506 A Mudela file needs some red tape
508 \begin[verbatim,center]{mudela}
521 \begin[verbatim,center]{mudela}
544 Check-out this handy little script
545 that not only may save you quite some keystrokes,
546 but produces titles and takes care of
547 margins and (hopefully) papersizes.
548 See \file{ly2dvi (1)}.
550 \chapter{Input format reference}
554 This document describes the the GNU LilyPond input format, which is an
555 effective language for defining music. We call this language (rather
556 arrogantly) The Musical Definition Language or Mudela, for
557 short.\footnote{If anybody comes up with a better name, we'd gladly
558 take this. Gourlay already uses Musical Description Language,
559 G-Sharp Score Definition Language. ISO standard 10743 defines a
560 Standard Music Description Language. We're not being original here}
562 The first aim of Mudela is to define a piece of music, being complete
563 from both from a musical typesetting, as from a musical performing
566 The Musical Definition Language (Mudela), has a logical structure,
567 making use of identifiers, that allows for flexible input, and
568 definition reuse. See \file{MANIFESTO} for reasons and design considerations.
570 The below included for explanatory purposes only (i.e., for a complete
571 and up-to-date definition, see \file{lily/parser.y} and
572 \file{lily/lexer.l}):
574 As a related note, you should take a look at the examples and the init
575 files, as this document does not cover every aspect of mudela yet, and
576 may be out of date.\footnote{Ok, I am being pessimistic here. This
577 just is a disclaimer. Docs usually are written after the program
578 itself.} This document intends to give an idea of how it works, it
579 is not a guide on how to use it.
582 \section{Basic elements}
586 The de-facto extension of Mudela is \file{.ly}. Files may be included by
587 entering \verb+\include+ at the start of a line:
594 \subsection{Comments}
596 Line comments are introduced by a
598 Block comments are delimited
605 \subsection{Versions}
607 Occasionally, small changes in syntax across different versions of
608 Mudela might give syntax errors. To warn you about possible
609 incompatibilities, you can specify the Mudela version for which the
610 inputfile was written,
615 A perl-script which tries to convert to newer versions
616 (\file{convert-mudela}) is included in the LilyPond distribution.
620 Keywords are preceded by a backslash: \verb+\+. They contain
621 alphabetic characters only.
623 Identifiers in their normal form consist start with a backslash, a
624 alpha character, followed by alpha-numerics. Identifiers can contain
625 any characters (except whitespace,
626 and \verb+%+), if you use this construct:
629 \$i'm_a_weird!!!identifier
632 (which is the identifier with the name
633 \verb+i'm_a_weird!!!identifier+). \verb+$+ Takes any sequence of
634 characters which are not whitespace, \verb+$+ and \verb+%+.
635 \verb+$i'm_a_weird!!!string+
636 \def\foobar{$} % silly fontlock mode
638 \subsection{Nesting characters}
640 Mudela uses the brace (\verb+{+ and \verb+}+) for most hierarchical
641 structures. For chords the \verb+<+ and the \verb+>+ are used as
644 \subsection{Constants}
646 Please note that -.5 is not a Real.
655 \subsection{Identifiers}
657 When assigning identifiers you use
663 If you reuse identifiers, then the previous contents will be thrown
664 away after the right hand is evaluated, eg
666 bla = \melodic { \bla }
670 When using identifiers they have to be escaped:
673 oboe = \melodic { ... }
674 \score{ \melodic { \oboe }}
677 The left-hand part of the assignment is really a string, so
679 "Foo bar 4 2 " = \melodic { .. }
682 is also a valid assignment (but you would have trouble referencing to it)
685 \subsection{Hierarchical structures}
687 The general structure consists of declarations:
696 \TYPE{ <type specific data> }
699 (Currently, \verb+\score+ is the only type that can be instantiated
700 at top level. Currently declarations can only be done at top level)
702 Most instantiations that use an IDENTIFIER are specified as follows:
705 \TYPE{ IDENTIFIER [...] }
708 Some exceptions on this rule have been made to prevent inputting
709 Mudela becoming tedious
714 To simplify different aspects of music definition (entering the notes
715 and manipulating them) Mudela has a number of different input "modes":
722 At the start of parsing, Mudela assumes normal mode.
723 In Normal mode, a word is looked up in the following order:
725 \item{\verb+word+} string
726 \item{\verb|"string"|} string
727 \item{\verb|\word|} keyword, identifier
729 In normal mode, a word is assumed to start with an alphabetic
730 character, followed by alpha-numeric characters.
732 \item[Note mode] Note mode is introduced by the keyword
733 \verb+\melodic+. In Note mode, a word is looked up in the following
736 \item{\verb+word+} notename, string
737 \item{\verb|"string"|} string
738 \item{\verb|\word|} keyword, identifier
741 In Note mode a word is considered to have alphabetic characters only,
742 so the underscore (\_) is illegal. If you accidently mistype a
743 notename, the parser will assume that you are entering a string (and
744 it will most likely complain that you should be in \verb|\lyrics| mode to
748 \item[Lyric mode] Lyrics mode (and thus Simple mudela) is introduced
749 by the keyword \verb+\lyrics+. Because of the various control
750 characters that can appear in lyrics, eg, ``foreign language''
751 accents, the inputting a string containing these has been made very
754 In Lyrics mode, a word is looked up in the following order:
756 \item{\verb+word+} string (thus a lyric)
757 \item{\verb|"string"|} string
758 \item{\verb|\word|} keyword, identifier
761 In Lyric mode every sequence of non-digit and non-white characters
762 starting with an alphabetic character or the \_ is considered a word.
765 a&@&@&TSI|{[ % a word
766 1THtrhortho % not a "word"
767 Leise Fl\"u\ss{}teren meine Sapfe % 4 words
768 _ _ _ _ % 4 words: 4 spaces
772 These modes are of a lexical nature. Normal and Note mode largely
773 resemble each other, save the possibility of entering Reals,
774 meaning of \verb+_+ and the resolution of words
778 You enter a note by giving the name and the reciprocal of the duration:
780 \begin[fragment,verbatim]{mudela}
784 is a A-1 pitched crotchet. The ' signifies an octave change. A-1 is 440
785 Hz concert-pitch. \verb+c'+ is also known as the central c. More examples:
787 \begin[fragment,verbatim]{mudela}
790 A % 110, uppercase octavates down
796 The last one is an A flat, (just below 110 Hz concert-pitch). The \verb+*2/3+
797 signifies that this note is part of a triplet (3 in stead of 2). The
798 duration is one and a half quarter note (\verb+4.+) times 2/3.
800 Notenames are just a special kind of identifiers, and can be declared
801 for any language appropriate (see \file{init/dutch.ly}). The default language
802 for notenames is defined to be Dutch. In Dutch, the notenames are
803 a,b,c,d,e,f and g. Sharps are formed by adding the extension "is",
804 flats by adding ``es''
808 cisis disis eisis fisis gisis aisis bisis
810 cis dis eis fis gis ais bis
814 ces des es fes ges as bes
816 ceses deses eses feses geses ases beses
819 Rests are named r or s
822 s % a "space" rest, nothing is printed.
825 These notenames along with duration are enough material to construct
828 \begin[verbatim,fragment]{mudela}
834 Music is able to express more. generally speaking, the other
835 'features' are either connected between notes (slurs, beams: spanning
836 requests) or attached to notes (eg. accents). The former are
837 implemented as START and STOP stop features and then attached to the note.
840 \item{[ and ]} start and stop a beam
841 \item{( and )} start and stop a slur
845 \begin[verbatim,fragment]{mudela}
848 e8(] [)g8 <c'8] e'8> % NO nesting!
849 [2/3 c8 c8 c8]1/1 % a triplet
852 Please note that these two characters do \emph{not} necessarrily nest,
853 they should be attached to the note. For this reason, the construct
854 \verb+[ <c4 c4>]+ will generate a parse error.
856 \subsection{Slurs and Ties}
858 Ties connect the noteheads of adjacent notes. They are entered as follows:
860 \begin[verbatim,fragment]{mudela}
864 Slurs connect whole chords, and try to avoid crossing stems. They are
867 \begin[verbatim,fragment]{mudela}
873 Symbols which can be put at either side (above or below) of a staff
874 are entered as follows:
875 \begin[verbatim,fragment]{mudela}
876 a-^ % marcato, direction: default
877 %a^- % portato, direction: above note
878 a_. % staccato, direction: below note
879 a^\fermata % predefined identifier
880 c_"marcato" % add a text
885 If you want to define your own scripts refer to \file{init/script.ly} for
889 Dynamics can be put after the notename:
891 a4 \dynamic { 0 } % 0 = fff, 7 = ppp
894 Mudela defines the following dynamic identifiers:
897 ppp pp p mp mf f ff fff sfz fz fp
899 and the following abbreviations:
902 \> % start decrescendo
903 \! % end crescendo/decrescendo
906 \subsection{Defaults}
908 If omit the duration of a note, a default value is substituted. For
909 this default value mudela uses the last duration explicitly entered.
911 Thus the following inputs are equivalent
913 c4 c4 c16 c16 c16 s16 c4 c16
914 c4 c c16 c c c c4 c16
917 If you are typing music which does not lie in the "small" and "large"
918 octave, you can prevent having to type \verb+'+ all the time by using the
919 \verb+\octave+ command: These two lines have the same pitch.
921 c'' d'' e'' c d e c d e
922 \octave c''; c d e ''c ''d ''e \octave c; c d e
925 By default the setting of \verb+\octave+ is 0.
929 Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
932 All syllables are entered separately, separated by whitespace
934 Twin-4 kle4 twin-4 kle4 ...
937 Two syllables or words that compose a single
938 duration entry are bound together using an underscore
943 \section{Composition: forming bigger structures}
945 The previous examples tacitly assumed that a sequence of notes is
946 printed in a left to right manner. This is not entirely correct, you
947 will get the bigger picture in this section.
949 In mathematics you can form expressions by combining expressions,
950 which are ultimately some kind of atom or terminal symbol. The same
951 goes for mudela: there are some basic building blocks, and by
952 combining those you create complex music.
954 You can combine music in three ways:
956 \item If you enclose a sequence of music-elements in braces ( \verb+{+
957 and \verb+}+ ), then you form another kind of music called (Voice) with those pieces.
958 The duration of the Voice is the sum of the durations of its elements
960 { c c g g a a g2 } % twinkle twinkle
961 { { c c g g} { a a g2 } }
963 \item You can stack music by enclosing a sequence of music elements
964 with \verb+<+ and \verb+>+. This is called a Chord. The duration of a Chord is
965 the union of the durations of its elements Example:
967 <a4 {cis8 cis8} e'4> % a-major chord
970 You can form music by transposing music:
973 d % from c to the d that's one octave down
974 { e4 f4 } % the horizontal music
978 Of course you can also combine these three mechanisms.
980 { c <c e> <c e g> <c e g \transpose d' dis > } % 4 increasing chords
983 The basic building block in Mudela is called Request. Examples of
984 Requests are: Timing (such as Meter), Rhythmic, Melodic, Note (which is a combination of
985 Rhythmic and Melodic), Musicscript (put an accent over a note or
986 rest), etc. For the actual up to date listing, you should consult the
987 LilyPond source code: the Request types form a big class hierarchy.
989 Normally you don't enter Requests directly, since that would be
990 tedious. Mudela has standard abbreviations for the most common
991 combination of Requests. If you enter \verb+c4+, this is an
996 notename: 0 acc: 0 oct: -1
1005 The \verb+Request_chord+ is a special kind of chord which only allows
1006 Requests as its elements. The examples of the previous section were
1007 processed with \verb+{+ and \verb+}+ enclosing the input.
1009 \subsection{Durations}
1011 A duration always starts with the duration type (1,2,4 etc), and then
1012 any optional multipliers/dots. Old fashioned durations can be entered
1021 \subsection{Meters/groupings}
1023 A meter has this form:
1028 Rhythmic grouping is a concept closely associated with this. For
1029 example, in a 5/8 meter, the counts are grouped 2+3. In mudela this is
1034 You can start the piece with a partial measure, the command takes the
1035 same syntax as grouping:
1040 Make the piece start with a upstep [english translation?]
1041 lasting 1 3/4 quarter notes.
1043 These commands are also "voice elements", and constitute ``Music''
1044 (consisting of stuff with duration 0).
1047 \subsection{Voicegroups}
1052 If more than one "voice" is in a staff, then you have the option of
1053 putting the different voices into so called voicegroups: members of
1054 the same voicegroup share certain characteristics, among others:
1061 For the actual list, see the init file \file{init/register.ly}
1063 Putting different musical lines in to the same voicegroup effectively
1064 makes LilyPond try to form chords of all those lines. Putting
1065 different musical lines in to different voicegroups effectively makes
1066 LilyPond try to set those lines as independently as possible.
1068 [adsolete. Has to be fixed in lily]
1070 You can set the voicegroup of a voice with the command \verb+\group+, e.g.,
1081 oboeII = \melodic { \group "oboes";
1089 melodicregs \melodic{ oboeI }
1094 In this example, the two oboe voices share one staff and are initially
1095 in the voicegroup called "oboes". They will share beams, dynamics etc.
1096 After two quarter notes, oboeI "pushes" its group: a new voicegroup is
1097 created, called "oboes+solo". The \verb+\group "-"+ command makes the
1098 voice enter "oboes" again.
1100 Please do note that [] are voicegroup wide; the previous input is
1101 valid: the beam, started in oboeI, voicegroup "oboes" is also ended in
1102 voicegroup "oboes", albeit not in oboeI but oboeII
1104 This concept may seem contorted, but it allows you to set the separate
1105 oboe parts without changing the \verb+oboeI+ and \verb+oboeII+ (assuming that
1106 you edit the [] in the example.)
1110 < { .... } {......} >
1112 makes a chord (all horizontal parts are in the same voicegroup). The construct
1114 \multi 2 < { ....} { .... } >
1116 creates horizontal parts which behave independently. You will have to
1117 set voicegroup features by hand (\verb+\stem+ and \verb+\hshift+. See examples)
1121 \multi 3 < { ....} { .... } >
1123 creates a chord with each part in a different staff
1126 \subsection{Examples}
1128 Examples are included with the GNU LilyPond distribution. For the sake of
1129 maintenance no long examples are included in this document.
1134 This language has a number of roots. First and foremost, GNU
1135 LilyPond's predecessor mpp was the inspiration of the Note-mode input.
1136 Secondly, the hierarchical structure looks a lot like Rayce's (Rayce
1137 is a raytracer that I've written as a hobby project. ), which in turn
1138 owes a lot to POVRay.
1140 Now, we know, musictypesetting and raytracing do not necessarily
1141 require the same input format, and we know that a lot more ways exist
1142 to convert music to ASCII, but we did give this language some
1143 thoughts. As always suggestions are appreciated.