1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
15 This chapter introduces readers to LilyPond and the
19 * About the documentation::
23 @node About the documentation
24 @section About the documentation
26 This section explains the different portions of the documentation.
28 @cindex Learning Manual
29 @cindex Music Glossary
30 @cindex Notation Reference
31 @cindex Application Usage
33 @cindex Internals Reference
35 @c leave these lines wrapping around. It's some texinfo 4.12 thing. -gp
36 @c This is actually a limitation of texi2html. -jm
38 * About the Learning Manual:: this manual introduces LilyPond, giving in-depth explanations of how to create notation.
39 * About the Music Glossary:: this manual explains musical terms and gives translations of terms in other languages.
40 * About the Notation Reference:: 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 Learning Manual and is familiar with the English musical terms presented in the Musical Glossary.
41 * About the Application Usage:: this discusses the actual programs and operating system-specific issues.
42 * About the Snippet List:: this is a collection of short LilyPond examples.
43 * About the Internals Reference:: this document gives reference information about LilyPond's internal structures, which is required for constructing tweaks.
44 * Other documentation:: there are a few other portions of the documentation, such as News items and the mailist archives.
48 @node About the Learning Manual
49 @unnumberedsubsec About the Learning Manual
51 @cindex Learning Manual
53 This book explains how to begin learning LilyPond, as well as
54 explaining some key concepts in easy terms. You should read these
55 chapters in a linear fashion.
57 There is a paragraph @strong{See also} at the end of each section,
58 which contains cross-references to other sections: you should not
59 follow these cross-references at first reading; when you have read all
60 of the Learning Manual, you may want to read some sections again and
61 follow cross-references for further reading.
66 @ref{Introduction}: explains the background and overall goal of
70 @ref{Tutorial}: gives a gentle introduction to typesetting music.
71 First time users should start here.
74 @ref{Fundamental concepts}: explains some general concepts about
75 the LilyPond file format. If you are not certain where to place a
76 command, read this chapter!
79 @ref{Tweaking output}: shows how to change the default engraving
80 that LilyPond produces.
83 @ref{Working on LilyPond projects}: discusses practical uses of
84 LilyPond and how to avoid some common problems. Read this before
85 undertaking large projects!
89 The Learning Manual also contains appendices which are not part of the
90 recommended linear reading. They may be useful for later
96 @ref{Templates}: shows ready-made templates of LilyPond pieces.
97 Just cut and paste a template into a file, add notes, and you're
101 @ref{Scheme tutorial}: presents a short introduction to Scheme,
102 the programming language that music functions use. This is
103 material for advanced tweaks; many users never touch Scheme at
109 @node About the Music Glossary
110 @unnumberedsubsec About the Music Glossary
112 @cindex Music Glossary
116 @cindex foreign languages
119 @rglosnamed{Top,Music glossary}
120 this explains musical terms, and includes translations to various
121 languages. If you are not familiar with music notation or music
122 terminology (especially if you are a non-native English speaker),
123 it is highly advisable to consult the glossary.
126 @node About the Notation Reference
127 @unnumberedsubsec About the Notation Reference
129 @cindex Notation Reference
131 @cindex reference charts
132 @cindex charts, reference
134 This book explains all the LilyPond commands which produce
135 notation. It assumes that readers are familiar with the concepts
136 in the Learning Manual.
141 @ruser{Musical notation}:
142 discusses topics grouped by notation construct. This section
143 gives details about basic notation that will be useful in almost
144 any notation project.
147 @ruser{Specialist notation}:
148 discusses topics grouped by notation construct. This section
149 gives details about special notation that will only be useful for
150 particular instrument (or vocal) groups.
153 @ruser{General input and output}:
154 discusses general information about LilyPond input files and
158 @ruser{Spacing issues}:
159 discusses issues which affect the global output, such as selecting
160 paper size or specifying page breaks.
163 @ruser{Changing defaults}:
164 explains how to tweak LilyPond to produce exactly the notation you
168 @ruser{Interfaces for programmers}:
169 explains how to create music functions with scheme.
173 The Notation Reference also contains appendices with useful
179 @ruser{Literature list}:
180 contains a set of useful reference books for those who wish to
181 know more on notation and engraving.
184 @ruser{Notation manual tables}:
185 are a set of tables showing the chord names, MIDI instruments, a
186 list of color names, and the Feta font.
190 is a handy reference of the most common LilyPond commands.
193 @ruser{LilyPond command index}:
194 an index of all LilyPond @code{\commands}.
197 @ruser{LilyPond index}:
203 @node About the Application Usage
204 @unnumberedsubsec About the Application Usage
206 @cindex Application Usage
207 @cindex integrating LilyPond with other programs
209 This book explains how to execute the programs and how to integrate
210 LilyPond notation with other programs.
216 explains how to install LilyPond, including compilation if
221 describes how to configure your computer for optimum LilyPond
222 usage, such as using special environments for certain text
226 @rprogram{Running LilyPond}:
227 shows how to run LilyPond and its helper programs. In addition,
228 this section explains how to upgrade input files from previous
229 versions of LilyPond.
232 @rprogram{LilyPond-book}:
233 explains the details behind creating documents with in-line music
234 examples, like this manual.
237 @rprogram{Converting from other formats}:
238 explains how to run the conversion programs. These programs are
239 supplied with the LilyPond package, and convert a variety of music
240 formats to the @code{.ly} format.
245 @node About the Snippet List
246 @unnumberedsubsec About the Snippet List
251 @cindex LilyPond Snippet Repository
253 @rlsrnamed{Top,LilyPond Snippet List}: this shows a
254 selected set of LilyPond snippets from the
255 @uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}
256 (LSR). All the snippets are in the public domain.
258 Please note that this document is not an exact subset of LSR. LSR
259 is running a stable LilyPond version, so any snippet which
260 demonstrates new features of a development version must be added
261 separately. These are stored in @file{input/new/} in the LilyPond
264 The list of snippets for each subsection of the Notation Reference are
265 also linked from the @strong{See also} portion.
268 @node About the Internals Reference
269 @unnumberedsubsec About the Internals Reference
271 @cindex Internals Reference
273 @rinternalsnamed{Top,Internals Reference}: this is a set
274 of heavily cross linked HTML pages which document the nitty-gritty
275 details of each and every LilyPond class, object, and function.
276 It is produced directly from the formatting definitions in the
279 Almost all formatting functionality that is used internally is
280 available directly to the user. For example, most variables that
281 control thickness values, distances, etc., can be changed in input
282 files. There are a huge number of formatting options, and all of
283 them are described in this document. Each section of the Notation
284 Reference has a @b{See also} subsection, which refers to the
285 generated documentation. In the HTML document, these subsections
286 have clickable links.
289 @node Other documentation
290 @unnumberedsubsec Other documentation
292 There are a number of other sources of information which may be
300 @uref{../topdocs/NEWS.html,News}:
303 @uref{../../topdocs/NEWS.html,News}:
309 this is a summary of important changes
310 and new features in LilyPond since the previous version.
312 @item @uref{http://lists.gnu.org/archive/html/lilypond-user/, The
313 lilypond-user mailist archives}: this is a collection of previous
314 emails sent to the user list. Many questions have been asked
315 multiple times; there is a very good chance that if you have a
316 question, the answer might be found in these archives.
318 @item @uref{http://lists.gnu.org/archive/html/lilypond-devel/, The
319 lilypond-devel mailist archives}: this is a collection of previous
320 emails sent to the developer's list. The discussion here is more
321 technical; if you have an advanced question about lilypond
322 internals, the answer might be in these archives.
324 @item Embedded music fragments: in all HTML documents that have
325 music fragments embedded, the exact LilyPond input that was used
326 to produce that image can be viewed by clicking the image.
328 @item Init files: the location of the documentation files that are
329 mentioned here can vary from system to system. On occasion, this
330 manual refers to initialization and example files. Throughout this
331 manual, we refer to input files relative to the top-directory of the
332 source archive. For example, @file{input/@/lsr/@/dirname/@/bla@/.ly}
333 may refer to the file
334 @file{lilypond@/2.x.y/@/input/@/lsr/@/dirname/@/bla@/.ly}. On binary
335 packages for the UNIX platform, the documentation and examples can
336 typically be found somewhere below
337 @file{/usr/@/share/@/doc/@/lilypond/}. Initialization files, for
338 example @file{scm/@/lily@/.scm}, or @file{ly/@/engraver@/-init@/.ly},
339 are usually found in the directory @file{/usr/@/share/@/lilypond/}.
340 For more details, see @ref{Other sources of information}.