@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
@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
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
@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
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
@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{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
-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.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
-@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