\documentclass{article}
\usepackage{a4wide}
\title{Introduction to GNU LilyPond}
-\author{Jan Nieuwenhuizen}
+\author{Jan Nieuwenhuizen \& Han-Wen Nienhuys}
\date{March 2, 1998}
\def\file#1{\verb+#1+}
\emph{\Large ***Under construction***}
\section{Introduction}
-This document should provide a gentle introduction to
-LilyPond's input language, Mudela.
-For completeness and nifty features see
-\file{input/*.ly}
-and
-\file{lily/parser.y}, \file{lily/lexer.l}.
-By tradition, Mudela files have the extension \file{.ly}.
-
-Mudela is an ascii script language
-that is especially designed
-to be easy to read and write.
-In the following sections
-the basic elements of Mudela are presented
-in a series of simple examples.
-Each example has
-a verbatim snippet of Mudela%
-% a snippet of Mudela as it's typed-in%
-\footnote{
-In an effort not to bore you too much with details,
-we leave-out some red tape
-that's needed for a valid piece of Mudela.
-Therefore, before you try-out any of the examples,
-be sure to read the section `A complete example'.}
-on the left
-and the resulting fragment of music on the right
-as it was produced by LilyPond.
-
-\section{Notes}
-
-Let's start with a single note, a quarter C
-
-\begin[fragment,verbatim,center]{mudela}
-c
+This document is a gentle introduction to using LilyPond to typeset
+simple music.
+
+
+LilyPond is a so called ``batch'' program. This means, that you use a
+texteditor (such as emacs or vi) to create an input file. When you
+are done editing your input file, you run LilyPond. If Lily
+finds any errors in your input file she\footnote{ If computer programs
+could have gender, we're sure that LilyPond is a female computer
+program, so we will refer to the program as a she. This gender-bending
+is not to tease you, dear reader. We do it in real life as well. In
+the past two years LilyPond has become sort of a baby daughter to us,
+keeping us awake at night, but also providing lots of joy. We hope
+you do not mind our little aberration from computer-manual tradition.
+%
+% The name LilyPond is actually sort of a girl's name. Can you guess which
+% one ?
+%
+} complain. If everything is well, than she'll generate a file that
+you can process further to view or print it.
+
+To get you started we'll run down the full procedure for you once.
+
+\begin{enumerate}
+\item
+Fire up your favourite editor (if you know none, try \texttt{joe silly.ly}),
+and key in the following text:
+\begin{verbatim}
+\score {
+ <
+ \type Staff = aStaff \melodic { g'2 e'4 }
+ \type Lyrics = yell \lyric { Air2 ball!4 }
+ >
+}
+\end{verbatim}
+
+save your file as \file{silly.ly}. As might have noticed, the input
+files to LilyPond have the extension \file{.ly}.
+
+\item
+Run LilyPond on your newly created file: \verb+lilypond silly+.
+LilyPond will then print all kinds of mumbo jumbo that can safely
+ignored.
+You might see something like this:
+\begin{verbatim}
+GNU LilyPond 0.1.55/FlowerLib 1.1.39
+Parsing ... [/home/hanwen/musix/spacer/init/lily-init.ly[/home/hanwen/
+
+ ... stuff left out here ...
+
+ Documentation/silly.ly]
+Interpreting music ...[1] (time: 0.04 seconds)
+Preprocessing elements...
+Calculating column positions ... [2]
+Approximated: 1 lines, (with an average of 4.0 columns)
+Time: 0.01 seconds
+warning: Can not solve this casting problem exactly; revert to Word_wrap
+[2]Time: 0.00 seconds
+
+Postprocessing elements...
+TeX output to silly.tex ...
+\end{verbatim}
+ All has gone well; there were some warning but no errors. The
+ output is a \file{TeX}\footnote{%
+ \file{TeX} is usually spelled as
+ \TeX. It is batch program for typesetting text, developed by the
+ famous programmer and scientist Donald Knuth to typeset his famous The
+ Art of Computer Programming bookseries. As you can see \TeX\ can be
+ adapted to do a lot more. In fact, the document that you are
+ reading was also done with \TeX.} file, and it is called
+ \file{silly.tex}.
+\item
+ To do something useful with the output you have to run \TeX\ on it
+ first. type \verb+tex silly+. The output should resemble this:
+\begin{verbatim}
+This is TeX, Version 3.14159 (C version 6.1)
+(silly.tex
+Babel <v3.6h> and hyphenation patterns for american, dutch, loaded.
+(/home/hanwen/lib/texmf/tex/lilypond/lilyponddefs.tex
+(/home/hanwen/lib/texmf/tex/lilypond/dyndefs.tex)
+(/home/hanwen/lib/texmf/tex/lilypond/fetdefs.tex
+(/home/hanwen/lib/texmf/tex/lilypond/feta20.tex)
+(/home/hanwen/lib/texmf/tex/lilypond/lily-ps-defs.tex))) [1] )
+Output written on silly.dvi (1 page, 3084 bytes).
+Transcript written on silly.log.
+\end{verbatim}
+ The human translation is ``everything went OK, the result is one
+ page long, and I put it in \file{silly.dvi}''. The \file{silly.dvi}
+ file is a description of how a piece of text looks when it is
+ printed. You can view it, or print it. If you are using a Unix
+ system equipped with X-Windows, issue the command \file{xdvi silly}
+ to view the result. If this is not the case, consult your local
+ \TeX\ guru on printing and viewing DVI files. What is in your
+ window should look like this:
+\begin{mudela}
+\score {
+ <
+ \type Staff = aStaff \melodic { g'2 e'4 }
+ \type Lyrics = yell \lyric { Air2 ball!4 }
+ >
+}
\end{mudela}
+\end{enumerate}
+
+The remainder of this document is not about \TeX, and mostly not even
+about LilyPond. What you entered into your text editor in step~1. and
+fed to LilyPond is a special kind of file composed of notenames,
+special words and punctation. The remainder of this document explains
+how to combine these elements to express a piece of music in the
+language that LilyPond understands. So we try to explain how to use
+LilyPond, and not how LilyPond works; the input language of LilyPond
+is the subject of the document. For want of a better name we call
+this language Mudela (short for Music Description Language).
+
+This document does not cover all of Mudela. Due to technical details,
+the precise working of Mudela is coupled to the innards of LilyPond.
+If you really want to know all the details, your best bet would be to
+get the sources to LilyPond and read the parser and scanner
+source\footnote{ They are in \file{lilypond-x.y.z/lily/parser.y},
+\file{lilypond-x.y.z/lily/lexer.l}. Of course, it would be even
+better if you would improve LilyPond and send the resulting diffs to
+us. But that would a really different ballpark (And we
+haven't started on the programming guide yet.)}
+
+In the following sections the basic elements of Mudela are presented.
+We don't want to bore you too much with details, so we will leave-out
+some red tape that's needed for a valid piece of Mudela: to be
+precise, we will write \verb+X Y Z+, when we really mean
+\begin{verbatim}
+\score {
+ \melodic { X Y Z }
+ \paper {}
+}
+\end{verbatim}
+Usually, we will also print the resulting fragment of music on the
+right just as it was produced by LilyPond.
-Now that was easy and entering a scale is not much harder
+For the remainder we will assume that you can carry out steps 1 to 4
+from the above instruction. We will also assume that you know how
+music notation works, and that you are familiar with terms such as
+``note'', ``clef'', ``slur'' etc.
-%\subsection{Pitches}
+\section{When you know the notes to print\ldots}
+The basic building block of music is the note. You can have LilyPond
+print a note by specifying the pitch and the duration. The pitch of
+the central C, also know as c$^1$ is written as \verb+c'+. A quarter
+note duration is written as \verb+4+:
\begin[fragment,verbatim,center]{mudela}
-c d e f g a b
+c'4
+\end{mudela}
+The \verb+c'+ actually consists of two parts: one for the note name,
+and one part for the octave. The number of apostrophes specifies the
+octave to use, and the letter which note name to use. The duration of
+a note is specified as a number: a whole note is denoted by 1, the
+half note by 2, the quarter by 4, and so on. This gives us already
+enough material to make simple songs:
+\begin[fragment,verbatim]{mudela}
+ c''4 d''4 e''4 c''4
+ e''4 f''4 g''2
+ g''8 a''8 g''8 f''8 e''4 c''4
+ c''4 g'4 c''2
\end{mudela}
+You might wonder: ``what if I would
+
+
% \subsection{Durations}
However, having only quarter notes may get a bit dull.
\bar "|:"; c c \bar ":|:"; c c \bar ":|"; c c \bar "|.";
\end{mudela}
-\section{Scripts}
-
-Staccato may be abbreviated
-\begin[fragment,verbatim,center]{mudela}
-a-\staccato a-.
-\end{mudela}
-
-Marcato
-\begin[fragment,verbatim,center]{mudela}
-a-\marcato a-|
-\end{mudela}
-
-Staccatissimo
-\begin[fragment,verbatim,center]{mudela}
-a-\staccatissimo a-^
-\end{mudela}
-
-Sforzato
-% duh?
-% a-\sforzato a->
-\begin[fragment,verbatim,center]{mudela}
-a-\accent a->
-\end{mudela}
-
-\begin[fragment,verbatim,center]{mudela}
-a-\fermata
-\end{mudela}
-
-\begin[fragment,verbatim,center]{mudela}
-a-\fermata
-\end{mudela}
-
-Dynamics from pianississimo upto mezzopiano
-\begin[fragment,verbatim,center]{mudela}
-a\ppp a\pp a\p a\mp
-\end{mudela}
-
-from fortississimo downto mezzoforte
-\begin[fragment,verbatim,center]{mudela}
-a\fff a\ff a\f a\mf
-\end{mudela}
-
-sforzando, sforzato and rinforzato
-% huh?
-% a\sfz a\sf a\rf
-\begin[fragment,verbatim,center]{mudela}
-a\sfz a\sf
-\end{mudela}
-
-Fingering
-\begin[fragment,verbatim,center]{mudela}
-[e8-1 c'-5 g-3 f-2] a''-\flageolet
-\end{mudela}
-
-Bowing
-\begin[fragment,verbatim,center]{mudela}
-c-\upbow d-\downbow
-\end{mudela}
-
-Footwork
-\begin[fragment,verbatim,center]{mudela}
-\clef "bass"; \octave c;
- 'b4.-\lheel [cis8-\ltoe dis8-\rtoe e8-\rheel]
-\end{mudela}
-
\section{Chords and Voices}
Here's a simple chord
\end{document}
+% kut en peer.
+
+\begin{verbatim}
+
+% twinkle, v1
+\score {
+ \melodic {
+ c4 c4 g4 g4 a4 a4 g2
+ f4 f4 e4 e4 d4 d4 c2
+ }
+ \paper {}
+}
+\end{verbatim}
+
+there are a few things to note about this example:
+
+The braces are grouping characters. In general, in mudela data entry
+for a data section called ``foobar'' looks like this:
+
+\begin{verbatim}
+\foobar { ...... }
+\end{verbatim}
+
+To see if it actually works, we run it through LilyPond. Invoke the
+command
+\begin{verbatim}
+ lilypond twinkle.ly
+\end{verbatim}
+When LilyPond starts working it will produce various ``operator
+pacification'' messages, which you can safely ignore for now. The run
+should have left a file called \file{lelie.tex} in your working
+directory. You can process that file with \TeX, and it will look like
+this:
+
+\begin{mudela}
+\score {
+ \melodic {
+ c4 c4 g4 g4 a4 a4 g2
+ f4 f4 e4 e4 d4 d4 c2
+ }
+ \paper {}
+}
+\end{mudela}
+
+As you can see, this is the song that we wanted, albeit a little
+low-pitched. You would probably want a version of the song which has
+all notes an octave higher. This can be done by adding a
+\verb+\octave+ command to the source. This sets the default octave
+for all notes. Another convenience is the default duration: if you do
+not specify a duration with the notename, the last explicitly entered
+is used. The improved version reads thus
+
+
+\begin[verbatim]{mudela}
+ % twinkle v2
+\score {
+ \melodic {
+ \octave c';
+ c4 c g g a a g2
+ f4 f e e d d c2
+ }
+ \paper {}
+}
+\end{mudela}
+
+
+
+FIXME rewrite starting here.
+
+\begin[verbatim]{mudela}
+ \score {
+ \melodic { % {...} is a voice
+ c'4 g'4 % c and g are pitches, 4 is the duration
+ % (crotchet/quarter note)
+ c''4 ''c4 % c' is 1 octave up, 'c 1 down.
+ <c'4 g'4> % <...> is a chord
+ }
+}
+\end{mudela}
+
+
+\begin[fragment,verbatim]{mudela}
+ { c4 e4 g4 }
+\end{mudela}
+
+Basics: the \verb+%+ introduces a comment. All music is inside a
+\verb+\score+ block which represents one movement, ie one contiguous
+block of music. Voices are grouped by \verb+{+ and \verb+}+ and
+chords by \verb+<+ and \verb+>+.
+
+
+The \verb+\octave+ command controls the default pitch (octave). If you
+do not specify duration, the last one entered is used. The
+\verb+\paper+ block contains parameters for spacing and dimensions.
+
projects / lilypond.git / commitdiff