@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
version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.11.51"
+
@node Introduction
@chapter Introduction
+This chapter introduces readers to LilyPond and the
+documentation.
+
+@menu
+* Background::
+* About the documentation::
+@end menu
+
+
+@node Background
+@section Background
+
+This section covers the overall goals and architecture of
+LilyPond.
@menu
* Engraving::
* What symbols to engrave?::
* Music representation::
* Example applications::
-* About this manual::
@end menu
@node Engraving
-@section Engraving
+@unnumberedsubsec Engraving
The art of music typography is called @emph{(plate) engraving}. The
term derives from the traditional process of music printing. Just a
@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
@node Automated engraving
-@section Automated engraving
+@unnumberedsubsec Automated engraving
How do we go about implementing typography? If craftsmen need over
ten years to become true masters, how could we simple hackers ever
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
@node What symbols to engrave?
-@section What symbols to engrave?
+@unnumberedsubsec What symbols to engrave?
@cindex engraving
@cindex typography
@seealso
-Program reference: @internalsref{Contexts}.
+Internals Reference: @rinternals{Contexts}.
@lilypond[quote,ragged-right]
\include "engraver-example.ily"
@end lilypond
@node Music representation
-@section Music representation
+@unnumberedsubsec Music representation
Ideally, the input format for any high-level formatting system is an
abstract description of the content. In this case, that would be the
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
@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.
+
+@c FIXME: change this. I can explain it better. -gp
@example
<<c4 d4 e4>>
@end example
@node Example applications
-@section Example applications
+@unnumberedsubsec Example applications
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.
-@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
to mix music and text in documents.
+@node About the documentation
+@section About the documentation
-@node About this manual
-@section About this manual
+This section explains the different portions of the documentation.
+
+@c leave these lines wrapping around. It's some texinfo 4.12 thing. -gp
+@menu
+* About the Learning Manual (LM):: this manual introduces LilyPond, giving in-depth explanations of how to create notation.
-The manual is divided into four books.
+* About the Music Glossary (MG):: this manual explains musical terms and gives translations of terms in other languages.
-@subsubheading Learning manual
+* About the Notation Reference (NR):: this manual is the main portion of the documentation. It provides detailed information about creating notation. This book assumes that the reader knows basic material covered in the LM and is familiar with the English musical terms presented in the MG.
-This book explains how to begin learning LilyPond, as well as explaining
-some key concepts in easy terms.
+* About the Application Usage (AU):: this discusses the actual programs and operation system-specific issues.
-@itemize @bullet
+* About the Snippet List (SL):: this is a collection of short LilyPond examples.
+
+* About the Internals Reference (IR):: this document gives information about LilyPond internal programming information, which is required for constructing tweaks.
+
+* Other documentation:: there are a few other portions of the documentation, such as News items and the mailist archives.
+
+@end menu
+
+
+@node About the Learning Manual (LM)
+@unnumberedsubsec About the Learning Manual (LM)
+
+This book explains how to begin learning LilyPond, as well as
+explaining some key concepts in easy terms. You should read these
+chapters in a linear fashion.
+
+@itemize
@item
-@ifhtml
-The
-@end ifhtml
-@emph{@ref{Tutorial}},
-gives a gentle introduction to typesetting music. First time
-users should start here.
+@ref{Introduction}: explains the background and overall goal of
+LilyPond.
@item
-@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!
+@ref{Tutorial}: gives a gentle introduction to typesetting music.
+First time users should start here.
@item
-@emph{@ref{Working on LilyPond projects}},
-discusses practical uses of LilyPond and how to avoid some common
-problems.
+@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{Tweaking output}},
-shows how to change the default engraving that LilyPond
-produces.
+@ref{Tweaking output}: shows how to change the default engraving
+that LilyPond produces.
-@end itemize
+@item
+@ref{Working on LilyPond projects}: discusses practical uses of
+LilyPond and how to avoid some common problems. Read this before
+undertaking large projects!
-@subsubheading Notation reference
+@end itemize
-This book explains all the LilyPond commands which produce notation. It
-assumes that readers are familiar with the concepts in the Learning
-manual.
+The LM also contains appendices which are not part of the
+recommended linear reading. They may be useful for later
+viewing:
-@itemize @bullet
+@itemize
@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.
+@ref{Templates}: shows ready-made templates of LilyPond pieces.
+Just cut and paste a template into a file, add notes, and you're
+done!
@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.
+@ref{Scheme tutorial}: presents a short introduction to Scheme,
+the programming language that music functions use. This is
+material for advanced tweaks; many users never touch Scheme at
+all.
+
+@end itemize
+
+
+@node About the Music Glossary (MG)
+@unnumberedsubsec About the Music Glossary (MG)
+
+@cindex idiom
+@cindex jargon
+@cindex terminology
+@cindex foreign languages
+@cindex language
+
+@ref{Top,Music glossary,,music-glossary}:
+this explains musical terms, and includes translations to various
+languages. 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.
+
+
+@node About the Notation Reference (NR)
+@unnumberedsubsec About the 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.
+
+@itemize
@item
-@emph{@ref{Advanced notation}},
-discusses topics grouped by notation construct. This section gives
-details about complicated or unusual notation.
+@ruser{Musical 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{Changing defaults}},
-explains how to fine tune layout.
+@ruser{Specialist 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{Non-musical notation}},
-discusses non-musical output such as titles, multiple movements,
-and how to select which MIDI instruments to use.
+@ruser{Input syntax}:
+discusses general information about LilyPond files and controlling
+output.
@item
-@emph{@ref{Spacing issues}},
+@ruser{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.
+@ruser{Changing defaults}:
+explains how to tweak LilyPond to produce exactly the notation you
+want.
+
+@item
+@ruser{Interfaces for programmers}:
+explains how to create music functions with scheme.
@end itemize
+The NR also contains appendices with useful reference charts.
-@subsubheading Program usage
+@itemize
-This book explains how to execute the program and how to integrate
-LilyPond notation with other programs.
+@item
+@ruser{Literature list}:
+contains a set of useful reference books for those who wish to
+know more on notation and engraving.
-@itemize @bullet
+@item
+@ruser{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{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.
+@ruser{Cheat sheet}:
+is a handy reference of the most common LilyPond commands.
@item
-@emph{@ref{LilyPond-book}},
-explains the details behind creating
-documents with in-line music examples, like this manual.
+@ruser{LilyPond command index}:
+an index of all LilyPond @code{\commands}.
@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.
+@ruser{LilyPond index}:
+a complete index.
@end itemize
-@subsubheading Appendices
+@node About the Application Usage (AU)
+@unnumberedsubsec About the Application Usage (AU)
-This book contains useful reference charts.
-
-@itemize @bullet
-@item
-@ifhtml
-The
-@end ifhtml
-@emph{@ref{Literature list}},
-contains a set of useful reference books for those who wish to know
-more on notation and engraving.
+This book explains how to execute the program and how to integrate
+LilyPond notation with other programs.
-@item
-The
-@emph{@ref{Scheme tutorial}},
-presents a short introduction to Scheme, the programming
-language that music functions use.
+@itemize
@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.
+@rprogram{Install}:
+explains how to install LilyPond (including compilation if
+desired).
@item
-@emph{@ref{Templates}},
-of LilyPond pieces. Just cut and paste a
-template into a file, add notes, and you're done!
+@rprogram{Setup}:
+describes how to configure your computer for optimum LilyPond
+usage, such as using special environments for certain text
+editors.
@item
-The
-@emph{@ref{Cheat sheet}},
-is a handy reference of the most common LilyPond commands.
+@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
-The
-@emph{@ref{LilyPond command index}},
-is an index of all LilyPond @code{\commands}.
+@rprogram{LilyPond-book}:
+explains the details behind creating documents with in-line music
+examples, like this manual.
@item
-The
-@emph{@ref{LilyPond index}},
-is a complete index.
+@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 @bullet
-@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.
+@node About the Snippet List (SL)
+@unnumberedsubsec About the Snippet List (SL)
@cindex snippets
@cindex LSR
-@item
-The
-@ifhtml
-@uref{source/input/lsr/collated-files.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.
+@c FIXME: check on kainhofer.
+@ref{Top,LilyPond Snippet List,,lilypond-snippets}:
+this shows a selected set of LilyPond snippets from the
+@uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}
+(LSR). It is in the public domain.
+
+Please note that this document is not an exact subset of LSR. LSR
+is running a stable LilyPond version, so any snippet which
+demonstrates new features of a development version must be added
+separately. These are stored in @file{input/new/} in the LilyPond
+source tree.
+
+The list of snippets for each subsection of the Notation Reference
+(NR) are also linked from the @strong{See also} portion.
+
+
+@node About the Internals Reference (IR)
+@unnumberedsubsec About the Internals Reference (IR)
+
+@c zzz
+@itemize
@item
The
@iftex
-Program reference
+Internals Reference
@end iftex
@ifnottex
-@ref{Top,Program reference,,lilypond-internals}
+@ref{Top,Internals Reference,,lilypond-internals}
@end ifnottex
is a set of heavily cross linked HTML pages, which document the
nitty-gritty details of each and every LilyPond class, object, and
@end itemize
+@node Other documentation
+@unnumberedsubsec Other documentation
+
+FIXME: most of this should go higher up. Discuss News, mailist
+archives, ...?
+
+There are a number of other places which may be very valuable.
+
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/lilypond.html, one big page},
+@uref{source/Documentation/user/lilypond-big-page.html, one big page},
@end ifhtml
which can be searched easily using the search facility of a web
browser.
input files relative to the top-directory of the source archive. For
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
+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},
@cindex lilypond-internals
@cindex internal documentation
@cindex Scheme
-@cindex extending lilypond
+@cindex extending LilyPond
@cindex index
Finally, this and all other manuals, are available online both as PDF
@uref{http://@/www@/.lilypond@/.org/}.
+
+
projects / lilypond.git / blobdiff