@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.38"
+
@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
+@subsection 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
+@subsection 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?
+@subsection 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
+@subsection 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
@node Example applications
-@section Example applications
+@subsection 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 manuals:
-The manual is divided into four books.
+@itemize
+@item
+Learning Manual (LM): this introduces LilyPond, giving in-depth
+explanations of how to create notation.
+
+@item
+Music Glossary (MG): this explains musical terms and gives
+translations of terms in other languages.
-@subsubheading Learning manual
+@item
+Notation Reference (NR): this is the @q{main} portion of the
+documentation. It provides detailed information about creating
+notation.
+
+@item
+Application Usage (AU): this discusses the actual programs and
+operation system-specific issues.
+
+@item
+Snippet List (SL): this is a collection of useful snippets from
+the
+@uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository},
+a public-domain collection of LilyPond examples.
+
+@item
+Other documentation: there are a few other portions of the
+documentation, such as News items and the mailist archives.
+
+@end itemize
+
+@menu
+* About the Learning Manual (LM)::
+* About the Music Glossary (MG)::
+* About the Notation Reference (NR)::
+* About the Application Usage (AU)::
+* About the Snippet List (SL)::
+* Other documentation::
+@end menu
+
+@c zz
+@node About the Learning Manual (LM)
+@subsection About the Learning Manual (LM)
+
+
+@node About the Music Glossary (MG)
+@subsection About the Music Glossary (MG)
+
+@node About the Notation Reference (NR)
+@subsection About the Notation Reference (NR)
+
+@node About the Application Usage (AU)
+@subsection About the Application Usage (AU)
+
+
+@node About the Snippet List (SL)
+@subsection About the Snippet List (SL)
+
+
+@node Other documentation
+@subsection Other documentation
+
+
+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.
+some key concepts in easy terms. It is recommended to read these
+chapters in a linear fashion.
-@itemize @bullet
+@itemize
@item
@ifhtml
users should start here.
@item
-@emph{@ref{Putting it all together}},
-explains some general concepts about the lilypond file format. If
+@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
@end itemize
-@subsubheading Notation reference
+
+@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.
-@itemize @bullet
+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.
@end itemize
-@subsubheading Program usage
-
-This book explains how to execute the program and how to integrate
-LilyPond notation with other programs.
-
-@itemize @bullet
-
-@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 Appendices
This book contains useful reference charts.
-@itemize @bullet
+@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{Templates}},
+@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
+
+
+@subheading Program usage
+
+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 @bullet
+@itemize
@cindex idiom
@cindex jargon
@cindex terminology
@item
The
@ifhtml
-@uref{source/input/lsr/collated-files.html,Snippets}
+@uref{source/input/lsr/lilypond-snippets/index.html,Snippets}
@end ifhtml
@ifnothtml
Snippets
@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
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
projects / lilypond.git / blobdiff