-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely
+@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
@node Introduction
@chapter Introduction
@menu
-* Engraving::
-* Automated engraving::
-* What symbols to engrave?::
-* Music representation::
-* Example applications::
-* About this manual::
+* Engraving::
+* Automated engraving::
+* What symbols to engrave?::
+* Music representation::
+* Example applications::
+* About this manual::
@end menu
our staff lines, which are also much thicker than lines in the
computer edition.
-@multitable @columnfractions .05 .3 .3 .3 .05
+@multitable @columnfractions .125 .25 .25 .25 .125
@item @tab
@ifnotinfo
@iftex
-@image{henle-flat-bw,4cm}
+@image{henle-flat-gray,,4cm}
@end iftex
@ifnottex
-@image{henle-flat-bw,,,png}
+@image{henle-flat-gray,,,png}
@end ifnottex
@tab
@iftex
-@image{baer-flat-bw,4cm}
+@image{baer-flat-gray,,4cm}
@end iftex
@ifnottex
-@image{baer-flat-bw,,,png}
+@image{baer-flat-gray,,,png}
@end ifnottex
@tab
@iftex
-@image{lily-flat-bw,4cm}
+@image{lily-flat-bw,,4cm}
@end iftex
@ifnottex
@image{lily-flat-bw,,,png}
@end ifnotinfo
@ifinfo
@c workaround for makeinfo-4.6: line breaks and multi-column cookies
-@image{henle-flat-bw,,,png} @image{baer-flat-bw,,,png} @image{lily-flat-bw,,,png}
+@image{henle-flat-bw,,,png} @image{baer-flat-bw,,,png}
+@image{lily-flat-bw,,,png}
@end ifinfo
@item @tab
@c introduce illustrating aspects of engraving, spacing...
In spacing, the distribution of space should reflect the durations
between notes. However, many modern scores adhere to the durations
-with mathematical precision, which leads to poor results. In the
-next example a motive is printed twice. It is printed once using
-exact mathematical spacing, and once with corrections. Can you
-spot which fragment is which?
+with mathematical precision, which leads to poor results. In the next
+example a motive is printed twice: once using exact mathematical
+spacing, and once with corrections. Can you spot which fragment is
+which?
@cindex optical spacing
-@lilypondfile[quote,noindent]{spacing-optical.ly}
+@c file spacing-optical.
+@c need to include it here, because we want two images.
+@lilypond
+\paper {
+ ragged-right = ##t
+ indent = #0.0
+}
+
+music = {
+ c'4 e''4 e'4 b'4 |
+ \stemDown
+ b'8[ e'' a' e'']
+ \stemNeutral
+ e'8[ e'8 e'8 e'8]
+}
+
+\score
+{
+ \music
+ \layout {
+ \context {
+ \Staff
+ \override NoteSpacing #'stem-spacing-correction = #0.6
+ }
+ }
+}
+@end lilypond
+
+@lilypond
+\paper {
+ ragged-right = ##t
+ indent = #0.0
+}
+
+music = {
+ c'4 e''4 e'4 b'4 |
+ \stemDown
+ b'8[ e'' a' e'']
+ \stemNeutral
+ e'8[ e'8 e'8 e'8]
+}
+\score
+{
+ \music
+ \layout {
+ \context {
+ \Staff
+ \override NoteSpacing #'stem-spacing-correction = #0.0
+ \override NoteSpacing #'same-direction-correction = #0.0
+ \override StaffSpacing #'stem-spacing-correction = #0.0
+ }
+ }
+}
+@end lilypond
@cindex regular rhythms
@cindex regular spacing
-The fragment only uses quarter notes: notes that are played in a
-constant rhythm. The spacing should reflect that. Unfortunately, the
-eye deceives us a little; not only does it notice the distance between
+Each bar in the fragment only uses notes that are played in a constant
+rhythm. The spacing should reflect that. Unfortunately, the eye
+deceives us a little; not only does it notice the distance between
note heads, it also takes into account the distance between
consecutive stems. As a result, the notes of an up-stem/@/down-stem
-combination should be put farther apart, and the notes of a down-stem/@/up-stem
-combination should be put closer together, all depending on the
-combined vertical positions of the notes. The first two measures are
-printed with this correction, the last two measures without. The notes
-in the last two measures form down-stem/@/up-stem clumps of notes.
+combination should be put farther apart, and the notes of a
+down-stem/@/up-stem combination should be put closer together, all
+depending on the combined vertical positions of the notes. The upper
+two measures are printed with this correction, the lower two measures
+without, forming down-stem/@/up-stem clumps of notes.
@cindex typography
Musicians are usually more absorbed with performing than with studying
-the looks of a piece of music, so nitpicking about typographical details
-may seem academical. But it is not. In larger pieces with monotonous
-rhythms, spacing corrections lead to subtle variations in the layout
-of every line, giving each one a distinct visual signature. Without
-this signature all lines would look the same, and they become like a
-labyrinth. If a musician looks away once or has a lapse in
+the looks of a piece of music, so nitpicking about typographical
+details may seem academical. But it is not. In larger pieces with
+monotonous rhythms, spacing corrections lead to subtle variations in
+the layout of every line, giving each one a distinct visual signature.
+Without this signature all lines would look the same, and they become
+like a labyrinth. If a musician looks away once or has a lapse in
concentration, the lines might lose their place on the page.
Similarly, the strong visual look of bold symbols on heavy staff lines
-stands out better when the music is far away from the reader, for example,
-if it is on a music stand. A careful distribution of white space allows
-music to be set very tightly without cluttering symbols together. The
-result minimizes the number of page turns, which is a great advantage.
+stands out better when the music is far away from the reader, for
+example, if it is on a music stand. A careful distribution of white
+space allows music to be set very tightly without cluttering symbols
+together. The result minimizes the number of page turns, which is a
+great advantage.
This is a common characteristic of typography. Layout should be
pretty, not only for its own sake, but especially because it helps the
-reader in her task. For performance material like sheet music, this is
-of double importance: musicians have a limited amount of attention. The
-less attention they need for reading, the more they can focus on
-playing the music. In other words, better typography translates to better
-performances.
+reader in her task. For performance material like sheet music, this
+is of double importance: musicians have a limited amount of attention.
+The less attention they need for reading, the more they can focus on
+playing the music. In other words, better typography translates to
+better performances.
These examples demonstrate that music typography is an art that is
subtle and complex, and that producing it requires considerable
have all directions down (or left). The second chord has all
directions up (right).
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
\new Score \with {
\override SpacingSpanner #'spacing-increment = #3
\override TimeSignature #'transparent = ##t
style -- is a variable with a preset value. You are free to alter this
value, giving your score a different typographical impression.
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
fragment = {
\clef bass f8 as8
c'4-~ c'16 as g f e16 g bes c' des'4
containing procedures. These procedures perform the actual
formatting, and by substituting different ones, we can change the
appearance of objects. In the following example, the rule which note
-head objects are used to produce their symbol is changed during the music
-fragment.
+head objects are used to produce their symbol is changed during the
+music fragment.
+
+@lilypond[quote,ragged-right]
+#(set-global-staff-size 30)
-@c FIXME: this example has errors:
-@c programming error: Grob `NoteHead' has no interface for property `text'
-@c Continuing; crossing fingers
-@lilypond[quote,raggedright]
#(define (mc-squared grob orig current)
- (let ((interfaces (ly:grob-property grob 'interfaces))
- (pos (ly:grob-property grob 'staff-position)))
- (if (and (memq 'note-head-interface interfaces)
- (memq pos '(-2 -3 -5)))
+ (let* ((interfaces (ly:grob-interfaces grob))
+ (pos (ly:grob-property grob 'staff-position)))
+ (if (memq 'note-head-interface interfaces)
(begin
- (ly:grob-set-property! grob 'print-function Text_interface::print)
+ (ly:grob-set-property! grob 'stencil ly:text-interface::print)
(ly:grob-set-property! grob 'font-family 'roman)
- (ly:grob-set-property!
- grob 'text
- (make-raise-markup
- -0.5
- (case pos
- ((-5) (make-simple-markup "m"))
- ((-3) (make-simple-markup "c "))
- ((-2) (make-smaller-markup (make-bold-markup "2")))
- (else (make-simple-markup "bla")))))))))
+ (ly:grob-set-property! grob 'text
+ (make-raise-markup -0.5
+ (case pos
+ ((-5) (make-simple-markup "m"))
+ ((-3) (make-simple-markup "c "))
+ ((-2) (make-smaller-markup (make-bold-markup "2")))
+ (else (make-simple-markup "bla")))))))))
\new Voice \relative c' {
\stemUp
\set autoBeaming = ##f
\time 2/4
<d f g>4
- \once \override NoteHead #'print-function = #Note_head::brew_ez_stencil
+ \once \override NoteHead #'stencil = #ly:note-head::brew-ez-stencil
+ \once \override NoteHead #'font-size = #-7
+ \once \override NoteHead #'font-family = #'sans
+ \once \override NoteHead #'font-series = #'bold
<d f g>
\once \override NoteHead #'style = #'cross
<d f g>
- \applyoutput #mc-squared
+ \applyOutput #'Voice #mc-squared
<d f g>
<<
{ d8[ es-( fis^^ g] fis2-) }
- \repeat unfold 5 { \applyoutput #mc-squared s8 }
+ \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 }
>>
}
@end lilypond
@cindex engraving
@cindex typography
-The formatting process decides where to place
-symbols. However, this can only be done once it is decided @emph{what}
-symbols should be printed, in other words what notation to use.
+The formatting process decides where to place symbols. However, this
+can only be done once it is decided @emph{what} symbols should be
+printed, in other words what notation to use.
Common music notation is a system of recording music that has evolved
over the past 1000 years. The form that is now in common use dates
-from the early renaissance. Although the basic form (i.e., note heads on a
-5-line staff) has not changed, the details still evolve to express the
-innovations of contemporary notation. Hence, it encompasses some 500
-years of music. Its applications range from monophonic melodies to
-monstrous counterpoints for large orchestras.
+from the early renaissance. Although the basic form (i.e., note heads
+on a 5-line staff) has not changed, the details still evolve to
+express the innovations of contemporary notation. Hence, it
+encompasses some 500 years of music. Its applications range from
+monophonic melodies to monstrous counterpoints for large orchestras.
How can we get a grip on such a many-headed beast, and force it into
the confines of a computer program? Our solution is to break up the
digestible and programmable chunks: every type of symbol is handled by
a separate module, a so-called plug-in. Each plug-in is completely
modular and independent, so each can be developed and improved
-separately. Such plug-ins are called @code{engraver}s, by analogy with
-craftsmen who translate musical ideas to graphic symbols.
+separately. Such plug-ins are called @code{engraver}s, by analogy
+with craftsmen who translate musical ideas to graphic symbols.
In the following example, we see how we start out with a plug-in for
note heads, the @code{Note_heads_engraver}.
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
\include "engraver-example.ily"
\score {
@noindent
Then a @code{Staff_symbol_engraver} adds the staff
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
\include "engraver-example.ily"
\score {
@noindent
the @code{Clef_engraver} defines a reference point for the staff
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
\include "engraver-example.ily"
\score {
@noindent
and the @code{Stem_engraver} adds stems.
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
\include "engraver-example.ily"
\score {
}
@end lilypond
+@noindent
The @code{Stem_engraver} is notified of any note head coming along.
Every time one (or more, for a chord) note head is seen, a stem
object is created and connected to the note head. By adding
time signature, and key signature, we get a complete piece of
notation.
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
\include "engraver-example.ily"
\score { \topVoice }
@end lilypond
This system works well for monophonic music, but what about
polyphony? In polyphonic notation, many voices can share a staff.
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
\include "engraver-example.ily"
-\new Staff << \topVoice \\ \botVoice >>
+\new Staff << \topVoice \\ \botVoice >>
@end lilypond
In this situation, the accidentals and staff are shared, but the stems,
slurs, beams, etc., are private to each voice. Hence, engravers should
be grouped. The engravers for note heads, stems, slurs, etc., go into a
-group called `Voice context,' while the engravers for key, accidental,
-bar, etc., go into a group called `Staff context.' In the case of
+group called @q{Voice context,} while the engravers for key, accidental,
+bar, etc., go into a group called @q{Staff context.} In the case of
polyphony, a single Staff context contains more than one Voice context.
Similarly, multiple Staff contexts can be put into a single Score
context. The Score context is the top level notation context.
Program reference: @internalsref{Contexts}.
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
\include "engraver-example.ily"
\score {
<<
@noindent
Chords can be constructed with @code{<<} and @code{>>} enclosing the notes
-@c < > is not a music expression,
+@c < > is not a music expression,
@c so we use <<>> iso. <> to drive home the point of
@c expressions. Don't change this back --hwn.
@example
@noindent
By adding chord names and lyrics we obtain a lead sheet.
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
<<
\chords { c2 c f2 c }
\new Staff \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
Polyphonic notation and piano music can also be printed. The following
example combines some more exotic constructs.
-@lilypondfile[quote,raggedright]{screech-boink.ly}
+@lilypondfile[quote,ragged-right]{screech-boink.ly}
The fragments shown above have all been written by hand, but that is
not a requirement. Since the formatting engine is mostly automatic, it
This manual also shows an application: the input format is text, and
can therefore be easily embedded in other text-based formats such as
-La@TeX{}, HTML, or in the case of this manual, Texinfo. By means of a
+@LaTeX{}, HTML, or in the case of this manual, Texinfo. By means of a
special program, the input fragments can be replaced by music images
in the resulting PDF or HTML output files. This makes it easy
to mix music and text in documents.
users should start here.
@item
-@ifhtml
-The
-@end ifhtml
-@emph{@ref{Example templates}}
-provides templates of LilyPond pieces. Just cut and paste a
-template into a file, add notes, and you're done!
+@emph{@ref{Putting it all together}}
+explains some general concepts about the lilypond file format. If
+you are not certain where to place a command, read this chapter!
@item
-@ifhtml
-The
-@end ifhtml
-@c @emph{@ref{Notation manual}} @c FIXME
-@emph{Notation manual}
-discusses topics grouped by notation construct. Once you master the
-basics, this is the place to look up details.
+@emph{@ref{Working on LilyPond projects}}
+discusses practical uses of LilyPond and how to avoid some common
+problems.
+
+@item
+@emph{@ref{Tweaking output}}
+shows how to change the default engraving that LilyPond
+produces.
+
+@item
+@emph{@ref{Basic notation}}
+discusses topics grouped by notation construct. This section gives
+details about basic notation that will be useful in almost any
+notation project.
+
+@item
+@emph{@ref{Instrument-specific notation}}
+discusses topics grouped by notation construct. This section gives
+details about special notation that will only be useful for particular
+instrument (or vocal) groups.
+
+@item
+@emph{@ref{Advanced notation}}
+discusses topics grouped by notation construct. This section gives
+details about complicated or unusual notation.
@item
-@ifhtml
-The
-@end ifhtml
@emph{@ref{Changing defaults}}
explains how to fine tune layout.
@item
-@ifhtml
-The chapter
-@end ifhtml
-@emph{@ref{Running LilyPond}} shows how to run LilyPond and its helper
-programs.
+@emph{@ref{Non-musical notation}}
+discusses non-musical output such as titles, multiple movements,
+and how to select which MIDI instruments to use.
+
+@item
+@emph{@ref{Spacing issues}}
+discusses issues which affect the global output, such as selecting
+paper size or specifying page breaks.
+
+@item
+@emph{@ref{Interfaces for programmers}}
+explains how to create music functions.
+
+@item
+@emph{@ref{Running LilyPond}}
+shows how to run LilyPond and its helper programs. In addition, this
+section explains how to upgrade input files from previous versions of
+LilyPond.
@item
-@ifhtml
-The chapter
-@end ifhtml
@emph{@ref{LilyPond-book}} explains the details behind creating
-documents with in-line music examples (like this manual).
+documents with in-line music examples, like this manual.
@item
-@ifhtml
-The chapter
-@end ifhtml
@emph{@ref{Converting from other formats}}
-explains how to run the conversion programs. These programs
-are supplied with the LilyPond package, and convert a variety of music
-formats to the @code{.ly} format. In addition, this section explains
-how to upgrade input files from previous versions of LilyPond.
+explains how to run the conversion programs. These programs are
+supplied with the LilyPond package, and convert a variety of music
+formats to the @code{.ly} format.
@item
@ifhtml
@emph{@ref{Literature list}}
contains a set of useful reference books for those who wish to know
more on notation and engraving.
+
+@item
+The
+@emph{@ref{Scheme tutorial}}
+presents a short introduction to Scheme, the programming
+language that music functions use.
+
+@item
+@emph{@ref{Notation manual tables}}
+are a set of tables showing the chord names, MIDI instruments,
+a list of color names, and the Feta font.
+
+@item
+@emph{@ref{Example templates}}
+provides templates of LilyPond pieces. Just cut and paste a
+template into a file, add notes, and you're done!
+
+@item
+The
+@emph{@ref{Cheat sheet}}
+is a handy reference of the most common LilyPond commands.
+
+@item
+The
+@emph{@ref{LilyPond command index}}
+is an index of all LilyPond @code{\commands}.
+
+@item
+The
+@emph{@ref{LilyPond index}}
+is a complete index.
+
@end itemize
+
Once you are an experienced user, you can use the manual as reference:
there is an extensive index@footnote{If you are looking for something,
and you cannot find it in the manual, that is considered a bug. In
a big HTML page,
@end iftex
@ifhtml
-@uref{source/Documentation/user/out-www/lilypond.html, one big page},
+@uref{source/Documentation/user/lilypond.html, one big page},
@end ifhtml
which can be searched easily using the search facility of a web
browser.
available directly to the user. For example, all variables that
control thickness values, distances, etc., can be changed in input
files. There are a huge number of formatting options, and all of them
-are described in this document. Each section of the
-notation manual has a @b{See also} subsection, which refers to the
-generated documentation. In the HTML document, these subsections
-have clickable links.
+are described in this document. Each section of the notation manual
+has a @b{See also} subsection, which refers to the generated
+documentation. In the HTML document, these subsections have clickable
+links.
+@cindex snippets
@item
@ifnothtml
Various input examples.
@ifhtml
@c Works, but link name is not so nice; so write-out macro
@c @inputfileref{input/test,Various input examples}.
-@uref{source/input/test/out-www/collated-files.html,Various input examples}.
+@uref{source/input/test/collated-files.html,Various input examples}.
@end ifhtml
-@cindex snippets
This collection of files shows various tips and tricks, and is
available as a big HTML document, with pictures and explanatory texts
@ifhtml
@c Works, but link name is not so nice; so write-out macro
@c @inputfileref{input/regression,The regression tests}.
-@uref{source/input/regression/out-www/collated-files.html,The regression tests}.
+@uref{source/input/regression/collated-files.html,The regression tests}.
@end ifhtml
This collection of files tests each notation and engraving feature of
initialization and example files. Throughout this manual, we refer to
input files relative to the top-directory of the source archive. For
example, @file{input/@/test/@/bla@/.ly} may refer to the file
-@file{lilypond@/-2.4.0/@/input/@/test/@/bla@/.ly}. On binary packages
+@file{lilypond@/2.x.y/@/input/@/test/@/bla@/.ly}. On binary packages
for the Unix platform, the documentation and examples can typically be
found somewhere below @file{/usr/@/share/@/doc/@/lilypond/}.
Initialization files, for example @file{scm/@/lily@/.scm}, or
@cindex internal documentation
@cindex Scheme
@cindex extending lilypond
-@cindex bug report
@cindex index
Finally, this and all other manuals, are available online both as PDF
files and HTML from the web site, which can be found at
@uref{http://@/www@/.lilypond@/.org/}.
-@cindex website
-@cindex URL
projects / lilypond.git / blobdiff