@c -*- coding: utf-8; mode: texinfo; -*-
-@c This file is part of lilypond.tely
+@c This file is part of lilypond-learning.tely
@ignore
Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
engraving and typical computer output, and the third picture shows how
LilyPond mimics the traditional look. The left picture shows a scan
of a flat symbol from an edition published in 2000. The center
-depicts a symbol from a hand-engraved B@"{a}renreiter edition of the
+depicts a symbol from a hand-engraved Bärenreiter edition of the
same music. The left scan illustrates typical flaws of computer
print: the staff lines are thin, the weight of the flat symbol matches
the light lines and it has a straight layout with sharp corners. By
-contrast, the B@"{a}renreiter flat has a bold, almost voluptuous
+contrast, the Bärenreiter flat has a bold, almost voluptuous
rounded look. Our flat symbol is designed after, among others, this
one. It is rounded, and its weight harmonizes with the thickness of
our staff lines, which are also much thicker than lines in the
@end ifnottex
@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{lilypond/henle-flat-bw,,,png} @image{lilypond/baer-flat-bw,,,png}
+@image{lilypond/lily-flat-bw,,,png}
@end ifinfo
@item @tab
Henle (2000)
@tab
-B@"{a}renreiter (1950)
+Bärenreiter (1950)
@tab
LilyPond Feta font (2003)
the developers. That proved to be unsatisfactory for a number of
reasons:
-@itemize @bullet
+@itemize
@item When LilyPond makes mistakes,
users need to override formatting decisions. Therefore, the user must
have access to the formatting engine. Hence, rules and settings cannot
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}
+note heads, the @code{Note_heads_engraver}.
@lilypond[quote,ragged-right]
\include "engraver-example.ily"
@end lilypond
@noindent
-and the @code{Stem_engraver} adds stems
+and the @code{Stem_engraver} adds stems.
@lilypond[quote,ragged-right]
\include "engraver-example.ily"
@seealso
-Program reference: @internalsref{Contexts}.
+Internals Reference: @internalsref{Contexts}.
@lilypond[quote,ragged-right]
\include "engraver-example.ily"
to type
@example
-c'4 d'8
+@{
+ c'4 d'8
+@}
@end example
@noindent
a quarter note C1 (middle C) and an eighth note D1 (D above middle C)
-@lilypond[quote,fragment]
-c'4 d'8
+@lilypond[quote]
+{
+ c'4 d'8
+}
@end lilypond
On a microscopic scale, such syntax is easy to use. On a larger
We have written LilyPond as an experiment of how to condense the art
of music engraving into a computer program. Thanks to all that hard
work, the program can now be used to perform useful tasks. The
-simplest application is printing notes
+simplest application is printing notes.
-@lilypond[quote,relative=1,fragment]
-\time 2/4 c4 c g'4 g a4 a g2
+@lilypond[quote,relative=1]
+{
+ \time 2/4
+ c4 c g'4 g a4 a g2
+}
@end lilypond
@noindent
-By adding chord names and lyrics we obtain a lead sheet:
+By adding chord names and lyrics we obtain a lead sheet.
@lilypond[quote,ragged-right]
<<
@end lilypond
Polyphonic notation and piano music can also be printed. The following
-example combines some more exotic constructs
+example combines some more exotic constructs.
@lilypondfile[quote,ragged-right]{screech-boink.ly}
@node About this manual
@section About this manual
-The manual is divided into the following chapters:
-@itemize @bullet
+FIXME: needs almost-complete rewrite. -gp
+
+There are four manuals about LilyPond: the @emph{Learning Manual},
+the @emph{Notation Reference}, the @emph{Application Usage}, and the
+@emph{Internals Reference}.
+
+
+@subheading Learning Manual (LM)
+
+This book explains how to begin learning LilyPond, as well as explaining
+some key concepts in easy terms. It is recommended to read these
+chapters in a linear fashion.
+
+@itemize
@item
@ifhtml
The
@end ifhtml
-@emph{@ref{Tutorial}}
+@emph{@ref{Tutorial}},
gives a gentle introduction to typesetting music. First time
users should start here.
@item
-@emph{@ref{Putting it all together}}
+@emph{@ref{Fundamental concepts}},
explains some general concepts about the lilypond file format. If
you are not certain where to place a command, read this chapter!
@item
-@emph{@ref{Working on LilyPond projects}}
+@emph{@ref{Working on LilyPond projects}},
discusses practical uses of LilyPond and how to avoid some common
problems.
@item
-@emph{@ref{Tweaking output}}
+@emph{@ref{Tweaking output}},
shows how to change the default engraving that LilyPond
produces.
+@end itemize
+
+
+@subheading Notation Reference (NR)
+
+This book explains all the LilyPond commands which produce notation. It
+assumes that readers are familiar with the concepts in the Learning
+manual.
+
+All of this needs to be rewritten after GDP, anyway.
+
+@ignore
+
+@itemize
+
@item
-@emph{@ref{Basic notation}}
+@emph{@r ef{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}}
+@emph{@r ef{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}}
+@emph{@r ef{Advanced notation}},
discusses topics grouped by notation construct. This section gives
details about complicated or unusual notation.
@item
-@emph{@ref{Changing defaults}}
+@emph{@r ef{Changing defaults}},
explains how to fine tune layout.
@item
-@emph{@ref{Non-musical notation}}
+@emph{@r ef{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}}
+@emph{@r ef{Spacing issues}},
discusses issues which affect the global output, such as selecting
paper size or specifying page breaks.
@item
-@emph{@ref{Interfaces for programmers}}
+@emph{@r ef{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.
+@end itemize
-@item
-@emph{@ref{LilyPond-book}} explains the details behind creating
-documents with in-line music examples, like this manual.
-@item
-@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.
+@subsubheading Appendices
+
+This book contains useful reference charts.
+@itemize
@item
@ifhtml
The
@end ifhtml
-@emph{@ref{Literature list}}
+@emph{@r ef{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}}
+@emph{@r ef{Scheme tutorial}},
presents a short introduction to Scheme, the programming
language that music functions use.
@item
-@emph{@ref{Notation manual tables}}
+@emph{@r ef{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
+@emph{@r ef{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}}
+@emph{@r ef{Cheat sheet}},
is a handy reference of the most common LilyPond commands.
@item
The
-@emph{@ref{LilyPond command index}}
+@emph{@r ef{LilyPond command index}},
is an index of all LilyPond @code{\commands}.
@item
The
-@emph{@ref{LilyPond index}}
+@emph{@r ef{LilyPond index}},
is a complete index.
@end itemize
+@end ignore
-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
-that case, please file a bug report.}, but the document is also
-available in
-@iftex
-a big HTML page,
-@end iftex
-@ifhtml
-@uref{source/Documentation/user/lilypond.html, one big page},
-@end ifhtml
-which can be searched easily using the search facility of a web
-browser.
-@cindex search in manual
-@cindex using the manual
+@subheading Program usage
-@c FIXME:
-@c add/integrate glossary, put in list above
-If you are not familiar with music notation or music terminology
-(especially if you are a non-native English speaker), it is advisable
-to consult the glossary as well.
-@iftex
-The music glossary explains musical terms, and includes translations
-to various languages. It is a separate document, available in HTML
-and PDF.
-@end iftex
-@ifnottex
-The @ref{Top,Music glossary,,music-glossary}, explains musical terms and
-includes translations to various languages. It is also available in
-PDF.
-@end ifnottex
+This book explains how to execute the program and how to integrate
+LilyPond notation with other programs.
+
+@itemize
+
+@item
+@emph{@rprogram{Install}},
+explains how to install LilyPond (including compilation if desired).
+
+@item
+@emph{@rprogram{Setup}},
+describes how to configure your computer for optimum LilyPond usage,
+such as using special environments for certain text editors.
+
+@item
+@emph{@rprogram{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
+@emph{@rprogram{LilyPond-book}},
+explains the details behind creating
+documents with in-line music examples, like this manual.
+
+@item
+@emph{@rprogram{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.
+
+@end itemize
+
+
+
+@subsubheading Other information
+
+There are a number of other places which may be very valuable.
+
+@itemize
@cindex idiom
@cindex jargon
@cindex terminology
@cindex foreign languages
@cindex language
+@item
+@ifnottex
+The @ref{Top,Music glossary,,music-glossary}, explains musical terms and
+includes translations to various languages. It is also available in
+PDF.
+@end ifnottex
+@iftex
+The music glossary explains musical terms, and includes translations
+to various languages. It is a separate document, available in HTML
+and PDF.
+@end iftex
+If you are not familiar with music notation or music terminology
+(especially if you are a non-native English speaker), it is highly
+advisable to consult the glossary.
+@cindex snippets
+@cindex LSR
+@item
+The
+@ifhtml
+@uref{source/input/lsr/snippets/index.html,Snippets}
+@end ifhtml
+@ifnothtml
+Snippets
+@end ifnothtml
+are a great collection of short examples which demonstrate tricks, tips,
+and special features of LilyPond. Most of these snippets can also be
+found in the @uref{http://lsr.dsi.unimi.it/,LilyPond Snippet
+Repository}. This website also has a searchable LilyPond manual.
-This manual is not complete without a number of other documents. They
-are not available in print, but should be included with the
-documentation package for your platform
-@itemize @bullet
@item
+The
@iftex
-Program reference
+Internals Reference
@end iftex
@ifnottex
-@ref{Top,Program reference,,lilypond-internals}.
+@ref{Top,Internals Reference,,lilypond-internals}
@end ifnottex
-
-The program reference is a set of heavily cross linked HTML pages,
-which document the nitty-gritty details of each and every LilyPond
-class, object, and function. It is produced directly from the
-formatting definitions used.
+is a set of heavily cross linked HTML pages, which document the
+nitty-gritty details of each and every LilyPond class, object, and
+function. It is produced directly from the formatting definitions used.
Almost all formatting functionality that is used internally, is
-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.
+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.
-@cindex snippets
-@item
-@ifnothtml
-Various input examples.
-@end ifnothtml
-@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/collated-files.html,Various input examples}.
-@end ifhtml
+@end itemize
-This collection of files shows various tips and tricks, and is
-available as a big HTML document, with pictures and explanatory texts
-included.
-@item
-@ifnothtml
-The regression tests.
-@end ifnothtml
+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
+that case, please file a bug report.}, but the document is also
+available in
+@iftex
+a big HTML page,
+@end iftex
@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/collated-files.html,The regression tests}.
+@uref{source/Documentation/user/lilypond-big-page.html, one big page},
@end ifhtml
-
-This collection of files tests each notation and engraving feature of
-LilyPond in one file. The collection is primarily there to help us
-debug problems, but it can be instructive to see how we exercise the
-program. The format is similar to the tips and tricks document.
-@end itemize
+which can be searched easily using the search facility of a web
+browser.
In all HTML documents that have music fragments embedded, the LilyPond
input that was used to produce that image can be viewed by clicking
the image.
-The location of the documentation files that are mentioned here can
-vary from system to system. On occasion, this manual refers to
+The location of the documentation files that are mentioned here can vary
+from system to system. On occasion, this manual refers to
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.8.0/@/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
-@file{ly/@/engraver@/-init@/.ly}, are usually found in the directory
-@file{/usr/@/share/@/lilypond/}.
+example, @file{input/@/lsr/@/dirname/@/bla@/.ly} may refer to the file
+@file{lilypond@/2.x.y/@/input/@/lsr/@/dirname/@/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 @file{ly/@/engraver@/-init@/.ly},
+are usually found in the directory @file{/usr/@/share/@/lilypond/}.
@cindex adjusting output
@cindex variables
files and HTML from the web site, which can be found at
@uref{http://@/www@/.lilypond@/.org/}.
+
projects / lilypond.git / blobdiff