-@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
-
-
-
projects / lilypond.git / commitdiff