From 74974cbb8d12ae3a8994b80f2c4d70a87d406474 Mon Sep 17 00:00:00 2001 From: Han-Wen Nienhuys Date: Mon, 8 Jul 2002 23:37:28 +0000 Subject: [PATCH] intro, tut --- Documentation/user/introduction.itely | 119 ++++++++----- Documentation/user/preface.itely | 4 + Documentation/user/tutorial.itely | 241 ++++++++++++++------------ 3 files changed, 201 insertions(+), 163 deletions(-) diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index 4e4a4d5610..5d0109babd 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -148,54 +148,77 @@ down-up combination should be put closer. The first two measures are printed with this correction, the last two measures without. The notes in the last two measures form downstem/upstems clumps of notes. -Experts have the knowledge to make such adjustments themselves by -hand. For a skilled engraver, a computer drawing program is sufficient -to produce excellent music typography. However, laypeople don't have -the knowledge to think of such details. For a musician, the interface -of a program should be familiar. This is a place where there is a -choice of two paradigms: most musicians are familiar with notation, -and with music. Most graphically oriented programs offer an interface -that shows notation, and allow you to enter the music by placing notes -on a staff. - - -Interactive programs always have to load and save their data from -files on the disk. In a program that deals with music notation, the -notation always has to converted to some kind of representation of the -music inside. - -[todo] - - -When we view the problem of making beautiful sheet music for a given -piece of music as a scientific puzzle, then we can only solve that -puzzle if it is well-stated. Hence, when we design an input format, we -want it to be neatly defined and have precise semantics. Such formats -also have the advantage of being easier to write code for. - - -Many music encodings exist today but most of the encodings have not -been tailored either for human use, or for processing it with a -computer. By its nature, LilyPond input has both features: it is -concise, suitable for human input, and it can be processed -automatically: it may be converted into MIDI or into print. - - -However, one big problem with music, is that there are no standards -for encoding music. Sure, you can record performances using MIDI, but -that offers far too little information for adequate musicological -purposes. With LilyPond we've taken a reverse approach: we have tried -to come up with musical format that can cater virtually all music as -long as it can be notated. - -LilyPond input focuses on musical concepts such as pitch, duration and -music expressions. Musical data is rhythmic, and implies an ordering -of events. This ordering is used to create compound musical concepts: -Large musical structures are built recursively from smaller -expressions: a sequence of music expressions forms a new, longer and -bigger music expression. In this sense, the input is recursive. It -shares this property with very music encodings. The recursive nature -will appeal to the more hackerish musician. +We hope that these examples serve to show that music typography is a +subtle business, and that it requires skill and knowledge to produce +good engraving---skill and knowledge most people lack. It was our +challenge to see if we could put such knowledge into a computer +program. + +One of the first questions that pop up when you design such a program, +is what kind of input the program should expect. Many music notation +programs offer a graphical interface that shows notation, and allows +you to enter the music by placing notes on a staff. Although this is a +obvious way to design a program, from our point of view, this is +cheating. After all, the core message of a piece of music notation +simply is the music itself. If you start by offering music notation to +the user, you have already skipped one conversion, even if it perhaps +is implicit. If we want to generate music notation, then the obvious +candidate for the source format should be the music itself. + +Of course, on paper this theory sounds very good. In practice, it +opens a can of worms. What really @emph{is} music? Many philosophical +treatises must have been written on the subject. Even if you're more +practically inclined, you will notice that an enormous number of +different ways to represent music in a computer exist, and they are +much more incompatible than the formats for wordprocessors and +spreadsheets. Anyone who has tried to exchange data files from +between different computer programs can attest to this. + +The cause of this problem is that music is inherently two-dimensional: +in polyphonic music, notes have time and pitch as their two +coordinates, and they often are related in both directions. Computer +files on the other hand are essentially one-dimensional: they are a +long stream of characters. When you represent music in a file, then +you have to flatten this two-dimensional information breaking the +timing or the pitch, relations, and there is no universal agreement on +how to do this. + +It might seem that when designing a music representation, we have +myriad of choices. Luckily, we have some requirements that shaped the +input format into what it is now. A music representation is about +@emph{music}, so it should be free from notation as much as possible: +the format is about pitches and durations, not about symbols and +offsets. Since LilyPond is a compiler, the input format is its user +interface, and users have to key in the music into the file directly, +requiring that the input format has a friendly syntax. We, as +programmers and scientists also like the format to have a clean formal +definition. After all, producing music notation is a difficult +problem, and in the scientific world, difficult problems always must +be well-specified. Moreover, formally defined formats are easier to +write programs for. Finally, enough information should be present to +be able to produce a printed score. + +These ideas shaped music representation elegantly builds complex +musical constructs from simple entities like notes and rests, in much +the same way that one builds complex formulae from simple expressions +such as numbers and mathematical operators. + +The strict separation between musical information and typesetting also +gives a blueprint of the program: first it reads the music +representation, then it interprets the music---reading it +`left-to-right', and translating the musical information to a layout +specification. When the layout is computed, the resulting symbols are +written to an output file. + +Much more could be said about the inner working of the program, but we +will leave it at this. Those who are interested can inspect the source +code, which is available freely, or inquire on the development mailing +list. + +We hope that you understand where LilyPond came from, and what we +tried to achieve. The rest of this manual less philosophical: it +instructs you how use the input language to print beautiful music. + diff --git a/Documentation/user/preface.itely b/Documentation/user/preface.itely index 5e33dd5ed5..5829a8fa3b 100644 --- a/Documentation/user/preface.itely +++ b/Documentation/user/preface.itely @@ -33,6 +33,10 @@ Jeremie Lumbroso, should mention many more people, these are from AUTHORS @end ignore +We always maintain that wrote this program to satisfy our curiosity, +to have fun together, to help people, but ultimately, LilyPond is a +way to express our deep love for music. May it help you create lots of +beautiful music! Han-Wen and Jan diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index a79be72b54..5ab44df9fb 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -12,6 +12,7 @@ @menu * First steps:: Music language of LilyPond * Running LilyPond:: Printing music +* More basics:: * Printing lyrics:: * A melody with chords :: * More stanzas:: @@ -241,8 +242,127 @@ LilyPond source file looks like: @separate +@node Running LilyPond +@section Running LilyPond + +In the last section, we explained what kind of things you could enter +in a lilypond file. In this section we explain how to run LilyPond, +and how view or print the output. If you have not used LilyPond +before, want to test your setup of LilyPond, or try to run an example +file yourself, then read this section. The instructions that follow +are for running LilyPond on Unix-like systems. Some additional +instructions for running LilyPond on Windows are given at the end of +this section. + +You begin with opening a terminal window, and start up a text editor. +For example, open an xterm and execute @code{joe}. In your text editor, +enter the following input, and save the file as @file{test.ly}: + +@quotation +@example +\score @{ + \notes @{ c'4 e' g' @} +@} +@end example +@end quotation + +@cindex ly2dvi + +@c now this is weird, running ly2dvi to run LilyPond +@c (therefore name change proposal) + +LilyPond is the program that computes the sheet music. All other +things, such as adding titles, page breaking and other page layout, +are done by a small wrapper program called +@code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and +then adds the titling and page layout instructions. To process +@file{test.ly} with ly2dvi, proceed as follows: + +@quotation +@example +ly2dvi -P test.ly +@end example +@end quotation + +You will see the following on your screen: + +@quotation +@example +GNU LilyPond 1.4.0 +Now processing: `/home/fred/ly/test.ly' +Parsing... +Interpreting music...[1] + @emph{ ... more interesting stuff ... } +PS output to `test.ps'... +DVI output to `test.dvi'... +@end example +@end quotation +@cindex DVI file +@cindex Viewing music +@cindex xdvi + +The results of the ly2dvi run are two files, @file{test.dvi} and +@file{test.ps}. The PS file (@file{test.ps}) is the one you can print. +You can view the PS file using the program ghostview. If a version of +ghostview is installed on your system, one of these commands will +produce a window with some music notation on your screen: +@c eeek +@quotation +@example + gv test.ps + ghostview test.ps + ggv test.ps + kghostview test.ps +@end example +@end quotation +If you are satisfied with the looks of the music displayed on your +screen, you can print the PS file by clicking File/Print inside +ghostview. + +The DVI file (@file{test.dvi}) contains the same sheet music in a +different format. DVI files are more easily processed by the computer, +so viewing them usually is quicker. Execute @code{xdvi test.dvi} +to view the DVI file. + +If your DVI viewer does not have a "Print" button, you can print the +file by executing @code{lpr test.ps}. + +@c volgende alinea schrappen? + +If you can't get the examples to print, then you should look into +installing and configuring ghostscript. Refer to GhostScript's website +at @uref{http://www.ghostscript.com}. + +@cindex GhostScript +@cindex @code{lpr} +@cindex Printing output +@cindex PostScript + +@unnumberedsubsec Windows users +Windows users start the terminal by clicking on the LilyPond or Cygwin +icon. Notepad is sufficient for editing the LilyPond file. Viewing +the PS file can be done with: +@quotation +@example +@code{gsview32 test.ps} +@end example +@end quotation +You can also print from the command line by executing: +@quotation +@example +@code{gsview32 /s test.ps} +@end example +@end quotation + + @strong{SUMMARY} +To run LilyPond, enter a file, and run the command @code{ly2dvi} on +that file. The resulting files are either DVI or PostScript, and can +be viewed with @code{xdvi} (unix) and ghostview (unix and windows) +respectively. The following table summarizes the constructs that were +discussed in the previous two sections. + @multitable @columnfractions .3 .3 .4 @item @b{Syntax} @@ -302,12 +422,12 @@ s16_" " @end multitable -@c maybe legend here? - +@node More basics +@section More basics We continue with the introduction of the remaining musical constructs. - -Normal rests are entered just like notes with the name ``@code{r}'': +Normal rests are entered just like notes, but use the name +``@code{r}'': @quotation @example @@ -483,6 +603,8 @@ For example: @code{c f,} goes down; @code{f, f} are both the same; @strong{SUMMARY} +The following table summarizes the syntax learned in this section. + @multitable @columnfractions .3 .3 .4 @item @b{Syntax} @@ -842,117 +964,6 @@ lyrics, chords, orchestral scores and parts, fine tuning output, polyphonic music, and integrating text and music. -@node Running LilyPond -@section Running LilyPond - -In the last section, we explained what kind of things you could enter -in a lilypond file. In this section we explain how to run LilyPond, -and how view or print the output. If you have not used LilyPond -before, want to test your setup of LilyPond, or try to run an example -file yourself, then read this section. The instructions that follow -are for running LilyPond on Unix-like systems. Some additional -instructions for running LilyPond on Windows are given at the end of -this section. - -You begin with opening a terminal window, and start up a text editor. -For example, open an xterm and execute @code{joe}. In your text editor, -enter the following input, and save the file as @file{test.ly}: - -@quotation -@example -\score @{ - \notes @{ c'4 e' g' @} -@} -@end example -@end quotation - -@cindex ly2dvi - -@c now this is weird, running ly2dvi to run LilyPond -@c (therefore name change proposal) - -LilyPond is the program that computes the sheet music. All other -things, such as adding titles, page breaking and other page layout, -are done by a small wrapper program called -@code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and -then adds the titling and page layout instructions. To process -@file{test.ly} with ly2dvi, proceed as follows: - -@quotation -@example -ly2dvi -P test.ly -@end example -@end quotation - -You will see the following on your screen: - -@quotation -@example -GNU LilyPond 1.4.0 -Now processing: `/home/fred/ly/test.ly' -Parsing... -Interpreting music...[1] - @emph{ ... more interesting stuff ... } -PS output to `test.ps'... -DVI output to `test.dvi'... -@end example -@end quotation -@cindex DVI file -@cindex Viewing music -@cindex xdvi - -The results of the ly2dvi run are two files, @file{test.dvi} and -@file{test.ps}. The PS file (@file{test.ps}) is the one you can print. -You can view the PS file using the program ghostview. If a version of -ghostview is installed on your system, one of these commands will -produce a window with some music notation on your screen: -@c eeek -@quotation -@example - gv test.ps - ghostview test.ps - ggv test.ps - kghostview test.ps -@end example -@end quotation -If you are satisfied with the looks of the music displayed on your -screen, you can print the PS file by clicking File/Print inside -ghostview. - -The DVI file (@file{test.dvi}) contains the same sheet music in a -different format. DVI files are more easily processed by the computer, -so viewing them usually is quicker. Execute @code{xdvi test.dvi} -to view the DVI file. - -If your DVI viewer does not have a "Print" button, you can print the -file by executing @code{lpr test.ps}. - -@c volgende alinea schrappen? - -If you can't get the examples to print, then you should look into -installing and configuring ghostscript. Refer to GhostScript's website -at @uref{http://www.ghostscript.com}. - -@cindex GhostScript -@cindex @code{lpr} -@cindex Printing output -@cindex PostScript - -@unnumberedsubsec Windows users -Windows users start the terminal by clicking on the LilyPond or Cygwin -icon. Notepad is sufficient for editing the LilyPond file. Viewing -the PS file can be done with: -@quotation -@example -@code{gsview32 test.ps} -@end example -@end quotation -You can also print from the command line by executing: -@quotation -@example -@code{gsview32 /s test.ps} -@end example -@end quotation -- 2.39.5