@end lilypond
A list of all engravers is in the internal documentation,
-@internalsref{All engravers}.
+see @internalsref{All engravers}.
It is also possible to define new contexts from scratch. To do this,
you must define give the new context a name. In the following
@cindex evaluating Scheme
@cindex LISP
-LilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a
-language from the LISP family. You can learn more about Scheme at
-@uref{http://www.scheme.org}. It is used to represent data throughout
-the whole program.
+LilyPond internally uses GUILE, a Scheme-interpreter.
+
+
+Scheme is used to represent data throughout the whole program.
In some places of the input file, Scheme expressions also form valid
syntax: wherever it is allowed, GUILE can be accessed directly by
\property Staff.autoBeaming = ##f
@end example
-Scheme is a full-blown programming language, and a full discussion is
-outside the scope of this document. Interested readers are referred to
-the website @uref{http://www.schemers.org/} for more information on
-Scheme.
-
+Scheme is a full-blown programming language, from the LISP family. and
+a full discussion is outside the scope of this document. Interested
+readers are referred to the website @uref{http://www.schemers.org/}
+for more information on Scheme.
+The GUILE library for extension is documented at
+@uref{http://www.gnu.org/software/guile}.
+@ifinfo
+When it is installed, the following link should take you to its manual
+@ref{(guile.info)guile}
+@end ifinfo
@menu
* Input variables and Scheme::
@end itemize
Many functions are defined to manipulate these data structures. They
-are all listed and documented in @internalsref{All scheme functions}.
+are all listed and documented in the internals manual, see
+@internalsref{All scheme functions}.
@node Assignments
The following example is such a recursive function: it first extracts
the @code{elements} of an expression, reverses them and puts them
-back. Then it recurses, both on @code{elements} and @code{element}.
+back. Then it recurses, both on @code{elements} and @code{element}
+children.
@example
#(define (reverse-music music)
(let* ((elements (ly:get-mus-property music 'elements))
solved if they are well-specified. Moreover, formally defined formats
are easier to write programs for.
-
These ideas shaped our music representation: it is a compact format
that can easily be typed by hand. It complex musical constructs from
simple entities like notes and rests, in much the same way that one
builds complex formulas from simple expressions such as numbers and
mathematical operators.
-@node Program design
-@section Program design
+@node Example applications
+@section Example applications
-The strict separation between musical information and typesetting also
-gives a blueprint of the program: first it reads the music
-representation, then it interprets the music---reading it
-`left-to-right', and translating the musical information to a layout
-specification. When the layout is computed, the resulting symbols are
-written to an output file.
+As programmers and hedonists enjoy beautifully written code, and
+beautifully printed music, but this program can applied to
+do useful things. In this section, we show a few small examples of
+what is possible.
-TODO: more about design?
+[todo: show examples]
-@node Example applications
-@section Example applications
-TODO: show what sort of things lily can be used for.
+The following example combines some more exotic uses of notation
+
+@lilypondfile{screech-boink.ly}
@node About this manual
@section About this manual
-[
-
The manual is divided into the following chapters
-@itemize
+@table @strong
@item Tutorial
-gives a gentle introduction into using lilypond
-@item
-Reference manual: each aspect of typesetting music is discussed
+ Gives a gentle introduction into typesetting music.
+ Start here if you have never used lilypond before.
+@item Reference manual
+ Here, each aspect of typesetting music is discussed.
+@item Internals
+ This chapter discusses how it works from the inside, and how you can
+ extend the program.
+@item Invoking
+ This chapter explains how to runn LilyPond and its helper programs.
+@end itemize
+
+Once you are experienced with, you can simply use the manual as
+reference: there is an extensive index@footnote{If you are looking for
+something, and you cannot find it by using the index, that is
+considered a bug. In that case, please file a bug report}, but the
+document is also available in
+@ifhtml
+One Big Page,
+@end ifhtml
+@ifnothtml
+@uref{One Big Page,../lilypond.html}
+@end ifnothtml
+which is is available for text search using your browser's search
+facility.
+@cindex search in manual
+@cindex using the manual
+
+
+If you are familiar with music notation, and music terminology
+(especially if you are a foreigner), then it is advisable to consult
+the glossary as well. This documents explains many terms, and includes
+translations to various languages. It is a
+@ifhtml
+@uref{separate document,../glossary.html}
+@end ifhtml
+@ifnothtml
+separate document, and can be printed as well.
+@end ifnothtml
+@cindex idiom
+@cindex jargon
+@cindex terminology
+@cindex foreign languages
+@cindex language
+
+
+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
-Advanced topics: how it works from the inside, scripting lilypond.
+Generated internal documentation.
+@ifhtml
+available @uref{here,../lilypond-internals/lilypond-internals.html}
+@end ifhtml
+
+Almost all formatting functionality that is used internally, is
+available directly to the user. For example, all variables that
+control thicknesses, distances, etc, can be changed from input
+files. There are a huge number of formatting options, and it would be
+impossible to describe them all in a hand-written manual. The
+generated internal documentation is a heavily crosslinked HTML
+document, produced directly from the formatting definitions used. It
+the nit-gritty details of each and every LilyPond class, object and
+function.
+
+Each section of the reference manual has a @b{See also}
+subsection, with links (in the HTML document, at least) to the
+generated documentation.
+
@item
-Invoking: running LilyPond and its helper programs.
-@end itemize
+ Templates
+@ifhtml
+available @uref{here,../../../input/templates/out-www/collated-files.html}
+@end ifhtml
-This manual is not complete: a part of the functionality is available
-through a generic system of properties: variables that can be set by
-the user to override certain functionality. Accompanying this manual
-is a document that describes all properties available, and all types
-of typographic and musical objects.
-
-TODO: rewrite rest of this section too.
-]
-
-As you will notice in the coming pages the program makes good
-decisions in a lot of cases: what comes out of LilyPond generally
-looks good. The default layout of lilypond even is suitable for
-publication for some specific files. However, some aspects of the
-formatting are not yet very good. For us programmers, this gives
-inspiration for improving the program. However, most users are more
-interested in improving their printouts, and then they have to make
-manual adjustments to the output. Another aspect of our system of
-encoding through ASCII then shows: it can be complicated to fine tune
-the layout of a piece. There is no graphical user interface, where you
-can simply click and drag a symbol. On the other hand, if you have
-written the code for tuning one specific aspect of the layout, then
-you can simply store the file on disk, retrieve it when you need it:
-there is no need to remember how you did it, since it is all in the
-input file.
+ When you have gone through the tutorial, you theoretically should be
+able to start writing input files. However, this turns out to be a
+little intimidating. To give you a headstart, we have collected a
+number of often-used formats in example files. You can take one of
+these example files, and add notes in the appropriate places to
+generate output.
+@item
+ Various input examples
+@ifhtml
+available @uref{here,../../../input/test/out-www/collated-files.html}
+@end ifhtml
@cindex snippets
-@cindex adjusting output
-Lilypond also comes with a huge collection of snippets that show all
-kinds of tricks. This collection is much needed, because of the way
-LilyPond is structured. It is a large program, but almost all of the
-internal functionality is exported: that is, the variables that are
-internally used for formatting the sheet music are available directly
-to the user. These are variables to control thicknesses, distances,
-and other formatting options. There are a huge number of them, and it
-would be impossible to describe them all in a hand-written
-manual. There is no need to despair, there is an `automatic' manual,
-that lists all of the variables that are available. It is directly
-generated from the definitions that LilyPond itself uses, so it is
-always up to date. If you are reading this from a screen: it is
-available from the web, and is included with most binary
-distributions. If you are reading this from paper, then we advise you
-to use the digital version anyway: the hyperlinks make finding topics
-in the lilypond-internals manual much easier.
+These small files show various applications of lilypond, and are
+available as a big HTML document, with pictures and explanatory texts
+included.
+
+@item
+ The regression test
+@ifhtml
+available @uref{here,../../../input/regression/out-www/collated-files.html}
+@end ifhtml
+
+We strive to test each feature in a collection of input snippets. This
+is primarily to help us debug the program, but it can be instructive
+to see how we excercise the program. The format is like the input
+examples.
+
+@end itemize
+
+@cindex adjusting output
@cindex variables
@cindex properties
@cindex lilypond-internals
@cindex internal documentation
-
-For those who really want to get their hands dirty: it is even
-possible to add your own functionality, by extending LilyPond in the
-built-in scripting language, a dialect of the powerful programming
-language Scheme. There is no real distinction between what a user can
-do and what a programmer is allowed to do.
-
@cindex Scheme
@cindex extending lilypond
-
-In summary, this manual does not pretend to be exhaustive, but it is
-merely a guide that tries to explain the most important principles,
-and shows popular input idioms. The rest of the manual is structured
-as follows: it starts with a tutorial that explains how to use
-lilypond. In the tutorial, a number of fragments of increasing
-complexity are shown and explained. Then comes the reference manual,
-which gives more detailed information on all features. If you are new
-to lilypond, then you should start reading the tutorial, and
-experiment for yourself. If you already have some experience, then
-you can simply use the manual as reference: there is an extensive
-index@footnote{If you are looking for something, and you cannot find it
-by using the index, that is considered a bug. In that case, please
-file a bug report}, but the document is also available in One Big Page,
-@c should have hyperlink?
-which is is available for text search using your browser's search
-facility.
-
-@cindex searchin manual
-@cindex using the manual
@cindex bugreport
@cindex index
-@cindex tutorial
-@cindex overview of manual
-@cindex idiom
-
-[TODO: edit following]
-
-This is the end of the tutorial. If you read everything until this point
-(and understood everything!) then you are now an accomplished lilypond
-hacker. From here you should try fiddling with input files or making your
-own input files. Come back to the reference manual for more information
-if you get stuck!
-
-Do not forget to check out the
-@ifhtml
-@uref{../../../../input/template/out-www/template.html,templates},
-@uref{../../../../input/test/out-www/test.html,examples} and
-@uref{../../../../input/regression/out-www/regression.html,feature tests}.
-@end ifhtml
-@ifnothtml
-templates, examples and feature tests.
-@end ifnothtml
-If you want to see real action LilyPond, head over to
-@uref{http://www.mutopiaproject.org}, which has many examples of
-classical music typeset with LilyPond.
@unnumbered Preface
@menu
-* Preface to version 1.8::
-* Preface to version 1.6::
+* Preface to version 1.8::
+* Preface to version 1.6::
@end menu
@node Preface to version 1.8
@unnumberedsec Preface to version 1.8
-The 1.8 release brings old thing, in new, flashier
-clothes. Previously, the program used to have half-baked solutions to
-various problems. In version 1.8, we took the good parts of the
-solutions, threw away the bad code, and rebuilt the rest of the
-formatting code. Version 1.8 has revamped support for
+During the past year when we worked on 1.8, the focus has not so much
+been on adding shiny new features, or more excellent
+typography. Instead, we have taken stock of how various things worked
+on the inside. In many cases, we found new and more elegant ways to
+implement these systems, making them more robust and more flexible.
-@itemize
-@item Chord names
-@item Entering normal chords
-@item Formatting text
-@item Storing music expressions
-@item Manipulating identifiers and music
-@end itemize
+If you are familiar with LilyPond version 1.6, then version 1.8 will
+no offer no big surprises. The only real change from 1.6 to 1.8 is the
+way that formatted text is entered. There is now a new syntax that is
+more friendly, more versatile and extensible. We hope you like it.
-Version 1.8 is a preparation for version 2.0, which is expected to
-follow 1.8 shortly. Version 2.0 will have a number of significant,
-non-backwards-compatible changes in the input syntax.
+Less visible changes include rewritten chord name formatting and entry
+code, revised music expression storage, and tighter integration
+between lilypond variables and Scheme variables.
-Special thanks for version 1.8 go out to Juergen Reuter for lots of
-work on the ancient notation engine, and to Amy Zapf for pushing to
-rewrite chord name support
+Special thanks for version 1.8 go out to Juergen Reuter for lots of
+work on the ancient notation engine, and to Amy Zapf for pushing us to
+rewrite the chord name support
[wie meer?]
+Utrecht/Eindhoven, April/May 2003
+
@node Preface to version 1.6
@unnumberedsec Preface to version 1.6
and dots: durations are entered as their reciprocal values. For example,
a quarter note is entered using a @code{4} (since it is a 1/4 note), while
a half note is entered using a @code{2} (since it is a 1/2 note). For notes
-longer than a whole you must use identifiers.
+longer than a whole you must use variables.
+
@c FIXME: what is an identifier? I do not think it's been introduced yet.
@c and if it has, I obviously skipped that part. - Graham
}
@end lilypond
-The @code{EasyNotation} identifier overrides a @internalsref{Score}
+The @code{EasyNotation} variable overrides a @internalsref{Score}
context. You probably will want to print it with magnification or a
large font size to make it more readable. To print with
magnification, you must create a DVI file (with @file{ly2dvi}) and
This section describes how to change the way that LilyPond automatically
inserts accidentals before the running notes.
-[TODO: identifier vs. macro]
@menu
-* Using the predefined accidental macros::
+* Using the predefined accidental variables::
* Defining your own accidental typesettings::
@end menu
-@node Using the predefined accidental macros
-@subsection Using the predefined accidental macros
+@node Using the predefined accidental variables
+@subsection Using the predefined accidental variables
+
The constructs for describing the accidental typesetting rules are
-quite hairy, so non-experts should stick to the macros defined in
+quite hairy, so non-experts should stick to the variables defined in
@file{ly/property-init.ly}.
@cindex @file{property-init.ly}
-The macros operate on the ``Current'' context (see @ref{Context properties}). This
-means that the macros shuold normally be invoked right after the
-creation of the context in which the accidental typesetting described
-by the macro is to take effect. I.e. if you want to use
-piano-accidentals in a pianostaff then you issue
+The variables set properties in the ``Current'' context (see @ref{Context
+properties}). This means that the variables shuold normally be added
+right after the creation of the context in which the accidental
+typesetting described by the variable is to take effect. I.e. if you
+want to use piano-accidentals in a pianostaff then you issue
@code{\pianoAccidentals} first thing after the creation of the piano
staff:
@example
}
@end lilypond
-The macros are:
+The variables are:
@table @code
@item \defaultAccidentals
@cindex @code{\defaultAccidentals}
@item \voiceAccidentals
@cindex @code{\voiceAccidentals}
- The normal behaviour is to remember the accidentals on
- Staff-level.
- This macro, however, typesets accidentals individually for each
- voice.
- Apart from that the rule is similar to
- @code{\defaultAccidentals}.
+@c
+ The normal behaviour is to
+remember the accidentals on Staff-level. This variable, however,
+typesets accidentals individually for each voice. Apart from that the
+rule is similar to @code{\defaultAccidentals}.
This leads to some weird and often unwanted results
because accidentals from one voice do not get cancelled in other
@cindex @code{\modernVoiceCautionaries}
@item \modernVoiceCautionaries
-is the same as
-@code{\modernVoiceAccidentals}, but with the extra accidentals (the
-ones not typeset by @code{\voiceAccidentals}) typeset as cautionaries.
-Even though all accidentals typeset by @code{\defaultAccidentals}
-@emph{are} typeset by this macro then some of them are typeset as
-cautionaries.
+is the same as @code{\modernVoiceAccidentals}, but with the extra
+accidentals (the ones not typeset by @code{\voiceAccidentals}) typeset
+as cautionaries. Even though all accidentals typeset by
+@code{\defaultAccidentals} @emph{are} typeset by this variable then
+some of them are typeset as cautionaries.
@item \pianoAccidentals
@cindex @code{\pianoAccidentals}
@cindex @code{\rfz}
-Absolute dynamic marks are specified using an identifier after a
+Absolute dynamic marks are specified using an variable after a
note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
If you want to adjust padding or vertical direction of the dynamics,
you must set properties for the @internalsref{DynamicLineSpanner}
-object. Predefined identifiers to set the vertical direction are
-\dynamicUp and \dynamicDown.
+object. Predefined variables to set the vertical direction are
+@code{\dynamicUp} and @code{\dynamicDown}.
@cindex direction, of dynamics
@cindex @code{\dynamicDown}
@end example
@noindent
-is interpreted as the string identifier assignment. However,
-it can also be interpreted as making a string identifier @code{\foo}
-containing @code{"bar"}, or a music identifier @code{\foo} containing
-the syllable `bar'. The former interpretation is chosen. The latter
-can be specified using
+is interpreted as assigning a string identifier @code{\foo} such that
+it contains @code{"bar"}. However, it could also be interpreted as
+making or a music identifier @code{\foo} containing the syllable
+`bar'. The force the latter interpretation, use
@example
foo = \lyrics bar
@end example
Texts can be added to multi-measure rests by using the
@var{note}-@code{markup} syntax. In this case, the number is
replaced. If you need both texts and the number, you must add the
-number by hand. An identifier (@code{fermataMarkup}) is provided for
+number by hand. A variable (@code{\fermataMarkup}) is provided for
adding fermatas.
For @internalsref{Lyrics}, @internalsref{LyricsVoice},
@internalsref{ChordNames} and @internalsref{FiguredBass}, hara-kiri is
switched on by default. For normal staffs, hara kiri is available as a
-specialized @internalsref{Staff} context, with the name identifier
+specialized @internalsref{Staff} context, with the name variable
@code{\HaraKiriStaffContext}. Observe how the second staff in this
example disappears in the second line.
Definitions for these sizes are the files @file{paperSZ.ly}, where
@code{SZ} is one of 11, 13, 16, 19, 20, 23 and 26. If you include any
-of these files, the identifiers @code{paperEleven},
+of these files, the variables @code{paperEleven},
@code{paperThirteen}, @code{paperSixteen}, @code{paperNineteen},
@code{paperTwenty}, @code{paperTwentythree}, and @code{paperTwentysix}
are defined respectively. The default @code{\paper} block is also
projects / lilypond.git / commitdiff