Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@include included/generating-output.itexi
+
+@c \version "2.14.0"
@node Tutorial
@chapter Tutorial
@menu
* Compiling a file::
* How to write input files::
+* Dealing with errors::
* How to read the manuals::
@end menu
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
+@w{@samp{@{ c d e @}}} is valid input; @w{@samp{@{ C D E @}}} will
produce an error message.
There are several other text editors available with specific
support for LilyPond. For more information, see
-@rweb{Alternate input}.
+@rweb{Easier editing}.
@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!}
-@cindex running LilyPond under MacOS X
-@cindex MacOS X, running LilyPond
@node MacOS X
@subsection MacOS X
-@warning{These instructions assume that you are using the LilyPond
-application. If you are using any of the programs described in
-@rweb{Alternate input}, please consult the documentation for
-those programs if you have any problems.}
-
-
-@subsubheading Step 1. Create your @file{.ly} file
-
-Double click the @command{LilyPond.app}, an example file will open.
-
-@sourceimage{Learning_Macos_welcome,,,}
-
-From the menus along the top left of your screen, select
-@w{@code{File > Save}}.
-
-@sourceimage{Learning_Macos_Save_menu,,,}
-
-Choose a name for your file, for example @file{test.ly}.
-
-@sourceimage{Learning_Macos_Save_file_with_name,,,}
-
-
-@subsubheading Step 2. Compile (with LilyPad)
-
-From the same menus, select
-@w{@code{Compile > Tyepset}}.
-
-@sourceimage{Learning_Macos_Typeset_menu,,,}
-
-A new window will open showing a progress log of the compilation
-of the file you have just saved.
-
-@sourceimage{Learning_Macos_Compiling_log,,,}
-
-
-@subsubheading Step 3. View output
-
-Once the compilation has finished, a PDF file will be created with
-the same name as the original file and will be automatically
-opened in the default PDF viewer and displayed on your screen.
-
-@sourceimage{Learning_Macos_pdf_output,,,}
-
-
-@subsubheading Other commands
-
-To create new files for LilyPond, begin by selecting
-@w{@code{File > New}}
-
-@sourceimage{Learning_Macos_New_menu,,,}
-
-or @w{@code{File > Open}} to open and edit existing files you have
-saved previously.
-
-@sourceimage{Learning_Macos_Open_menu,,,}
-
-You must save any new edits you make to your file before you
-@w{@code{Compile > Tyepset}} and if the PDF file is not displayed
-check the window with the progress log for any errors.
+@cindex running LilyPond under MacOS X
+@cindex MacOS X, running LilyPond
-If you are not using the defualt Preview PDF viewer that comes
-with the Mac Operating system and you have the PDF file generated
-from a previous compilation open, then any further compilations
-may fail to generate an update PDF until you close the original.
+@lilypadOSX
-@cindex running LilyPond under Windows
-@cindex Windows, running LilyPond
@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
-@rweb{Alternate input}, please consult the documentation for
-those programs if you have any problems compiling a file.}
-
-
-@subsubheading Step 1. Create your @file{.ly} file
-
-Double-click the @command{LilyPond.app}, an example file will open.
-
-@sourceimage{Learning_Win7_Welcome_File_Whole,,,}
-
-From the menus that appear alonbg the top of the example file,
-select @w{@code{File > Save as}}. Do not use the @w{@code{File > Save}}
-for the example file as this will not work until you have given it a
-valid Lilypong file name.
-
-@sourceimage{Learning_Win7_Save_Menu,,,}
-
-Choose a name for your file, for example @file{test.ly}.
-
-@sourceimage{Learning_Win7_Save_File_With_Name,,,}
-
-
-@subsubheading Step 2a. Compile (with drag-and-drop)
-
-Depending on what you prefer, to compile your file either:
-
-Drag-and-drop the file directly onto the LilyPond icon.
-
-@sourceimage{Learning_Win7_Open_Dragndrop,,,}
-
-Right-click on the file and from the pop-up context menu choose
-@w{@code{Open with > LilyPond}}.
-
-@sourceimage{Learning_Win7_Open_Context_Menu,,,}
-
-
-@subsubheading Step 2b. Compile (with double-clicking)
-
-Or simply double-click the @file{test.ly}.
-
-
-@subsubheading Step 3. View output
-
-During the compilation of the @file{test.ly} file, a command window
-will, very briefly open and then close. Three additional files will
-have been created during this process.
-
-@sourceimage{Learning_Win7_All_Files_Created,,,}
-
-The PDF file contains the engraved @file{test.ly} file.
-
-@sourceimage{Learning_Win7_Pdf_Output,,,}
-
-
-@subsubheading Other commands
-
-To create a new file, begin by selecting @w{@code{File > New}} from
-within any previously created file.
-
-@sourceimage{Learning_Win7_New_Menu,,,}
-
-@noindent
-or @w{@code{File > Open}} to open and edit any files you have saved
-before.
-
-@sourceimage{Learning_Win7_Open_Menu,,,}
-
-You must save any new edits you make before you compile it and if the
-PDF file is not created, check the log file that will have been created
-during the compilation attempt, for any errors.
-
-@sourceimage{Learning_Win7_Log_File,,,}
-
-This log file is overwritten each time you compile your LilyPond file.
-
-The PS file is used internally by LilyPond to create the PDF file and
-can be ignored. It also gets overwritten each time you compile your
-file.
+@cindex running LilyPond under Windows
+@cindex Windows, running LilyPond
-If you are viewing your file in a PDF viewer, then you must close the
-PDF if you wish to make a new compilation as it may fail to create
-the new PDF while it is still being viewed.
+@lilypadWindows
-@cindex running LilyPond under Unix
-@cindex Unix, running LilyPond
@node Command-line
@subsection Command-line
-@warning{These instructions assume that you are familiar with
-command-line programs. If you are using any of the programs
-described in @rweb{Alternate input}, please consult the
-documentation for those programs if you have any problems
-compiling a file.}
-
-
-@subsubheading Step 1. Create your @file{.ly} file
-
-Create a text file called @file{test.ly} and enter:
-
-@example
-\version "@w{@version{}}"
-@{
- c' e' g' e'
-@}
-@end example
-
-
-@subsubheading Step 2. Compile (with command-line)
-
-To process @file{test.ly}, type the following at the command prompt:
-
-@example
-lilypond test.ly
-@end example
-
-@noindent
-You will see something resembling:
-
-@example
-GNU LilyPond @version{}
-Processing `test.ly'
-Parsing...
-Interpreting music...
-Preprocessing graphical objects...
-Solving 1 page-breaking chunks...[1: 1 pages]
-Drawing systems...
-Layout output to `test.ps'...
-Converting to `./test.pdf'...
-@end example
-
-@subsubheading Step 3. View output
-
-You may view or print the resulting @file{text.pdf}.
+@cindex running LilyPond under Unix
+@cindex Unix, running LilyPond
+@lilypadCommandLine
@node How to write input files
@section How to write input files
middle C.
By adding (or removing) quotes @code{'} or commas @code{,} from
-the @code{@w{\relative c' @{}} command, we can change the starting
-octave:
+the @q{@w{@code{@bs{}relative c'}}} command, we can change the
+starting octave:
@lilypond[verbatim,quote]
% one octave above middle C
@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.
+quotes @code{''} and not one double quote @code{"}@tie{}!
@c " - keeps quotes in order for context-sensitive editor -td
@subheading Durations (rhythms)
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.
+quarter note.
@lilypond[verbatim,quote]
\relative c'' {
@lilypond[verbatim,quote]
\relative c'' {
- a a a4. a8
+ a4 a a4. a8
a8. a16 a a8. a8 a4.
}
@end lilypond
@lilypond[verbatim,quote]
\relative c'' {
- a r r2
+ a4 r r2
r8 a r4 r4. r8
}
@end lilypond
}
@end lilypond
+@subheading Tempo marks
+
+@cindex tempo marks
+@cindex metronome marks
+
+@funindex \tempo
+@funindex tempo
+
+Music Glossary: @rglos{tempo indication}, @rglos{metronome}.
+
+The @notation{tempo indication} and @notation{metronome mark} can be
+set with the @code{\tempo} command:
+
+@lilypond[verbatim,quote]
+\relative c'' {
+ \time 3/4
+ \tempo "Andante"
+ a4 a a
+ \time 6/8
+ \tempo 4. = 96
+ a4. a
+ \time 4/4
+ \tempo "Presto" 4 = 120
+ a4 a a a
+}
+@end lilypond
+
@subheading Clef
@lilypond[verbatim,quote]
\relative c' {
- \clef treble
+ \clef "treble"
c1
- \clef alto
+ \clef "alto"
c1
- \clef tenor
+ \clef "tenor"
c1
- \clef bass
+ \clef "bass"
c1
}
@end lilypond
@lilypond[verbatim,quote]
\relative c, {
+ \clef "bass"
\time 3/4
- \clef bass
- c2 e8 c' g'2.
- f4 e d c4 c, r4
+ \tempo "Andante" 4 = 120
+ c2 e8 c'
+ g'2.
+ f4 e d
+ c4 c, r
}
@end lilypond
@funindex %@{ ... %@}
LilyPond input files are similar to source files in many common
-programming languages. They contain a version statement,
-are case sensitive, and white-space
-is generally ignored. Expressions are formed with curly braces
-@{ @}, and comments are denoted with @code{%} or
-@w{@code{%@{ ... %@}}}.
+programming languages. They contain a version statement, are case
+sensitive, and white-space is generally ignored. Expressions are
+formed with curly braces @w{@code{@{ @}}}, and comments are
+denoted with @code{%} or @w{@code{%@{ @dots{} %@}}}@tie{}.
If the previous sentences sound like nonsense, don't worry! We'll
explain what all these terms mean:
@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.
+@w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
+Notes are lower case: @w{@samp{@{ c d e @}}} is valid input;
+@w{@samp{@{ 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:
+@w{@samp{@{ c4 d e @}}} means the same thing as
+@w{@samp{@{ c4 @tie{} @tie{} @tie{} d e @}}} and:
@example
-@{ c d
+@{ c4 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:
+thumb is to indent code blocks with two spaces:
@example
@{
- c d e
+ c4 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.
+However, whitespace @emph{is} required to separate many
+syntactical elements from others. In other words, whitespace can
+always be @emph{added}, but not always @emph{eliminated}. Since
+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.
+every piece of LilyPond input needs to have
+@strong{@{@tie{}curly@tie{}braces@tie{}@}} 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.
+as @q{@w{@code{@bs{}relative c' @{ @dots{} @}}}}) also counts as a
+single music expression.
@cindex comments
@cindex line comment
This line, and the notes below are ignored,
since they are in a block comment.
- f f e e d d c2
+ f4 f e e d d c2
%@}
@end example
@end itemize
+@node Dealing with errors
+@section Dealing with errors
+
+@cindex troubleshooting
+
+Sometimes LilyPond doesn't produce the output you expect. This
+section provides some links to help you solve the problems you
+might encounter.
+
+
+@menu
+* General troubleshooting tips::
+* Some common errors::
+@end menu
+
+@node General troubleshooting tips
+@subsection General troubleshooting tips
+
+Troubleshooting LilyPond problems can be challenging for
+people who are used to a graphical interface, because invalid
+input files can be created. When this happens, a logical approach
+is the best way to identify and solve the problem. Some guidelines
+to help you learn to do this are provided in @rprogram{Troubleshooting}.
+
+
+@node Some common errors
+@subsection Some common errors
+
+@cindex common errors
+@cindex errors, common
+
+There are a few common errors that are difficult to troubleshoot
+based simply on the error messages that are displayed. These are
+described in @rprogram{Common errors}.
+
+
+
@node How to read the manuals
@section How to read the manuals
@menu
* Omitted material::
* Clickable examples::
-* Keyboard navigation::
* Overview of manuals::
@end menu
@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:
+LilyPond input must be surrounded by @code{@{ @}} marks or a
+@q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}}, 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
+@q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} like this:
@example
\relative c'' @{
- ... example goes here...
+ @dots{}example goes here@dots{}
@}
@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.
-
-Also, remember that every LilyPond file should have a @code{@bs{}version}
-statement. Because the examples in the manuals are snippets, not files,
-the @code{@bs{}version} statement is omitted. But you should make a
-practice of including them in your files.
+it does not make sense to add
+@q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} -- you should not
+place a @code{\relative} inside another @code{\relative}! If we
+included @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} 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.
+
+Also, remember that every LilyPond file should have a
+@code{\version} statement. Because the examples in the manuals
+are snippets, not files, the @code{\version} statement is omitted.
+But you should make a practice of including them in your files.
@node Clickable examples
@subsection Clickable examples
-@warning{This features is only available in the HTML manuals.}
+@warning{This feature 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
@c no verbatim here
@lilypond[quote]
\relative c'' {
- c-\markup { \bold \huge { Click here. } }
+ c4-\markup { \bold \huge { Click here. } }
}
@end lilypond
cut-&-pastable section} to the bottom of the file.
-@node Keyboard navigation
-@subsection Keyboard navigation
+@ignore
+This is item 825
+
+@n ode Keyboard navigation
+@s ubsection 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.
-
+@end ignore
@node Overview of manuals
@subsection Overview of manuals
Learning manual's @ref{Tweaking output}.
@item
-@strong{Before undertaking a large project}: read Usage document's
-@rprogram{Suggestions for writing files}.
+@strong{Before undertaking a large project}: read the Usage
+document's @rprogram{Suggestions for writing files}.
@end itemize