X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Flearning%2Ftutorial.itely;fp=Documentation%2Flearning%2Ftutorial.itely;h=6752a3bc409366b9317e494245a37decb959741a;hb=941dff9d2a67080e0dd8474f1e70f0c72ace6424;hp=0000000000000000000000000000000000000000;hpb=5a22d6233a39d3164e1ca043244794c268be4ad0;p=lilypond.git

diff --git a/Documentation/learning/tutorial.itely b/Documentation/learning/tutorial.itely
new file mode 100644
index 0000000000..6752a3bc40
--- /dev/null
+++ b/Documentation/learning/tutorial.itely
@@ -0,0 +1,766 @@
+@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.  For details, see the Contributors'
+    Guide, node Updating translation committishes..
+@end ignore
+
+@include included/generating-output.itexi
+
+@c \version "2.14.0"
+
+@node Tutorial
+@chapter Tutorial
+
+This chapter gives a basic introduction to working with LilyPond.
+
+@menu
+* Compiling a file::
+* How to write input files::
+* Dealing with errors::
+* How to read the manuals::
+@end menu
+
+@node Compiling a file
+@section Compiling a file
+
+This section introduces @qq{compiling}---the processing of
+LilyPond input files (written by you) to produce output files.
+
+@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 output file(s).  Output files are
+generally PDF (for printing or viewing), MIDI (for playing), and
+PNG (for online use).  LilyPond input files are simple text files.
+
+This example shows a simple input file:
+
+@example
+\version "@w{@version{}}"
+@{
+  c' e' g' e'
+@}
+@end example
+
+The graphical output is:
+
+@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.  They 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{@samp{@{ c d e @}}} is valid input; @w{@samp{@{ C D E @}}} will
+produce an error message.
+
+
+@smallspace
+
+@subheading Producing output
+
+@cindex PDF file
+@cindex viewing music
+@cindex text editors
+
+The method of 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 specific
+support for LilyPond.  For more information, see
+@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!}
+
+
+@node MacOS X
+@subsection MacOS X
+
+@cindex running LilyPond under MacOS X
+@cindex MacOS X, running LilyPond
+
+@lilypadOSX
+
+
+@node Windows
+@subsection Windows
+
+@cindex running LilyPond under Windows
+@cindex Windows, running LilyPond
+
+@lilypadWindows
+
+
+@node Command-line
+@subsection Command-line
+
+@cindex running LilyPond under Unix
+@cindex Unix, running LilyPond
+
+@lilypadCommandLine
+
+@node How to write input files
+@section How to write input files
+
+This section introduces some basic LilyPond syntax to help get you
+started writing input files.
+
+@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 @q{@w{@code{@bs{}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{}!
+@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 note.
+
+@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'' {
+  a4 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'' {
+  a4 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 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
+
+@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, {
+  \clef "bass"
+  \time 3/4
+  \tempo "Andante" 4 = 120
+  c2 e8 c'
+  g'2.
+  f4 e d
+  c4 c, r
+}
+@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
+@cindex versioning
+@cindex version
+@cindex version number
+
+@funindex \version
+@funindex { ... }
+@funindex %
+@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 @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:
+
+@itemize
+
+@item
+@strong{Version statement}:
+Every LilyPond file should contain a version statement.  A version
+statement is a line that describes the version of LilyPond for which
+the file was written, as in the following example:
+
+@example
+\version "@w{@version{}}"
+@end example
+
+By convention, the version statement is placed at the top of the
+LilyPond file.
+
+The version statement is important for at least two reasons.  First,
+it allows automatic updating of the input file as LilyPond syntax
+changes.  Second, it describes the version of LilyPond needed to
+compile the file.
+
+If the version statement is omitted from an input file, LilyPond will print
+a warning during the compilation of the file.
+
+@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{@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{@samp{@{ c4 d e @}}} means the same thing as
+@w{@samp{@{ c4 @tie{} @tie{} @tie{} d e @}}} and:
+
+@example
+@{ 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 two spaces:
+
+@example
+@{
+  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 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{@{@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 @q{@w{@code{@bs{}relative c' @{ @dots{} @}}}}) 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.
+
+  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
+
+This section shows how to read the documentation efficiently, and
+also introduces some useful interactive features available in the
+online version.
+
+@menu
+* Omitted material::
+* Clickable examples::
+* Overview of manuals::
+@end menu
+
+
+@node Omitted material
+@subsection Omitted material
+
+
+@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 @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'' @{
+  @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
+@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 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
+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'' {
+  c4-\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.
+
+
+@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
+
+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 the Usage
+document's @rprogram{Suggestions for writing files}.
+
+@end itemize
+
+
+