From: Graham Percival Date: Sat, 3 Oct 2009 13:48:10 +0000 (+0100) Subject: Doc: rename first chapter of Learning to "Tutorial". X-Git-Tag: release/2.13.6-1~78 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=6534189fd37642e2c934621af55ee8069960ddf1;p=lilypond.git Doc: rename first chapter of Learning to "Tutorial". --- diff --git a/Documentation/learning.tely b/Documentation/learning.tely index 9a618e686d..adcecb5ece 100644 --- a/Documentation/learning.tely +++ b/Documentation/learning.tely @@ -43,7 +43,7 @@ by the authors. @ifnottex @menu -* Introduction:: Basics of typesetting with LilyPond. +* Tutorial:: Basics of typesetting with LilyPond. * Common notation:: Writing very commmon notation. * Fundamental concepts:: Basic concepts required for reading the rest of the manuals. * Tweaking output:: Introduction to modifying output. @@ -66,7 +66,7 @@ Appendices @c INCLUDES -@include learning/introduction.itely +@include learning/tutorial.itely @include learning/common-notation.itely @include learning/fundamental.itely @include learning/tweaks.itely diff --git a/Documentation/learning/common-notation.itely b/Documentation/learning/common-notation.itely index c9eb78dd1d..beb2c84204 100644 --- a/Documentation/learning/common-notation.itely +++ b/Documentation/learning/common-notation.itely @@ -33,7 +33,7 @@ Tutorial guidelines: (different from policy.txt!) This chapter explains how to create beautiful printed music containing common musical notation, following the material in -@ref{Introduction}. +@ref{Tutorial}. @menu * Single staff notation:: diff --git a/Documentation/learning/introduction.itely b/Documentation/learning/introduction.itely deleted file mode 100644 index 7e34c686cc..0000000000 --- a/Documentation/learning/introduction.itely +++ /dev/null @@ -1,742 +0,0 @@ -@c -*- coding: utf-8; mode: texinfo; -*- - -@ignore - Translation of GIT committish: FILL-IN-HEAD-COMMITTISH - - When revising a translation, copy the HEAD committish of the - version that you are working on. See TRANSLATION for details. -@end ignore - -@c \version "2.12.0" - -@node Introduction -@chapter Introduction - -This chapter gives a basic introduction to working with LilyPond. - -@menu -* Compiling a file:: -* How to write input files:: -* How to read the manuals:: -@end menu - -@node Compiling a file -@section Compiling a file - -FIXME: insert text - -@menu -* Entering input:: -* MacOS X:: -* Windows:: -* Command-line:: -@end menu - -@node Entering input -@subsection Entering input - -@cindex compiling -@cindex first example -@cindex example, first -@cindex case sensitive - -@qq{Compiling} is the term used for processing an input file -in LilyPond format to produce a file which can be printed and -(optionally) a MIDI file which can be played. LilyPond input -files are simple text files. The first example -shows what a simple input file looks like. - -To create sheet music, we write an input file that specifies the -notation. For example, if we write: - -@example -@{ - c' e' g' e' -@} -@end example - -@noindent -the result looks like this: - -@c in this case we don't want verbatim -@lilypond[quote] -{ - c' e' g' e' -} -@end lilypond - -@warning{Notes and lyrics in LilyPond input must always be -surrounded by @w{@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 -in your own music! For more information about the display of -examples in the manual, see @ref{How to read the manuals}.} - -In addition, LilyPond input is @strong{case sensitive}. -@w{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will -produce an error message. - - -@smallspace - -@subheading Viewing output - -@c TODO: move index entries -@cindex PDF file -@cindex viewing music -@cindex text editors -@cindex running LilyPond under MacOS X -@cindex MacOS X, running LilyPond -@cindex running LilyPond under Windows -@cindex Windows, running LilyPond -@cindex running LilyPond under Unix -@cindex Unix, running LilyPond - -Producing output depends on your operating system and the -program(s) you use. - -@itemize - -@item -@ref{MacOS X, @sourceimage{logo-macosx,,,}} -@ref{MacOS X, MacOS X} (graphical) - -@item -@ref{Windows, @sourceimage{logo-windows,,,}} -@ref{Windows, Microsoft Windows} (graphical) - -@item -@ref{Command-line, @sourceimage{logo-linux,,,} -@sourceimage{logo-freebsd,,,} -@sourceimage{logo-macosx,,,} -@sourceimage{logo-windows,,,} -} -@ref{Command-line, All operating systems} (command-line) - -@end itemize - -There are several other text editors available with better support -for LilyPond. For more information, see -@rgeneral{Alternate input}. - -@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!} - - -@node MacOS X -@subsection MacOS X - -@warning{These instructions assume that you are using the built-in -LilyPad editor. If you are using any of the programs described in -@rgeneral{Alternate input}, please consult the documentation for -those programs if you have any problems compiling a file.} - - -If you double click @command{LilyPond.app}, it will open with an -example file. Save it, for example, to @file{test.ly} on your -Desktop, and then process it with the menu command -@w{@code{Compile > Typeset File}}. The resulting PDF file will be -displayed on your screen. - -For future use of LilyPond, you should begin by selecting @q{New} -or @q{Open}. You must save your file before typesetting it. If -any errors occur in processing, please see the log window. - -@c FIXME: add screenshots - -@node Windows -@subsection Windows - -@warning{These instructions assume that you are using the built-in -LilyPad editor. If you are using any of the programs described in -@rgeneral{Alternate input}, please consult the documentation for -those programs if you have any problems compiling a file.} - -On Windows, if you double-click in the LilyPond icon on the -Desktop, it will open a simple text editor with an example file. -Save it, for example, to @file{test.ly} on your Desktop and then -double-click on the file to process it (the file icon looks like a -note). After some seconds, you will get a file @file{test.pdf} on -your desktop. Double-click on this PDF file to view the typeset -score. An alternative method to process the @file{test.ly} file -is to drag and drop it onto the LilyPond icon using your mouse -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, 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 -what LilyPond has done to the file. If any errors occur, please -examine this file. - -@c FIXME: add screenshots - - -@node Command-line -@subsection Command-line - -@warning{These instructions assume that you are using commond unix -command-line programs. If you are using any of the programs -described in @rgeneral{Alternate input}, please consult the -documentation for those programs if you have any problems -compiling a file.} - - -Create a text file called @file{test.ly} and enter: - -@example -@{ - c' e' g' e' -@} -@end example - -To process @file{test.ly}, proceed as follows: - -@example -lilypond test.ly -@end example - -@noindent -You will see something resembling: - -@example -lilypond test.ly -GNU LilyPond @version{} -Processing `test.ly' -Parsing... -Interpreting music... -Preprocessing graphical objects... -Finding the ideal number of pages... -Fitting music on 1 page... -Drawing systems... -Layout output to `test.ps'... -Converting to `test.pdf'... -@end example - -You may view or print the resulting @file{text.pdf}. - - -@node How to write input files -@section How to write input files - -FIXME: insert text - -@menu -* Simple notation:: -* Working on input files:: -@end menu - - -@node Simple notation -@subsection Simple notation - -@cindex simple notation -@cindex notation, simple - -LilyPond will add some notation elements automatically. In the -next example, we have only specified four pitches, but LilyPond -has added a clef, time signature, and rhythms. - -@lilypond[verbatim,quote] -{ - c' e' g' e' -} -@end lilypond - -@noindent -This behavior may be altered, but in most cases these automatic -values are useful. - - -@subheading Pitches - -@cindex pitches -@cindex relative mode -@cindex quote, single -@cindex comma -@cindex accidentals and relative mode -@cindex relative mode, and accidentals - -@funindex \relative -@funindex relative -@funindex ' -@funindex , - -Music Glossary: @rglos{pitch}, @rglos{interval}, -@rglos{scale}, @rglos{middle C}, @rglos{octave}, -@rglos{accidental}. - -The easiest way to enter notes is by using @code{\relative} mode. -In this mode, the octave is chosen automatically by assuming the -following note is always to be placed closest to the previous -note, i.e., it is to be placed in the octave which is within three -staff spaces of the previous note. We begin by entering the most -elementary piece of music, a @notation{scale}, in which every note -is within just one staff space of the previous note. - -@lilypond[verbatim,quote] -% set the starting point to middle C -\relative c' { - c d e f - g a b c -} -@end lilypond - -The initial note is @notation{middle C}. Each successive note is -placed closest to the previous note -- in other words, the first -@code{c} is the closest C to middle C. This is followed by the -closest D to the previous note. We can create melodies which have -larger intervals, still using only @code{\relative} mode: - -@lilypond[verbatim,quote] -\relative c' { - d f a g - c b f d -} -@end lilypond - -@noindent -It is not necessary for the first note of the melody to start on -the note which specifies the starting pitch. In the previous -example, the first note -- the @code{d} -- is the closest D to -middle C. - -By adding (or removing) quotes @code{'} or commas @code{,} from -the @code{@w{\relative c' @{}} command, we can change the starting -octave: - -@lilypond[verbatim,quote] -% one octave above middle C -\relative c'' { - e c a c -} -@end lilypond - -Relative mode can be confusing initially, but is the easiest way -to enter most melodies. Let us see how this relative calculation -works in practice. Starting from a B, which is on the middle line -in a treble clef, you can reach a C, D and E within 3 staff spaces -going up, and an A, G and F within 3 staff spaces going down. So -if the note following a B is a C, D or E it will be assumed to be -above the B, and an A, G or F will be assumed to be below. - -@lilypond[verbatim,quote] -\relative c'' { - 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 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 4 up or 3 down, so is the f below -} -@end lilypond - -Exactly the same happens even when any of these notes are -sharpened or flattened. @notation{Accidentals} are -@strong{totally ignored} in the calculation of relative position. -Precisely the same staff space counting is done from a note at any -other position on the staff. - -To add intervals that are larger than three staff spaces, we can -raise the @notation{octave} by adding a single quote @code{'} (or -apostrophe) to the note name. We can lower the octave by adding a -comma @code{,} to the note name. - -@lilypond[verbatim,quote] -\relative c'' { - a a, c' f, - g g'' a,, f' -} -@end lilypond - -@noindent -To change a note by two (or more!) octaves, we use multiple -@code{''} or @code{,,} -- but be careful that you use two single -quotes @code{''} and not one double quote @code{"}@tie{}! The -initial value in @code{@w{\relative c'}} may also be modified like -this. -@c " - keeps quotes in order for context-sensitive editor -td - -@subheading Durations (rhythms) - -@cindex note durations -@cindex durations -@cindex rhythms -@cindex whole note -@cindex half note -@cindex quarter note -@cindex dotted note -@cindex notating durations - -Music Glossary: @rglos{beam}, @rglos{duration}, -@rglos{whole note}, @rglos{half note}, @rglos{quarter note}, -@rglos{dotted note}. - -The @notation{duration} of a note is specified by a number after -the note name: @code{1} for a @notation{whole note}, @code{2} for -a @notation{half note}, @code{4} for a @notation{quarter note} and -so on. @notation{Beams} are added automatically. - -If you do not specify a duration, the previous duration is used -for the next note. The duration of the first note defaults to a -quarter. - -@lilypond[verbatim,quote] -\relative c'' { - a1 - a2 a4 a8 a - a16 a a a a32 a a a a64 a a a a a a a a2 -} -@end lilypond - -To create @notation{dotted notes}, add a dot @code{.} to the -duration number. The duration of a dotted note must be stated -explicitly (i.e., with a number). - -@lilypond[verbatim,quote] -\relative c'' { - a a a4. a8 - a8. a16 a a8. a8 a4. -} -@end lilypond - - -@subheading Rests - -@cindex rest -@cindex notating rests - -Music Glossary: @rglos{rest}. - -A @notation{rest} is entered just like a note with the name -@code{r}@tie{}: - -@lilypond[verbatim,quote] -\relative c'' { - a r r2 - r8 a r4 r4. r8 -} -@end lilypond - - -@subheading Time signature - -@cindex time signature - -@funindex \time -@funindex time - -Music Glossary: @rglos{time signature}. - -The @notation{time signature} can be set with the @code{\time} -command: - -@lilypond[verbatim,quote] -\relative c'' { - \time 3/4 - a4 a a - \time 6/8 - a4. a - \time 4/4 - a4 a a a -} -@end lilypond - - -@subheading Clef - -@cindex clef -@cindex treble -@cindex alto -@cindex tenor -@cindex bass - -@funindex \clef -@funindex clef - -Music Glossary: @rglos{clef}. - -The @notation{clef} can be set using the @code{\clef} command: - -@lilypond[verbatim,quote] -\relative c' { - \clef treble - c1 - \clef alto - c1 - \clef tenor - c1 - \clef bass - c1 -} -@end lilypond - - -@subheading All together - -Here is a small example showing all these elements together: - -@lilypond[verbatim,quote] -\relative c, { - \time 3/4 - \clef bass - c2 e8 c' g'2. - f4 e d c4 c, r4 -} -@end lilypond - - -@seealso -Notation Reference: @ruser{Writing pitches}, -@ruser{Writing rhythms}, @ruser{Writing rests}, -@ruser{Time signature}, @ruser{Clef}. - - -@node Working on input files -@subsection Working on input files - -@cindex curly braces -@cindex braces, curly -@cindex comments -@cindex line comment -@cindex comment, line -@cindex block comment -@cindex comment, line -@cindex case sensitive -@cindex whitespace insensitive -@cindex expressions - -@funindex { ... } -@funindex % -@funindex %@{ ... %@} - -LilyPond input files are similar to source files in many common -programming languages. They are case sensitive, and white-space -is generally ignored. Expressions are formed with curly braces -@{ @}, and comments are denoted with @code{%} or -@w{@code{%@{ ... %@}}}. - -If the previous sentences sound like nonsense, don't worry! We'll -explain what all these terms mean: - -@itemize - -@item -@strong{Case sensitive}: -it matters whether you enter a letter in lower case (e.g. -@w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}). -Notes are lower case: @w{@code{@{ c d e @}}} is valid input; -@w{@code{@{ C D E @}}} will produce an error message. - -@item -@strong{Whitespace insensitive}: -it does not matter how many spaces (or tabs or new lines) you add. -@w{@code{@{ c d e @}}} means the same thing as -@w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and: - -@example -@{ c d - e @} -@end example - -@noindent -Of course, the previous example is hard to read. A good rule of -thumb is to indent code blocks with either a tab or two spaces: - -@example -@{ - c d e -@} -@end example - -However, whitespace @emph{is} required to separate many syntactical -elements from others. In other words, whitespace can always be -@emph{added}, but it cannot be @emph{eliminated}. As missing -whitespace can give rise to strange errors it is advisable to -always insert whitespace before and after every syntactic element, -for example, before and after every curly brace. - -@item -@strong{Expressions}: -every piece of LilyPond input needs to have @strong{@{ curly -braces @}} placed around the input. These braces tell LilyPond -that the input is a single music expression, just like parentheses -@code{()} in mathematics. The braces should be surrounded by a -space unless they are at the beginning or end of a line to avoid -ambiguities. - -A LilyPond command followed by a simple expression in braces (such -as @w{@code{\relative @{ @}}}) also counts as a single music -expression. - -@cindex comments -@cindex line comment -@cindex block comment -@item -@strong{Comments}: -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. 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 - c4 c g' g a a g2 - -%@{ - This line, and the notes below are ignored, - since they are in a block comment. - - f f e e d d c2 -%@} -@end example - -@end itemize - - -@node How to read the manuals -@section How to read the manuals - -FIXME: fluff here - -@menu -* Omitting braces:: -* Clickable examples:: -* Keyboard navigation:: -* Overview of manuals:: -@end menu - - -@node Omitting braces -@subsection Omitting braces - - -@cindex how to read the manual -@cindex manual, reading -@cindex reading the manual -@cindex examples, clickable -@cindex clickable examples -@cindex tips for constructing files -@cindex templates -@cindex constructing files, tips -@cindex files, tips for constructing - -LilyPond input must be surrounded by @{ @} marks or a -@code{@w{\relative c'' @{ ... @}}}, as we saw in @ref{Working on -input files}. For the rest of this manual, most examples will -omit this. To replicate the examples, you may copy and paste the -displayed input, but you @strong{must} add the -@code{@w{\relative c'' @{ @}}} like this: - -@example -\relative c'' @{ - ... example goes here... -@} -@end example - -Why omit the braces? Most examples in this manual can be inserted -into the middle of a longer piece of music. For these examples, -it does not make sense to add @code{@w{\relative c'' @{ @}}} -- -you should not place a @code{\relative} inside another -@code{\relative}! If we included @code{@w{\relative c'' @{ @}}} -around every example, you would not be able to copy a small -documentation example and paste it inside a longer piece of your -own. Most people want to add material to an existing piece, so we -format the manual this way. - - -@node Clickable examples -@subsection Clickable examples - -@warning{This features is only available in the HTML manuals.} - -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. Try it on -this image: - -@c no verbatim here -@lilypond[quote] -\relative c'' { - c-\markup { \bold \huge { Click here. } } -} -@end lilypond - -By cutting and pasting everything in the @qq{ly snippet} section, -you have a starting template for experiments. To see exactly the -same output (line-width and all), copy everything from @qq{Start -cut-&-pastable section} to the bottom of the file. - - -@node Keyboard navigation -@subsection Keyboard navigation - -@warning{This features is only available in the HTML manuals.} - -@c TODO: once this is figured out, insert it here. - -We are currently working on this feature. - - -@node Overview of manuals -@subsection Overview of manuals - -There is a lot of documentation for LilyPond. New users are -sometimes confused about what part(s) they should read, and -occasionally skip over reading vital portions. - -@warning{Please do not skip over important parts of the -documentation. You will find it much harder to understand later -sections.} - -@itemize - -@item -@strong{Before trying to do @emph{anything}}: read the Learning -manual's @ref{Introduction}, and @ref{Common notation}. If you -encounter musical terms which you do not recognize, please look -them up in the @rglosnamed{Top, Glossary}. - -@item -@strong{Before trying to write a complete piece of music}: read -the Learning manual's @ref{Fundamental concepts}. After that, you -may want to look in relevant sections of the -@rusernamed{Top, Notation reference}. - -@item -@strong{Before trying to change the default output}: read the -Learning manual's @ref{Tweaking output}. - -@item -@strong{Before undertaking a large project}: read Usage document's -@rprogram{Suggestions for writing files}. - -@end itemize - - - diff --git a/Documentation/learning/tutorial.itely b/Documentation/learning/tutorial.itely new file mode 100644 index 0000000000..f048922cbc --- /dev/null +++ b/Documentation/learning/tutorial.itely @@ -0,0 +1,742 @@ +@c -*- coding: utf-8; mode: texinfo; -*- + +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore + +@c \version "2.12.0" + +@node Tutorial +@chapter Tutorial + +This chapter gives a basic introduction to working with LilyPond. + +@menu +* Compiling a file:: +* How to write input files:: +* How to read the manuals:: +@end menu + +@node Compiling a file +@section Compiling a file + +FIXME: insert text + +@menu +* Entering input:: +* MacOS X:: +* Windows:: +* Command-line:: +@end menu + +@node Entering input +@subsection Entering input + +@cindex compiling +@cindex first example +@cindex example, first +@cindex case sensitive + +@qq{Compiling} is the term used for processing an input file +in LilyPond format to produce a file which can be printed and +(optionally) a MIDI file which can be played. LilyPond input +files are simple text files. The first example +shows what a simple input file looks like. + +To create sheet music, we write an input file that specifies the +notation. For example, if we write: + +@example +@{ + c' e' g' e' +@} +@end example + +@noindent +the result looks like this: + +@c in this case we don't want verbatim +@lilypond[quote] +{ + c' e' g' e' +} +@end lilypond + +@warning{Notes and lyrics in LilyPond input must always be +surrounded by @w{@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 +in your own music! For more information about the display of +examples in the manual, see @ref{How to read the manuals}.} + +In addition, LilyPond input is @strong{case sensitive}. +@w{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will +produce an error message. + + +@smallspace + +@subheading Viewing output + +@c TODO: move index entries +@cindex PDF file +@cindex viewing music +@cindex text editors +@cindex running LilyPond under MacOS X +@cindex MacOS X, running LilyPond +@cindex running LilyPond under Windows +@cindex Windows, running LilyPond +@cindex running LilyPond under Unix +@cindex Unix, running LilyPond + +Producing output depends on your operating system and the +program(s) you use. + +@itemize + +@item +@ref{MacOS X, @sourceimage{logo-macosx,,,}} +@ref{MacOS X, MacOS X} (graphical) + +@item +@ref{Windows, @sourceimage{logo-windows,,,}} +@ref{Windows, Microsoft Windows} (graphical) + +@item +@ref{Command-line, @sourceimage{logo-linux,,,} +@sourceimage{logo-freebsd,,,} +@sourceimage{logo-macosx,,,} +@sourceimage{logo-windows,,,} +} +@ref{Command-line, All operating systems} (command-line) + +@end itemize + +There are several other text editors available with better support +for LilyPond. For more information, see +@rgeneral{Alternate input}. + +@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!} + + +@node MacOS X +@subsection MacOS X + +@warning{These instructions assume that you are using the built-in +LilyPad editor. If you are using any of the programs described in +@rgeneral{Alternate input}, please consult the documentation for +those programs if you have any problems compiling a file.} + + +If you double click @command{LilyPond.app}, it will open with an +example file. Save it, for example, to @file{test.ly} on your +Desktop, and then process it with the menu command +@w{@code{Compile > Typeset File}}. The resulting PDF file will be +displayed on your screen. + +For future use of LilyPond, you should begin by selecting @q{New} +or @q{Open}. You must save your file before typesetting it. If +any errors occur in processing, please see the log window. + +@c FIXME: add screenshots + +@node Windows +@subsection Windows + +@warning{These instructions assume that you are using the built-in +LilyPad editor. If you are using any of the programs described in +@rgeneral{Alternate input}, please consult the documentation for +those programs if you have any problems compiling a file.} + +On Windows, if you double-click in the LilyPond icon on the +Desktop, it will open a simple text editor with an example file. +Save it, for example, to @file{test.ly} on your Desktop and then +double-click on the file to process it (the file icon looks like a +note). After some seconds, you will get a file @file{test.pdf} on +your desktop. Double-click on this PDF file to view the typeset +score. An alternative method to process the @file{test.ly} file +is to drag and drop it onto the LilyPond icon using your mouse +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, 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 +what LilyPond has done to the file. If any errors occur, please +examine this file. + +@c FIXME: add screenshots + + +@node Command-line +@subsection Command-line + +@warning{These instructions assume that you are using commond unix +command-line programs. If you are using any of the programs +described in @rgeneral{Alternate input}, please consult the +documentation for those programs if you have any problems +compiling a file.} + + +Create a text file called @file{test.ly} and enter: + +@example +@{ + c' e' g' e' +@} +@end example + +To process @file{test.ly}, proceed as follows: + +@example +lilypond test.ly +@end example + +@noindent +You will see something resembling: + +@example +lilypond test.ly +GNU LilyPond @version{} +Processing `test.ly' +Parsing... +Interpreting music... +Preprocessing graphical objects... +Finding the ideal number of pages... +Fitting music on 1 page... +Drawing systems... +Layout output to `test.ps'... +Converting to `test.pdf'... +@end example + +You may view or print the resulting @file{text.pdf}. + + +@node How to write input files +@section How to write input files + +FIXME: insert text + +@menu +* Simple notation:: +* Working on input files:: +@end menu + + +@node Simple notation +@subsection Simple notation + +@cindex simple notation +@cindex notation, simple + +LilyPond will add some notation elements automatically. In the +next example, we have only specified four pitches, but LilyPond +has added a clef, time signature, and rhythms. + +@lilypond[verbatim,quote] +{ + c' e' g' e' +} +@end lilypond + +@noindent +This behavior may be altered, but in most cases these automatic +values are useful. + + +@subheading Pitches + +@cindex pitches +@cindex relative mode +@cindex quote, single +@cindex comma +@cindex accidentals and relative mode +@cindex relative mode, and accidentals + +@funindex \relative +@funindex relative +@funindex ' +@funindex , + +Music Glossary: @rglos{pitch}, @rglos{interval}, +@rglos{scale}, @rglos{middle C}, @rglos{octave}, +@rglos{accidental}. + +The easiest way to enter notes is by using @code{\relative} mode. +In this mode, the octave is chosen automatically by assuming the +following note is always to be placed closest to the previous +note, i.e., it is to be placed in the octave which is within three +staff spaces of the previous note. We begin by entering the most +elementary piece of music, a @notation{scale}, in which every note +is within just one staff space of the previous note. + +@lilypond[verbatim,quote] +% set the starting point to middle C +\relative c' { + c d e f + g a b c +} +@end lilypond + +The initial note is @notation{middle C}. Each successive note is +placed closest to the previous note -- in other words, the first +@code{c} is the closest C to middle C. This is followed by the +closest D to the previous note. We can create melodies which have +larger intervals, still using only @code{\relative} mode: + +@lilypond[verbatim,quote] +\relative c' { + d f a g + c b f d +} +@end lilypond + +@noindent +It is not necessary for the first note of the melody to start on +the note which specifies the starting pitch. In the previous +example, the first note -- the @code{d} -- is the closest D to +middle C. + +By adding (or removing) quotes @code{'} or commas @code{,} from +the @code{@w{\relative c' @{}} command, we can change the starting +octave: + +@lilypond[verbatim,quote] +% one octave above middle C +\relative c'' { + e c a c +} +@end lilypond + +Relative mode can be confusing initially, but is the easiest way +to enter most melodies. Let us see how this relative calculation +works in practice. Starting from a B, which is on the middle line +in a treble clef, you can reach a C, D and E within 3 staff spaces +going up, and an A, G and F within 3 staff spaces going down. So +if the note following a B is a C, D or E it will be assumed to be +above the B, and an A, G or F will be assumed to be below. + +@lilypond[verbatim,quote] +\relative c'' { + 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 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 4 up or 3 down, so is the f below +} +@end lilypond + +Exactly the same happens even when any of these notes are +sharpened or flattened. @notation{Accidentals} are +@strong{totally ignored} in the calculation of relative position. +Precisely the same staff space counting is done from a note at any +other position on the staff. + +To add intervals that are larger than three staff spaces, we can +raise the @notation{octave} by adding a single quote @code{'} (or +apostrophe) to the note name. We can lower the octave by adding a +comma @code{,} to the note name. + +@lilypond[verbatim,quote] +\relative c'' { + a a, c' f, + g g'' a,, f' +} +@end lilypond + +@noindent +To change a note by two (or more!) octaves, we use multiple +@code{''} or @code{,,} -- but be careful that you use two single +quotes @code{''} and not one double quote @code{"}@tie{}! The +initial value in @code{@w{\relative c'}} may also be modified like +this. +@c " - keeps quotes in order for context-sensitive editor -td + +@subheading Durations (rhythms) + +@cindex note durations +@cindex durations +@cindex rhythms +@cindex whole note +@cindex half note +@cindex quarter note +@cindex dotted note +@cindex notating durations + +Music Glossary: @rglos{beam}, @rglos{duration}, +@rglos{whole note}, @rglos{half note}, @rglos{quarter note}, +@rglos{dotted note}. + +The @notation{duration} of a note is specified by a number after +the note name: @code{1} for a @notation{whole note}, @code{2} for +a @notation{half note}, @code{4} for a @notation{quarter note} and +so on. @notation{Beams} are added automatically. + +If you do not specify a duration, the previous duration is used +for the next note. The duration of the first note defaults to a +quarter. + +@lilypond[verbatim,quote] +\relative c'' { + a1 + a2 a4 a8 a + a16 a a a a32 a a a a64 a a a a a a a a2 +} +@end lilypond + +To create @notation{dotted notes}, add a dot @code{.} to the +duration number. The duration of a dotted note must be stated +explicitly (i.e., with a number). + +@lilypond[verbatim,quote] +\relative c'' { + a a a4. a8 + a8. a16 a a8. a8 a4. +} +@end lilypond + + +@subheading Rests + +@cindex rest +@cindex notating rests + +Music Glossary: @rglos{rest}. + +A @notation{rest} is entered just like a note with the name +@code{r}@tie{}: + +@lilypond[verbatim,quote] +\relative c'' { + a r r2 + r8 a r4 r4. r8 +} +@end lilypond + + +@subheading Time signature + +@cindex time signature + +@funindex \time +@funindex time + +Music Glossary: @rglos{time signature}. + +The @notation{time signature} can be set with the @code{\time} +command: + +@lilypond[verbatim,quote] +\relative c'' { + \time 3/4 + a4 a a + \time 6/8 + a4. a + \time 4/4 + a4 a a a +} +@end lilypond + + +@subheading Clef + +@cindex clef +@cindex treble +@cindex alto +@cindex tenor +@cindex bass + +@funindex \clef +@funindex clef + +Music Glossary: @rglos{clef}. + +The @notation{clef} can be set using the @code{\clef} command: + +@lilypond[verbatim,quote] +\relative c' { + \clef treble + c1 + \clef alto + c1 + \clef tenor + c1 + \clef bass + c1 +} +@end lilypond + + +@subheading All together + +Here is a small example showing all these elements together: + +@lilypond[verbatim,quote] +\relative c, { + \time 3/4 + \clef bass + c2 e8 c' g'2. + f4 e d c4 c, r4 +} +@end lilypond + + +@seealso +Notation Reference: @ruser{Writing pitches}, +@ruser{Writing rhythms}, @ruser{Writing rests}, +@ruser{Time signature}, @ruser{Clef}. + + +@node Working on input files +@subsection Working on input files + +@cindex curly braces +@cindex braces, curly +@cindex comments +@cindex line comment +@cindex comment, line +@cindex block comment +@cindex comment, line +@cindex case sensitive +@cindex whitespace insensitive +@cindex expressions + +@funindex { ... } +@funindex % +@funindex %@{ ... %@} + +LilyPond input files are similar to source files in many common +programming languages. They are case sensitive, and white-space +is generally ignored. Expressions are formed with curly braces +@{ @}, and comments are denoted with @code{%} or +@w{@code{%@{ ... %@}}}. + +If the previous sentences sound like nonsense, don't worry! We'll +explain what all these terms mean: + +@itemize + +@item +@strong{Case sensitive}: +it matters whether you enter a letter in lower case (e.g. +@w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}). +Notes are lower case: @w{@code{@{ c d e @}}} is valid input; +@w{@code{@{ C D E @}}} will produce an error message. + +@item +@strong{Whitespace insensitive}: +it does not matter how many spaces (or tabs or new lines) you add. +@w{@code{@{ c d e @}}} means the same thing as +@w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and: + +@example +@{ c d + e @} +@end example + +@noindent +Of course, the previous example is hard to read. A good rule of +thumb is to indent code blocks with either a tab or two spaces: + +@example +@{ + c d e +@} +@end example + +However, whitespace @emph{is} required to separate many syntactical +elements from others. In other words, whitespace can always be +@emph{added}, but it cannot be @emph{eliminated}. As missing +whitespace can give rise to strange errors it is advisable to +always insert whitespace before and after every syntactic element, +for example, before and after every curly brace. + +@item +@strong{Expressions}: +every piece of LilyPond input needs to have @strong{@{ curly +braces @}} placed around the input. These braces tell LilyPond +that the input is a single music expression, just like parentheses +@code{()} in mathematics. The braces should be surrounded by a +space unless they are at the beginning or end of a line to avoid +ambiguities. + +A LilyPond command followed by a simple expression in braces (such +as @w{@code{\relative @{ @}}}) also counts as a single music +expression. + +@cindex comments +@cindex line comment +@cindex block comment +@item +@strong{Comments}: +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. 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 + c4 c g' g a a g2 + +%@{ + This line, and the notes below are ignored, + since they are in a block comment. + + f f e e d d c2 +%@} +@end example + +@end itemize + + +@node How to read the manuals +@section How to read the manuals + +FIXME: fluff here + +@menu +* Omitting braces:: +* Clickable examples:: +* Keyboard navigation:: +* Overview of manuals:: +@end menu + + +@node Omitting braces +@subsection Omitting braces + + +@cindex how to read the manual +@cindex manual, reading +@cindex reading the manual +@cindex examples, clickable +@cindex clickable examples +@cindex tips for constructing files +@cindex templates +@cindex constructing files, tips +@cindex files, tips for constructing + +LilyPond input must be surrounded by @{ @} marks or a +@code{@w{\relative c'' @{ ... @}}}, as we saw in @ref{Working on +input files}. For the rest of this manual, most examples will +omit this. To replicate the examples, you may copy and paste the +displayed input, but you @strong{must} add the +@code{@w{\relative c'' @{ @}}} like this: + +@example +\relative c'' @{ + ... example goes here... +@} +@end example + +Why omit the braces? Most examples in this manual can be inserted +into the middle of a longer piece of music. For these examples, +it does not make sense to add @code{@w{\relative c'' @{ @}}} -- +you should not place a @code{\relative} inside another +@code{\relative}! If we included @code{@w{\relative c'' @{ @}}} +around every example, you would not be able to copy a small +documentation example and paste it inside a longer piece of your +own. Most people want to add material to an existing piece, so we +format the manual this way. + + +@node Clickable examples +@subsection Clickable examples + +@warning{This features is only available in the HTML manuals.} + +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. Try it on +this image: + +@c no verbatim here +@lilypond[quote] +\relative c'' { + c-\markup { \bold \huge { Click here. } } +} +@end lilypond + +By cutting and pasting everything in the @qq{ly snippet} section, +you have a starting template for experiments. To see exactly the +same output (line-width and all), copy everything from @qq{Start +cut-&-pastable section} to the bottom of the file. + + +@node Keyboard navigation +@subsection Keyboard navigation + +@warning{This features is only available in the HTML manuals.} + +@c TODO: once this is figured out, insert it here. + +We are currently working on this feature. + + +@node Overview of manuals +@subsection Overview of manuals + +There is a lot of documentation for LilyPond. New users are +sometimes confused about what part(s) they should read, and +occasionally skip over reading vital portions. + +@warning{Please do not skip over important parts of the +documentation. You will find it much harder to understand later +sections.} + +@itemize + +@item +@strong{Before trying to do @emph{anything}}: read the Learning +manual's @ref{Tutorial}, and @ref{Common notation}. If you +encounter musical terms which you do not recognize, please look +them up in the @rglosnamed{Top, Glossary}. + +@item +@strong{Before trying to write a complete piece of music}: read +the Learning manual's @ref{Fundamental concepts}. After that, you +may want to look in relevant sections of the +@rusernamed{Top, Notation reference}. + +@item +@strong{Before trying to change the default output}: read the +Learning manual's @ref{Tweaking output}. + +@item +@strong{Before undertaking a large project}: read Usage document's +@rprogram{Suggestions for writing files}. + +@end itemize + + +