From fc11a72feed378a63094042acc3ec644a344a5e1 Mon Sep 17 00:00:00 2001 From: hanwen Date: Tue, 22 Jul 2003 12:18:53 +0000 Subject: [PATCH] * Documentation/user/introduction.itely: revise * Documentation/user/tutorial.itely: reorganise. --- ChangeLog | 4 + Documentation/user/introduction.itely | 198 +++++++------- Documentation/user/tutorial.itely | 467 +++++++++++++++++++--------------- 3 files changed, 368 insertions(+), 301 deletions(-) diff --git a/ChangeLog b/ChangeLog index 4e77c536d4..bd294082d8 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,9 @@ 2003-07-22 Han-Wen Nienhuys + * Documentation/user/introduction.itely: revise + + * Documentation/user/tutorial.itely: reorganise. + * Documentation/topdocs/index.tely: remove. * Documentation/header.html.in: prune. diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index 3c9f721797..be8d69730c 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -192,34 +192,30 @@ in the last two measures form down-stem/up-stems clumps of notes. @node Typography and program architecture @section Typography and program architecture -Producing good engraving requires skill and knowledge. It was our -challenge to see if we could put such typographical knowledge into a -computer program. Capturing that knowledge has two aspects: first, it -has to be acquired. Then, it has to be encoded in data-structures and -algorithms. As the previous examples show, there is a lot of subtlety -involved in music engraving, and unfortunately, only a small fraction -of these details are documented. - -One reason for the time that it takes to become a master engraver, is -that all these details must be learned either from experience or from -other engravers: as an engraver gets older and wiser, he will be able +Producing good engraving requires skill and knowledge. As the +previous examples show, there is a lot of subtlety involved in music +engraving, and unfortunately, only a small fraction of these details +are documented. Master engraver must learn all these details from +experience or from other engravers, which is why it takes so long to +become a master. As an engraver gets older and wiser, he will be able to produce better and more complex pieces. A similar situation is -present when putting typography into computer programs. It is not -possible to come up with a final solution for a problem at the first -try. Instead, we start out with simple solution that might cover 75% -of the cases, and gradually refine that solution over the course of -months or years, so that 90 or 95 % of the cases are handled. - -This has an important implication for the design of the -program. During development, almost every piece of formatting code -must be considered as temporary. When the need arises, is to be -replaced a solution that will cover even more cases. A clean way to -accomplish this, is a ``plug-in'' architecture: an architecture where -new pieces of code can be inserted in the program dynamically. In -such a program, a new solution can be developed along-side the -existing code. It can be perfected separately until it is better than -the existing solution, at which point, the new solution is switched on -by default, and the old one is removed. +present when putting typographical knowledge into a computer program. +It is not possible to come up with a definitive solution for a problem +at the first try. Instead, we start out with simple solution that +might cover 75% of the cases, and gradually refine that solution over +the course of months or years, so 90 or 95 % of the cases are +handled. + +This has an important implication for the design of the program: at +any time, almost every piece of formatting code must be considered as +temporary. When the need arises, it is to be replaced a solution that +will cover even more cases. is A ``plug-in'' architecture is a clean +way to accomplish this. This is an architecture where new pieces of +code can be inserted in the program dynamically. In such a program, a +new solution can be developed along-side the existing code. For +testing, it is plugged in, but for production use, the old solution is +used. The new module can be perfected separately until it is better +than the existing solution, at which point it replaces the old one. Until that time, users must have a way to deal with imperfections: these 25%, 10% or 5% of the cases that are not handled @@ -229,8 +225,9 @@ in generic variables, and let the user manipulate these variables. For example, consider the following fragment of notation. @lilypond -\score { \notes { - g'4-\f g4 +\score { \notes \relative c'' { +\stemUp + c4-\f f4 } \paper { raggedright = ##t } } @@ -243,21 +240,23 @@ general. This may be remedied by inserting extra space between the high note and the `f', as shown in this example @lilypond -\score { \notes { +\score { \notes \relative c'' { +\stemUp \once\property Voice. DynamicLineSpanner \override #'padding = #4.0 - g'4-\f g4 + c4-\f f4 } \paper { raggedright = ##t } } @end lilypond -This was achieved with the input statement +This was achieved with the following input statement. @example - \property Voice. DynamicLineSpanner \override #'padding = #4.0 + \once \property Voice. DynamicLineSpanner \override #'padding = #4.0 @end example -which increases the amount of space (@code{padding}) between the note -and the dynamic symbol to 4.0 (which is measured in staff space, so -4.0 equals the height of a staff). +It increases the amount of space (@code{padding}) between the note and +the dynamic symbol to 4.0 (which is measured in staff space, so 4.0 +equals the height of a staff). The keyword @code{\once} indicates that +this is a tweak: it is only done one time. Both design aspects, a plug-in architecture, and formatting variables, are built on top of GUILE, an interpreter for the programming language @@ -270,11 +269,12 @@ Consider the case of a publisher that is not satisfied with the in the default layout, and wants heavier stems. Normally, they are @code{1.3} times the thickness of staff lines, but suppose that their editions require them to be twice the thickness of the staff lines. The same -mechanism can be used to adjust a setting globally. By issuing +mechanism can be used to adjust a setting globally. By issuing the +following command, the entire piece is now formatted with thicker stems: @example \property Score.Stem \override #'thickness = #2.0 @end example -the entire piece is formatted with thick stems: + @lilypond \score { \notes { \property Score.Stem \override #'thickness = #2.0 @@ -310,22 +310,25 @@ The full scope of this functionality certainly is intimidating, but there is no need to fear: normally, it is not necessary to define style-sheets or rewrite formatting functions. In fact, LilyPond gets a lot of formatting right automatically, so adjusting individual layout -situations is not needed very often at all. +situations is not needed often at all. @node Music representation @section Music representation -One of the big questions when writing batch programs, is what kind of -input the program should expect. Many music notation programs offer a -graphical interface that shows notation, and allow you to enter the -music by placing notes on a staff. From our point of view, this design -is a form of cheating. After all, the core message of a piece of music -notation simply is the music itself. If you start by offering notation -to the user, you have already skipped one conversion, even if it is -implicit. If we want to generate music notation from something else, -then the obvious candidate for the source is the music itself. +Our premise is that LilyPond is a system that does music formatting +completely automatically. Under this assumption, the output does not +have to be touched up. Consequently, an interactive display of the +output, where it is possible to reposition notation elements, is +superfluous. This implies that the program should be a batch program: +the input is entered in a file, which is @emph{compiled}, i.e. then +put through the program. The final output is produced as a file ready +to view or print. The compiler fills in all the details of the +notation, those details should be left out of the input file. In other +words, the input should mirror the content as closely as possible. In +the case of music notation the content is the music itself, so that is +what the input should consist of. On paper this theory sounds very good. In practice, it opens a can of worms. What really @emph{is} music? Many philosophical treatises must @@ -344,27 +347,29 @@ definition exactly the musical meaning of the score. There are also more practical concerns. Our users have to key in the music into the file directly, so the input format should have a friendly syntax: a quarter note C is entered as @code{c4}, the code -@code{r8.} signifies a dotted eighth rest. - -As programmers and scientists, we want a clean formal -definition. After all, producing music notation is a difficult -problem, and problems can only be solved if they are -well-specified. Moreover, formally defined formats are easier to write -programs for. We have chosen for a format that is based on music -expressions: complex musical constructs are built from simple entities -like notes and rests in much the same way that complex formulas are -built from simple expressions such as numbers and mathematical -operators. The language is described by a context-free -grammar. Reading such languages robustly is a well studied problem, -and we use a standard solution to do it. - -LilyPond is a batch program, so the syntax of the program is its -user-interface. It is the part that they see most, so it is easy to -think that music representation is a very important or interesting -problem. In reality, less than 10% of the source code of the program -handles reading and representing the input, and they form the easy -bits of the program. Converting the music to notation, and calculating -a pretty layout is much more difficult. +@code{r8.} signifies a dotted eighth rest. Notes and rests form the +simplest musical expressions in the input syntax. More complex +constructs are produced by combining them into compound +structures. This is done s in much the same way that complex +mathematical formulas are built from simple expressions such as +numbers and operators. + +In effect, the input format is a language, and the rules of that +language can be specified succinctly with a so-called context-free +grammar. The grammar formally specificies what types of input form +valid `sentences.' Reading such languages, and splitting them into +grammatical structures is a problem with standard solutions. +Moreover, they make the format easier to understand: a a concise +formal definition permits a simple informal description. + +The user-interface of LilyPond is its syntax. That part is what users +see most. As a results, some users think that music representation is +a very important or interesting problem. In reality, less than 10% of +the source code of the program handles reading and representing the +input, and they form the easy bits of the program. In our opinion, +producing music notation, and formatting it prettily are the +interesting and important parts: they take up most of the bulk of the +code, and are the most difficult things to get right. @node Example applications @section Example applications @@ -379,6 +384,7 @@ simplest application is printing notes. @end lilypond By adding chord names and lyrics we obtain a lead sheet: + @lilypond[raggedright] \score { < \context ChordNames \chords { c2 c f2 c } @@ -391,11 +397,12 @@ example combines some more exotic constructs. @lilypondfile{screech-boink.ly} -The fragments shown above have all been written by hand, but that is not -a requirement. Since the formatting engine is mostly automatic, it can -serve as an output means for other programs that manipulate music. It -can also be used to convert databases of musical fragments to images for -use on websites on multimedia presentations. +The fragments shown above have all been written by hand, but that is +not a requirement. Since the formatting engine is mostly automatic, it +can serve as an output means for other programs that manipulate +music. For example, it can also be used to convert databases of +musical fragments to images for use on websites and multimedia +presentations. This manual also shows an application: the input format is plain text, and can therefore be easily embedded in other text-based formats, such @@ -422,7 +429,14 @@ First time users should start here. The @end ifhtml @emph{@ref{Notation manual}} -discusses topics grouped by notation construct. +discusses topics grouped by notation construct. Once you master the +basics, this is the place to lookup details. +@item +@ifhtml +The +@end ifhtml +@emph{@ref{Literature}} +chapter lists useful reference books on notation and engraving. @item @ifhtml The @@ -455,18 +469,16 @@ browser. @cindex search in manual @cindex using the manual -@c TODO: advise to buy a book on notation? If you are not familiar with music notation, or music terminology -(especially if you are a foreigner), then it is advisable to consult -the glossary as well. The glossary explains musical terms, and -includes translations to various languages. It is a +(especially if you are a non-native English speaker), then it is +advisable to consult the glossary as well. The glossary explains +musical terms, and includes translations to various languages. It is a @ifhtml @uref{../glossary.html,separate document} @end ifhtml @ifnothtml -separate document, available in HTML and PDF and can be printed as -well. +separate document, available in HTML and PDF. @end ifnothtml @cindex idiom @cindex jargon @@ -486,17 +498,17 @@ Generated internal documentation. available @uref{../lilypond-internals/lilypond-internals.html,here} @end ifhtml -The generated internal documentation is a heavily crosslinked HTML -document, produced directly from the formatting definitions used. It -documents the nit-gritty details of each and every LilyPond class, -object and function. +The generated internal documentation is a set of heavily crosslinked +HTML pages, which documents the nit-gritty details of each and every +LilyPond class, object and function. It is produced directly from the +formatting definitions used. Almost all formatting functionality that is used internally, is available directly to the user. For example, all variables that control thicknesses, distances, etc, can be changed in input files. There are a huge number of formatting options, and all of them are described in the generated documentation. Each section of the -reference manual has a @b{See also} subsection, which refers to the +notation manual has a @b{See also} subsection, which refers to the the generated documentation. In the HTML document, these subsections have clickable links. @@ -508,7 +520,7 @@ have clickable links. After you have gone through the tutorial, in theory you should be able to write input files. In practice, writing files from scratch turns -out to be intimidating. To give a headstart, we have collected a +out to be intimidating. To give you a headstart, we have collected a number of often-used formats in example files. These files can be used as a start, by copying the template, and adding notes in the appropriate places. @@ -530,14 +542,18 @@ big HTML document, with pictures and explanatory texts included. available @uref{../../../input/regression/out-www/collated-files.html,here} @end ifhtml -We strive to test each feature in one test file. This collection is -primarilyt there to help us debug problems, but it can be instructive -to see how we excercise the program. The format is like the tips and -tricks document. +This collection of files tests each notation and engraving feature of +LilyPond in one file. The collection is primarily there to help us +debug problems, but it can be instructive to see how we excercise the +program. The format is like the tips and tricks document. @end itemize +In all HTML documents that have music fragments embedded, the LilyPond +input that was used to produce that image can be viewed by clicking +the image. + The location of the documentation files that are mentioned here can vary from system to system. On occasion, this manual refers to initialization and example files. Throughout this manual, we refer to diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index eee67cf14e..f5d7ea39be 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -15,7 +15,12 @@ @menu * First steps:: Music language of LilyPond. * Running LilyPond:: Printing music. -* More basics:: +* More about pitches and accidentals:: +* Octave entry :: +* Relative octave entry:: +* Combining music into compound expressions:: +* Adding articulation marks to notes :: +* Combining notes into chords:: * Printing lyrics:: * A lead sheet:: * Listening to output:: @@ -29,16 +34,28 @@ * Integrating text and music:: Integrating text and music. @end menu -Printing music with LilyPond is a two step process. First, the music -to be printed is described in a text file. After that, LilyPond reads -this @emph{input file} that describes the music and produces an -@emph{output file} that can be printed or viewed. - -This tutorial starts with a short introduction to the LilyPond music -language. After this first contact, we will show you how to to -produce printed output, normally using the program @code{ly2dvi}. You -should then be able to create and print your first sheets of music. -Before starting out, it will be convenient for you to print +Using LilyPond comes down to encoding music in an input file. After +entering the music, the program is run on the file producing output +which can be viewed or printed. In this tutorial, we will show step +by step how to enter such files, by showing fragments of input and the +corresponding output. At the end of every section, a paragraph will +list where to find further information on the topics discussed. + +Many people learn programs by trying and fiddling around with the +program. This is also possible with LilyPond. If you click on a +picture in the HTML version of this manual, you will see the exact +LilyPond input that was used to generate that image. +@ifhtml +For example, +@lilypond[relative 1,verbatim,singleline] + c'^\markup { \bold \huge { Click on this image! } } +@end lilypond +As you can see, most of input shown is simplified a little. This has +been done for reasons of space and clarity. +@end ifhtml +By cutting and pasting that into your own files, you have a starting +template for experiments. If you like learning in this way, you will +probably want to print out or bookmark @ifhtml the @end ifhtml @@ -46,6 +63,11 @@ the reference. +This tutorial starts with a short introduction to the LilyPond music +language. After this first contact, we will show you how to to +produce printed output, normally using the program @code{ly2dvi}. You +should then be able to create and print your first sheets of music. + @node First steps @section First steps @@ -69,9 +91,6 @@ then the result looks like this: c d e f g a b @end lilypond -We will continue with this format: First we show a snippet of input, -then the resulting output. - The length of a note is specified by adding a number, @samp{1} for a @rglos{whole note}, @samp{2} for a @rglos{half note}, and so on: @@ -96,21 +115,25 @@ a4 a a2 a \transpose c c' { a a a2 a s16_" " } @end lilypond -A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a -@rglos{flat} (@texiflat{}) by adding @samp{es}. As you might expect, -a @rglos{double sharp} or @rglos{double flat} is made by adding -@samp{isis} or @samp{eses}:@footnote{This syntax derived from note -naming conventions in Nordic and Germanic languages, like German and -Dutch.} +Rests are entered just like notes, but with the name ``@code{r}'': + +@cindex rests +@quotation @example -cis1 ees fisis aeses +r2 r4 r8 r16 @end example -@lilypond[notime] +@lilypond[fragment] \property Score.timing = ##f -\transpose c c' { cis1 ees fisis aeses s16_" " } +\property Staff.Clef = \turnOff +\property Staff.TimeSignature = \turnOff +r2 r4 r8 r16 +s16_" " @end lilypond +@end quotation +@separate + Add a dot @samp{.} after the duration to get a @rglos{dotted note}: @@ -123,9 +146,6 @@ a2. a4 a8. a16 \transpose c c' { a2. a4 a8. a16 s16_" " } @end lilypond -Entering pitches and durations is fully explained in @ref{Pitches} and -@ref{Durations}. - The @rglos{meter} (or @rglos{time signature}) can be set with the @code{\time} command: @@ -147,9 +167,6 @@ s4_" " s16_" " @end lilypond -Time signatures and other timing commands are described in @ref{Time -signature}. - The @rglos{clef} can be set using the @code{\clef} command: @@ -175,27 +192,26 @@ s4_" " s16_" " @end lilypond -Clefs are fully explained in @ref{Clef}. - - -These commands must be enclosed in @code{\notes @{@dots{}@}}. This -indicates that music (as opposed to @rglos{lyrics}) follows: +Notes and commands like @code{\clef} and @code{\time} , are enclosed +in @code{\notes @{@dots{}@}}. This indicates that music (as opposed +to @rglos{lyrics}) follows: @example \notes @{ \time 3/4 \clef bass c2 e4 g2. - f4 e d c2. + f4 e d c2 r4 @} @end example Now the piece of music is almost ready to be printed. The final step is to combine the music with a printing command. -The printing command is the so-called @code{\paper} block. Later on -you will see that the @code{\paper} block is used to customize -printing specifics. The music and the @code{\paper} block are combined by -enclosing them in @code{\score @{ ... @}}. This is what a full source file looks like: +The printing command is the so-called @code{\paper} block. The +@code{\paper} block is used to customize printing specifics, but we +accept the defaults for now. The music and the @code{\paper} block +are combined by enclosing them in @code{\score @{ ... @}}. The +following is a complete and valid input file. @example \score @{ @@ -203,7 +219,7 @@ enclosing them in @code{\score @{ ... @}}. This is what a full source file look \time 3/4 \clef bass c2 e4 g2. - f4 e d c2. + f4 e d c2 r4 @} \paper @{ @} @} @@ -215,7 +231,7 @@ enclosing them in @code{\score @{ ... @}}. This is what a full source file look \time 3/4 \clef bass c2 e4 g2. - f4 e d c2. + f4 e d c2 r4 } \paper { linewidth = 55 * \staffspace @@ -223,6 +239,15 @@ enclosing them in @code{\score @{ ... @}}. This is what a full source file look } @end lilypond +During the rest of the tutorial, we will often leave out @code{\score} +and @code{\paper}, for clarity. However, both must be present when +feeding the file to LilyPond. + +More elaborate information on entering pitches and durations is in +@ref{Pitches} and @ref{Durations}. Clefs are fully explained in +@ref{Clef}. Time signatures and other timing commands are described +in @ref{Time signature}. + @node Running LilyPond @section Running LilyPond @@ -232,8 +257,8 @@ in a LilyPond file. In this section we explain what commands to run and how to view or print the output. If you have not used LilyPond before, want to test your setup, or want to run an example file yourself, read this section. The instructions that follow are for -Unix-like systems. Some additional instructions for Microsoft Windows are given -at the end of this section. +Unix-like systems. Some additional instructions for Microsoft Windows +are given at the end of this section. Begin by opening a terminal window and starting a text editor. For example, you could open an xterm and execute @code{joe}. In your @@ -266,11 +291,11 @@ ly2dvi -p test.ly @end example @end quotation -You will see the following on your screen: +You will see something resembling: @quotation @example -GNU LilyPond 1.7.16 +GNU LilyPond 1.8.0 Now processing: `/home/fred/ly/test.ly' Parsing... Interpreting music...[1] @@ -283,12 +308,17 @@ DVI output to `test.dvi'... @cindex Viewing music @cindex xdvi -The results of the ly2dvi run are two files, @file{test.dvi} and -@file{test.pdf}. The PDF file (@file{test.pdf}) is the one you can -print or view. For example, viewing PDF can be done with 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: +The result of the ly2dvi is the file @file{test.pdf}.@footnote{ For +@TeX{} afficionados, there is also a (@file{test.dvi}) file. It can be +viewed with @code{xdvi}. The DVI uses a lot of PostScript specials, +which do not show up in the magnifying glass. The specials also mean +that the DVI file cannot be processed with @code{dvilj}. Use +@code{dvips} for printing. +@cindex dvips +@cindex dvilj +@cindex DVI driver +} One the following commands should put the PDF on your +screen. @c eeek @quotation @example @@ -298,22 +328,11 @@ screen: kghostview test.pdf xpdf test.pdf gpdf test.pdf + acroread test.pdf @end example @end quotation If the music on your screen looks good, you can print it 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. You can run @code{xdvi test.dvi} -@c KDVI doesn't grok the PS specials. -@c or -@c @code{kdvi test.dvi} -@c -to view the DVI file. In Xdvi, the mouse buttons -activate magnifying glasses. Unfortunately, variable symbols (such as -beams and slurs) are not displayed in the magnifying glasses. - +File/Print inside your viewing program. @cindex Ghostscript @cindex @code{lpr} @@ -321,113 +340,50 @@ beams and slurs) are not displayed in the magnifying glasses. @cindex PostScript @cindex PDF -If you are familiar with @TeX{}, be warned: do not use other DVI -drivers like @code{dvilj}. LilyPond DVI use embedded PostScript code -and will not render correctly with other DVI drivers besides -@code{dvips}. - -@cindex dvips -@cindex dvilj -@cindex DVI driver - - -Various commands for formatting and printing music are detailed in -@ref{Invoking LilyPond}. - - -@unnumberedsubsec Windows users On Windows, the terminal is started by clicking on the LilyPond or Cygwin icon. Any text editor (such as NotePad, Emacs or Vim) may be -used to edit the LilyPond file. When Cygwin's @code{XFree86} X11 -window system is installed along with @code{tetex-x11} and -@code{ghostscript-x11} packages, then the @code{dvi} output may be -viewed with @code{xdvi test.dvi} as described above. If you have -installed a PostScript/PDF viewer, such as @code{GSView} from -@uref{http://www.cs.wisc.edu/~ghost}, viewing the PDF file can be done -with: +used to edit the LilyPond file. If you have a PDF viewer installed, +use that for viewing the PDF +@c where on file system for double-click people? +If you have no viewer, then you can download @code{GSView} from +@uref{http://www.cs.wisc.edu/~ghost}. With @code{GSView}, +the PDF file can viewed with @quotation @example @code{gsview32 test.pdf} @end example @end quotation -Printing may be done by executing +Printing may be done with @quotation @example @code{gsview32 /s test.pdf} @end example @end quotation +The commands for formatting and printing music are detailed in +@ref{Invoking LilyPond}. -@node More basics -@section More basics - -We continue with the introduction of more musical constructs. Normal -rests are entered just like notes with the name ``@code{r}'': - -@cindex rests -@quotation -@example -r2 r4 r8 r16 -@end example - -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.Clef = \turnOff -\property Staff.TimeSignature = \turnOff -r2 r4 r8 r16 -s16_" " -@end lilypond -@end quotation -@separate - -Rests are described in full detail in @ref{Rests}. - - -@c Tim wants to move this quotes example just before the: quotes-do not-work -@c score, but we'd need to remove quotes from the other two (key and -@c tie) examples... +@node More about pitches and accidentals +@section More about pitches and accidentals -@c better to have this just before the `octaves are bad' snipped -@c but we'd need to remove the ', from \key and tie -To raise a note by an octave, add a high quote @code{'} (apostrophe) to -the note name, to lower a note one octave, add a ``low quote'' @code{,} -(a comma). Middle C is @code{c'}: +A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a +@rglos{flat} (@texiflat{}) by adding @samp{es}. As you might expect, +a @rglos{double sharp} or @rglos{double flat} is made by adding +@samp{isis} or @samp{eses}:@footnote{This syntax derived from note +naming conventions in Nordic and Germanic languages, like German and +Dutch.} -@quotation @example -c'4 c'' c''' \clef bass c c, +cis1 ees fisis aeses @end example -@lilypond[fragment] +@lilypond[notime] \property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -c'4 c'' c''' \clef bass c c, +\transpose c c' { cis1 ees fisis aeses s16_" " } @end lilypond -@end quotation -@separate -@cindex tie -A tie is created by adding a tilde ``@code{~}'' to the first note -being tied. -@quotation -@lilypond[fragment,verbatim] -g'4-~ g' a'2-~ a'4 -@end lilypond -@end quotation -@separate -@cindex slurs versus ties -A tie is different from a slur. A tie simply makes the first note -sound longer, and can only be used on pairs of notes with the same -pitch. Slurs indicate the articulations of notes, and can be used on -larger groups of notes. Slurs and ties are also nested in practice: -@lilypond[fragment, relative=1] -c2-~-( c8 fis fis4 ~ fis2 g2-) -@end lilypond - -The notation manual discusses ties in @ref{Ties}. - @cindex key signature, setting The key signature is set with the command ``@code{\key}'', followed by @@ -435,9 +391,9 @@ a pitch and @code{\major} or @code{\minor}: @quotation @example \key d \major -g'1 +g1 \key c \minor -g' +g @end example @lilypond[fragment] @@ -450,22 +406,29 @@ g' @end quotation +@cindex tie +A tie is created by adding a tilde ``@code{~}'' to the first note +being tied. +@quotation +@lilypond[fragment,verbatim,relative 2] +g4-~ g a2-~ a4 +@end lilypond +@end quotation +@separate -@c bit on the long/complex/scary taste -@c cheating a bit: two lines makes for a friendlier look -This example shows notes, ties, octave marks, and rests in action. +This example shows the key signature, accidentals and ties in action. @quotation @example \score @{ \notes @{ \time 4/4 - \key d \minor + \key g \minor \clef violin - r4 r8 d''8 cis''4 e'' - d''8 a'4.-~ a' b'8 - cis''4 cis''8 cis'' bis'4 d''8 cis''-~ - cis''2 r2 + r4 r8 a8 gis4 b + g8 d4.-~ d' e'8 + fis4 fis8 fis8 eis4 a8 gis-~ + gis2 r2 @} \paper @{ @} @} @@ -473,43 +436,89 @@ This example shows notes, ties, octave marks, and rests in action. @lilypond \score { - \notes { + \notes { \transpose c c' { \time 4/4 + \key g \minor \clef violin - \key d \minor - r4 r8 d''8 cis''4 e'' - d''8 a'4.-~ a' b'8 - cis''4 cis''8 cis'' bis'4 d''8 cis''-~ - cis''2 r2 - } - \paper { linewidth = 50*\staffspace } + r4 r8 a8 gis4 b + g8 d4.-~ d' e'8 + fis4 fis8 fis8 eis4 a8 gis-~ + gis2 r2 + }} + \paper { linewidth = #(* 50 staffspace) } } @end lilypond @end quotation - @cindex accidentals -There are some interesting points to note in this example. +There are some interesting points to note in this example. Bar lines +and beams are drawn automatically. Line breaks are calculated +automatically; it does not matter where the lines breaks are in the +source file. Finally, the order of time, key and clef changes is not +relevant: in the printout, these are ordered according to standard +notation conventions. + Accidentals (sharps and flats) do not have to be marked explicitly: -you just enter the note name, and an accidental is printed -automatically, only when necessary. Bar lines and beams are drawn -automatically. Line breaks are calculated automatically; it does not -matter where the lines breaks are in the source file. Finally, the -order of time, key and clef changes is not relevant: in the printout, -these are ordered using standard notation conventions. - -The example also indicates that a piece of music written in a high -register needs lots of quotes. This makes the input less readable, -and is also a potential source of errors. - -The solution is to use ``relative octave'' mode. In practice, this is -the most convenient way to copy existing music. To use relative mode, -add @code{\relative} before the piece of music. You must also give a -note from which relative starts, in this case @code{c''}. If you do -not use octavation quotes (i.e. do not add ' or , after a note), -relative mode chooses the note that is closest to the previous one. -@c do not use commas or quotes in this sentence -For example: @code{c f} goes up; @code{c g} goes down: +you just enter the pitch of the note, and an accidental is printed +only when necessary. The flip side of this mechanism, is that you have +to mark notes as sharp or flat, even when they do not get accidentals. +For example, in the key of C-sharp major, no note gets an explicit +accidental, but still you enter +@lilypond[fragment,verbatim] +\clef bass +\key cis \major +cis dis eis fis gis ais bis +@end lilypond + +Adding all alterations explicitly might require some more effort when +typing, but the advantage is that transposing is easier. It also makes +it possible to use different conventions for when to print +accidentals. + +@node Octave entry +@section Octave entry + + +@c Tim wants to move this quotes example just before the: quotes-do not-work +@c score, but we'd need to remove quotes from the other two (key and +@c tie) examples... + +@c better to have this just before the `octaves are bad' snipped +@c but we'd need to remove the ', from \key and tie +To raise a note by an octave, add a high quote @code{'} (apostrophe) to +the note name, to lower a note one octave, add a ``low quote'' @code{,} +(a comma). Middle C is @code{c'}: + +@quotation +@example +c'4 c'' c''' \clef bass c c, +@end example + +@lilypond[fragment] +\property Score.timing = ##f +\property Staff.TimeSignature = \turnOff +c'4 c'' c''' \clef bass c c, +@end lilypond +@end quotation +@separate + +An example of the use of quotes is in the following Mozart fragment. +@lilypond[singleline,fragment,verbatim] + \key a \major + \time 6/8 + cis''8. d''16 cis''8 e''4 e''8 + b'8. cis''16 b'8 d''4 d''8 +@end lilypond + +This example shows that music in a high register needs lots of quotes. +This makes the input less readable, and it is a source of errors. The +solution is to use ``relative octave'' mode. In practice, this is the +most convenient way to copy existing music. To use relative mode, add +@code{\relative} before the piece of music. You must also give a note +from which relative starts, in this case @code{c''}. If you do not +use octavation quotes (i.e. do not add ' or , after a note), relative +mode chooses the note that is closest to the previous one. +For example, @code{c f} goes up while @code{c g} goes down. @quotation @example @@ -530,7 +539,18 @@ For example: @code{c f} goes up; @code{c g} goes down: Since most music has small intervals, in relative mode pieces can be -written almost without using octavation quotes. +written almost without using octavation quotes. In relative mode, the +Mozart example is entered as +@c +@lilypond[singleline,fragment,verbatim] +\relative c'' { + \key a \major + \time 6/8 + cis8. d16 cis8 e4 e8 + b8. cis16 b8 d4 d8 +} +@end lilypond + @c needed better, maybe even redundant explanation @c added another example below. @@ -598,23 +618,11 @@ Here is an example of the difference between relative mode and @end quotation @separate -@cindex slur -A slur is drawn across many notes, and indicates bound articulation -(legato). The starting note and ending note are marked with a -``@code{(}'' and a ``@code{)}'' respectively: -@quotation -@lilypond[fragment,relative 1, verbatim] -d4-( c16-)-( cis d e c cis d e-)-( d4-) -@end lilypond -@end quotation -@separate -@cindex phrasing slurs -If you need two slurs at the same time (one for articulation, one for -phrasing), you can also make a phrasing slur with @code{\(} and -@code{\)}. +@node Relative octave entry +@section Relative octave entry @c lousy example @c ? --hwn @@ -642,15 +650,15 @@ a8-[ ais-] d-[ es r d-] @end quotation @separate -@menu -* Combining music into compound expressions:: -* Adding articulation marks to notes :: -* Basic rhythmical commands:: -* Commenting input files:: -@end menu +Rests are described in full detail in @ref{Rests}. + +The notation manual discusses ties in @ref{Ties}. + + + @node Combining music into compound expressions -@subsection Combining music into compound expressions +@section Combining music into compound expressions To print more than one staff, each piece of music that makes up a staff is marked by adding @code{\context Staff} before it. These @@ -747,7 +755,7 @@ braces at the end of an expression. For example @end example @node Adding articulation marks to notes -@subsection Adding articulation marks to notes +@section Adding articulation marks to notes @cindex articulation @cindex accents @@ -791,6 +799,39 @@ c2-\< c2-\!-\ff c2-\> c2-\! @end quotation @separate + + +@cindex slur + +A slur is drawn across many notes, and indicates bound articulation +(legato). The starting note and ending note are marked with a +``@code{(}'' and a ``@code{)}'' respectively: + +@quotation +@lilypond[fragment,relative 1, verbatim] +d4-( c16-)-( cis d e c cis d e-)-( d4-) +@end lilypond +@end quotation +@separate +@cindex slurs versus ties +A slur is different from a tie. A tie simply makes the first note +sound longer, and can only be used on pairs of notes with the same +pitch. Slurs indicate the articulations of notes, and can be used on +larger groups of notes. Slurs and ties are also nested in practice: +@lilypond[fragment, relative=1] +c2-~-( c8 fis fis4 ~ fis2 g2-) +@end lilypond + +@cindex phrasing slurs +If you need two slurs at the same time (one for articulation, one for +phrasing), you can also make a phrasing slur with @code{\(} and +@code{\)}. + + + +@node Combining notes into chords +@section Combining notes into chords + @cindex chords Chords can be made by surrounding pitches with @code{<<} and @code{>}>: @@ -822,6 +863,12 @@ r4 <>8-\>-( <> <> <>8-\!-) @separate + +@menu +* Basic rhythmical commands:: +* Commenting input files:: +@end menu + @node Basic rhythmical commands @subsection Basic rhythmical commands @@ -1203,7 +1250,7 @@ in @ref{Polyphony}. Piano music is always typeset in two staffs connected by a brace. Printing such a staff is done similar to the polyphonic example in -@ref{More basics}: +@ref{Combining music into compound expressions}: @example < \context Staff = up @{ @dots{} @} \context Staff = down @{ @dots{} @} -- 2.11.4.GIT