@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.
@c INCLUDES
-@include learning/introduction.itely
+@include learning/tutorial.itely
@include learning/common-notation.itely
@include learning/fundamental.itely
@include learning/tweaks.itely
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::
+++ /dev/null
-@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
-
-
-
--- /dev/null
+@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
+
+
+
projects / lilypond.git / commitdiff