X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=765bd4aff14c58efd9975298da541a818ef53f38;hb=3dd560c0c440c9e97730ca13f6d5abbb020bb02e;hp=eee42edf36c931903cca77068e23f7670c55c6b5;hpb=db3257e9d02cd10450dd4324ca1c6c0854ad23c4;p=lilypond.git diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index eee42edf36..765bd4aff1 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -31,8 +31,9 @@ Tutorial guidelines: (different from policy.txt!) @chapter Tutorial This tutorial starts with an introduction to the LilyPond music -language and how to produce printed music. After this first -contact we will explain how to create common musical notation. +language and explains how to produce printed music. After this first +contact we will explain how to create beautiful printed music +containing common musical notation. @menu * First steps:: @@ -59,7 +60,11 @@ This section gives a basic introduction to working with LilyPond. @node Compiling a file @subsection Compiling a file -The first example demonstrates how to start working with LilyPond. +@qq{Compiling} is the term used for processing an input text file +in LilyPond format to produce a file which can be printed and +(optionally) a MIDI file which can be played. The first example +shows what a simple input text file looks like. + To create sheet music, we write a text file that specifies the notation. For example, if we write: @@ -79,8 +84,8 @@ the result looks like this: } @end lilypond -@warning{Every piece of LilyPond input needs to have -@strong{@{ curly braces @}} placed around the input. The braces +@warning{Notes and lyrics in LilyPond input must always be +surrounded by @strong{@{ curly braces @}}. The braces should also be surrounded by a space unless they are at the beginning or end of a line to avoid ambiguities. The braces may be omitted in some examples in this manual, but don't forget them @@ -106,7 +111,7 @@ Note that there are several other text editors available with better support for LilyPond. For more information, see @rprogram{Text editor support}. -@warning{the first time you ever run LilyPond, it may take a +@warning{The first time you ever run LilyPond, it may take a minute or two because all of the system fonts have to be analyzed first. After this, LilyPond will be much faster!} @@ -138,7 +143,10 @@ pointer. To edit an existing @file{.ly} file, right-click on it and select @qq{Edit source}. To get an empty file to start from, run the editor as described above and use @qq{New} in -the @qq{File} menu. +the @qq{File} menu, or right-click on the desktop and select +@qq{New..Text Document}, change its name to a name of your choice +and change the file extension to @code{.ly}. Double-click the +icon to type in your LilyPond source code as before. Double-clicking the file does not only result in a PDF file, but also produces a @file{.log} file that contains some information on @@ -147,7 +155,7 @@ examine this file. @subsubheading Unix -Create a file (such as @file{test.ly}) and enter: +Create a text file called @file{test.ly} and enter: @example @{ @@ -260,9 +268,9 @@ above the B, and an A, G or F will be assumed to be below. b c % c is 1 staff space up, so is the c above b d % d is 2 up or 5 down, so is the d above b e % e is 3 up or 4 down, so is the e above - b a % a is 4 up or 3 down, so is the a below + b a % a is 6 up or 1 down, so is the a below b g % g is 5 up or 2 down, so is the g below - b f % f is 6 up or 1 down, so is the f below + b f % f is 4 up or 3 down, so is the f below } @end lilypond @@ -290,7 +298,7 @@ To change a note by two (or more!) octaves, we use multiple quotes @code{''} and not one double quote @code{"}@tie{}! The initial value in @code{\relative c'} may also be modified like this. - +@c " - keeps quotes in order for context-sensitive editor -td @subheading Durations (rhythms) @@ -407,7 +415,7 @@ Notation Reference: @ruser{Writing pitches}, LilyPond input files are similar to source files in many common programming languages. They are case sensitive, and white-space -is generally equivalent. Expressions are formed with curly braces +is generally ignored. Expressions are formed with curly braces @{ @}, and comments are denoted with @code{%} or @code{%@{ ... %@}}. @@ -454,8 +462,9 @@ that the input is a single music expression, just like parentheses space unless they are at the beginning or end of a line to avoid ambiguities. -A function (such as @code{\relative @{ @}}) also counts as a -single music expression. +A LilyPond command followed by a simple expression in braces (such +as @code{\relative @{ @}}) also counts as a single music +expression. @cindex comments @cindex line comment @@ -466,10 +475,22 @@ a comment is a remark for the human reader of the music input; it is ignored while parsing, so it has no effect on the printed output. There are two types of comments. The percent symbol @code{%} introduces a line comment; anything after @code{%} on -that line is ignored. A block comment marks a whole section of -music input as a comment. Anything that is enclosed in @code{%@{} -and @code{%@}} is ignored. (Comments do not nest.) The following -fragment shows possible uses for comments: +that line is ignored. By convention, a line comment is placed +@emph{above} the code it refers to. + +@example +a4 a a a +% this comment refers to the Bs +b2 b +@end example + +A block comment marks a whole section of music input as a comment. +Anything that is enclosed in @code{%@{} and @code{%@}} is ignored. +However, block comments do not @q{nest}. This means that you +cannot place a block comment inside another block comment. If you +try, the first @code{%@}} will terminate @emph{both} block +comments. The following fragment shows possible uses for +comments: @example % notes for twinkle twinkle follow @@ -538,7 +559,8 @@ cut-&-pastable section} to the bottom of the file. There are more tips for constructing input files in -@ref{Suggestions for writing LilyPond files}. +@ref{Suggestions for writing LilyPond files}. But it might be +best to read through the rest of the tutorial first. @@ -609,7 +631,7 @@ note's @notation{pitch}! This is a feature that often causes confusion to newcomers, so let us explain it in more detail. LilyPond makes a sharp distinction between musical content and -layout. The alteration (@notation{flat}, @notation{natural} or +layout. The alteration (@notation{flat}, @notation{natural sign} or @notation{sharp}) of a note is part of the pitch, and is therefore musical content. Whether an accidental (a @emph{printed} flat, natural or sharp sign) is printed in front of the corresponding @@ -627,8 +649,8 @@ d cis fis @end lilypond @noindent -No note has a printed accidental, but you must still add the -@code{is} to @code{cis} and @code{fis}. +No note has a printed accidental, but you must still add +@code{is} and type @code{cis} and @code{fis} in the input file. The code @code{e} does not mean @qq{print a black dot just below the first line of the staff.} Rather, it means @qq{there is a @@ -689,12 +711,12 @@ d4( c16) cis( d e c cis d) e( d4) @cindex phrasing slurs @subheading Phrasing slurs -Music Glossary: @rglos{phrasing}, @rglos{legato}. +Music Glossary: @rglos{slurs}, @rglos{phrasing}. Slurs to indicate longer @notation{phrasing} can be entered with -@code{\(} and @code{\)}. You can have both @notation{legato} -slurs and phrasing slurs at the same time, but you cannot have -simultaneous legato slurs or simultaneous phrasing slurs. +@code{\(} and @code{\)}. You can have both @notation{slurs} +and phrasing slurs at the same time, but you cannot have +simultaneous slurs or simultaneous phrasing slurs. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] a8(\( ais b c) cis2 b'2 a4 cis,\) @@ -780,8 +802,8 @@ c\ff c\mf c\p c\pp @cindex crescendo @notation{Crescendi} and @notation{decrescendi} are started with -the commands @code{\<} and @code{\>}. An ending dynamic, for -example @code{\f}, will finish the (de)crescendo, or the command +the commands @code{\<} and @code{\>}. The next dynamics sign, for +example @code{\f}, will end the (de)crescendo, or the command @code{\!} can be used: @lilypond[verbatim,quote,ragged-right,fragment,relative=2] @@ -790,7 +812,7 @@ c2\< c2\ff\> c2 c2\! @seealso -Notation Reference: @ruser{Articulations}, +Notation Reference: @ruser{Articulations and ornamentations}, @ruser{Fingering instructions}, @ruser{Dynamics}. @@ -887,7 +909,7 @@ Triplets make notes occupy 2/3 of their notated duration, so a @cindex appoggiatura @subheading Grace notes -Music Glossary: @rglos{grace notes}, @rglos{acciacccatura}, +Music Glossary: @rglos{grace notes}, @rglos{acciaccatura}, @rglos{appoggiatura}. @notation{Grace notes} are created with the @code{\grace} command, @@ -958,8 +980,8 @@ one). The result is another music expression: This mechanism is similar to mathematical formulas: a big formula is created by composing small formulas. Such formulas are called -expressions, and they can contain other music expressions, so you -can make arbitrarily complex and large expressions. For example, +expressions, and they can contain other expressions, so you can +make arbitrarily complex and large expressions. For example, @example 1 @@ -1008,6 +1030,7 @@ different amount of space. LilyPond does not care how much (or little) space there is at the beginning of a line, but indenting LilyPond code like this makes it much easier for humans to read. +@c FIXME: number of backslashes?! works in html but not pdf. @warning{each note is relative to the previous note in the input, not relative to the @code{c''} in the initial @code{\\relative} command.} @@ -1016,9 +1039,9 @@ the input, not relative to the @code{c''} in the initial @subheading Simultaneous music expressions: single staff To determine the number of staves in a piece, LilyPond looks at -the first expression. If it is a single note, there is one staff; -if there is a simultaneous expression, there is more than one -staff. +the beginning of the first expression. If is a single note, there +is one staff; if there is a simultaneous expression, there is more +than one staff. @lilypond[verbatim,quote,ragged-right] \relative c'' { @@ -1065,13 +1088,11 @@ creates a bigger music expression. In this way it resembles the minus sign in mathematics. The formula @math{(4+5)} is an expression, so @math{-(4+5)} is a bigger expression. -Time signatures entered in one staff affect all other -staves@footnote{This behavior may be changed if desired; for -details, see @ruser{Polymetric notation}.}. On the other hand, -the key signature of one staff does @emph{not} affect other -staves. This different default behaviour is because scores with -transposing instruments are more common than polyrhythmic -scores. +Time signatures entered in one staff affects all other staves by +default. On the other hand, the key signature of one staff does +@emph{not} affect other staves. This different default behaviour +is because scores with transposing instruments are more common +than polyrhythmic scores. @lilypond[verbatim,quote,ragged-right] \relative c'' { @@ -1124,7 +1145,7 @@ scores, and @code{\new ChoirStaff,} suitable for vocal scores. These staff groups each form another type of context, one that generates the brace at the left end of every system and also controls the extent -of barlines. +of bar lines. @seealso @@ -1139,10 +1160,12 @@ Notation Reference: @ruser{Piano music}, Music Glossary: @rglos{chord}. -@notation{Chords} can be made by surrounding pitches with single -angle brackets. Note that all the notes in a chord must have the -same duration, and that duration is placed after the closing -bracket. +We saw earlier how notes can be combined into @notation{chords} by +indicating they are simultaneous by enclosing them in double angle +brackets. However, the normal way of indicating a chord is to +surround the pitches with @emph{single} angle brackets. Note that +all the notes in a chord must have the same duration, and that the +duration is placed after the closing bracket. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] r4 4 2 @@ -1150,16 +1173,13 @@ r4 4 2 Think of chords as almost equivalent to single notes: almost everything you can attach to a single note can be attached -to a chord, and everything must go @emph{outside} the angle -brackets. For example, you can combine markings like beams and +to a chord, and everything must go @emph{outside} the angle +brackets. For example, you can combine markings like beams and ties with chords. They must be placed outside the angle brackets. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] r4 8[ ]~ 2 -@end lilypond - -@lilypond[verbatim,quote,ragged-right,fragment,relative=2] -r4 8\>( 4 \!) +r4 8( \> 4 \!) @end lilypond @@ -1328,7 +1348,7 @@ Here we have also used manual beaming (the square brackets @code{[ (see @ref{Automatic and manual beams}). As an alternative to using slurs, the melismata may be indicated -just in the lyrics by using an underscore, @code{_}, for each +in just the lyrics by using an underscore, @code{_}, for each note that should be included in the melisma: @lilypond[verbatim,quote,ragged-right] @@ -1455,7 +1475,7 @@ example from Handel's Judas Maccabæus: @noindent but scores any more complex than this simple example are better produced by separating out the staff structure -from the notes and lyrics with variables. These +from the notes and lyrics with variables. These are discussed in @ref{Organizing pieces with variables}. @seealso @@ -1565,7 +1585,7 @@ The @code{\version} statement records the version of LilyPond that was used to write the file: @example -\version "2.11.23" +\version "2.11.38" @end example @noindent @@ -1587,7 +1607,7 @@ main music expression; the @code{\header} block is usually placed underneath the @ref{Version number}. @example -\version "2.11.23" +\version "2.11.38" \header @{ title = "Symphony" composer = "Me" @@ -1702,3 +1722,4 @@ you have more experience. +