then process it with the menu command @samp{Compile > Typeset File}.
The resulting PDF file will be displayed on your screen.
-Be warned that the first time you ever run lilypond will take a minute
+Be warned that the first time you ever run LilyPond, it will take a minute
or two because all of the system fonts have to be analyzed first.
For future use of LilyPond, you should begin by selecting "New"
-or "Open".
+or "Open". You must save your file before typesetting it. If any errors
+occur in processing, please see the log window.
@subsubheading Windows
Save it on the desktop as @file{test.ly} and make sure that it is not
called @file{test.ly.TXT}. Double clicking @file{test.ly} will process
-the file and show the resulting PDF file.
+the file and show the resulting PDF file. To edit an existing
+@file{.ly} file, right-click on it and select @qq{Edit source}.
+
+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. 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.
+
+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.
@subsubheading Unix
example, you could open an xterm and execute
@code{joe}@footnote{There are macro files for VIM addicts, and there
is a @code{LilyPond-mode} for Emacs addicts. If they have not been
-installed already, refer to the file @file{INSTALL.txt}. These
+installed already, refer to the file @file{INSTALL.txt}. The
easiest editing environment is @file{LilyPondTool}. See
@ref{Editor support} for more information.}. In your
text editor, enter the following input and save the file as
@end lilypond
Putting a group of music expressions (e.g. notes) in braces means that
-are in sequence (i.e. each one follows the previous one). The result
+they are in sequence (i.e. each one follows the previous one). The result
is another music expression:
@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
This technique is useful for polyphonic music. To enter music
with more voices or more staves, we combine expressions in
-parallel. To indicate that two voices should play at the same time
-simple enter a simultaneous combination of music expressions. A
+parallel. To indicate that two voices should play at the same time,
+simply enter a simultaneous combination of music expressions. A
@q{simultaneous} music expression is formed by enclosing expressions inside
@code{<<} and @code{>>}. In the following example, three sequences (all
containing two separate notes) are combined simultaneously:
is at the beginning of a line, but indenting LilyPond code like this makes
it much easier for humans to read.
+@strong{Warning}: each note is relative to the
+previous note in the input, not relative to the @code{c''} in the
+initial @code{\relative} command.
+
+
@subheading Simultaneous music expressions: single staff
To determine the number of staves in a piece, LilyPond looks at the first
-exression. If it is a single note, there is one staff; if there is a
+expression. If it is a single note, there is one staff; if there is a
simultaneous expression, there is more than one staff.
@lilypond[quote,ragged-right,verbatim]
@end lilypond
You can combine markings like beams and ties with chords. They must
-be placed outside the angled brackets
+be placed outside the angle brackets
@lilypond[quote,fragment,verbatim,relative=2,fragment]
r4 <c e g>8[ <c f a>]~ <c f a>2
@lilypond[quote,ragged-right,verbatim]
\relative c'' {
- a4 e c r4
+ a4 e c8 e r4
b2 c4( d)
}
@end lilypond
@lilypond[quote,ragged-right,verbatim]
<<
\relative c'' {
- a4 e c r4
+ a4 e c8 e r4
b2 c4( d)
}
\addlyrics { One day this shall be free }
@lilypond[quote,ragged-right,verbatim]
<<
\relative c'' {
- a4 e c r4
+ a4 e c8 e r4
b2 c4( d)
}
\addlyrics { One day this shall be free __ }
@cindex chords
@cindex chord names
-@c TODO: revise this, \chords { } is shorter and more intuitive.
-@c I need help for this. -gp
-
In popular music it is common to denote accompaniment with chord names.
Such chords can be entered like notes,
\chordmode { c2 f4. g8 }
@end lilypond
-@noindent
Now each pitch is read as the root of a chord instead of a note.
-This mode is switched on with @code{\chordmode}
-
-Other chords can be created by adding modifiers after a colon. The
-following example shows a few common modifiers
+This mode is switched on with @code{\chordmode}. Other chords can be
+created by adding modifiers after a colon. The
+following example shows a few common modifiers:
@lilypond[quote,verbatim,ragged-right]
\chordmode { c2 f4:m g4:maj7 gis1:dim7 }
line for themselves. This is achieved by using @code{\chords} instead
of @code{\chordmode}. This uses the same syntax as @code{\chordmode},
but renders the notes in a @code{ChordNames} context, with the
-following result.
+following result:
@lilypond[quote,verbatim,ragged-right]
\chords { c2 f4.:m g4.:maj7 gis8:dim7 }
@cindex lead sheet
When put together, chord names, lyrics and a melody form
-a lead sheet, for example,
+a lead sheet,
@lilypond[quote,verbatim,ragged-right]
-% this melody needs to be changed. See my new example in 2.4.1. -gp
<<
- \chords { r2 c:sus4 f }
- \relative {
- r4 c' \times 2/3 { f g g }
- \times 2/3 { g4( a2) }
+ \chords { c2 g:sus4 f e }
+ \relative c'' {
+ a4 e c8 e r4
+ b2 c4( d)
}
- \addlyrics { I want to break free __ }
+ \addlyrics { One day this shall be free __ }
>>
@end lilypond
+
+@moreinfo
+@quotation
A complete list of modifiers and other options for layout can be found
in @ref{Chords}.
+@end quotation
@node Final touches
music with many staves, the input files can become very confusing. We can
reduce this confusion by using @emph{identifiers}.
-Identifiers (also known as variables or macros), we can break up
+With identifiers (also known as variables or macros), we can break up
complex music expressions. An identifier is assigned as follows
@example
@end lilypond
@noindent
-The name of an identifier should have alphabetic characters only: no
+The name of an identifier must have alphabetic characters only: no
numbers, underscores, or dashes.
It is possible to use variables for many other types of objects in the
* Style sheets::
* Updating old files::
* Troubleshooting (taking it all apart)::
+* Minimal examples::
@end menu
Now start slowly uncommenting more and more of the
@code{bass} part until you find the problem line.
+Another very useful debugging technique is constructing
+@ref{Minimal examples}.
+
+
+@node Minimal examples
+@section Minimal examples
+
+A minimal example is an example which is small as possible. These
+examples are much easier to understand than long examples. Minimal
+examples are used for
+
+@itemize
+@item Bug reports
+@item Sending a help request to mailists
+@item Adding an example to the @uref{http://lsr@/.dsi@/.unimi/2.it/,LilyPond
+Snippet Repository}
+@end itemize
+
+To construct an example which is as small as possible, the rule is
+quite simple: remove anything which is not necessary. When trying to
+remove unnecessary parts of a file, it is a very good idea to comment
+out lines instead of deleting them. That way, if you discover that you
+actually @emph{do} need some lines, you can un-comment them, instead of
+typing them in from scratch.
+
+There are two exceptions to the @qq{as small as possible} rule:
+
+@itemize
+@item Include the @code{\version} number.
+@item If possible, use @code{\paper@{ ragged-right=##t @}} at the
+top of your example.
+@end itemize
+
+The whole point of a minimal example is to make it easy to read:
+
+@itemize
+@item Avoid using complicated notes, keys, or time signatures, unless you
+wish to demonstrate something is about the behavior of those items.
+@item Do not use \override commands unless that is the point of the
+example.
+@end itemize
+
projects / lilypond.git / commitdiff