+1.3.126
+=======
+* Doco:
+ - fixes,
+ - updates,
+ - rewrites.
+ - Changed license to FDL.
+ - added index entries
+ - tutorial: 0-th tune
+ - literature overview.
+ - removed development stuff.
+
+
1.3.125.jcn3
============
* Clef workarounds for Coriolan.
-1.3.125.jcn2
-============
-
* Moved feature and regression-test input to input/feature, input/regression.
* Added some regtests.
* Bugfix: measure System_start_delimiter's *-collapse-height in staff-space.
-1.3.125.jcn1
-============
-
* Fixed some info and html links.
* Automatic knees now on by default for vertical distances >= 7 staff-space.
-1.3.124.jcn3
-============
+1.3.125
+=======
* Updated Coriolan.
author = {Kurt Stone},
publisher= {Norton},
address={New York},
- note ={Out of print. Heussenstamm writes: The most important book on notation in recent years. },
+ note ={Heussenstamm writes: The most important book on notation in recent years. },
}
@Book {Heussenstamm87,
@itemize @bullet
-@item a sample input which causes the error. This is @strong{important
-} to determine the cause of the problem.
+@item a sample input which causes the error. Without this, we can not
+verify your problem.
(and you will do us a favor if send a @strong{small} sample file)
-@item which LilyPond version you use. This is @strong{important information}
+@item which LilyPond version you use. Without this, we can not verify
+your problem.
This information tells us if you've found a new bug, or an old one.
@end itemize
-You can send the report to @email{bug-gnu-music@@gnu.org}---You don't
-have to be subscribed to this mailinglist, or you can enter the bug in
-the LilyPond wiki, at
-@uref{http://appel.lilypond.org/wiki?LilyPondBugs}.
+You can send the report to @email{bug-gnu-music@@gnu.org}. This is a
+mailinglist, but you don't have to be subscribed to it. You may also
+enter the bug in the LilyPond wiki, at
+@uref{http://appel.lilypond.org/wiki?LilyPondBugs}.
@c -*-texinfo-*-
@node convert-ly
-@section convert-ly
+@chapter convert-ly
-Convert-ly sequentially applies different
-lilypond-conversions to upgrade a Lilypond input file. It uses
-@code{\version} statements in the file to detect the old version
-number.
+Convert-ly sequentially applies different conversions to upgrade a
+Lilypond input file. It uses @code{\version} statements in the file to
+detect the old version number.
@subsection Invoking convert-ly
@end example
-@table @samp
+@table @code
@item --output
The output file to write.
@item --edit
Not all language changes are handled. Multiple output options won't
work.
-convert-ly is written in python, so you have install
-@uref{http://www.python.org,python}. It was written by
-@email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}.
+@code{convert-ly} is written in @uref{http://www.python.org,Python}. It
+was written by @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}.
--- /dev/null
+@c -*-texinfo-*-
+
+@node Conversion tools
+@chapter Converting to LilyPond format.
+
+@section midi2ly
+
+Midi2ly translates a MIDI input file to a LilyPond source file.
+Midi2ly is part of the GNU LilyPond music typesetting package.
+
+@subsection Invoking midi2ly
+
+@example
+ midi2ly [options] midi-file
+@end example
+
+@table @code
+@item -b, --no-quantify,
+ Write exact durations, e.g.: `a4*385/384'.
+@item -D, --debug,
+ Print lots of debugging stuff.
+@item -h, --help,
+ Show a summary of usage.
+@item -I, --include=@file{DIR},
+ Add DIR to search path.
+@item -k, --key=ACC[:MINOR],
+ Set default key. ACC > 0 sets number of sharps; ACC < 0 sets number
+ of flats. A minor key is indicated by ":1".
+@item -n, --no-silly,
+ Assume no plets or double dots, assume smallest (reciprocal) duration 16.
+@item -o, --output=@file{FILE},
+ Set @file{FILE} as default output.
+@item -p, --no-plets,
+ Assume no plets.
+@item -q, --quiet,
+ Be quiet.
+@item -s, --smallest=N,
+ Assume no shorter (reciprocal) durations than N.
+@item -v, --verbose,
+ Be verbose.
+@item -w, --warranty,
+ Show the warranty with which midi2ly comes. (It comes with @strong{NO WARRANTY}!)
+@item -x, --no-double-dots,
+ Assume no double dotted notes.
+@end table
+
+
+@section etf2ly
+
+@subsection Invoking etf2ly
+Usage:
+
+
+
+@example
+ etf2ly [OPTION]... ETF-FILE
+@end example
+
+Convert ETF to LilyPond.
+
+Options:
+@table @code
+@item -h,--help
+this help
+@item -o,--output=FILE
+set output filename to FILE
+@item -v,--version
+version information
+@end table
+
+Enigma Transport Format is a format used by Coda Music Technology's
+Finale product. This program will convert a subset of ETF to a
+ready-to-use lilypond file.
+
+Report bugs to bug-gnu-music@@gnu.org
+
+Written by Han-Wen Nienhuys
+
+[descibe abc2ly, pmx2ly, etf2ly, musedata2ly here]
+
@c -*-texinfo-*-
@c Move chapter
-@node Internals
-@chapter Internals
-
-@menu
-* Conversion stages:: Lilypond is a multi-pass program.
-* Moment::
-* Grobs:: Graphical object
-* Engraver::
-* Music_iterator::
-* Music::
-* Molecules:: Molecules are stand-alone descriptions of output
-* Font metrics:: Font metrics
-@end menu
-
-@node Conversion stages
-@section Conversion stages
-
-When translating the input to notation, there are number of distinct
-phases. We list them here:
-
-@table @samp
-
-@item Parsing:
-
-The .ly file is read, and converted to a list of @code{Scores}, which
-each contain @code{Music} and paper/midi-definitions.
-
-@item Interpreting music
-@cindex interpreting music
-
-All music events are "read" in the same order as they would be played
-(or read from paper). At every step of the interpretation, musical
-events are delivered to
-interpretation contexts,
-@cindex engraver
-which use them to build grobs (or MIDI objects, for MIDI output).
-
-@item Prebreaking
-
-@cindex prebreaking
-
-At places where line breaks may occur, clefs and bars are prepared for
-a possible line break.
-
-@item Preprocessing
-
-@cindex preprocessing
-
-In this stage, all information that is needed to determine line breaking
-is computed.
-
-@item Break calculation:
-
-The lines and horizontal positions of the columns are determined.
-
-@item Breaking
-
-Relations between all grobs are modified to reflect line breaks. See
-also @ref{Pointer substitution}.
-
-@item Outputting:
-
-All vertical dimensions and spanning objects are computed, and all grobs
-are output, line by line.
-
-@end table
-
-@node Moment
-@section Moment
-
-Moment is a rational number. Since GUILE doesn't support them natively,
-so we created our own rational data type.
-
-@defun moment?
-@end defun
-
-@defun make-moment num den
-create the rational number @var{num}/@var{den}.
-@end defun
-
-@node Grobs
-@section Grobs
-
-This section is about Grobs (short for Graphical Objects), which are
-formatting objects used to create the final output. This material is
-normally the domain of LilyPond gurus, but occasionally, a normal user
-also has to deal with grobs.
-
-The most simple interaction with Grobs are when you use
-@code{\override}:
-
-@example
- \property Voice.Stem \override #'direction = #1
-@end example
-
-This piece of lily input causes all stem objects to be stem-up
-henceforth. In effect, you are telling lilypond to extend the defintion
-of the "Stem" grob with the setting @code{direction := 1}. Of course
-there are many more ways of customizing Lily output, and since most of
-them involve Grobs in some form, this section explains some details of
-how grobs work.
-
-@menu
-* What is a grob?::
-* Callbacks::
-* Setting grob properties::
-* Items and Spanners::
-* Pointer substitution::
-* Grob Scheme functions::
-@end menu
-
-@node What is a grob?
-@subsection What is a grob?
-
-In music notation, lots of symbols are related in some way. You can
-think of music notation as a graph where nodes are formed by the
-symbols, and the arcs by their relations. A grob is node in that
-graph. A grob stores references to other grobs, the directed edges in
-the graph.
-
-The objective of this big graph of grobs, is to specify the notation
-problem. The solution of this problem is a description of the printout
-that is in closed form, i.e. but a list of values. These values are
-Molecules. (see @ref{Molecules})
-
-All grobs have an X and Y-position on the page. These X and Y positions
-are stored in a relative format, so they can easily be combined by
-stacking them, hanging one grob to the side of another, and coupling
-them into a grouping-grob.
-
-Each grob has a reference point, or parent: the position of a grob is
-stored relative to that reference point. For example the X-reference
-point of a staccato dot usually is the note head that it applies
-to. Whenever the note head is moved, the staccato dot moves along
-automatically.
-
-If you keep following offset reference points, you will always end up at
-the root-object. This root object is called @rgrob{Line_of_score}, and it
-represents a system (ie. a line of music).
-
-All grobs carry a set of grob-properties. In the Stem example above,
-the property @code{direction} is set to value @code{1}. The function
-that draws the symbol (@code{Stem::brew_molecule}) uses the value of
-@code{direction} to determine how to print the stem and the flag. The
-appearance of a grob is determined solely by the values of its
-properties.
-
-Often, a grob also is associated with a symbol. On the other hand,
-Some grobs do not print any symbols, but take care of grouping
-objects. For example, there is a separate grob that stacks staffs
-vertically, so they are not printed in overstrike. The
-@rgrob{NoteCollision} is another example of an abstract grob. It only
-moves around chords, but doesn't print anything.
-
-A complete list of grob types is found in
-@ref{(lilypond-internals)LilyPond backend}
-
-Grobs are created in the "Interpreting music" phase, by things in
-LilyPond called engravers. In this phase of the translation, a load of
-grobs are created, and they are linked into a giant network of objects.
-This network of grobs forms the "specification" of the print
-problem. This problem is then solved: configurations, directions,
-dimensions, line breaks, etc. are calculated. Finally, the printing
-description in the form of Molecules (@ref{Molecules}) is extracted from
-the network. These are then dumped into the output file
-
-@node Callbacks
-@subsection Callbacks
-
-Offsets of grobs are relative to a parent reference point. Most
-positions are not known when an object is created, so these are
-calculated as needed. This is done by adding a callback for a specific
-direction.
-
-Suppose you have the following code in a .ly file.
-@example
- #(define (my-callback gr axis)
- (* 2.0 (get-gr-property grob 'direction))
- )
-
-....
-
- \property Voice.Stem \override #'Y-offset-callbacks = #(list
- my-callback)
-@end example
-
-When the Y-offset of a Stem object is needed, LilyPond will
-automatically execute all callbacks for that object. In this case, it
-will find @code{my-callback}, and execute that. The result is that the
-stem is translated by two staff spaces in its direction.
-
-(note: Y-offset-callbacks is also a property)
-
-
-Offset callbacks can be stacked, ie.
-
-@example
- \property .... \override #'Y-offset-callbacks = #(list
- callback1 callback2 callback3)
-
-@end example
-
-The callbacks will be executed in the order callback3 callback2
-callback1. This is used for quantized positioning: the staccato dot is
-above or below a note head, and it must not be on a staff-line.
-
-To achieve this, for the staccato there are two callbacks: one callback
-that positions the grob above or below the note head, and one callback
-that rounds the Y-position of the grob to the nearest open space.
-
-Similarly, the size of a grob are determined through callbacks, settable
-with grob properties @code{X-extent-callback} and @code{Y-extent-callback}.
-There can be only one extent-callback for each axis. No callback (value #f)
-means: "empty in this direction". If you fill in a pair, that pair
-hard-codes the extent in that coordinate.
-
-
-@node Setting grob properties
-@subsection Setting grob properties
-
-Grob properties are stored as GUILE association lists, with symbols as
-keys. From C++, element properties can be accessed using the functions
-
-@example
- SCM get_grob_property (SCM) const;
- void set_grob_property (const char * , SCM val);
- void set_immutable_grob_property (const char * , SCM val);
- void set_immutable_grob_property (SCM key, SCM val);
- void set_grob_property (SCM , SCM val);
- void set_grob_pointer (const char*, SCM val);
- SCM remove_grob_property (const char* nm);
-@end example
-
-In GUILE, LilyPond provides
-
-@example
- ly-get-grob-property GROB SYMBOL
- ly-set-grob-property GROB SYMBOL VALUE
-@end example
-
-All lookup functions identify undefined properties with
-end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
-
-Properties are stored in two ways:
-@itemize @bullet
-@item mutable properties:
-element properties that change from object to object. The storage of
-these are private to a grob. Typically this is used to store lists of
-pointers to other grobs
-
-@item immutable properties:
-element properties that are shared across different grobs of the same
-type. The storage is shared, and hence it is read-only. Typically, this
-is used to store function callbacks, and values for shared element
-properties are read from @file{scm/element-description.scm}.
-@end itemize
-
-There are two ways to manually set grob properties.
-
-You can change immutable grob properties. This is done with the
-\override syntax:
-
-@example
- \property Voice.Stem \override #'direction = #1
-@end example
-
-This will push the entry @code{'(direction . 1)} on the immutable
-property list for stems, in effect overriding the setting from
-@file{scm/element-description.scm}. This can be undone by
-
-@example
- \property Voice.stem \revert #'direction
-@end example
-
-If you use this a lot, this gets old quickly. So we also have a
-shorthand,
-
-@example
- \property Context.GrobType \set #'prop = #VAL
-@end example
-
-this does a @code{\revert} followed by a @code{\override}
-
-The second way is \outputproperty. This construct looks like
-
-@example
- \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
-@end example
-
-In this case, in every grob that satisfies @var{pred}, the property
-assignment @var{sym} = @var{val} is done. For example
-
-@example
- \outputproperty
- #(lambda (gr) (string? (ly-get-grob-property gr
- 'text)))
- #'extra-offset = #'(-1.0 . 0.0)
-@end example
-
-This shifts all elements that have a @code{text} property one staff
-space to the left. This mechanism is rather clumsy to use, but it allows
-you tweak any setting of any grob.
-
-@node Items and Spanners
-@unnumberedsubsec Items and Spanners
-
-Grobs can also be distinguished in their role in the horizontal spacing.
-A lot of grobs define constraints on the spacing by their sizes. For
-example, note heads, clefs, stems, and all other symbols with a fixed
-shape. These grobs form a subtype called @code{Item}.
-
-Other grobs have a shape that depends on the horizontal spacing. For
-example, slur, beam, tie, etc. These grobs form a subtype called
-@code{Spanner}. All spanners have two span-points (these must be
-@code{Item}s), one on the left and one on the right. The left bound is
-also the X-reference point.
-
-Some items need special treatment for line breaking. For example, a
-clef is normally only printed at the start of a line (ie. after a line
-break). To model this, `breakable' items (clef, key signature, bar lines,
-etc.) are copied twice. Then we have three versions of each breakable
-item: one version if there is no line break, one version that is printed
-before the line break (at the end of a system), one version that is
-printed after the line break.
-
-Whether these versions are visible and take up space, is determined by
-the outcome of the visibility-lambda. This is a function taking a
-direction (-1, 0 or 1) and returns a cons of booleans, signifying wether
-this grob should be transparent and invisible.
-
-@node Pointer substitution
-@unnumberedsubsec Pointer substitution
-
-
-Symbols that cross line-breaks (such as slurs) cause some more
-complications. When a spanner crosses a line-break, then the spanner is
-"broken into pieces", for every line that the spanner is in, a copy of
-the grob is made. A substitution process redirects all grob-reference
-so that spanner grob will only reference other grobs in the same line.
-
-@node Grob Scheme functions
-@unnumberedsubsec Grob Scheme functions
-
-
-@defun ly-get-grob-property g sym
- Get the value of a value in grob @var{g} of property @var{sym}. It
-will return @code{'()} (end-of-list) if not true.
-@end defun
-
-@defun ly-set-grob-property g sym val
-@end defun
-
-@defun ly-get-spanner-bound spanner dir
-@end defun
-
-@defun ly-grob? g
-@end defun
-
-
-
-@node Engraver
-@section Engraver
-
-@node Music_iterator
-@section Music_iterator
-
-@node Music
-@section Music
-
-@node Molecules
-@section Molecules
-
-@cindex Molecule
-@cindex Atom
-@cindex Output description
-
-The objective of any typesetting system is to put ink on paper in the
-right places. For LilyPond, this final stage is left to the TeX and the
-printer subsystem. For lily, the last stage in processing a score is
-outputting a description of what to put where. This description roughly
-looks like
-
-@example
- PUT glyph AT (x,y)
- PUT glyph AT (x,y)
- PUT glyph AT (x,y)
-@end example
-
-you merely have to look at the tex output of lily to see this.
-Internally these instructions are encoded in Molecules:@footnote{At some
-point LilyPond also contained Atom-objects, but they have been replaced
-by Scheme expressions.}. A molecule is an object that combines
-dimension information (how large is this glyph ?) with
-what-to-print-where.
-
-Conceptually, Molecules can be constructed from Scheme code, by
-translating a Molecule and by combining two molecules. In BNF
-notation:
-
-@example
- Molecule = COMBINE Molecule Molecule
- | TRANSLATE Offset Molecule
- | GLYPH-DESCRIPTION
- ;
-@end example
-
-If you are interested in seeing how this information is stored, you
-can run with the @code{-f scm} option. The scheme expressions are then
-dumped onto the output file.
-
-(refer to the C++ code for more details). All visible,
-ie. non-transparant, grobs have a callback to create a Molecule. The
-name of the property is @code{molecule-callback}, and its value should
-be a Scheme function taking one argument (the grob) and returning a
-Molecule.
-
-@defun molecule? m
-@end defun
-
-@defun ly-combine-molecule-at-edge mol1 axis dir mol2 padding
-@end defun
-
-@defun molecule? m
-@end defun
-
-@defun ly-get-molecule-extent! mol axis
-@end defun
-
-@defun ly-set-molecule-extent! mol axis extent
-@end defun
-
-@node Font metrics
-@section Font metrics
-
-The font object represents the metric information of a font. Every font
-that is loaded into LilyPond can be accessed via Scheme.
-
-[tfm vs. afm]
-
-
-@defun ly-get-default-font gr
-This returns the default font for grob @var{gr}.
-@end defun
-
-@defun ly-find-glyph-by-name font name
-This function retrieves a Molecule for the glyph named @var{name} in
-@var{font}. The font must be available as a afm file.
-@cindex afm file
-
-@end defun
-
@node Development
@chapter Development
@example
".hh" Include files
- ".cc" Implementation files
- ".icc" Inline definition files
- ".tcc" non inline Template defs
+ ".cc" Implementation files
+ ".icc" Inline definition files
+ ".tcc" non inline Template defs
@end example
in emacs:
@example
- (setq auto-mode-alist
- (append '(("\\.make$" . makefile-mode)
- ("\\.cc$" . c++-mode)
- ("\\.icc$" . c++-mode)
- ("\\.tcc$" . c++-mode)
- ("\\.hh$" . c++-mode)
- ("\\.pod$" . text-mode)
- )
- auto-mode-alist))
+ (setq auto-mode-alist
+ (append '(("\\.make$" . makefile-mode)
+ ("\\.cc$" . c++-mode)
+ ("\\.icc$" . c++-mode)
+ ("\\.tcc$" . c++-mode)
+ ("\\.hh$" . c++-mode)
+ ("\\.pod$" . text-mode)
+ )
+ auto-mode-alist))
@end example
Standard GNU coding style is used. In emacs:
@example
- (add-hook 'c++-mode-hook
- '(lambda() (c-set-style "gnu")
- )
- )
+ (add-hook 'c++-mode-hook
+ '(lambda() (c-set-style "gnu")
+ )
+ )
@end example
If you like using font-lock, you can also add this to your @file{.emacs}:
@example
- (setq font-lock-maximum-decoration t)
- (setq c++-font-lock-keywords-3
- (append
- c++-font-lock-keywords-3
- '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
- ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
- ))
+ (setq font-lock-maximum-decoration t)
+ (setq c++-font-lock-keywords-3
+ (append
+ c++-font-lock-keywords-3
+ '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
+ ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
+ ))
@end example
@unnumberedsubsec Classes and Types
@example
- This_is_a_class
+ This_is_a_class
@end example
@unnumberedsubsec Members
@example
- Class::member ()
- Type Class::member_type_
- Type Class::member_type ()
+ Class::member ()
+ Type Class::member_type_
+ Type Class::member_type ()
@end example
the @code{type} is a Hungarian notation postfix for @code{Type}. See below
@unnumberedsubsec Types
-@table @samp
+@table @code
@item @code{byte}
unsigned char. (The postfix _by is ambiguous)
@item @code{b}
@example
- /*
+ /*
Slur blah. blah.
- */
- class Slur @{
+ */
+ class Slur @{
...
@};
- Slur* slur_p = new Slur;
+ Slur* slur_p = new Slur;
@end example
The following types modify the meaning of the prefix.
These are preceded by the prefixes:
-@table @samp
+@table @code
@item @code{a}
array
@item @code{arr}
static class members do not need the static_ prefix in the name (the
Class::var notation usually makes it clear that it is static)
-@table @samp
+@table @code
@item @code{loop_i}
Variable loop: an integer
@item @code{u}
@example
- static Array<int*> foo
+ static Array<int*> foo
@end example
@example
- foo_static_l_arr
+ foo_static_l_arr
@end example
@example
VERSION:
- ...
- MY_PATCH_LEVEL=jcn1
+ ...
+ MY_PATCH_LEVEL=jcn1
@end example
In @file{CHANGES}, enter a summary of changes:
@example
- 0.1.73.jcn1
+ 0.1.73.jcn1
===========
* A concise, yet clearly readable description of what changed.
@item Helping @uref{primrose.sourceforge.net,primrose}, a tool for
scanning sheet music.
@end itemize
+
+@node ETF format
+@section An incomplete description of the Enigma Transport Format
+
+Enigma Transport Format (ETF for short) is a format designed by Coda music
+technology, and it is used in the proprietary notation package
+Finale. Since it is very poorly documented, I'll attempt some
+documentation here.
+
+ETF is an memory dump where object pointers have been replaced by object
+numbers. The numbers are larger than 0 and the number 0 is used to
+denote the nil pointer. The dump is encoded in ASCII (where the mac
+version uses CR, and the PC CR/LF as line delimiters)
+
+A file is divided into sections like this
+
+@example
+^section-header
+DATA
+^section-header
+DATA
+
+(etc.)
+@end example
+
+@var{DATA} is stored in the form of tagged lines, where a tagged line looks
+like
+
+@example
+^TG(N1[,N2]) X1 X2 X3 (etc)
+@end example
+
+The caret is at the start of the line, @code{TG} is a two letter tag,
+and @var{N1} (and optionally @var{N2}) are numbers identifying the
+object to be described. @var{X3}, @var{X4} etc contain data in the form
+of either a signed 16 bit number, or a 32 bit number (in hex, with a $
+sign prepended). The number of Xs per line for a certain tag is
+constant.
+
+The numbers in @code{N1} need not be consecutive or ascending, mostly.
+
+
+If an object is too large to fit on a single line (which typically has
+only five X's), it is put on multiple lines and padded with zero's, eg.
+
+@example
+^GF(1,2) 3 0 1 2 3
+^GF(1,2) 4 0 0 0 0
+@end example
+
+(the GF object requires 6 16 bit words, hence the 4 padding zeroes).
+
+Note structure:
+
+Each staff can contain up to four layers, where a layer correspond to a
+horizontal `line' of notes. Each layer is broken up into frames, where
+each frame is one measure of a layer.
+
+@example
+ ^GF(s,m) @var{c} @var{flags} @var{f1} @var{f2} @var{f3}
+ ^GF(s,m) @var{f4} 0 0 0 0
+@end example
+
+Here @var{s} is the staff number, @var{m} the measure number,
+@var{flags} is a 16-bit bit-vector, and @var{f1} to @var{f4} are frame
+identifiers. @var{c} is a clef-identifier.
+
+There is a second variant of the @code{GF} tag, which has only one line;
+it looks like
+
+@example
+ ^GF(s,m) @var{fr} @var{c} @var{x} @var{y} @var{z}
+@end example
+
+here, @code{fr} is a frame number, @code{c} the clef number. The
+function of x, y , z is unknown.
+
+A frame is described by the FR tag
+
+@example
+ ^FR(@var{n}) @var{n1} @var{n2} 0 0
+@end example
+
+This means frame number @var{n} runs from note @var{n1} to note @var{n2}
+Where `running from' is interpreted as ``that part of a linked note list
+that starts with note @var{n1} and ends with note @var{n2}''. This is
+something different from the sequence of notes
+@var{n1}, @var{n1 + 1} , ... , @var{n2 - 1}, @var{n2}.
+
+Notes (or more accurately chord-notes/rests) are described as follows:
+
+@example
+ ^eE(@var{n}) @var{l1 l2 dur pos $flags extflags pitchcount}
+ pitchrecords
+@end example
+
+This is note number @var{n} (in list where @var{l1} and @var{l2} are
+previous and next).
+
+Durations are stored as a number where 1024 is the quarter note, 512 the
+eighth, etc. Dotted notes are stored by multiplying the dur field
+appropriately.
+
+pitchcount is the number of pitch records. Each pitchrecord looks like
+@example
+ pitch $flags
+@end example
+(note that the line starts with spaces, and not with a caret)
+
+
+pitch is a 16 bit number, where the lower order 4-bits is a signed
+nybble which adds an alteration (0 = natural, 1 = sharp, etc.)
+The remaining 12 bits encodes the note-name (octave inclusive.)
+
+Both the alteration and the note-name are relative to the scale as
+defined by the key-signature in this measure. The person who invented
+this should have his head checked out.
+
+The key and time signature are defined in the MS field
+@example
+ ^MS(n) space key beats beatlen y z
+@end example
+
+@var{n} is the measure number. @var{space} is the width of the
+measure (?), @var{key} the number of the keysignature (0 = C major, 1 G
+major, etc. 255 = F major, 254 = Bflat major). beats and beatlen
+determine time signature.
+
+Key and time are determined score wide. The mind boggles at how they
+plan to do polytonal and polymetric music. And how do they do
+mid-measure keychanges?
+
+Slurs are (among others) stored with an Sx tag
+
+@example
+ ^Sx(@var{slurnumber}) @var{stuff}
+@end example
+
+The slur has many parameters. The 6th number on the first line is the
+starting note, the 3rd number on the 4th line the ending note.
+
+
+Some other information can be found in the Finale Plug-in Development
+(there is a vague manual, and some source files that are useful).
+
+You can download the PDK from Coda's website,
+@uref{http://www.codamusic.com/coda/Fin2000_pdk_download.asp}. You do
+need to register as a user (you can also do it if you have never bought
+an coda product).
+
+
+More tags:
+@example
+RU - repeat
+ES - end repeat
+ET - end repeat text
+BR - backw repeat
+mt - measure text
+pT - page text
+TX - text blocks
+SD - shape
+DY - score expr
+AC - tempo
+GF - clef
+IS - staff spec
+DO (shape expression),
+DT (text expression),
+IK (chord playback),
+IS (staff spec),
+IV (chord suffix),
+IX (articulation definition - documented in edata.h),
+Iu (instrument used - documented in edata.h),
+LA (layer preferences - documented in eprfdata.h),
+MN (measure number region),
+MS (measure spec),
+PS (page spec),
+RS (repeat style - documented in edata.h),
+RT (text repeat style text - documented in edata.h),
+SD (shape),
+SS (staff system spec),
+TX (text block),
+pT (page text)
+
+TP - tuplet
+
+sl - slur shapetag
+@end example
+
+
--- /dev/null
+
+@node GNU Free Documentation License
+@appendixsec GNU Free Documentation License
+
+@cindex FDL, GNU Free Documentation License
+@center Version 1.1, March 2000
+
+@display
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
+@acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
+@acronym{PDF}, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+@end enumerate
+
+@page
+@appendixsubsec ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+ Copyright (C) @var{year} @var{your name}.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+@end group
+@end smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
+
+++ /dev/null
-@c -*-texinfo-*-
-@ignore
-
-TODO
- * move some stuff to refman
- * merge some stuff with refman entries
-
- * add @ref{}s to lilypond-internals:
- @rgrob{Name} to grob
- @reng{Name} to engraver
-
- there's a very simple, very general noXXX mechanism; try
-
-noop \property Staff.VoltaBrace = #'()
-yes: \property Staff.VoltaBracket = #'((meta . ((interfaces . ()))))
-
-
- visibility?
- brew_molecule?
-@end ignore
-
-
-@node Features
-@chapter Features
-
-@menu
-* Arpeggio:: Arpeggio
-* Glissando:: Glissando
-* Manual beam settings:: Manual beam settings
-* Slur attachments:: Slur attachments
-* Text spanner:: Text spanner
-* Engraver hacking:: Engraver hacking
-* Part combiner:: Part combiner
-* Markup text:: Markup text
-* Apply hacking:: Apply hacking
-* Output property:: Output property
-* Embedded TeX:: Embedded TeX
-* Embedded PostScript:: Embedded PostScript
-@c * Index:: Checking Feature index
-@end menu
-
-
-@node Arpeggio
-@section Arpeggio
-@cindex argepeggio
-
-@cindex broken arpeggio
-
-You can specify an @rgrob{Arpeggio} sign on a chord by issuing an
-@c FIXME
-@c @code{\arpeggio}@indexcode{\arpeggio} request:
-@code{\arpeggio} request:
-
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \context Voice <c'\arpeggio e g c>
-@end lilypond
-@end quotation
-
-Typesetting of simultanious chords with arpeggios can be controlled with
-the property @code{PianoStaff.connectArpeggios} @footnote{ FIXME:
-connectArpeggios. Can't find the English terms for two kinds of
-arpeggio (Dutch: gebroken arpeggio vs doorlopend arpeggio).} By
-default, LilyPond prints broken arpeggios; when set to true, one
-extended arpeggio sign is printed.
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \context PianoStaff <
- \property PianoStaff.connectArpeggios = ##t
- \context Staff \context Voice <c''\arpeggio e g c>
- \context Staff=other \context Voice <c,\arpeggio e g>
- >
-@end lilypond
-@end quotation
-
-@node Glissando
-@section Glissando
-@cindex glissando
-
-A @rgrob{Glissando} line can be requested by issuing a
-@c FIXME
-@c @code{\glissando}@indexcode{\glissando} request:
-@code{\glissando} request:
-
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- c'' \glissando c'
-@end lilypond
-@end quotation
-
-Printing of the additional text @samp{gliss.} is currently not
-supported.
-
-
-@subsection Follow Thread
-@cindex follow thread
-@cindex staff switching
-@cindex cross staff
-
-@c Documented here because it looks like a glissando...
-A glissando-like line can be printed to connect notes whenever a thread
-switches to another staff. This is enabled if the property
-@code{PianoStaff.followThread}@indexcode{followThread} is set to true:
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \context PianoStaff <
- \property PianoStaff.followThread = ##t
- \context Staff \context Voice {
- c'1
- \translator Staff=two
- b2 a
- }
- \context Staff=two {\clef bass; \skip 1*2;}
- >
-@end lilypond
-@end quotation
-
-@node Manual beam settings
-@section Manual beam settings
-@cindex beams
-@cindex beam settings
-@cindex manual beams
-
-
-@c auto knees
-
-In some cases it may be necessary to override LilyPond's automatic
-beaming algorithm. For example, the auto beamer will not beam over
-rests, so if you want that, specify the begin and end point manually
-using @code{[}@indexcode{[} and @code{]}@indexcode{]}:
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \context Staff {
- r4 [r8 g'' a]
- }
-@end lilypond
-@end quotation
-
-Similarly, for beams over bar lines:
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \context Staff {
- a''8 r a2 r8 [a a]
- }
-@end lilypond
-@end quotation
-
-If you have specific wishes for the number of beams, you can fully
-control the number of beams through the properties
-@code{Voice.stemLeftBeamCount}@indexcode{stemLeftBeamCount};
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \context Staff {
- [f'8 r16 f g a]
- [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
- }
-@end lilypond
-@end quotation
-
-and @code{Voice.stemRightBeamCount}@indexcode{stemRightBeamCount}:
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- f'32 g a b b a g f
-
- \property Voice.autoBeamSettings
- \set #'(end * * * *) = #(make-moment 1 4)
- f32 g a b b a g f
-
- f32 g a
- \property Voice.stemRightBeamCount = #1 b
- \property Voice.stemLeftBeamCount = #1 b
- a g f
-@end lilypond
-@end quotation
-
-Conventionally, stems extend to the middle staff line, and thus so do
-beams. The extending of the stems can be controlled through
-@code{Voice.Stem}'s grob-property
-@code{no-stem-extend}@indexcode{no-stem-extend}:
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \grace a'8 a4
- \property Voice.Stem \set #'no-stem-extend = ##t
- \grace g8 g4 [g8 g]
-@end lilypond
-@end quotation
-
-The beam symbol can be tweaked through @code{Voice.Beam}'s
-grob-properties @code{height-hs} and @code{y-position-hs}.
-
-Set @code{height-hs} to zero, to get horizontal beams:
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \property Voice.Beam \set #'direction = #1
- \property Voice.Beam \set #'height-hs = #0
- [a''8 e' d c]
-@end lilypond
-@end quotation
-
-Both are in half spaces. Here's how you'd specify a weird looking beam
-that instead of beaing horizontal, falls two staff spaces (ie, four half
-spaces):
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \property Voice.Beam \set #'y-position-hs = #4
- \property Voice.Beam \set #'height-hs = #-4
- [c'8 c]
-@end lilypond
-@end quotation
-
-The direction of a perfectly centred beams can be
-controlled through @code{Voice.Beam}'s grob-property
-@code{default-neutral-direction}@indexcode{default-neutral-direction}
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- [b''8 b]
- \property Voice.Beam \set #'default-neutral-direction = #-1
- [b b]
-@end lilypond
-@end quotation
-
-There are several ways to calculate the direction of a beam.
-
-[Ross] states that the majority of the notes dictates the
-direction (and not the mean of "center distance")
-
-But is that because it really looks better, or because he wants
-to provide some real simple hands-on rules?
-
-We have our doubts, so we simply provide all sensible alternatives:
-
-@table @samp
-@item majority
-number count of up or down notes
-@item mean
-mean centre distance of all notes
-@item median
-mean centre distance weighted per note
-@end table
-
-You can spot the differences of these settings from these simple
-examples:
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- [d''8 a]
- \property Voice.Beam \set #'dir-function = #beam-dir-mean
- [d a]
- \property Voice.Beam \set #'dir-function = #beam-dir-median
- [d a]
-@end lilypond
-@end quotation
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \time 3/8;
- [d''8 a a]
- \property Voice.Beam \set #'dir-function = #beam-dir-mean
- [d a a]
- \property Voice.Beam \set #'dir-function = #beam-dir-median
- [d a a]
-@end lilypond
-@end quotation
-
-These beam direction functions are defined in @file{scm/beam.scm}. If
-your favourite algorithm isn't one of these, you can hook up your own.
-
-
-
-@node Slur attachments
-@section Slur attachments
-
-The ending of a slur should whenever possible be attached to a note
-head. Only in some instances where beams are involved, LilyPond may
-attach a slur to a stem end. In some cases, you may want to override
-LilyPond's decision, eg to attach the slur to the stem end. This can be
-done through @code{Voice.Slur}'s grob-property @code{attachment}:
-@c FIXME: make @ref{} to backend doco
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \property Voice.Slur \set #'direction = #1
- \property Voice.Stem \set #'length = #5.5
- g''8(g)g4
- g4(g8)g
- \property Voice.Slur \set #'attachment = #'(stem . stem)
- g8(g)g4
- g4(g8)g
-@end lilypond
-@end quotation
-
-Trying Before | After example...
-@c Fix rolled into 4.0a prerelease
-@c is this nice?
-
-@multitable @columnfractions .40 .40
-@item
-@noindent
-@lilypond[fragment,relative,verbatim]
-\property Voice.Slur
- \set #'direction = #1
-g''8(g)g4
-g4(g8)g
-@end lilypond
-@tab
-@lilypond[fragment,relative,verbatim]
-\property Voice.Slur
- \set #'direction = #1
-\property Voice.Stem
- \set #'length = #5.5
-\property Voice.Slur
- \set #'attachment = #'(stem . stem)
-g''8(g)g4
-g4(g8)g
-@end lilypond
-@end multitable
-
-
-Similarly, slurs can be attached to note heads even when beams are
-involved (aka Ophee slurs):
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \property Voice.Slur \set #'direction = #1
- \property Voice.Slur \set #'attachment = #'(head . head)
- g''16()g()g()g()d'()d()d()d
-@end lilypond
-@end quotation
-
-If a slur would strike through a stem or beam, LilyPond will move the
-slur away vertically (upward or downward). In some cases, this may
-cause ugly slurs that you may want to correct:
-
-@quotation
-@lilypond[fragment,relative,verbatim]
- \property Voice.Stem \set #'direction = #1
- \property Voice.Slur \set #'direction = #1
- d'32( d'4 )d8..
- \property Voice.Slur \set #'attachment = #'(stem . stem)
- d,32( d'4 )d8..
-@end lilypond
-@end quotation
-
-LilyPond will increase the curvature of a slur trying to stay free of
-note heads and stems. However, if the curvature would increase too much,
-the slur will be reverted to its default shape. This decision is based
-on @code{Voice.Slur}'s grob-property @code{beautiful} value. In some
-cases, you may find ugly slurs beautiful, and tell LilyPond so by
-increasing the @code{beautiful} value:
-
-@quotation
-@lilypond[verbatim]
-\score {
- \notes \context PianoStaff <
- \time 6/4;
- \context Staff=up { s1 * 6/4 }
- \context Staff=down <
- \clef bass;
- \autochange Staff \context Voice
- \notes \relative c {
- d,8( a' d f a d f d a f d )a
- }
- >
- >
- \paper {
- linewidth = -1.;
- \translator {
- \VoiceContext
- Slur \override #'beautiful = #5.0
- Slur \override #'direction = #1
- Stem \override #'direction = #-1
- autoBeamSettings \override #'(end * * * *)
- = #(make-moment 1 2)
- }
- \translator {
- \PianoStaffContext
- VerticalAlignment \override #'threshold = #'(5 . 5)
- }
- }
-}
-@end lilypond
-@end quotation
-
-
-@node Text spanner
-@section Text spanner
-
-
-
-Have crescendo set a text spanner iso hairpin
-
-
-@lilypond[fragment,relative,verbatim]
- \context Voice {
- \property Voice.crescendoText = "cresc."
- \property Voice.crescendoSpanner = #'dashed-line
- a''2\mf\< a a \!a
- }
-@end lilypond
-
-@subsection Ottava
-
-@lilypond[fragment,relative,verbatim]
- a'''' b c a
- \property Voice.TextSpanner \set #'type = #'dotted-line
- \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
- \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
- \property Staff.centralCPosition = #-13
- a\spanrequest \start "text" b c a \spanrequest \stop "text"
-@end lilypond
-
-
-
-@node Engraver hacking
-@section Engraver hacking
-
-No time signature, no barlines...
-@lilypond[verbatim]
-\score {
- \notes \relative c'' {
- a b c d
- d c b a
- }
- \paper {
- linewidth = -1.;
- \translator {
- \StaffContext
- whichBar = #""
- \remove "Time_signature_engraver";
- }
- }
-}
-@end lilypond
-
-No staff, no clef, squash pitches
-@lilypond[verbatim]
-\score {
- \notes { c4 c4 c8 c8 }
- \paper {
- linewidth = -1.;
- \translator {
- \StaffContext
- \remove Staff_symbol_engraver;
- \consists Pitch_squash_engraver;
- \remove Clef_engraver;
- }
- }
-}
-@end lilypond
-
-
-@node Part combiner
-@section Part combiner
-
-@lilypond[verbatim]
-\score{
- \context Staff = flauti <
- \time 4/4;
- \context Voice=one \partcombine Voice
- \context Thread=one \notes\relative c'' {
- c4 d e f | b,4 d c d | r2 e4 f | c4 d e f |
- c4 r e f | c4 r e f | c4 r a r | a a r a |
- a2 \property Voice.soloADue = ##f a |
- }
- \context Thread=two \notes\relative c'' {
- g4 b d f | r2 c4 d | a c c d | a4. b8 c4 d
- c r e r | r2 s2 | a,4 r a r | a r r a |
- a2 \property Voice.soloADue = ##f a |
- }
- >
- \paper{
- linewidth = 80 * \staffspace;
- \translator{
- \ThreadContext
- \consists Rest_engraver;
- }
- \translator{
- \VoiceContext
- \remove Rest_engraver;
- }
- }
-}
-@end lilypond
-
-
-
-
-@node Markup text
-@section Markup text
-
-Metrome hack...
-
-
-
-@lilypond[verbatim]
-#(define note '(rows (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
-#(define eight-note `(rows ,note ((kern . -0.1) (music ((raise . 3.5) "flags-u3")))))
-#(define dotted-eight-note `(rows ,eight-note (music "dots-dot")))
-
-\score {
- \notes\relative c'' {
- a1^#`(rows ,dotted-eight-note " = 64")
- }
- \paper {
- linewidth = -1.;
- \translator{
- \ScoreContext
- TextScript \override #'font-shape = #'upright
- }
- }
-}
-@end lilypond
-
-
-@node Output property
-@section Output property
-
-@lilypond[fragment,relative,verbatim]
- \outputproperty #(make-type-checker 'note-head-interface)
- #'extra-offset = #'(2 . 3)
- c''2 c
-@end lilypond
-
-Don't move the finger 2, only text "m.d." ...
-@lilypond[verbatim]
-#(define (make-text-checker text)
- (lambda (grob) (equal? text (ly-get-elt-property grob 'text))))
-
-\score {
- \notes\relative c''' {
- \property Voice.Stem \set #'direction = #1
- \outputproperty #(make-text-checker "m.d.")
- #'extra-offset = #'(-3.5 . -4.5)
- a^2^"m.d."
- }
- \paper { linewidth = -1.; }
-}
-@end lilypond
-
-
-@c equalizer
-
-
-@node Apply hacking
-@section Apply hacking
-
-@lilypond[verbatim]
-music = \notes { c'4 d'4( e'4 f'4 }
-
-#(define (reverse-music music)
- (let* ((elements (ly-get-mus-property music 'elements))
- (reversed (reverse elements))
- (span-dir (ly-get-mus-property music 'span-direction)))
-
- (ly-set-mus-property music 'elements reversed)
-
- (if (dir? span-dir)
- (ly-set-mus-property music 'span-direction (- span-dir)))
-
- (map reverse-music reversed)
-
- music))
-
-\score {
- \context Voice {
- \music
- \apply #reverse-music \music
- }
- \paper { linewidth = -1.; }
-}
-@end lilypond
-
-@example
- Here's a copy of my feature request :
-@quotation
- Your task, if you accept it is to implement a \smarttranspose
- command> that would translate such oddities into more natural
- notations. Double accidentals should be removed, as well as #E
- (-> F), bC (-> B), bF (-> E), #B (-> C).
-@end quotation
-
-You mean like this. (Sorry 'bout the nuked indentation.)
-@end example
-
-
-@lilypond[verbatim]
-#(define (unhair-pitch p)
- (let* ((o (pitch-octave p))
- (a (pitch-alteration p))
- (n (pitch-notename p)))
-
- (cond
- ((and (> a 0) (or (eq? n 6) (eq? n 2)))
- (set! a (- a 1)) (set! n (+ n 1)))
- ((and (< a 0) (or (eq? n 0) (eq? n 3)))
- (set! a (+ a 1)) (set! n (- n 1))))
-
- (cond
- ((eq? a 2) (set! a 0) (set! n (+ n 1)))
- ((eq? a -2) (set! a 0) (set! n (- n 1))))
-
- (if (< n 0) (begin (set! o (- o 1)) (set! n (+ n 7))))
- (if (> n 7) (begin (set! o (+ o 1)) (set! n (- n 7))))
-
- (make-pitch o n a)))
-
-#(define (smart-transpose music pitch)
- (let* ((es (ly-get-mus-property music 'elements))
- (e (ly-get-mus-property music 'element))
- (p (ly-get-mus-property music 'pitch))
- (body (ly-get-mus-property music 'body))
- (alts (ly-get-mus-property music 'alternatives)))
-
- (if (pair? es)
- (ly-set-mus-property
- music 'elements
- (map (lambda (x) (smart-transpose x pitch)) es)))
-
- (if (music? alts)
- (ly-set-mus-property
- music 'alternatives
- (smart-transpose alts pitch)))
-
- (if (music? body)
- (ly-set-mus-property
- music 'body
- (smart-transpose body pitch)))
-
- (if (music? e)
- (ly-set-mus-property
- music 'element
- (smart-transpose e pitch)))
-
- (if (pitch? p)
- (begin
- (set! p (unhair-pitch (Pitch::transpose p pitch)))
- (ly-set-mus-property music 'pitch p)))
-
- music))
-
-
-music = \notes \relative c' { c4 d e f g a b c }
-
-\score {
- \notes \context Staff {
- \transpose ais' \music
- \apply #(lambda (x) (smart-transpose x (make-pitch 0 5 1)))
- \music
- }
- \paper { linewidth = -1.; }
-}
-@end lilypond
-
-
-@node Embedded TeX
-@section Embedded TeX
-@lilypond[fragment,relative,verbatim]
- a''^"3 $\\times$ \\`a deux"
-@end lilypond
-
-@node Embedded PostScript
-@section Embedded PostScript
-
-Arbitrary lines and curves not supported...
-
-[TODO:] Make a direct postscript command?
-
-@lilypond[verbatim]
-\score {
- \notes \relative c'' {
- a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
- -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
- b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
- s2
- a'1
- }
- \paper { linewidth = 70 * \staffspace; }
-}
-@end lilypond
-
-@ignore
-@node Index
-@section Checking Feature index
-
-@printindex cp
-
-
-@bye
-@end ignore
-
-
--- /dev/null
+@node Internals
+@chapter Internals
+
+@menu
+* Conversion stages:: Lilypond is a multi-pass program.
+* Moment::
+* Grobs:: Graphical object
+* Engraver::
+* Music_iterator::
+* Music::
+* Molecules:: Molecules are stand-alone descriptions of output
+* Font metrics:: Font metrics
+@end menu
+
+@node Conversion stages
+@section Conversion stages
+
+When translating the input to notation, there are number of distinct
+phases. We list them here:
+
+@table @code
+
+@item Parsing:
+
+The .ly file is read, and converted to a list of @code{Scores}, which
+each contain @code{Music} and paper/midi-definitions.
+
+@item Interpreting music
+@cindex interpreting music
+
+All music events are "read" in the same order as they would be played
+(or read from paper). At every step of the interpretation, musical
+events are delivered to
+interpretation contexts,
+@cindex engraver
+which use them to build grobs (or MIDI objects, for MIDI output).
+
+@item Prebreaking
+
+@cindex prebreaking
+
+At places where line breaks may occur, clefs and bars are prepared for
+a possible line break.
+
+@item Preprocessing
+
+@cindex preprocessing
+
+In this stage, all information that is needed to determine line breaking
+is computed.
+
+@item Break calculation:
+
+The lines and horizontal positions of the columns are determined.
+
+@item Breaking
+
+Relations between all grobs are modified to reflect line breaks. See
+also @ref{Pointer substitution}.
+
+@item Outputting:
+
+All vertical dimensions and spanning objects are computed, and all grobs
+are output, line by line.
+
+@end table
+
+@node Moment
+@section Moment
+
+Moment is a rational number. Since GUILE doesn't support them natively,
+so we created our own rational data type.
+
+@defun moment?
+@end defun
+
+@defun make-moment num den
+create the rational number @var{num}/@var{den}.
+@end defun
+
+@node Grobs
+@section Grobs
+
+This section is about Grobs (short for Graphical Objects), which are
+formatting objects used to create the final output. This material is
+normally the domain of LilyPond gurus, but occasionally, a normal user
+also has to deal with grobs.
+
+The most simple interaction with Grobs are when you use
+@code{\override}:
+
+@example
+ \property Voice.Stem \override #'direction = #1
+@end example
+
+This piece of lily input causes all stem objects to be stem-up
+henceforth. In effect, you are telling lilypond to extend the defintion
+of the "Stem" grob with the setting @code{direction := 1}. Of course
+there are many more ways of customizing Lily output, and since most of
+them involve Grobs in some form, this section explains some details of
+how grobs work.
+
+@menu
+* What is a grob?::
+* Callbacks::
+* Setting grob properties::
+* Items and Spanners::
+* Pointer substitution::
+* Grob Scheme functions::
+@end menu
+
+@node What is a grob?
+@subsection What is a grob?
+
+In music notation, lots of symbols are related in some way. You can
+think of music notation as a graph where nodes are formed by the
+symbols, and the arcs by their relations. A grob is node in that
+graph. A grob stores references to other grobs, the directed edges in
+the graph.
+
+The objective of this big graph of grobs, is to specify the notation
+problem. The solution of this problem is a description of the printout
+that is in closed form, i.e. but a list of values. These values are
+Molecules. (see @ref{Molecules})
+
+All grobs have an X and Y-position on the page. These X and Y positions
+are stored in a relative format, so they can easily be combined by
+stacking them, hanging one grob to the side of another, and coupling
+them into a grouping-grob.
+
+Each grob has a reference point, or parent: the position of a grob is
+stored relative to that reference point. For example the X-reference
+point of a staccato dot usually is the note head that it applies
+to. Whenever the note head is moved, the staccato dot moves along
+automatically.
+
+If you keep following offset reference points, you will always end up at
+the root-object. This root object is called @rgrob{Line_of_score}, and it
+represents a system (ie. a line of music).
+
+All grobs carry a set of grob-properties. In the Stem example above,
+the property @code{direction} is set to value @code{1}. The function
+that draws the symbol (@code{Stem::brew_molecule}) uses the value of
+@code{direction} to determine how to print the stem and the flag. The
+appearance of a grob is determined solely by the values of its
+properties.
+
+Often, a grob also is associated with a symbol. On the other hand,
+Some grobs do not print any symbols, but take care of grouping
+objects. For example, there is a separate grob that stacks staffs
+vertically, so they are not printed in overstrike. The
+@rgrob{NoteCollision} is another example of an abstract grob. It only
+moves around chords, but doesn't print anything.
+
+A complete list of grob types is found in
+@ref{(lilypond-internals)LilyPond backend}
+
+Grobs are created in the "Interpreting music" phase, by things in
+LilyPond called engravers. In this phase of the translation, a load of
+grobs are created, and they are linked into a giant network of objects.
+This network of grobs forms the "specification" of the print
+problem. This problem is then solved: configurations, directions,
+dimensions, line breaks, etc. are calculated. Finally, the printing
+description in the form of Molecules (@ref{Molecules}) is extracted from
+the network. These are then dumped into the output file
+
+@node Callbacks
+@subsection Callbacks
+
+Offsets of grobs are relative to a parent reference point. Most
+positions are not known when an object is created, so these are
+calculated as needed. This is done by adding a callback for a specific
+direction.
+
+Suppose you have the following code in a .ly file.
+@example
+ #(define (my-callback gr axis)
+ (* 2.0 (get-gr-property grob 'direction))
+ )
+
+....
+
+ \property Voice.Stem \override #'Y-offset-callbacks = #(list
+ my-callback)
+@end example
+
+When the Y-offset of a Stem object is needed, LilyPond will
+automatically execute all callbacks for that object. In this case, it
+will find @code{my-callback}, and execute that. The result is that the
+stem is translated by two staff spaces in its direction.
+
+(note: Y-offset-callbacks is also a property)
+
+
+Offset callbacks can be stacked, ie.
+
+@example
+ \property .... \override #'Y-offset-callbacks = #(list
+ callback1 callback2 callback3)
+
+@end example
+
+The callbacks will be executed in the order callback3 callback2
+callback1. This is used for quantized positioning: the staccato dot is
+above or below a note head, and it must not be on a staff-line.
+
+To achieve this, for the staccato there are two callbacks: one callback
+that positions the grob above or below the note head, and one callback
+that rounds the Y-position of the grob to the nearest open space.
+
+Similarly, the size of a grob are determined through callbacks, settable
+with grob properties @code{X-extent-callback} and @code{Y-extent-callback}.
+There can be only one extent-callback for each axis. No callback (value #f)
+means: "empty in this direction". If you fill in a pair, that pair
+hard-codes the extent in that coordinate.
+
+
+@node Setting grob properties
+@subsection Setting grob properties
+
+Grob properties are stored as GUILE association lists, with symbols as
+keys. From C++, element properties can be accessed using the functions
+
+@example
+ SCM get_grob_property (SCM) const;
+ void set_grob_property (const char * , SCM val);
+ void set_immutable_grob_property (const char * , SCM val);
+ void set_immutable_grob_property (SCM key, SCM val);
+ void set_grob_property (SCM , SCM val);
+ void set_grob_pointer (const char*, SCM val);
+ SCM remove_grob_property (const char* nm);
+@end example
+
+In GUILE, LilyPond provides
+
+@example
+ ly-get-grob-property GROB SYMBOL
+ ly-set-grob-property GROB SYMBOL VALUE
+@end example
+
+All lookup functions identify undefined properties with
+end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
+
+Properties are stored in two ways:
+@itemize @bullet
+@item mutable properties:
+element properties that change from object to object. The storage of
+these are private to a grob. Typically this is used to store lists of
+pointers to other grobs
+
+@item immutable properties:
+element properties that are shared across different grobs of the same
+type. The storage is shared, and hence it is read-only. Typically, this
+is used to store function callbacks, and values for shared element
+properties are read from @file{scm/element-description.scm}.
+@end itemize
+
+There are two ways to manually set grob properties.
+
+You can change immutable grob properties. This is done with the
+\override syntax:
+
+@example
+ \property Voice.Stem \override #'direction = #1
+@end example
+
+This will push the entry @code{'(direction . 1)} on the immutable
+property list for stems, in effect overriding the setting from
+@file{scm/element-description.scm}. This can be undone by
+
+@example
+ \property Voice.stem \revert #'direction
+@end example
+
+If you use this a lot, this gets old quickly. So we also have a
+shorthand,
+
+@example
+ \property Context.GrobType \set #'prop = #VAL
+@end example
+
+this does a @code{\revert} followed by a @code{\override}
+
+The second way is \outputproperty. This construct looks like
+
+@example
+ \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
+@end example
+
+In this case, in every grob that satisfies @var{pred}, the property
+assignment @var{sym} = @var{val} is done. For example
+
+@example
+ \outputproperty
+ #(lambda (gr) (string? (ly-get-grob-property gr
+ 'text)))
+ #'extra-offset = #'(-1.0 . 0.0)
+@end example
+
+This shifts all elements that have a @code{text} property one staff
+space to the left. This mechanism is rather clumsy to use, but it allows
+you tweak any setting of any grob.
+
+@node Items and Spanners
+@unnumberedsubsec Items and Spanners
+
+Grobs can also be distinguished in their role in the horizontal spacing.
+A lot of grobs define constraints on the spacing by their sizes. For
+example, note heads, clefs, stems, and all other symbols with a fixed
+shape. These grobs form a subtype called @code{Item}.
+
+Other grobs have a shape that depends on the horizontal spacing. For
+example, slur, beam, tie, etc. These grobs form a subtype called
+@code{Spanner}. All spanners have two span-points (these must be
+@code{Item}s), one on the left and one on the right. The left bound is
+also the X-reference point.
+
+Some items need special treatment for line breaking. For example, a
+clef is normally only printed at the start of a line (ie. after a line
+break). To model this, `breakable' items (clef, key signature, bar lines,
+etc.) are copied twice. Then we have three versions of each breakable
+item: one version if there is no line break, one version that is printed
+before the line break (at the end of a system), one version that is
+printed after the line break.
+
+Whether these versions are visible and take up space, is determined by
+the outcome of the visibility-lambda. This is a function taking a
+direction (-1, 0 or 1) and returns a cons of booleans, signifying wether
+this grob should be transparent and have no extent.
+
+@node Pointer substitution
+@unnumberedsubsec Pointer substitution
+
+
+Symbols that cross line-breaks (such as slurs) cause some more
+complications. When a spanner crosses a line-break, then the spanner is
+"broken into pieces", for every line that the spanner is in, a copy of
+the grob is made. A substitution process redirects all grob-reference
+so that spanner grob will only reference other grobs in the same line.
+
+@node Grob Scheme functions
+@unnumberedsubsec Grob Scheme functions
+
+
+@defun ly-get-grob-property g sym
+ Get the value of a value in grob @var{g} of property @var{sym}. It
+will return @code{'()} (end-of-list) if @var{g} doesn't have @var{sym} set.
+@end defun
+
+@defun ly-set-grob-property g sym val
+@end defun
+
+@defun ly-get-spanner-bound spanner dir
+@end defun
+
+@defun ly-grob? g
+@end defun
+
+@node Duration
+@section Duration
+
+@defun make-duration length dotcount
+
+@var{length} is the negative logarithm (base 2) of the duration:
+1 is a half note, 2 is a quarter note, 3 is an eighth
+note, etc. The number of dots after the note is given by
+@var{dotcount}.
+
+@end defun
+
+
+@node Pitch data type
+@section Pitch data type
+
+
+
+@defun make-pitch octave note shift
+
+@var{octave} is specified by an integer, zero for the octave
+containing middle C. @var{note} is a number from 0 to 7, with 0
+corresponding to C and 7 corresponding to B. The shift is zero for a
+natural, negative to add flats, or positive to add sharps.
+@end defun
+
+@defun pitch-octave
+@end defun
+
+@defun pitch-notename
+@end defun
+
+@defun pitch-alteration
+@end defun
+
+@defun pitch-semitones
+@end defun
+
+@defun Pitch::transpose
+@end defun
+
+@node Engraver
+@section Engraver
+
+@defun ly-get-trans-property
+@end defun
+
+@defun ly-set-trans-property
+@end defun
+
+@node Music_iterator
+@section Music_iterator
+
+@defun c++-function?
+@end defun
+
+@node Music
+@section Music
+
+@defun ly-get-mus-property
+@end defun
+
+@defun ly-set-mus-property
+@end defun
+
+
+@node Molecules
+@section Molecules
+
+@cindex Molecule
+@cindex Atom
+@cindex Output description
+
+The objective of any typesetting system is to put ink on paper in the
+right places. For LilyPond, this final stage is left to the TeX and the
+printer subsystem. For lily, the last stage in processing a score is
+outputting a description of what to put where. This description roughly
+looks like
+
+@example
+ PUT glyph AT (x,y)
+ PUT glyph AT (x,y)
+ PUT glyph AT (x,y)
+@end example
+
+you merely have to look at the tex output of lily to see this.
+Internally these instructions are encoded in Molecules:@footnote{At some
+point LilyPond also contained Atom-objects, but they have been replaced
+by Scheme expressions, making the name outdated.}. A molecule is an
+object that combines dimension information (how large is this glyph ?)
+with what-to-print-where.
+
+Conceptually, Molecules can be constructed from Scheme code, by
+translating a Molecule and by combining two molecules. In BNF
+notation:
+
+@example
+ Molecule = COMBINE Molecule Molecule
+ | TRANSLATE Offset Molecule
+ | GLYPH-DESCRIPTION
+ ;
+@end example
+
+If you are interested in seeing how this information is stored, you
+can run with the @code{-f scm} option. The scheme expressions are then
+dumped onto the output file.
+
+(refer to the C++ code for more details). All visible,
+ie. non-transparant, grobs have a callback to create a Molecule. The
+name of the property is @code{molecule-callback}, and its value should
+be a Scheme function taking one argument (the grob) and returning a
+Molecule.
+
+@defun molecule? m
+@end defun
+
+@defun ly-combine-molecule-at-edge mol1 axis dir mol2 padding
+@end defun
+
+@defun ly-get-molecule-extent! mol axis
+@end defun
+
+@defun ly-set-molecule-extent! mol axis extent
+@end defun
+
+@node Font metrics
+@section Font metrics
+
+The font object represents the metric information of a font. Every font
+that is loaded into LilyPond can be accessed via Scheme.
+
+LilyPond only needs to know the dimension of glyph to be able to process
+them. This information is present in font-metric files. LilyPond can
+read two types of font-metrics: @TeX{} Font Metric files (tfm files) and
+Adobe Font Metric files (afm files). AFM files are more versatile, and
+LilyPond needs those features to typeset musical symbols. So LilyPond
+will always try to load afm files first.
+
+
+@defun ly-get-default-font gr
+This returns the default font for grob @var{gr}.
+@end defun
+
+@defun ly-find-glyph-by-name font name
+This function retrieves a Molecule for the glyph named @var{name} in
+@var{font}. The font must be available as a afm file.
+@cindex afm file
+
+@end defun
+
+@node Miscellaneous Scheme functions
+@section Miscellaneous Scheme functions
+
+@defun ly-input-location?
+@end defun
+
+@defun ly-warn
+@end defun
+
+@defun ly-version
+@end defun
+
+@defun ly-gulp-file
+@end defun
+
+@defun dir?
+@end defun
+
+@defun ly-number->string
+@end defun
+
+
@unnumberedsec Lilypond Command Options
-@table @samp
+@table @code
@item -f,--format=
- Output format for sheet music. Choices are tex (for @TeX{}
- output), ps (for PostScript) and scm (for a direct Scheme
- dump)
+Output format for sheet music. Choices are tex (for @TeX{}
+output), ps (for PostScript) and scm (for a Scheme
+dump)
@item -h,--help
- Show a summary of usage.
+Show a summary of usage.
@item --include, -I=DIRECTORY
- Add @file{DIRECTORY} to the search path for input files.
-
+Add @file{DIRECTORY} to the search path for input files.
+@cindex file searching
+@cindex search path
@item -i,--init=FILE
- Set init file to @file{FILE} (default: @file{init.ly}).
+Set init file to @file{FILE} (default: @file{init.ly}).
@item -m,--no-paper
- Disable @TeX{} output. If you have a \midi definition, it will do the
- midi output only.
+@cindex MIDI
+Disable @TeX{} output. If you have a @code{\midi} definition, it will do the
+midi output only.
@item -M,--dependencies
- Output rules to be included in Makefile.
+Output rules to be included in Makefile.
@item -o,--output=FILE
- Set the default output file to @file{FILE}.
+Set the default output file to @file{FILE}.
@item -Q,--find-old-relative
- show all changes needed to convert a file to relative octave syntax.
+show all changes needed to convert a file to relative octave syntax.
@item -s,--safe
- Disallow untrusted @code{\include} directives, backslashes in @TeX{}
-code and named output.
+Disallow untrusted @code{\include} directives, in-line
+Scheme evaluation, backslashes in @TeX{}, code.
-WARNING: the --safe option has not been reviewed for over a year; do
-not rely on for automatic lily invocation (eg. over the
-web). Volunteers are welcome.
+@strong{WARNING}: the @code{--safe} option has not been reviewed for
+over a year; do not rely on it for automatic invocation (e.g. over the
+web). Volunteers are welcome to do a new audit.
@item -T,--no-timestamps
- don't timestamp the output
+don't timestamp the output
+
@item -t,--test
- Switch on any experimental features. Not for general public use.
+Switch on any experimental features. Not for general public use.
@item -v,--version
- Show version information
+Show version information
@item -V,--verbose
- verbose
+Be verbose
@item -w,--warranty
- Show the warranty with which GNU LilyPond comes. (It comes with
- @strong{NO WARRANTY}!)
+Show the warranty with which GNU LilyPond comes. (It comes with
+@strong{NO WARRANTY}!)
@end table
@section Environment variables
-@table @samp
+@table @code
@item LILYINCLUDE
- additional directories for finding lilypond data. The
- format is like the format of @file{PATH}.
+additional directories for finding lilypond data. The
+format is like the format of @file{PATH}.
@item LILYPONDPREFIX
- This specifies a directory where locale messages and
-data-files will be looked up by default. The directory should contain
+This specifies a directory where locale messages and
+data files will be looked up by default. The directory should contain
subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
@item LANG
- selects the language for the warning messages of LilyPond.
+selects the language for the warning messages of LilyPond.
@end table
@section Options
-@table @samp
+@table @code
@item eps
the music is created as eps graphics that can be inserted in
the middle of a text line, not only as a separate paragraph.
@subsection Command line options
-@table @samp
+@table @code
@item @option{-f}, @option{--format=}
Specify the document type to process, @code{latex} or @code{texi}.
@item -M, --dependencies
Write dependencies to out-www/filename.dep
@item --dep-prefix=PREF
- prepend PREF before each -M dependency
+ prepend PREF before each -M dependency
@item -n, --no-lily
- don't run lilypond
+ don't run lilypond
@item --no-pictures
- don't generate pictures
+ don't generate pictures
@item --read-lys
- don't write ly files. This way you can do
- @example
- lilypond-book file.tely
- convert-ly
- lilypond-book --read-lys
- @end example
+ don't write ly files. This way you can do
+ @example
+ lilypond-book file.tely
+ convert-ly
+ lilypond-book --read-lys
+ @end example
@item --outname=FILE
The name of La@TeX{} file to output. If this option is not given,
the output name derived from the input name.
@item --outdir=
- where to place generated files
+ where to place generated files
@item --version
- print version information
+ print version information
@item --help
- Print a short help message
+ Print a short help message
@end table
@subtitle The music typesetter
@author Han-Wen Nienhuys, Jan Nieuwenhuizen and Adrian Mariano
- Copyright @copyright{} 1999 by the authors
-@vskip 0pt plus 1filll
-Permission is granted to make and distribute verbatim
-copies of this manual provided the copyright notice and
-this permission notice are preserved on all copies.
+Copyright @copyright{} 1999--2001 by the authors
-Permission is granted to copy and distribute modified
-versions of this manual under the conditions for
-verbatim copying, provided also that the sections
-entitled ``Copying'' and ``GNU General Public License''
-are included exactly as in the original, and provided
-that the entire resulting derived work is distributed
-under the terms of a permission notice identical to this
-one.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
-Permission is granted to copy and distribute
-translations of this manual into another language,
-under the above conditions for modified versions,
-except that this permission notice may be stated in a
-translation approved by the Free Software Foundation.
@end titlepage
Copyright 1999 Han-Wen Nienhuys, Jan Nieuwenhuizen and Adrian Mariano
-Permission is granted to make and distribute verbatim
-copies of this manual provided the copyright notice and
-this permission notice are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX
-and print the results, provided the printed document
-carries a copying permission notice identical to this
-one except for the removal of this paragraph (this
-paragraph not being relevant to the printed manual).
-
-@end ignore
-
-Permission is granted to copy and distribute modified
-versions of this manual under the conditions for
-verbatim copying, provided also that the sections
-entitled ``Copying'' and ``GNU General Public License''
-are included exactly as in the original, and provided
-that the entire resulting derived work is distributed
-under the terms of a permission notice identical to this
-one.
-
-Permission is granted to copy and distribute
-translations of this manual into another language,
-under the above conditions for modified versions,
-except that this permission notice may be stated in a
-translation approved by the Free Software Foundation.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
@end ifinfo
-@ignore
-Should add disclaimer, abstract
-
-"GNU LilyPond has no connection with the music package Rosegarden, other
-than the names being similar :-)"
-
-@end ignore
-
@ifnottex
@node Top
@c FIXME: this should not be necessary...
@top
-@end ifnottex
@chapter GNU LilyPond --- The music typesetter
@menu
* Tutorial:: A tutorial introduction to LilyPond.
+* Reference Manual:: Reference Manual.
+* Tricks:: Features, tips and tricks.
* Invoking LilyPond:: Operation.
* Bug reports:: Where to report bugs.
-* Reference Manual:: Reference Manual.
-* Features:: Features, tips and tricks.
-* Utility programs:: External programs.
+* ly2dvi:: Generating nice output with titles.
+* convert-ly:: Upgrading input files.
+* Conversion tools:: Converting from MIDI input.
* Internals:: How it all works.
-* Development:: On developing code for LilyPond.
* Index of internals:(lilypond-internals). Auto generated detailed documentation.
* Index:: Unified index.
* Function Index:: Function index.
+* GNU Free Documentation License:: FDL.
@end menu
+@end ifnottex
+
@contents
@mbinclude macros.itexi
-
@mbinclude tutorial.itely
-
+@mbinclude refman.itely
+@mbinclude tricks.itely
+@mbinclude internals.itely
@mbinclude invoking.itexi
-
@mbinclude bugs.itexi
-
-@mbinclude refman.itely
-
-@mbinclude features.itely
-
-@mbinclude programs.itexi
-
-@mbinclude development.itexi
+@mbinclude ly2dvi.itexi
+@mbinclude convert-ly.itexi
+@mbinclude convertors.itely
+@mbinclude literature.itely
@c FIXME: Index has two alphabetically sorted lists @code vs plain?
@node Index
@printindex fn
-
+@mbinclude fdl.itexi
@bye
--- /dev/null
+@node Literature
+@chapter Literature
+
+If you need to know more about music notation, here are some interesting titles to read
+
+@table @emph
+@item banter
+Harald Banter, Akkord Lexikon. Schott's S\"ohne
+1987. Mainz, Germany ISBN 3-7957-2095-8
+
+Comprehensive overview of commonly used chords. Suggests (and uses) a
+unification for all different kinds of chord names.
+
+
+
+@item ross,
+Ted Ross, Teach yourself the art of music engraving and processing.
+Hansen House, Miami, Florida 1987
+
+This is about engraving, i.e. professional typesetting. It contains
+directions on good typesetting, but the sections on reproduction
+technicalities, how to use pens and history are interesting.
+Especially the section on Music Typewriters is amusing....
+
+@item gerou96
+
+Tom Gerou and Linda Lusk, Essential Dictionary of Music
+Notation. Alfred Publishing, Van Nuys CA ISBN 0-88284-768-6
+
+A concise, alphabetically ordered list of typesetting and music
+(notation) issues with a rather simplistic attitude but in most cases
+"good-enough" answers.
+
+
+@item Stone80
+
+Kurt Stone, Music Notation in the Twentieth Century
+Norton, New York 1980.
+
+The most important book on notation in recent years.
+
+
+@item hader48,
+
+Karl Hader, Aus der Werkstatt eines Notenstechers. Waldheim--Eberle
+Verlag, Vienna 1948.
+
+
+Hader was the chief-engraver of the Waldheim-Eberle music publishers.
+This beautiful booklet was intended as an introduction for laymen on
+the art of engraving. It contains a step by step, in-depth
+explanation of how to cut and stamp music into zinc plates. It also
+contains a few compactly formulated rules on musical orthography. Out
+of print.
+
+@item wanske,
+
+1988
+Helene Wanske, Musiknotation --- Von der Syntax des Notenstichs zum EDV-gesteuerten Notensatz.
+Schott-Verlag, Mainz 1988.
+ISBN 3-7957-2886-x
+
+I. A very thorough overview of engraving practices of various
+craftsmen. It includes detailed specs of characters, dimensions
+etc. II. a thorough overview of a anonymous (by now antiquated)
+automated system. EDV Means e(lektronischen) D(aten)v(erarbeitung),
+electronic data processing HWN.
+
+@item read-notation,
+Gardner Read, Music Notation: a Manual of Modern Practice.
+Taplinger Publishing, New York (2nd edition).
+
+This is as close to the ``standard''
+ reference work for music notation issues as one is likely to get.
+@end table
@c -*-texinfo-*-
@node ly2dvi
-@section ly2dvi
+@chapter ly2dvi
Ly2dvi is a Python script which creates input file for La@TeX{},
based on information from the output files from LilyPond.
ly2dvi [options] inputfile[.ly] [....]
-@table @samp
+@table @code
@item -D,--debug
Set debug mode. There are two levels - in level one some debug
info is written, in level two the command @strong{set -x} is run, which
Ly2dvi responds to several parameters specified in the LilyPond
file. They are overridden by corresponding command line options.
-@table @samp
+@table @code
@item language="";
Specify La@TeX{} language
@item latexheaders="";
@subsection Ly2dvi Environment
-@table @samp
+@table @code
@item LILYPONDPREFIX
Sets the root directory of the LilyPond installation
@item LILYINCLUDE
additional text definitions from the LilyPond file. In the current
version the following are defined:
-@table @samp
+@table @code
@item title
The title of the music. Centered on top of the first page.
@item subtitle
in the shown sequence. In the current version the following are
allowed:
-@table @samp
+@table @code
@item DEBUG=value
This turns off (default) or on the debug capabilities. Possible
values are 0 (off) and 1 (on).
The initialization process reads inputs for several sources. Below is
a list of priorities for lowest to hightest proirity.
+[FIXME: should use ly2dvirc iso lilyrc]
+
@itemize @bullet
@item Program's defaults
@item Values found in LilyPond output file
@item command line options
@end itemize
-Note that this differs slightly from the original bourne shell
-version.
-
@subsection Ly2dvi Bugs
-@c should?
-FIXME.
-See @ref{Bug reports}.
-If you have found a bug, you should send a bugreport.
+See @ref{Bug reports}. If you have found a bug, you should send a
+bugreport.
@itemize @bullet
@item Send a copy of the input which causes the error.
-
-@ifnottex
-@macro keyindex {word}
-@cindex @code{ \word\ }
-@end macro
-
-@macro indexcode {word}
-@cindex @code{ \word\ }
-@end macro
-@end ifnottex
-
-@iftex
-@macro keyindex {word}
-@cindex @code{ \word\ }
-
-@end macro
-
-@macro indexcode {word}
-@cindex @code{ \word\ }
-
-@end macro
-@end iftex
-
@ifinfo
@macro rgrob {word}
-@ref{ (lilypond-internals)Grob \word\, \word\ },
+@ref{ (lilypond-internals)\word\, \word\ },
@end macro
@macro reng {word}
@ifnotinfo
@macro rgrob {word}
-@ref{ (lilypond-internals)Grob \word\, \word\ }
+@ref{ (lilypond-internals)\word\, \word\ }
@end macro
@macro reng {word}
+++ /dev/null
-@c -*-texinfo-*-
-
-@node midi2ly
-@section midi2ly
-
-Midi2ly translates a MIDI input file to a LilyPond source file.
-Midi2ly is part of the GNU LilyPond music typesetting package.
-
-@subsection Invoking midi2ly
-
- midi2ly [options] midi-file
-
-
-@table @samp
-@item -b, --no-quantify,
- Write exact durations, e.g.: `a4*385/384'.
-@item -D, --debug,
- Print lots of debugging stuff.
-@item -h, --help,
- Show a summary of usage.
-@item -I, --include=@file{DIR},
- Add DIR to search path.
-@item -k, --key=ACC[:MINOR],
- Set default key. ACC > 0 sets number of sharps; ACC < 0 sets number
- of flats. A minor key is indicated by ":1".
-@item -n, --no-silly,
- Assume no plets or double dots, assume smallest (reciprocal) duration 16.
-@item -o, --output=@file{FILE},
- Set @file{FILE} as default output.
-@item -p, --no-plets,
- Assume no plets.
-@item -q, --quiet,
- Be quiet.
-@item -s, --smallest=N,
- Assume no shorter (reciprocal) durations than N.
-@item -v, --verbose,
- Be verbose.
-@item -w, --warranty,
- Show the warranty with which midi2ly comes. (It comes with @strong{NO WARRANTY}!)
-@item -x, --no-double-dots,
- Assume no double dotted notes.
-@end table
@chapter Utility programs
@menu
-* ly2dvi:: Generating nice output with titles.
-* convert-ly:: Upgrading input files.
-* midi2ly:: Converting from MIDI input.
@end menu
-@mbinclude ly2dvi.itexi
-@mbinclude convert-ly.itexi
-@mbinclude midi2ly.itexi
@table @samp
- @item @code{midiInstrument}@indexcode{midiInstrument} @propertytype{string}
+@cindex @code{midiInstrument}
+ @item @code{midiInstrument} @propertytype{string}
Sets the instrument for MIDI output. If this property is not set
then LilyPond will use the @code{instrument} property. This must
be set to one of the strings on the list of MIDI instruments that
appears in section @ref{midilist}. If you use a string which
is not listed, LilyPond will silently substitute piano.
+@cindex @code{transposing}
- @item @code{transposing}@indexcode{transposing} @propertytype{integer}
+ @item @code{transposing} @propertytype{integer}
Transpose the MIDI output. Set this property to the number of
half-steps to transpose by.
@c -*-texinfo-*-
-@c TODO:
-@c - Reinsert subsection commands that were lost in the
-@c ancient conversion from YODL! /MB
-@c - Restructure! Separate internal commands from user level commands. /MB
-@c - Add some words about Guile. /MB
-@c - Fix indexing (keyindex) so it doesn't add line breaks /MB
-@c
-@c FIXME: Index has two alphabetically sorted lists @code vs plain?
-@c
-@c If we'd include the auto-generated documentation, we 'd get a lot of
-@c very useful index entries.
-@c
-
@node Reference Manual
@chapter Reference Manual
* Other languages:: Note names in various languages
* Lexical modes:: modes
* Types:: Types
+* Assignments:: Assignments
* Music expressions:: Music expressions
* Atomic music expressions:: Atomic music expressions
* Note specification:: notedesc
@section Overview
-This document@footnote{This document has been revised for LilyPond 1.2.}
+[todo: pedals]
+
+This document
describes the the GNU LilyPond input format This format represents a
piece of music in an elegant way, but contains enough information for
both automatic typesetting and automatic performances.
+This document has been revised for LilyPond 1.3.125
+
+[todo: ]
+
+There are two things to note here. The format contains musical
+concepts like pitches and durations, instead of symbols and positions:
+the input format tries to capture the meaning of @emph{music}, and not
+notation. Second, the format tries to be @emph{context-free}:
+a note will sound the same regardless of the current time signature,
+the key, etc.
+
+The purpose of LilyPond is explained informally by the term `music
+typesetter'. This is not a fully correct name: not only does the
+program print musical symbols, it also makes esthetic decisions. All
+symbols and their placement is @emph{generated} from a high-level musical
+description. In other words, LilyPond would be best
+described by `music compiler' or `music to notation compiler'.
+
+
LilyPond input can be classified into three types:
@itemize @bullet
This section describes what you may enter at top level.
-
+@unnumberedsubsec Score definition
@cindex score definition
The output is generated combining a music expression with an output
@var{outputdefs} are zero or more output definitions. If no output
definition is supplied, the default @code{\paper} block will be added.
-@cindex header
+@unnumberedsubsec Header definition
+@cindex headers
-@keyindex{header}
+@cindex @code{\header}
The syntax is
@example
\header @{ @var{key1} = @var{val1};
+@cindex @code{ly2dvi}
@var{key2} = @var{val2}; @dots{} @}
@end example
+
A header describes the file's contents. It can also appear in a
-@code{\score} block. Tools like @code{ly2dvi}@indexcode{ly2dvi} can use this
+@code{\score} block. Tools like @code{ly2dvi} can use this
information for generating titles. Key values that are used by
@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
metre, arranger, piece and tagline.
It is customary to put the @code{\header} at the top of the file.
+@unnumberedsubsec Default output
+
+A @code{\midi} or @code{\paper} block at top-level sets the default
+paper block for all scores that lack an explicit paper block.
+
+@unnumberedsubsec Scheme statements
+
+Scheme statements maybe issued to produce interesting side-effects.
+
+
@node Pitch names
@section Pitch names
+@unnumberedsubsec Pitch name definition
@cindex pitch names
+
@cindex note names
@cindex chord modifier names
Note names and chord modifiers can be customised for nationalities.
languages and conventions. The syntax is as follows.
+@cindex @code{\pitchnames}
+@cindex @code{\chordmodifiers}
+
@example
- \pitchnames@keyindex{pitchnames} @var{scheme-alist}
- \chordmodifiers@keyindex{chordmodifiers} @var{scheme-alist}
+ \pitchnames @var{scheme-alist}
+ \chordmodifiers @var{scheme-alist}
@end example
See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
A @code{\paper} block at top level sets the default paper block. A
@code{\midi} block at top level works similarly.
-Identifier assignments may appear at top level. Semicolons are
-forbidden after top level assignments.
-
+@unnumberedsubsec Assignments
@cindex assignments
+@cindex @code{#}
+
+Identifier assignments may appear at top level. @ref{Assignments}
+
@node Lexical conventions
@section Lexical conventions
@unnumberedsubsec Comments
@cindex comment
+@cindex @code{%}
-@indexcode{%}
-A one line comment is introduced by a `@code{%}' character.
-Block comments are started by `@code{%@{}' and ended by `@code{%@}}'.
+A one line comment is introduced by a @code{%} character.
+Block comments are started by @code{%@{} and ended by `@code{%@}}'.
They cannot be nested.
@unnumberedsubsec Scheme
-@indexcode{#}
-LilyPond contains a Scheme interpreter (the GUILE library) for
-internal use. The interpreter is accessed by the pound sign:
+
@cindex Scheme
@cindex GUILE
@cindex Scheme, in-line code
-Whereever the syntax allows Scheme expressions, you may enter one as
+LilyPond contains a Scheme interpreter (the GUILE library) for
+internal use. In some places Scheme expressions also form valid syntax:
+whereever it is allowed,
@example
#@var{scheme}
@end example
-
-Evaluates the specified Scheme code. If this is used at toplevel, then
+evaluates the specified Scheme code. If this is used at toplevel, then
the result is discarded. Example:
@example
- \property Staff.TestObject \override #'symbol = #(+ 1 2)
+ \property Staff.TestObject \override #'foobar = #(+ 1 2)
@end example
-(in this case, @code{\override} expects two Scheme expressions.
+@code{\override} expects two Scheme expressions, so there are two Scheme
+expressions. The first one is a symbol (@code{foobar}), the second one
+an integer (namely, 3).
-[refer appendix/ online intro on Scheme]
+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.
@unnumberedsubsec Keywords
-
@cindex keyword
+
Keywords start with a backslash, followed by a number of lower case
alphabetic characters. These are all the keywords.
simultaneous sequential accepts alternative bar breathe
char chordmodifiers chords clef cm consists consistsend
context denies duration dynamicscript elementdescriptions
-font grace header in lyrics key mark musicalpitch
+font grace header in lyrics key mark pitch
time times midi mm name pitchnames notes outputproperty
override set revert partial paper penalty property pt
relative remove repeat addlyrics partcombine score
@unnumberedsubsec Integers
-@cindex integer
+@cindex integers
+@cindex @code{+}
+@cindex @code{-}
+@cindex @code{*}
+@cindex @code{/}
Formed from an optional minus sign followed by digits. Arithmetic
operations cannot be done with integers, and integers cannot be mixed
with reals.
@unnumberedsubsec Reals
+@cindex real numbers
+
+
+
-@cindex real
-
Formed from an optional minus sign and a sequence of digits followed
by a @emph{required} decimal point and an optional exponent such as
@code{-1.2e3}. Reals can be built up using the usual operations:
-`@code{+}@indexcode{+}', `@code{-}@indexcode{-}', `@code{*}@indexcode{*}', and
-`@code{/}@indexcode{/}', with parentheses for grouping.
+`@code{+}', `@code{-}', `@code{*}', and
+`@code{/}', with parentheses for grouping.
-A real constant can be followed by one of the dimension
-keywords:
+@cindex @code{\mm},
+@cindex @code{\in}
+@cindex @code{\cm}
+@cindex @code{\pt}
@cindex dimensions
- @code{\mm}@keyindex{mm},
-@code{\pt}@keyindex{pt}, @code{\in}@keyindex{in}, or
-@code{\cm}@keyindex{cm}, for millimeters, points, inches and
-centimeters, respectively. This converts the number to a real that
-is the internal representation of dimensions.
+
+A real constant can be followed by one of the dimension keywords:
+@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
+points, inches and centimeters, respectively. This converts the number
+to a real that is the internal representation of dimensions.
-@unnumberedsubsec
+@unnumberedsubsec Strings
@cindex string
-
-Begins and ends with the `@code{"}' character. To include a `@code{"}'
-character in a string write `@code{\"}'. Various other backslash
+@cindex concatenate
+
+Begins and ends with the @code{"} character. To include a @code{"}
+character in a string write @code{\"}. Various other backslash
sequences have special interpretations as in the C language. A string
that contains no spaces can be written without the quotes. See
@ref{Lexical modes} for details on unquoted strings; their interpretation varies
depending on the situation. Strings can be concatenated with the
-`@code{+}' operator.
+@code{+} operator.
The tokenizer accepts the following commands. They have no grammatical
function, hence they can appear anywhere in the input.
-@example
- \maininput@keyindex{maininput}
-@end example
+@unnumberedsubsec Main input
-This command is used in init files to signal that the user file must
-be read. This command cannot be used in a user file.
+@cindex @code{\maininput}
-@unnumberedsubsec file inclusion
+The @code{\maininput} command is used in init files to signal that the
+user file must be read. This command cannot be used in a user file.
+@unnumberedsubsec File inclusion
+@cindex @code{\include}
@example
- \include@keyindex{include} @var{file}
+ \include @var{filename}
@end example
-Include @var{file}. The argument @var{file} may be a quoted string (an
+Include @var{filename}. The argument @var{filename} may be a quoted string (an
unquoted string will not work here!) or a string identifier. The full
filename including the @file{.ly} extension must be given,
@unnumberedsubsec Version information
-
+@cindex @code{\version}
@example
- \version@keyindex{version} @var{string} ;
+ \version @var{string} ;
@end example
Specify the version of LilyPond that a file was written for. The
argument is a version string in quotes, for example @code{"1.2.0"}.
This is used to detect invalid input, and to aid
-@code{convert-ly}, a tool that automatically upgrades input files.
-@cindex convert-ly
-
-@node Other languages
-@section Other languages
-@cindex Note names, international
-
-Note name definitions have been provided in various languages.
-Simply include the language specific init file. For example:
-`@code{\include "english.ly"}'. The available language files and the
-names they define are:
+@code{convert-ly} a tool that automatically upgrades input files. See
+See @ref{convert-ly} for more information on @code{convert-ly}.
-@example
- Note Names sharp flat
-nederlands.ly c d e f g a bes b -is -es
-english.ly c d e f g a bf b -s/-sharp -f/-flat
-deutsch.ly c d e f g a b h -is -es
-norsk.ly c d e f g a b h -iss/-is -ess/-es
-svenska.ly c d e f g a b h -iss -ess
-italiano.ly do re mi fa sol la sib si -d -b
-catalan.ly do re mi fa sol la sib si -d/-s -b
-@end example
+@cindex convert-ly
-Pitch names can be redefined using the @code{\pitchnames} command, see
-@ref{Pitch names}.
@node Lexical modes
@section Lexical modes
@cindex modes
-To simplify entering notes, lyrics, and chords, @emph{Lilypond} has three
+To simplify entering notes, lyrics, and chords, LilyPond has three
special input modes on top of the default mode. In each mode, words
are identified on the input. If @code{"word"} is encountered, it is
treated as a string. If @code{\word} is encountered, it is treated as
two ways: Different modes treat unquoted words differently, and
different modes have different rules for deciding what is a word.
-@table @samp
- @item Normal mode.
-@cindex mode!normal
+@table @asis
+@item Normal mode.
+@cindex normal mode
- At the start of parsing, @emph{Lilypond} is in Normal mode. In Normal
- mode, a word is an alphabetic character followed by alphanumeric
- characters. If @code{word} is encountered on the input it is
- treated as a string.
-
- @item Note mode.
-@cindex mode!note
-
- Note mode is introduced by the keyword
- @code{\notes}@keyindex{notes}. In Note mode, words can only
- contain alphabetic characters. If @code{word} is encountered,
- LilyPond first checks for a notename of @code{word}. If no
- notename is found, then @code{word} is treated as a string.
-
- Since combinations of numbers and dots are used for indicating
- durations, it is not possible to enter real numbers in this mode.
-
- @item Chord mode.
-@cindex mode!chord
-
- Chord mode is introduced by the keyword
- @code{\chords}@keyindex{chords}. It is similar to Note mode, but
- words are also looked up in a chord modifier table (containing
- @code{maj}, @code{dim}, etc).
-
- Since combinations of numbers and dots are used for indicating
- durations, you can not enter real numbers in this mode. Dashes
- and carets are used to indicate chord additions and subtractions,
- so scripts can not be entered in Chord mode.
-
- @item Lyrics mode.
-@cindex mode!lyric
-
- Lyrics mode is introduced by the keyword
- @code{\lyrics}@keyindex{lyrics}. This mode has rules that make it
- easy to include punctuation and diacritical marks in words. A
- word in Lyrics mode begins with: an alphabetic character,
- `@code{_}', `@code{?}', `@code{!}', `@code{:}', `@code{'}', the
- control characters @code{^A} through @code{^F}, @code{^Q} through
- @code{^W}, @code{^Y}, @code{^^}, any 8-bit character with ASCII code
- over 127, or a two-character combination of a backslash followed
- by one of `@code{`}', `@code{'}', `@code{"}', or
- `@code{^}'.@footnote{The purpose of Lyrics mode is that you can
- enter lyrics in @TeX{} format or a standard encoding without
- needing quotes. The precise definition of this mode indeed is
- ludicrous. This will remain so until the authors of LilyPond
- acquire a deeper understanding of character encoding, or someone
- else steps up to fix this.}
-
- Subsequent characters of a word can be any character that is not
- a digit and not white space. One important consequence of this
- is that a word can end with `@code{@}}', which may be confusing if
- you thought the closing brace was going to terminate Lyrics
- mode.@footnote{LilyPond will issue a warning, though.} Any
- `@code{_}' character which appears in an unquoted word is
- converted to a space. This provides a mechanism for introducing
- spaces into words without using quotes. Quoted words can also be
- used in Lyrics mode to specify words that cannot be written with
- the above rules. Here are some examples. Not all of these words
- are printable by @TeX{}.
+At the start of parsing, LilyPond is in Normal mode. In Normal
+mode, a word is an alphabetic character followed by alphanumeric
+characters. If @code{word} is encountered on the input it is
+treated as a string.
+
+@item Note mode.
+@cindex note mode
+
+@cindex @code{\notes}
+Note mode is introduced by the keyword
+@code{\notes}. In Note mode, words can only
+contain alphabetic characters. If @code{word} is encountered,
+LilyPond first checks for a notename of @code{word}. If no
+notename is found, then @code{word} is treated as a string.
+
+Since combinations of numbers and dots are used for indicating
+durations, it is not possible to enter real numbers in this mode.
+
+@item Chord mode.
+@cindex chord mode
+
+Chord mode is introduced by the keyword
+@code{\chords}. It is similar to Note mode, but
+words are also looked up in a chord modifier table (containing
+@code{maj}, @code{dim}, etc).
+
+Since combinations of numbers and dots are used for indicating
+durations, you can not enter real numbers in this mode. Dashes
+and carets are used to indicate chord additions and subtractions,
+so scripts can not be entered in Chord mode.
+
+@item Lyrics mode.
+@cindex lyric mode
+@cindex @code{\lyrics}
+
+Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has
+rules that make it easy to include punctuation and diacritical marks in
+words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{}
+format or a standard encoding without needing quotes. The precise
+definition of this mode is ludicrous, and this will remain so until the
+authors of LilyPond acquire a deeper understanding of character
+encoding, or someone else steps up to fix this.
+
+A word in Lyrics mode begins with: an alphabetic character, @code{_},
+@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
+through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
+any 8-bit character with ASCII code over 127, or a two-character
+combination of a backslash followed by one of @code{`}, @code{'},
+@code{"}, or @code{^}.
+
+Subsequent characters of a word can be any character that is not a digit
+and not white space. One important consequence of this is that a word
+can end with `@code{@}}', which may be confusing. However, LilyPond will
+issue a warning. Any @code{_} character which appears in an unquoted
+word is converted to a space. This provides a mechanism for introducing
+spaces into words without using quotes. Quoted words can also be used
+in Lyrics mode to specify words that cannot be written with the above
+rules. Here are some examples. Not all of these words are printable by
+@TeX{}.
@example
Ah! % a word
_ _ _ _ % 4 words, each one a space
@end example
- Since combinations of numbers and dots are used for indicating
- durations, you can not enter real numbers in this mode.
+Since combinations of numbers and dots are used for indicating
+durations, you can not enter real numbers in this mode.
@end table
-[todo: include short table showign differences]
+[todo: include short table showing differences]
@node Types
@section Types
@cindex Identifiers
-[say something about types]
-
All of the information in a LilyPond input file, is represented as a
Scheme value. In addition to normal Scheme data types (such as pair,
number, boolean, etc.), LilyPond has a number of specialized data types,
@itemize @bullet
- @item Input
- @item c++-function
- @item Music: see @ref{Music expressions}
- @item Identifier
- @item Translator_def:
+@item Input
+@item c++-function
+@item Music: see @ref{Music expressions}
+@item Identifier
+@item Translator_def:
See section @ref{contextdefs} for more information
-
- @item Duration
- @item Pitch
- @item Score
- @item Music_output_def (TODO: this is not really a Scheme object
-yet. Nevertheless, you can use identifiers to make references to them )
- @item Moment (rational number)
+@item Duration
+@item Pitch
+@item Score
+@item Music_output_def
+@item Moment (rational number)
@end itemize
LilyPond also includes some transient object types. Objects of these
during a lilypond run.
@itemize @bullet
- @item Grob: short for Graphical object. See @ref{Grobs}.
- @item Molecule: device-independent page output object,
- including dimensions. Produced by some Grob functions
- See @ref{Molecules}
- @item Translator: object that produces audio objects or Grobs. This is
+@item Grob: short for Graphical object. See @ref{Grobs}.
+@item Molecule: device-independent page output object,
+including dimensions. Produced by some Grob functions
+See @ref{Molecules}
+@item Translator: object that produces audio objects or Grobs. This is
not yet user accessible.
- @item Font_metric: object representing a font. (See @ref{Font metrics})
+@item Font_metric: object representing a font. (See @ref{Font metrics})
@c @item Audio_element: (todo, smobme)
@end itemize
+@node Assignments
+@unnumberedsubsec Assignments
+
Identifiers allow objects to be assigned to names during the parse
-stage. To assign an identifier, you use `@var{name}=@var{value}' and to
-refer to an identifier, you preceed its name with a backslash:
-`@code{\}@var{name}'. Identifier assignments must appear at top level
-in the @emph{Lilypond} file. Semicolons are forbidden after assignments
-appearing at top level but they are obligatory after assignments
-appearing in the @code{\paper} block, see Section @ref{Page layout}.
+stage. To assign an identifier, you use @var{name}@code{=}@var{value}
+and to refer to an identifier, you preceed its name with a backslash:
+`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
+the input-types listed above. Identifier assignments can appear at top
+level in the LilyPond file, but also in @code{\paper} blocks.
-@var{value} is any valid Scheme value or any of the input-types listed
-above.
+Semicolons are forbidden after top level assignments, but mandatory in
+other places. The rules about semicolons and assignments are very
+confusing, but when LilyPond input evolves more towards Scheme, we hope
+that this problem will grow smaller.
An identifier can be created with any string for its name, but you will
only be able to refer to identifiers whose names begin with a letter,
identifier in terms of its old value, e.g.
@example
- foo = \foo * 2.0
+foo = \foo * 2.0
@end example
When an identifier is referenced, the information it points to is
copied. For this reason, an identifier reference must always be the
- first item in a block.
+first item in a block.
@example
\paper @{
- foo = 1.0
- \paperIdent % wrong and invalid
+foo = 1.0
+\paperIdent % wrong and invalid
@}
\paper @{
- \paperIdent % correct
- foo = 1.0
+\paperIdent % correct
+foo = 1.0
@}
@end example
@cindex music expressions
-Music in @emph{Lilypond} is entered as a music expression. Notes, rests,
+Music in LilyPond is entered as a music expression. Notes, rests,
lyric syllables are music expressions (the atomic
expressions),
@cindex atomic music expressions
\sequential @{ c4 d4 @}
@end example
-The meaning of this compound expression is to play the `@code{c}'
-first, and then the `@code{d}' (as opposed to playing them
+The meaning of this compound expression is to play the @code{c}
+first, and then the @code{d} (as opposed to playing them
simultaneously, for instance).
Atomic music expression are discussed in
@cindex pitch
-@cindex duration
-
-
The syntax for pitch specification is
-
+@cindex @code{\pitch}
@example
- \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @}
+ \pitch @var{scmpitch}
@end example
-@var{octave} is specified by an integer, zero for the octave
-containing middle C. @var{note} is a number from 0 to 7, with 0
-corresponding to C and 7 corresponding to B. The shift is zero for a
-natural, negative to add flats, or positive to add sharps.
+@var{scmpitch} is a pitch scheme object, see @ref{Pitch}.
In Note and Chord mode, pitches may be designated by names. See
section @ref{Other languages} for pitch names in different languages.
-The syntax for duration specification is
+@cindex duration
+@cindex @code{\duration}
+The syntax for duration specification is
@example
- \duration@keyindex{duration}
- @{ @var{length} @var{dotcount} @}
+ \duration @var{scmduration}
@end example
-@var{length} is the negative logarithm (base 2) of the duration:
-1 is a half note, 2 is a quarter note, 3 is an eighth
-note, etc. The number of dots after the note is given by
-@var{dotcount}.
-
In Note, Chord, and Lyrics mode, durations may be designated by
numbers and dots.
The default names are the Dutch note names. The notes are specified
-by the letters `@code{c}' through `@code{b}', where `@code{c}' is an
+by the letters @code{c} through @code{b}, where @code{c} is an
octave below middle C and the letters span the octave above that C.
In Dutch,
-@cindex notenames!Dutch
-a sharp is formed by adding `@code{-is}' to the end of a pitch name. A
-flat is formed by adding `@code{-es}'. Double sharps and double flats
-are obtained by adding `@code{-isis}' or `@code{-eses}'. `@code{aes}'
-and `@code{ees}' are contracted to `@code{as}' and `@code{es}' in Dutch,
-but both forms will be accepted.
-
-LilyPond has predefined sets of notenames for various languages. See
-section @ref{Other languages}.
+@cindex note names, Dutch
+a sharp is formed by adding @code{-is} to the end of a pitch name. A
+flat is formed by adding @code{-es}. Double sharps and double flats are
+obtained by adding @code{-isis} or @code{-eses}. @code{aes} and
+@code{ees} are contracted to @code{as} and @code{es} in Dutch, but both
+forms will be accepted.
+
+LilyPond has predefined sets of notenames for various other languages.
+To use them, simply include the language specific init file. For
+example: @code{\include "english.ly"}. The available language files and
+the names they define are:
+
+@example
+ Note Names sharp flat
+nederlands.ly c d e f g a bes b -is -es
+english.ly c d e f g a bf b -s/-sharp -f/-flat
+deutsch.ly c d e f g a b h -is -es
+norsk.ly c d e f g a b h -iss/-is -ess/-es
+svenska.ly c d e f g a b h -iss -ess
+italiano.ly do re mi fa sol la sib si -d -b
+catalan.ly do re mi fa sol la sib si -d/-s -b
+@end example
+@cindex @code{'}
+@cindex @code{,}
+
+Pitch names can be redefined using the @code{\pitchnames} command, see
+@ref{Pitch names}.
+
+
+
The optional octave specification takes the form of a series of
-single quote (`@code{'}@indexcode{'}') characters or a series of comma
-(`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one
+single quote (`@code{'}') characters or a series of comma
+(`@code{,}') characters. Each @code{'} raises the pitch by one
octave; each @code{,} lowers the pitch by an octave.
@lilypond[fragment,verbatim,center]
ceses' eses' geses' ases' beses'
@end lilypond
-Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
-will determine what accidentals to typeset depending on the key and
-context. A reminder accidental
+LilyPond will determine what accidentals to typeset depending on the key
+and context, so alteration refer to what note is heard, not to whether
+accidentals are printed. A reminder accidental
@cindex reminder accidental
-can be forced by adding an exclamation mark `@code{!}' after the pitch.
+@cindex @code{?}
+can be forced by adding an exclamation mark @code{!} after the pitch.
A cautionary accidental,
@cindex cautionary accidental
+
i.e., an accidental within parentheses can be obtained by adding the
-question mark `@code{?}@indexcode{?}' after the pitch.
+question mark `@code{?}' after the pitch.
@lilypond[fragment,verbatim,center]
cis' d' e' cis' c'? d' e' c'!
@example
c'\longa c'\breve
c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
+r\longa r\breve
+r1 r2 r4 r8 r16 r32 r64 r64
@end example
-@end quotation
-
-@quotation
@lilypond[]
\score {
\notes \relative c'' {
- a\longa a\breve
+ a\longa a\breve \autoBeamOff
a1 a2 a4 a8 a16 a32 a64 a64
+ r\longa r\breve
+ r1 r2 r4 r8 r16 r32 r64 r64
}
\paper {
-%{ \translator {
+ \translator {
\StaffContext
- \remove "Clef_engraver";
- \remove "Staff_symbol_engraver";
- } %}
+ \remove "Clef_engraver";
+ \remove "Staff_symbol_engraver";
+ \remove "Time_signature_engraver";
+ \consists "Pitch_squash_engraver";
+ }
}
}
@end lilypond
@end quotation
-@quotation
+As you can see, the longa is not printed. To get a longa note head, you
+have to use a different style of note heads. See [TODO].
-@example
-r\longa r\breve
-r1 r2 r4 r8 r16 r32 r64 r64
-@end example
+@cindex @code{.}
-@end quotation
-@quotation
+If the duration is omitted then it is set equal to the previous duration
+entered. At the start of parsing there is no previous duration, so then
+a quarter note is assumed. The duration can be followed by a dot
+(`@code{.}') to obtain dotted note lengths.
-@lilypond[]
-\score {
- \notes \relative c'' {
- r\longa r\breve
- r1 r2 r4 r8 r16 r32 r64 r64
- }
- \paper {
- loose_column_distance = 2.5 * \staffspace;
- linewidth = -1.0;
- \translator {
- \StaffContext
- \remove "Clef_engraver";
- \remove "Staff_symbol_engraver";
- \remove "Bar_engraver";
- }
- }
-}
-@end lilypond
-@end quotation
+Rests are entered like notes, with note name `@code{r}'.
+There is also a note name
+`@code{s}', which produces a space of the specified
+duration.
-If the duration is omitted then it is set equal to the previous
-duration. If there is no previous duration, a quarter note is
-assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}')
-to obtain dotted note lengths.
@lilypond[fragment,verbatim,center]
a'4. b'4.
@end lilypond
+@cindex @code{r}
+@cindex @code{s}
+
+You can alter the length of duration by writing `@code{*}@var{fraction}'
+after it. This will not affect the appearance of note heads or rests.
-You can alter the length of duration by writing
-`@code{*}@var{fraction}' after it. This will not affect the
-appearance of note heads or rests.
+@unnumberedsubsec Multi measure rests
+@cindex @code{R}
-Rests are entered like notes, with note name `@code{r}@indexcode{r}', or
-`@code{R}@indexcode{R}'. There is also a note name
-`@code{s}@indexcode{s}', which produces a space of the specified
-duration. `@code{R}' is specifically meant for entering parts: the
-@code{R} rest can expand to fill a score with rests, or it can be
-printed as a single multimeasure rest.
+Multi_measure_rest are entered using `@code{R}'. It is specifically
+meant for entering parts: the rest can expand to fill a score with
+rests, or it can be printed as a single multimeasure rest This expansion
+is controlled by the property @code{Score.skipBars}. If this is set to true,
+Lily will not expand empty measures, and the multimeasure rests
+automatically adds the appropriate number.
-You can control the expansion by setting the property
-@code{Score.skipBars}. If this is set to true, Lily will not expand
-empty measures, and the multimeasure rests automatically adds the
-appropriate number.
+@lilypond[fragment]
+ \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
+@end lilypond
Note that there is currently no way to condense multiple rests into a
single multimeasure rest.
-
+@unnumberedsubsec Lyrics
@cindex lyrics expressions
Syllables are entered like notes, with pitches replaced by text. For
-example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each
+example, @code{Twin-4 kle4 twin-4 kle4} enters four syllables, each
with quarter note duration. Note that the hyphen has no special
meaning for lyrics, and does not introduce special symbols. See
section @ref{Lexical modes} for a description of what is interpreted as
lyrics.
Spaces can be introduced into a lyric either by using quotes
-(`@code{"}') or by using an underscore without quotes: `@code{He_could4
-not4}'. All unquoted underscores are converted to spaces. Printing
+(@code{"}) or by using an underscore without quotes: @code{He_could4
+not4}. All unquoted underscores are converted to spaces. Printing
lyrics is discussed in section @ref{lyricprint}.
-
+[explain automatic phrasing]
@cindex properties
+@unnumberedsubsec Translation property
+@cindex @code{\property}
@example
- \property@keyindex{property}
- @var{contextname}.@var{propname} = @var{value}
+ \property @var{contextname}.@var{propname} = @var{value}
@end example
Sets the @var{propname} property of the context @var{contextname} to
Depending on the context, it may be necessary to quote the strings or
to leave space on both sides of the dot.
-
-
@cindex translator switches
+@unnumberedsubsec Translator switches
+@cindex @code{\translator}
@example
- \translator@keyindex{translator}
- @var{contexttype} = @var{name}
+ \translator @var{contexttype} = @var{name}
@end example
A music expression indicating that the context which is a direct
@cindex output properties
-
+@unnumberedsubsec Output properties
These allow you to tweak what is happening in the back-end
directly. If you want to control every detail of the output
@lilypond[fragment,verbatim]
\relative c'' { c4
- \context Staff \outputproperty
- #(make-type-checker 'Note_head)
- #'extra-offset = #'(5.0 . 7.5)
+ \context Staff \outputproperty
+ #(make-type-checker 'note-head-interface)
+ #'extra-offset = #'(5.0 . 7.5)
<c8 e g> }
@end lilypond
This selects all note heads occurring at current staff level, and sets
-the extra-offset of those heads to (5,7.5), shifting them up and
-right.
+the @code{extra-offset} of those heads to @code{(5,7.5)}, shifting them
+up and right.
Use of this feature is entirely on your own risk: if you use this, the
result will depend very heavily on the implementation of the backend,
which we change regularly and unscrupulously.
-
-@cindex commands
-
-Commands are music expressions that have no duration.
-
+@unnumberedsubsec Key signature
+@cindex @code{\key}
@example
- @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;}
+ @code{\key} @var{pitch} @var{type} @code{;}
@end example
-
-Change the key signature. @var{type} should be
-@code{\major}@keyindex{major} or @code{\minor}@keyindex{minor} to get
-@var{pitch}-major or @var{pitch}-minor, respectively. The second
-argument is optional; the default is major keys. The @var{\context}
-argument can also be given as an integer, which tells the number of
-semitones that should be added to the pitch given in the subsequent
-@code{\key}@keyindex{key} commands to get the corresponding major key,
-e.g., @code{\minor}@keyindex{minor} is defined as 3. The standard
-mode names @code{\ionian}@keyindex{ionian},
-@code{\locrian}@keyindex{locrian}, @code{\aeolian}@keyindex{aeolian},
-@code{\mixolydian}@keyindex{mixolydian}, @code{\lydian}@keyindex{lydian},
-@code{\phrygian}@keyindex{phrygian}, and @code{\dorian}@keyindex{dorian}
-are also defined.
-
-
+@cindex @code{\minor}
+@cindex @code{\major}
+@cindex @code{\minor}
+@cindex @code{\ionian}
+@cindex @code{\locrian}
+@cindex @code{\aeolian}
+@cindex @code{\mixolydian}
+@cindex @code{\lydian}
+@cindex @code{\phrygian}
+@cindex @code{\dorian}
+
+Change the key signature. @var{type} should be @code{\major} or
+@code{\minor} to get @var{pitch}-major or @var{pitch}-minor,
+respectively. The second argument is optional; the default is major
+keys. The @var{\context} argument can also be given as an integer,
+which tells the number of semitones that should be added to the pitch
+given in the subsequent @code{\key} commands to get the corresponding
+major key, e.g., @code{\minor} is defined as 3. The standard mode names
+@code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian},
+@code{\lydian}, @code{\phrygian}, and @code{\dorian} are also defined.
+
+@unnumberedsubsec Rehearsal marks
+@cindex rehearsal marks
+@cindex mark
+@cindex @code{\mark}
@example
- \mark@keyindex{mark} @var{unsigned};
+ \mark @var{unsigned};
+@cindex @code{Mark_engraver}
\mark @var{string};
@end example
-Prints a mark over or under the staff. You must add
-@code{Mark_engraver}@indexcode{Mark_engraver} to the Score context for
-this to work.
+Prints a mark over or under the staff.
+
+@unnumberedsubsec barlines
-@node barlines
-@section barlines
+@cindex @code{\bar}
+@cindex measure lines
+@cindex repeat bars
@example
- \bar@keyindex{bar} @var{bartype};
+ \bar @var{bartype};
@end example
This is a short-cut for doing
@ref{Repeats}, and the documentation of @code{whichBar} in
@ref{(lilypond-internals)LilyPond context properties}.
+[FIXME]
+@unnumberedsubsec Time signature
+@cindex meter
+@cindex time signature
+@cindex @code{\time}
@example
- \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;}
+ \time @var{numerator}@code{/}@var{denominator} @code{;}
@end example
A short-cut for doing
See the documentation of @code{timeSignatureFraction}
+@unnumberedsubsec Tempo
+@cindex beats per minute
+@cindex metronome marking
+@cindex @code{\tempo}
@example
-
- \tempo@keyindex{tempo} @var{duration} = @var{perminute} @code{;}
+ \tempo @var{duration} = @var{perminute} @code{;}
@end example
-Used to specify the tempo. For example, `@code{\tempo 4 = 76;}'
-requests output with 76 quarter notes per minute.
+Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests
+output with 76 quarter notes per minute.
+@unnumberedsubsec Partial measures
+@cindex anacrusis
+@cindex upstep
+@cindex partial measure
+@cindex measure, partial
+@cindex shorten measures
+@cindex @code{\partial}
@example
- \partial@keyindex{partial} @var{duration} @code{;}
+ \partial @var{duration} @code{;}
@end example
Short cut for
@example
\property Score.measurePosition = @var{length of duration}
@end example
+@cindex @code{|}
See the documentation of @code{measurePosition}.
-@cindex anacrusis
-
-@cindex upstep
+@unnumberedsubsec Bar check
-@example
-
- @code{|}@indexcode{|}
@cindex bar check
+@cindex @code{barCheckNoSynchronize}
+@cindex @code{|}
-@end example
-@cindex shorten measures
+Bar checks help you find errors in the input: Whenever one is
+encountered during interpretation, a warning message is issued if it
+doesn't fall at a measure boundary. Depending on the value of
+@code{barCheckNoSynchronize}, the beginning of the measure will be
+relocated, so this can also be used to shorten measures.
-@cindex upstep
+A bar check is entered using the bar symbol, @code{|}
-`@code{|}' is a bar check. Whenever a bar check is encountered during
-interpretation, a warning message is issued if it doesn't fall at a
-measure boundary. This can help you finding errors in the input.
-Depending on the value of @code{barCheckNoSynchronize}
-@indexcode{barCheckNoSynchronize} The beginning of the measure will be
-relocated, so this can also be used to shorten measures.
+This can help you finding errors in the input.
+@unnumberedsubsec Line break penalty.
+@cindex @code{\penalty}
@example
- \penalty@keyindex{penalty} @var{int} @code{;}
+ \penalty @var{int} @code{;}
@end example
-Discourage or encourage line breaks. See identifiers
-@code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in
-section [on identifiers] [FIXME].
+Discourage or encourage line breaks. See @ref{Page layout}.
+@unnumberedsubsec Clef change
+@cindex @code{\clef}
@example
- \clef@keyindex{clef} @var{clefname} @code{;}
+ \clef @var{clefname} @code{;}
@end example
Short-cut for
[todo]
+@unnumberedsubsec Skip
@example
-
- \skip@keyindex{skip} @var{duration} @code{;}
+ \skip @var{duration} @code{;}
@end example
+@cindex @code{\skip}
Skips the amount of time specified by @var{duration}. If no other
music is played, a gap will be left for the skipped time with no
notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
-this has the same effect as the space rest `@code{s}'.
+this has the same effect as the spacer rest.
@node Manual beams
-@section Manual beams
-@cindex beams
+@unnumberedsubsec Manual beams
+
+@cindex beams, manual
+@cindex @code{]}
+@cindex @code{[}
A beam is specified by surrounding the beamed notes with brackets
-`@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'.
+`@code{[}' and `@code{]}'.
@lilypond[fragment,verbatim,center]
[a'8 a'] [a'16 a' a' a']
-@end lilypond
-
-Some more elaborate constructions:
-
-@lilypond[fragment,verbatim,center]
[a'16 <a' c''> c'' <a' c''>]
\times 2/3 { [e'8 f' g'] }
@end lilypond
Beaming can be generated automatically; see section @ref{Automatic Beaming}.
+@cindex @code{-}@code{-}
-To place tremolo marks between notes, use @code{\repeat} with tremolo
-style.
-@cindex tremolo beams
-To create tremolo beams on a single note, simply attach
-`@code{:}@var{length}' to the note itself.
-
-@lilypond[fragment,verbatim,center]
- \repeat "tremolo" 8 { c16 d16 }
- \repeat "tremolo" 4 { c16 d16 }
-@end lilypond
-
-@lilypond[fragment,verbatim,center]
- c'4:32
-@end lilypond
-
-
-@cindex --@@@code{-}@code{-}
-
-@indexcode{__}
-
+@unnumberedsubsec Lyric extender
@cindex extender
-
+@cindex lyric extender
@cindex hyphen
-The syntax for an extender mark is `@code{__}'. This syntax can only
-be used within lyrics mode. The syntax for a spanning hyphen (i.e.,
-a hyphen that will be printed between two lyric syllables) is
-`@code{-}@code{-}'.
+The syntax for an extender mark is @code{__}. This syntax can only
+be used within lyrics mode.
+@unnumberedsubsec Lyric hyphens
+The syntax for a spanning hyphen (i.e., a hyphen that will be printed
+between two lyric syllables) is `@code{-}@code{-}'.
+
+
+@unnumberedsubsec Ties
@cindex ties
+@cindex @code{~}
A tie connects two adjacent note heads of the same pitch. When used
with chords, it connects all of the note heads whose pitches match.
-Ties are indicated using the tilde symbol `@code{~}@indexcode{~}'.
+Ties are indicated using the tilde symbol `@code{~}'.
If you try to tie together chords which have no common pitches, a
warning message will appear and no ties will be created.
e' ~ e' <c' e' g'> ~ <c' e' g'>
@end lilypond
-@cindex articulations
+[sparseTies]
+@unnumberedsubsec Articulation
+@cindex articulations
@cindex scripts
-
@cindex ornaments
A variety of symbols can appear above and below notes to indicate
\score {
< \notes {
+ \property Score.LyricSyllable \override #'font-family =
+#'typewriter
+ \property Score.LyricSyllable \override #'font-shape = #'upright
c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
c''-\thumb c''-\segno c''-\coda
}
- \context Lyrics \lyrics {
+ \context Lyrics \lyrics {
accent__ marcato__ staccatissimo__ fermata
stopped__ staccato__ tenuto__ upbow
downbow__ lheel__ rheel__ ltoe
@end lilypond
+@unnumberedsubsec Text scripts
+
In addition, it is possible to place arbitrary strings of text or
@TeX{} above or below notes by using a string instead of an
-identifier: `@code{c^"text"}'. Fingerings
-@cindex fingering
+identifier: @code{c^"text"}. Fingerings
can be placed by simply using digits. All of these note ornaments
appear in the printed output but have no effect on the MIDI rendering of
the music.
+@cindex fingering
+
To save typing, fingering instructions (digits 0 to 9 are
supported) and single characters shorthands exist for a few
common symbols
@lilypond[]
-
\score {
- \notes {
- \property Voice.TextScript \set #'font-style = #'typewriter
+ \notes \context Voice {
+ \property Voice.TextScript \set #'font-family = #'typewriter
+ \property Voice.TextScript \set #'font-shape = #'upright
c''4-._"c-." s4
c''4--_"c-{}-" s4
c''4-+_"c-+" s4
@end lilypond
-Dynamic marks are specified by using an identifier after a note:
-`@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'.
-The available dynamic marks are:
-@code{\ppp}@keyindex{ppp},
-@code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp},
-@code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff},
-@code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff},
-@code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf},
-@code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp},
-@code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and
-@code{\rfz}@keyindex{rfz}.
+@cindex @code{\textscript}
@example
- \textscript@keyindex{textscript} @var{text} @var{style}
+ \textscript @var{text} @var{style}
@end example
Defines a text to be printed over or under a note. @var{style} is a
@end quotation
-This is equivalent to `@code{c4-6 c4-"foo"}'.
+This is equivalent to @code{c4-6 c4-"foo"}.
+@cindex @code{\script}
@cindex scripts
@example
- \script@keyindex{script} @var{alias}
+ \script @var{alias}
@end example
+@cindex @code{\script}
-Prints a symbol above or below a note. The argument is a string
-which points into the script-alias table defined in @file{script.scm}.
-The scheme definitions specify whether the symbol follows notes into
-the staff, dependence of symbol placement on staff direction, and a
-priority for placing several symbols over one note. Usually the
-@code{\script}@keyindex{script} keyword is not used directly. Various
+Prints a symbol above or below a note. The argument is a string which
+points into the script-alias table defined in @file{scm/script.scm}, for
+information on how to add scripts, read the comments in that file.
+Usually the @code{\script} keyword is not used directly. Various
helpful identifier definitions appear in @file{script.ly}.
-@cindex slur
-Slurs connects chords and try to avoid crossing stems. A slur is
-started with `@code{(}' and stopped with `@code{)}'. The
-starting `@code{(}' appears to the right of the first note in
-the slur. The terminal `@code{)}' appears to the left of the
-first note in the slur. This makes it possible to put a note in
-slurs from both sides:
+@unnumberedsubsec Dynamics
+
+@cindex @code{\ppp}
+@cindex @code{\pp}
+@cindex @code{\p}
+@cindex @code{\mp}
+@cindex @code{\mf}
+@cindex @code{\f}
+@cindex @code{\ff}
+@cindex @code{\fff}
+@cindex @code{\ffff}
+@cindex @code{\fp}
+@cindex @code{\sf}
+@cindex @code{\sff}
+@cindex @code{\sp}
+@cindex @code{\spp}
+@cindex @code{\sfz}
+@cindex @code{\rfz}
+@cindex crescendo
+@cindex @code{\cr}
+@cindex @code{\rc}
+@cindex @code{\decr}
+@cindex @code{\rced}
+@cindex @code{\<}
+@cindex @code{\>}
+@cindex @code{\"!}
+
+Dynamic marks are specified by using an identifier after a note:
+@code{c4-\ff} (the dash is optional for dynamics: `@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}, @code{\sp},
+@code{\spp}, @code{\sfz}, and
+@code{\rfz}.
+
+
+A crescendo mark is started with @code{\cr} and terminated with
+@code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is
+started with @code{\decr} and terminated with @code{\rced}. There are
+also shorthands for these marks. A crescendo can be started with
+@code{\<} and a decrescendo can be started with @code{\>}. Either one
+can be terminated with @code{\!}. Note that @code{\!} must go before
+the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
+after the last note. Because these marks are bound to notes, if you
+want to get several marks during one note, you must use spacer notes.
@lilypond[fragment,verbatim,center]
- f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
+ c'' \< \! c'' d'' \decr e'' \rced
+ < f''1 { s4 \< \! s2 \> \! s4 } >
@end lilypond
+[todo: text cr]
-@cindex crescendo
+@unnumberedsubsec Slurs
+@cindex slur
-A crescendo mark is started with @code{\cr}@keyindex{cr} and terminated
-with @code{\rc}@keyindex{rc}. A decrescendo mark is started with
-@code{\decr}@keyindex{decr} and terminated with
-@code{\rced}@keyindex{rced}. There are also shorthands for these
-marks. A crescendo can be started with @code{\<}@keyindex{<} and a
-decrescendo can be started with @code{\>}@keyindex{>}. Either one can
-be terminated with @code{\!}@keyindex{"!}. Note that @code{\!}
-must go before the last note of the dynamic mark whereas @code{\rc}
-and @code{\rced} go after the last note. Because these marks are
-bound to notes, if you want to get several marks during one note, you
-must use spacer notes.
+Slurs connects chords and try to avoid crossing stems. A slur is
+started with @code{(} and stopped with @code{)}. The
+starting @code{(} appears to the right of the first note in
+the slur. The terminal @code{)} appears to the left of the
+first note in the slur. This makes it possible to put a note in
+slurs from both sides:
@lilypond[fragment,verbatim,center]
- c'' \< \! c'' d'' \decr e'' \rced
- < f''1 { s4 \< \! s2 \> \! s4 } >
+ f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
@end lilypond
-@example
+@unnumberedsubsec Spanners
+@cindex @code{\spanrequest}
- \spanrequest@keyindex{spanrequest} @var{startstop} @var{type}
+@example
+ \spanrequest @var{startstop} @var{type}
@end example
+@cindex @code{\start}
+@cindex @code{\stop}
Define a spanning request. The @var{startstop} parameter is either -1
-(@code{\start}@keyindex{start}) or 1 (@code{\stop}@keyindex{stop}) and
-@var{type} is a string that describes what should be started.
-Supported types are @code{crescendo}, @code{decrescendo},
-@code{beam}, @code{slur}. This is an internal command. Users should
-use the shorthands which are defined in the initialization file
-@file{spanners.ly}.
+(@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
+describes what should be started. Supported types are @code{crescendo},
+@code{decrescendo}, @code{beam}, @code{slur}. This is an internal
+command. Users should use the shorthands which are defined in the
+initialization file @file{spanners.ly}.
You can attach a (general) span request to a note using
The slur syntax with parentheses is a shorthand for this.
-
-@node stem tremolo
-@section stem tremolo
+@node Stem tremolo
+@section Stem tremolo
@cindex tremolo marks
+@cindex @code{tremoloFlags}
+
+[FIXME: should be \repeat]
Tremolo marks can be printed on a single note by adding
`@code{:}[@var{length}]' after the note. The length must be at
least 8. A @var{length} value of 8 gives one line across
the note stem. If the length is omitted, then the last value is
-used, or the value of the @code{tremoloFlags}@indexcode{tremoloFlags} property if there was
+used, or the value of the @code{tremoloFlags} property if there was
no last value.
@lilypond[verbatim,fragment,center]
c'2:8 c':32
@end lilypond
+@section Arpeggio
+@cindex argepeggio
+@cindex broken arpeggio
+@cindex @code{\arpeggio}
+
+You can specify an @rgrob{Arpeggio} sign on a chord by issuing an
+@c FIXME
+@c @code{\arpeggio} request:
+@code{\arpeggio} request:
+
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \context Voice <c'\arpeggio e g c>
+@end lilypond
+@end quotation
+
+Typesetting of simultanious chords with arpeggios can be controlled with
+the property @code{PianoStaff.connectArpeggios} @footnote{ FIXME:
+connectArpeggios. Can't find the English terms for two kinds of
+arpeggio (Dutch: gebroken arpeggio vs doorlopend arpeggio).} By
+default, LilyPond prints broken arpeggios; when set to true, one
+extended arpeggio sign is printed.
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \context PianoStaff <
+ \property PianoStaff.connectArpeggios = ##t
+ \context Staff \context Voice <c''\arpeggio e g c>
+ \context Staff=other \context Voice <c,\arpeggio e g>
+ >
+@end lilypond
+@end quotation
+
+@section Glissando
+@cindex glissando
+@cindex @code{\glissando}
+
+A @rgrob{Glissando} line can be requested by issuing a
+@c FIXME
+@c @code{\glissando} request:
+@code{\glissando} request:
+
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ c'' \glissando c'
+@end lilypond
+@end quotation
+
+Printing of the additional text @samp{gliss.} must be done manually.
+
+
+@subsection Follow Thread
+@cindex follow thread
+@cindex staff switching
+@cindex cross staff
+
+@c Documented here because it looks like a glissando...
+@cindex @code{followThread}
+A glissando-like line can be printed to connect notes whenever a thread
+switches to another staff. This is enabled if the property
+@code{PianoStaff.followThread} is set to true:
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \context PianoStaff <
+ \property PianoStaff.followThread = ##t
+ \context Staff \context Voice {
+ c'1
+ \translator Staff=two
+ b2 a
+ }
+ \context Staff=two {\clef bass; \skip 1*2;}
+ >
+@end lilypond
+@end quotation
@node Compound music expressions
@section Compound music expressions
@lilypond[fragment,verbatim,center]
\notes \context Staff {
- \cadenzaOn
<a c'> <b d' > <c' e'>
< { a b c' } { c' d' e' } >
}
+
@end lilypond
+@cindex @code{\context}
@cindex context selection
-@c @keyindex{context}
@example
\context @var{contexttype} [= @var{contextname}] @var{musicexpr}
@cindex mode switch
-Mode switching keywords form compound music expressions: @code{\notes}
-@keyindex{notes} @var{musicexpr}, @code{\chords} @keyindex{chords}
-@var{musicexpr}, and @code{\lyrics} @keyindex{lyrics} @var{musicexpr}.
-These expressions do not add anything to the meaning of their
-arguments. They are just a way to indicate that the arguments should
-be parsed in indicated mode. See @ref{Lexical modes} for more
-information on modes.
+@cindex @code{\notes}
+@cindex @code{\chords}
+@cindex @code{\lyrics}
-@cindex sequential music
+Mode switching keywords form compound music expressions: @code{\notes}
+@var{musicexpr}, @code{\chords} @var{musicexpr},
+and @code{\lyrics} @var{musicexpr}. These
+expressions do not add anything to the meaning of their arguments. They
+are just a way to indicate that the arguments should be parsed in
+indicated mode. See @ref{Lexical modes} for more information on modes.
+[to lexer modes?]
+@unnumberedsubsec Sequential music
+@cindex @code{\sequential}
+@cindex sequential music
@example
-
- \sequential@keyindex{sequential}
- @code{@{} @var{musicexprlist} @code{@}}
+ \sequential @code{@{} @var{musicexprlist} @code{@}}
@end example
This means that list should be played or written in sequence, i.e.,
There is a shorthand, which leaves out the keyword:
@example
+@cindex @code{<}
+@cindex @code{>}
@code{@{} @var{musicexprlist} @code{@}}
@end example
+@unnumberedsubsec Simultaneous music
@cindex simultaneous music
-
-@indexcode{<}
-@indexcode{>}
+@cindex @code{\simultaneous}
@example
-
- \simultaneous@keyindex{simultaneous}
- @code{@{} @var{musicexprlist} @code{@}}
+ \simultaneous @code{@{} @var{musicexprlist} @code{@}}
@end example
It constructs a music expression where all of its arguments start at
elements. The following shorthand is a common idiom:
@example
-
@code{<} @var{musicexprlist} @code{>}
@end example
-@node relative
-@section relative
-@cindex relative pitch specification
+@node Relative octaves
+@section Relative octaves
+@cindex relative octave specification
It is easy to get confused by octave changing marks and accidentally
putting a pitch in the wrong octave. A much better way of entering a
note's octave is `the relative octave' mode.
+@cindex @code{\relative}
@example
-
- \relative@keyindex{relative} @var{startpitch} @var{musicexpr}
+ \relative @var{startpitch} @var{musicexpr}
@end example
The octave of notes that appear in @var{musicexpr} are calculated as
between this and the last note is always taken to be a fourth or
less.@footnote{The interval is determined without regarding
accidentals. A @code{fisis} following a @code{ceses} will be put above
-the @code{ceses}.} The octave changing marks `@code{'}' and `@code{,}'
+the @code{ceses}.} The octave changing marks @code{'} and @code{,}
can then be added to raise or lower the pitch by an extra octave.
Upon entering relative mode, an absolute starting pitch must be
specified that will act as the predecessor of the first note of
<c, e' g>
}
@end lilypond
+@cindex @code{\notes}
The pitch after the @code{\relative} contains a notename. To parse
the pitch as a notename, you have to be in note mode, so there must
-be a surrounding @code{\notes}@keyindex{notes} keyword (which is not
+be a surrounding @code{\notes} keyword (which is not
shown here).
The relative conversion will not affect @code{\transpose} or
It is strongly recommended to use relative pitch mode: less work,
less error-prone, and more readable.
-
+@node Entering named chords
+@unnumberedsubsec named chords
Chord names are a way to generate simultaneous music expressions that
correspond with traditional chord names. It can only be used in
is the chord duration in the usual notation. There are two kinds of
modifiers. One type is @emph{chord additions}, which are obtained by
listing intervals separated by dots. An interval is written by its
-number with an optional `@code{+}' or `@code{-}' to indicate raising or
+number with an optional @code{+} or @code{-} to indicate raising or
lowering by half a step. Chord additions has two effects: It adds
the specified interval and all lower odd numbered intervals to the
chord, and it may lower or raise the specified interval. Intervals
-must be separated by a dot (`@code{.}').
+must be separated by a dot (@code{.}).
+
+
+Throughout these examples, chords have been shifted around the staff
+using @code{\transpose}.
+
@quotation
@end lilypond
@end quotation
-The second type of modifier that may appear after the `@code{:}' is a
+@cindex @code{aug}
+@cindex @code{dim}
+@cindex @code{maj}
+@cindex @code{sus}
+
+The second type of modifier that may appear after the @code{:} is a
named modifier. Named modifiers are listed in the file
-@file{chord-modifiers.ly}. The available modifiers are `@code{m}' and
-`@code{min}' which lower the 3rd half a step, `@code{aug}@indexcode{aug}' which
-raises the 5th, `@code{dim}@indexcode{dim}' which lowers the 5th,
-`@code{maj}@indexcode{maj}' which adds a raised 7th, and `@code{sus}@indexcode{sus}'
+@file{chord-modifiers.ly}. The available modifiers are @code{m} and
+@code{min} which lower the 3rd half a step, `@code{aug}' which
+raises the 5th, `@code{dim}' which lowers the 5th,
+`@code{maj}' which adds a raised 7th, and `@code{sus}'
which replaces the 5th with a 4th.
@quotation
Chord subtractions are used to eliminate notes from a chord. The
-notes to be subtracted are listed after a `@code{^}' character,
+notes to be subtracted are listed after a @code{^} character,
separated by dots.
@lilypond[fragment,verbatim,center]
}
}
@end lilypond
+@cindex @code{/}
-Chord inversions can be specified by appending `@code{/}@indexcode{/}' and
+Chord inversions can be specified by appending `@code{/}' and
the name of a single note to a chord. This has the effect of
lowering the specified note by an octave so it becomes the lowest
note in the chord. If the specified note is not in the chord, a
}
@end lilypond
+@cindex @code{/+}
-Bass notes can be added by `@code{/+}@indexcode{/+}' and
+Bass notes can be added by `@code{/+}' and
the name of a single note to a chord. This has the effect of
adding the specified note to the chord, lowered by an octave,
so it becomes the lowest note in the chord.
@end lilypond
-Throughout these examples, chords have been shifted around the staff
-using @code{\transpose}.
-
-You should not combine @code{\relative} with named chords.
+The most interesting application is printing chords using chord names,
+See @ref{Chord names}.
+You should not combine @code{\relative} with named chords. [FIXME]
+@unnumberedsubsec Tuplets
@cindex tuplets
Tuplets are made out of a music expression by multiplying their
duration with a fraction.
+@cindex @code{\times}
@example
-
- \times@keyindex{times} @var{fraction} @var{musicexpr}
+ \times @var{fraction} @var{musicexpr}
@end example
The duration of @var{musicexpr} will be multiplied by the fraction.
@lilypond[fragment,verbatim,center]
g'4 \times 2/3 {c'4 c' c'} d'4 d'4
@end lilypond
+@cindex @code{\grace}
+@unnumberedsubsec Grace notes
+@cindex ornaments
@cindex grace notes
+@cindex @code{graceAlignPosition}
@example
-
- \grace@keyindex{grace} @var{musicexpr}
+ \grace @var{musicexpr}
@end example
A grace note expression has duration 0; the next real note is
assumed to be the main note.
-
You cannot have the grace note after the main note, in terms of
duration, and main notes, but you can typeset the grace notes to the
right of the main note using the property
-@code{graceAlignPosition}@indexcode{graceAlignPosition}.
+@code{graceAlignPosition}.
+@cindex @code{flagStyle}
When grace music is interpreted, a score-within-a-score is set up:
@var{musicexpr} has its own time bookkeeping, and you could (for
this score-within-a-score, you can create notes, beams, slurs, etc.
Unbeamed eighth notes and shorter by default have a slash through the
stem. This behavior can be controlled with the
-@code{flagStyle}@indexcode{flagStyle} property.
+@code{flagStyle} property.
@quotation
-
@lilypond[fragment,verbatim]
\relative c'' {
\grace c8 c4 \grace { [c16 c16] } c4
@end lilypond
@end quotation
+@cindex @code{\grace}
-At present, nesting @code{\grace}@keyindex{grace} notes, e.g.
-
+At present, nesting @code{\grace} notes is not supported. The following
+may cause run-time errors:
@example
-
@code{\grace @{ \grace c32 c16 @} c4}
@end example
-
-may result in run-time errors of LilyPond. Since the meaning of such
-a construct is unclear, we don't consider this a loss. Similarly,
-juxtaposing two @code{\grace} sections is syntactically valid, but
-makes no sense and may cause runtime errors.
+Since the meaning of such a construct is unclear, we don't consider
+this a loss. Similarly, juxtaposing two @code{\grace} sections is
+syntactically valid, but makes no sense and may cause runtime errors.
Ending a staff or score with grace notes may also generate a run-time
error, since there will be no main note to attach the grace notes to.
+The present implementation is not robust and generally kludgy. We expect
+it to change after LilyPond 1.4
@node Repeats
@section Repeats
@cindex repeats
+@cindex @code{\repeat}
-In order to specify repeats, use the @code{\repeat}@keyindex{repeat}
+In order to specify repeats, use the @code{\repeat}
keyword. Since repeats look and sound differently when played or
printed, there are a few different variants of repeats.
-@table @samp
- @item unfolded
- Repeated music is fully written (played) out. Useful for MIDI
- output.
+@table @asis
+@item unfolded
+Repeated music is fully written (played) out. Useful for MIDI
+output.
+
+@item volta
+This is the normal notation: Repeats are not written out, but
+alternative endings (voltas) are printed, left to right.
- @item volta
- This is the normal notation: Repeats are not written out, but
- alternative endings (voltas) are printed, left to right.
+@item folded
+Alternative endings are written stacked. Which is unfortunately not
+practical for anything right now.
- @item folded
- Alternative endings are written stacked, which is useful for
- lyrics.
+@item tremolo
+Make tremolo beams.
@end table
The syntax for repeats is
@example
-
\repeat @var{variant} @var{repeatcount} @var{repeatbody}
@end example
If you have alternative endings, you may add
+@cindex @code{\alternative}
@example
-
- \alternative@keyindex{alternative}
- @code{@{} @var{alternative1}
+ \alternative @code{@{} @var{alternative1}
@var{alternative2}
@var{alternative3} @dots{} @code{@}}
@end example
the specified number of repeats.
@quotation
-
@lilypond[fragment,verbatim]
\context Staff {
\relative c' {
{\partial 1; a a a a | b1 } }
}
}
-
@end lilypond
@end quotation
+As you can see, LilyPond doesn't remember the timing information, nor
+are slurs or ties repeated. We hope to fix this after 1.4.
+
It is possible to nest @code{\repeat}. This is not entirely
supported: the notes will come be in the right places, but the repeat
bars will not.
+To place tremolo marks between notes, use @code{\repeat} with tremolo
+style.
+@cindex tremolo beams
+To create tremolo beams on a single note, simply attach
+`@code{:}@var{length}' to the note itself.
+
+@lilypond[fragment,verbatim,center]
+ \repeat "tremolo" 8 { c16 d16 }
+ \repeat "tremolo" 4 { c16 d16 }
+@end lilypond
+@cindex @code{__}
+
+@lilypond[fragment,verbatim,center]
+
+ c'4:32
+@end lilypond
+
+
@node transpose
-@section transpose
+@section Transposition
@cindex transposition of pitches
+@cindex @code{\transpose}
-A music expression can be transposed with
-@code{\transpose}@keyindex{transpose}. The syntax is
-
+A music expression can be transposed with @code{\transpose}. The syntax
+is
@example
-
\transpose @var{pitch} @var{musicexpr}
@end example
will print flats.
@quotation
-
@lilypond[fragment,verbatim]
\context Staff {
\clef "F";
you must use @code{\transpose} first. @code{\relative} will have no
effect music that appears inside a @code{\transpose}.
-
-
+@unnumberedsubsec Adding melodies to lyrics
@cindex automatic lyric durations
+@cindex @code{\addlyrics}
-If you have lyrics that are set to a melody, you can import the
-rhythm of that melody into the lyrics using @code{\addlyrics}.
-@keyindex{addlyrics} The syntax for this is
-
+If you have lyrics that are set to a melody, you can import the rhythm
+of that melody into the lyrics using @code{\addlyrics}. The syntax for
+this is
@example
-
\addlyrics @var{musicexpr1 musicexpr2}
@end example
interpreted, but that every non-command atomic music expression
(``every syllable'') in @var{musicexpr2} is interpreted using timing
of @var{musicexpr1}.
+@cindex @code{automaticMelismata}
-If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the
+If the property @code{automaticMelismata} is set in the
context of @var{musicexpr1}, no lyrics will be put on slurred or tied
notes.
@quotation
-
@lilypond[verbatim,fragment]
\addlyrics
\transpose c'' {
}
\context Lyrics \lyrics {
do4 re mi fa }
-
@end lilypond
@end quotation
undesired effects when using multiple stanzas:
@quotation
-
@lilypond[verbatim,fragment]
\addlyrics
\transpose c'' {
It is valid (but probably not very useful) to use notes instead of
lyrics for @var{musicexpr2}.
+@node Transforming music
+@unnumberedsubsec Apply
+@unnumberedsubsec Transforming music
+
+Apply allows a Scheme-function to operate directly on the internal
+representation of music.
+@example
+ \apply #@var{func} @var{music}
+@end example
+The function takes two arguments, being a function and an musical
+argument for that function. The function should return a music
+expression.
+
+This example replaces the text string of a script. It also shows a dump
+of the music it processes.
+@lilypond[verbatim]
+#(define (testfunc x)
+ (if (eq? (ly-get-mus-property x 'text) "foo")
+ (ly-set-mus-property x 'text "bar"))
+ ;; recurse
+ (ly-set-mus-property x 'elements
+ (map testfunc (ly-get-mus-property x 'elements)))
+ (display x)
+ x
+)
+\score { \notes
+ \apply #testfunc { c4_"foo" }
+}
+@end lilypond
+For more information on what is possible, see the @ref{Tricks} and the
+automatically generated documentation.
@node Ambiguities
@section Ambiguities
-
@cindex ambiguities
+@cindex grammar
+
-The grammar contains a number of ambiguities.@footnote{The authors
-hope to resolve them at a later time.}
+The grammar contains a number of ambiguities. We hope to resolve them at
+some time.
@itemize @bullet
@item The assignment
-@node Notation conversion specifics
-@section Notation conversion specifics
-
-
@node Automatic Beaming
@section Automatic Beaming
@cindex automatic beam generation
@cindex autobeam
-@c beamAuto vs autoBeam ?
+@cindex @code{Voice.noAutoBeaming}
By default, LilyPond will generate beams automatically. This feature
-can be disabled by setting the
-@code{Voice.beamAuto}@indexcode{Voice.beamAuto} property to false.
-It can be overridden for specific cases by specifying explicit beams.
+can be disabled by setting the @code{Voice.noAutoBeaming} property to
+true. It can be overridden for specific cases by specifying explicit
+beams.
+@cindex @code{Voice.autoBeamSettings}
+@cindex @code{(end * * * *)}
+@cindex @code{(begin * * * *)}
A large number of Voice properties are used to decide how to generate
beams. Their default values appear in @file{scm/auto-beam.scm}. In
general, beams can begin anywhere, but their ending location is
significant. Beams can end on a beat, or at durations specified by the
properties in
-@code{Voice.autoBeamSettings}@indexcode{Voice.autoBeamSettings}.
+@code{Voice.autoBeamSettings}.
To end beams every quarter note, for example, you could set the property
-@code{(end * * * *)} @indexcode{(end * * * *)} to `@code{(make-moment 1
-4)}'. To end beams at every three eighth notes you would set
-it to `@code{(make-moment 1 8)}'.
+@code{(end * * * *)} to @code{(make-moment 1
+4)}. To end beams at every three eighth notes you would set
+it to @code{(make-moment 1 8)}.
The same syntax can be used to specify beam
starting points using
-@code{(begin * * * *)}@indexcode{(begin * * * *)}, eg:
+@code{(begin * * * *)}, eg:
@quotation
@example
\property Voice.autoBeamSettings \override
you would use @code{(end * * 1 32)}.
-@node Chord Names
-@section Chord Names
+@node Printing named chords
+@section Printing named chords
@cindex chord names
@cindex chords
@cindex printing!chord names
+@cindex @code{ChordNames}
+@cindex @code{ChordNameVoice}
-For displaying printed chord names, use the
-@code{ChordNames}@indexcode{ChordNames} and
-@code{ChordNameVoice}@indexcode{ChordNameVoice} contexts. The chords
-may be entered either using the notation described above, or directly
-using simultaneous music.
+For displaying printed chord names, use the @code{ChordNames} and
+@code{ChordNameVoice} contexts. The chords may be entered either using
+the notation described above, or directly using simultaneous music.
@quotation
@lilypond[verbatim]
@end lilypond
@end quotation
-
You can make the chord changes stand out more by setting property
-@code{ChordNames.chordChanges} to true. This will only display
-chord names when there's a change in the chords scheme, but always
-display the chord name after a line break:
+@code{ChordNames.chordChanges} to true. This will only display chord
+names when there's a change in the chords scheme, but always display the
+chord name after a line break:
@c bug
@quotation
@end lilypond
@end quotation
-The chord names that LilyPond should print are fully customisable. The
-default code can be found in @file{scm/chord-name.scm}. Chord names are
-based on Banter style naming, which is unambiguous and has a logical
-structure. Typical American style chord names are implemented as a
-variation on Banter names, they can be selected by setting property
-@code{ChordName.style} to @code{american}:
+The chord names that LilyPond should print are fully customizable. The
+code to print chord names is written in Scheme. It can be found in
+@file{scm/chord-name.scm}. Chord names are based on Banter style
+naming, which is unambiguous and has a logical structure. Typical
+American style chord names are implemented as a variation on Banter
+names, they can be selected by setting property @code{ChordName.style}
+to @code{american}:
@quotation
@lilypond[verbatim]
@end quotation
-@node lyricprint
+@node Printing lyrics
@section lyricprint
@cindex lyrics
@end quotation
You may want a continuous line after the syllables to show melismata.
-To achieve this effect, add a `@code{__}' lyric as a separate word
+To achieve this effect, add a @code{__} lyric as a separate word
after the lyric to be extended. This will create an extender, a line
that extends over the entire duration of the lyric. This line will
run all the way to the start of the next lyric, so you may want to
-shorten it by using a blank lyric (using `@code{_}').
+shorten it by using a blank lyric (using @code{_}).
@quotation
these can all contain multiple staffs).
Contexts associated with sheet music output are called @emph{notation
-contexts}, those for sound output are called playing contexts.
+contexts}, those for sound output are called performance contexts.
-Contexts are created either manually or automatically. Initially,
-the top level music expression is interpreted by the top level
-context (the @code{Score} context). When a atomic music expression
-(i.e. a note, a rest, @code{\bar}, or @code{\time} commands), a nested
-set of contexts is created that can process these atomic expressions,
-as in this example:
+Contexts are created either manually or automatically. Initially, the
+top level music expression is interpreted by the top level context (the
+@code{Score} context). When a atomic music expression (i.e. a note, a
+rest, etc.), a nested set of contexts is created that can process these
+atomic expressions, as in this example:
@example
-
- @example
-\score @{ \notes < c4 > @}
+\score @{ \notes @{ c4 @} @}
@end example
-@end example
-
The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
-context. When the note `@code{c4}' itself is interpreted, a set of
+context. When the note @code{c4} itself is interpreted, a set of
contexts is needed that will accept notes. The default for this is a
@code{Voice} context, contained in a @code{Staff} context. Creation of
these contexts results in the staff being printed.
-
@cindex context
You can also create contexts manually, and you probably have to do so
interpreted with a context of type @var{name}. If you specify a name,
the specific context with that name is searched.
+[type vs id]
+
If a context of the specified type and name can not be found, a new
one is created. For example,
In this example, the @code{c} and @code{d} are printed on the
default staff. For the @code{e}, a context Staff called
-`@code{another}' is specified; since that does not exist, a new
+@code{another} is specified; since that does not exist, a new
context is created. Within @code{another}, a (default) Voice context
is created for the @code{e4}. When all music referring to a
context is finished, the context is ended as well. So after the
@item
-
- A margin shape declaration. The syntax is
-
+
+ A margin shape declaration. The syntax is
+@cindex @code{\shape}
@example
\shape @var{indent1}@code{,} @var{width1}@code{,}
@var{indent2}@code{,} @var{width2} @dots{} @code{;}
- @end example
+ @end example
- @keyindex{shape}
+
Each pair of @var{indent} and @var{width} values is a dimension
specifying how far to indent and how wide to make the line.
@item \stylesheet declaration. Its syntax is
@example
- \stylesheet @var{alist}
+ \stylesheet @var{alist}
@end example
- See @file{font.scm} for details of @var{alist}.
+ See @file{font.scm} for details of @var{alist}.
@end itemize
The paper block has some variables you may want to use or change:
-@table @samp
- @item @code{indent}@indexcode{indent}
+@table @code
+@cindex @code{indent}
+ @item @code{indent}
The indentation of the first line of music.
+@cindex @code{staffspace}
- @item @code{staffspace}@indexcode{staffspace}
+ @item @code{staffspace}
The distance between two staff lines, calculated from the center
of the lines. You should use either this or @code{rulethickness}
as a unit for distances you modify.
- @item @code{linewidth}@indexcode{linewidth}
+@cindex @code{linewidth}
+ @item @code{linewidth}
Sets the width of the lines. If set to -1.0, a single
unjustified line is produced. If you use this variable, you
probably want to define it in staff spaces, ie
@example
linewidth = 30 * \staffspace;
@end example
+@cindex @code{textheight}
- @item @code{textheight}@indexcode{textheight}
+ @item @code{textheight}
Sets the total height of the music on each page. Only used by
ly2dvi.
+@cindex @code{interscoreline}
- @item @code{interscoreline}@indexcode{interscoreline}
+ @item @code{interscoreline}
Sets the spacing between the score lines. Defaults to 16 pt.
+@cindex @code{interscorelinefill}
- @item @code{interscorelinefill}@indexcode{interscorelinefill}
+ @item @code{interscorelinefill}
If set to a positive number, the distance between the score
lines will stretch in order to fill the full page. In that
case @code{interscoreline} specifies the minimum spacing.
Defaults to 0.
+@cindex @code{stafflinethickness}
- @item @code{stafflinethickness}@indexcode{stafflinethickness}
+ @item @code{stafflinethickness}
Determines the thickness of staff lines, and also acts as a scaling
parameter for other line thicknesses.
@end table
you want to have a line break where there is no barline, you can force a
barline by entering @code{\bar "";}.
+
@subsection Page breaks
Page breaks are normally computed by @TeX{}, so they are not under direct
@subsection Font size
@cindex font size
-@cindex paper size
The Feta font provides musical symbols at six different sizes. These
fonts are 11 point, 13 point, 16 point, 20 point,
The font definitions are generated using a Scheme function. For more
details, see the file @file{font.scm}.
-@subsection paper size
+@subsection Paper size
@cindex paper size
@cindex page size
+@cindex @code{papersize}
To change the paper size, you must first set the
-@code{papersize}@indexcode{papersize} variable at top level. Set it to
+@code{papersize} variable at top level. Set it to
the strings @code{a4}, @code{letter}, or @code{legal}. After this
specification, you must set the font as described above. If you want
the default font, then use the 20 point font. The new paper size will
will set the paper variables @code{hsize} and @code{vsize} (used by
@code{ly2dvi})
-@node contextdefs
-@section contextdefs
+@node Context definitions
+@section Context definitions
@cindex context definition
@cindex translator definition
A notation contexts is defined by the following information
-@enumerate i
+@enumerate 1
@item A name.
@item The LilyPond modules that do the actual conversion of music to
@var{typename} is one of
-@table @samp
- @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver}
+@table @code
+@cindex @code{Engraver_group_engraver}
+ @item @code{Engraver_group_engraver}
The standard cooperation engraver.
+@cindex @code{Score_engraver}
- @item @code{Score_engraver}@indexcode{Score_engraver}
+ @item @code{Score_engraver}
This is cooperation module that should be in the top level context.
+@cindex @code{Grace_engraver_group}
- @item @code{Grace_engraver_group}@indexcode{Grace_engraver_group}
+ @item @code{Grace_engraver_group}
This is a special cooperation module (resembling
@code{Score_engraver}) that is used to created an embedded
`miniscore'.
Some pre-defined identifiers can simplify modification of
translators. The pre-defined identifiers are:
-@table @samp
- @item @code{StaffContext}@indexcode{StaffContext}
+@table @code
+@cindex @code{StaffContext}
+ @item @code{StaffContext}
Default Staff context.
+@cindex @code{RhythmicStaffContext}
- @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext}
+ @item @code{RhythmicStaffContext}
Default RhythmicStaff context.
+@cindex @code{VoiceContext}
- @item @code{VoiceContext}@indexcode{VoiceContext}
+ @item @code{VoiceContext}
Default Voice context.
+@cindex @code{ScoreContext}
- @item @code{ScoreContext}@indexcode{ScoreContext}
+ @item @code{ScoreContext}
Default Score context.
+@cindex @code{ScoreWithNumbers}
- @item @code{ScoreWithNumbers}@indexcode{ScoreWithNumbers}
+ @item @code{ScoreWithNumbers}
Score context with numbering at the Score level.
+@cindex @code{BarNumberingStaffContext}
- @item @code{BarNumberingStaffContext}@indexcode{BarNumberingStaffContext}
+ @item @code{BarNumberingStaffContext}
Staff context with numbering at the Staff level.
+@cindex @code{HaraKiriStaffContext}
- @item @code{HaraKiriStaffContext}@indexcode{HaraKiriStaffContext}
+ @item @code{HaraKiriStaffContext}
Staff context that does not print if it only contains rests.
Useful for orchestral scores.@footnote{Harakiri, also called
- Seppuku, is the ritual suicide of the Samourai.}
+ Seppuku, is the ritual suicide of the Japanese Samourai warriors.}
+@cindex @code{OrchestralPartStaffContext}
- @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext}
+ @item @code{OrchestralPartStaffContext}
+@cindex @code{OrchestralScoreContext}
- @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext}
+ @item @code{OrchestralScoreContext}
@end table
Using these pre-defined values, you can remove or add items to the
-@cindex MIDI instrument names
-
@node midilist
-@section midilist
+@section MIDI instrument names
+@cindex instrument names
+@cindex @code{Staff.midiInstrument}
+@cindex @code{Staff.instrument}
+
+The MIDI instrument name is set by the @code{Staff.midiInstrument}
+property or, if that property is not set, the @code{Staff.instrument}
+property. The instrument name should be chosen from the following list.
+If the selected string does not exactly match, then LilyPond uses the
+default piano.
-The MIDI instrument name is set by the
-@code{Staff.midiInstrument}@indexcode{Staff.midiInstrument} property or,
-if that property is not set, the
-@code{Staff.instrument}@indexcode{Staff.instrument} property. The
-instrument name should be chosen from the following list. If the
-selected string does not exactly match, then LilyPond uses the default
-piano.
+[FIXME: to appendix ]
@c @quotation
provide shorthands for some settings. Most of them are in
@file{ly/declarations.ly} and @file{ly/property.ly}.
-@table @samp
- @item @code{\break}@keyindex{break}
+@table @code
+@cindex @code{\break}
+ @item @code{\break}
Force a line break in music by using a large argument for the
keyword @code{\penalty}.
- @item @code{\nobreak}@keyindex{nobreak}
+@cindex @code{\nobreak}
+ @item @code{\nobreak}
Prevent a line break in music by using a large negative argument
for the keyword @code{\penalty}.
- @item @code{\shiftOff}@keyindex{shiftOff}
+@cindex @code{\shiftOff}
+ @item @code{\shiftOff}
Disable horizontal shifting of note heads that collide.
- @item @code{\shiftOn}@keyindex{shiftOn}
+@cindex @code{\shiftOn}
+ @item @code{\shiftOn}
Enable note heads that collide with other note heads to be
shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
set different shift values.
- @item @code{\stemBoth}@keyindex{stemBoth}
+@cindex @code{\stemBoth}
+ @item @code{\stemBoth}
Allow stems, beams, and slurs to point either upwards or
downwards, decided automatically by LilyPond.
- @item @code{\stemDown}@keyindex{stemDown}
+@cindex @code{\stemDown}
+ @item @code{\stemDown}
Force stems, beams, and slurs to point down.
- @item @code{\stemUp}@keyindex{stemUp}
+@cindex @code{\stemUp}
+ @item @code{\stemUp}
Force stems, beams and slurs to point up.
@end table
+
+
@node Point and click
@section Point and click
[todo]
+
+
--- /dev/null
+@c -*-texinfo-*-
+@ignore
+
+TODO
+ * move some stuff to refman
+ * merge some stuff with refman entries
+
+ * add @ref{}s to lilypond-internals:
+ @rgrob{Name} to grob
+ @reng{Name} to engraver
+
+ there's a very simple, very general noXXX mechanism; try
+
+noop \property Staff.VoltaBrace = #'()
+yes: \property Staff.VoltaBracket = #'((meta . ((interfaces . ()))))
+
+
+ visibility?
+ brew_molecule?
+@end ignore
+
+
+@node Tricks
+@chapter Tricks
+
+@menu
+* Manual beam settings:: Manual beam settings
+* Slur attachments:: Slur attachments
+* Text spanner:: Text spanner
+* Engraver hacking:: Engraver hacking
+* Part combiner:: Part combiner
+* Markup text:: Markup text
+* Apply hacking:: Apply hacking
+* Output property:: Output property
+* Embedded TeX:: Embedded TeX
+* Embedded PostScript:: Embedded PostScript
+@c * Index:: Checking Feature index
+@end menu
+
+
+@node Manual beam settings
+@section Manual beam settings
+@cindex beams
+@cindex beam settings
+@cindex manual beams
+
+
+@c auto knees
+
+
+
+
+
+@cindex @code{]}
+
+In some cases it may be necessary to override LilyPond's automatic
+beaming algorithm. For example, the auto beamer will not beam over
+rests, so if you want that, specify the begin and end point manually
+using @code{[} and @code{]}:
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \context Staff {
+ r4 [r8 g'' a]
+ }
+@end lilypond
+@end quotation
+
+Similarly, for beams over bar lines:
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \context Staff {
+ a''8 r a2 r8 [a a]
+ }
+@end lilypond
+@end quotation
+@cindex @code{stemLeftBeamCount}
+
+If you have specific wishes for the number of beams, you can fully
+control the number of beams through the properties
+@code{Voice.stemLeftBeamCount};
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \context Staff {
+ [f'8 r16 f g a]
+ [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
+ }
+@end lilypond
+@end quotation
+@cindex @code{stemRightBeamCount}
+
+and @code{Voice.stemRightBeamCount}:
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ f'32 g a b b a g f
+
+ \property Voice.autoBeamSettings
+ \set #'(end * * * *) = #(make-moment 1 4)
+ f32 g a b b a g f
+
+ f32 g a
+ \property Voice.stemRightBeamCount = #1 b
+ \property Voice.stemLeftBeamCount = #1 b
+ a g f
+@end lilypond
+@end quotation
+@cindex @code{no-stem-extend}
+
+Conventionally, stems and beams extend to the middle staff line. This
+extension can be controlled through @code{Voice.Stem}'s grob-property
+@code{no-stem-extend}:
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \grace a'8 a4
+ \property Voice.Stem \set #'no-stem-extend = ##t
+ \grace g8 g4 [g8 g]
+@end lilypond
+@end quotation
+
+The beam symbol can be tweaked through @code{Voice.Beam}'s
+grob-properties @code{height-hs} and @code{y-position-hs}.
+
+Set @code{height-hs} to zero, to get horizontal beams:
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \property Voice.Beam \set #'direction = #1
+ \property Voice.Beam \set #'height-hs = #0
+ [a''8 e' d c]
+@end lilypond
+@end quotation
+
+Both are in half spaces. Here's how you'd specify a weird looking beam
+that instead of being horizontal, falls two staff spaces (ie, four half
+spaces):
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \property Voice.Beam \set #'y-position-hs = #4
+ \property Voice.Beam \set #'height-hs = #-4
+ [c'8 c]
+@end lilypond
+@end quotation
+@cindex @code{default-neutral-direction}
+
+The direction of a perfectly centred beams can be
+controlled through @code{Voice.Beam}'s grob-property
+@code{default-neutral-direction}
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ [b''8 b]
+ \property Voice.Beam \set #'default-neutral-direction = #-1
+ [b b]
+@end lilypond
+@end quotation
+
+There are several ways to calculate the direction of a beam.
+@table @code
+@item majority
+number count of up or down notes
+@item mean
+mean center distance of all notes
+@item median
+mean centre distance weighted per note
+@end table
+
+You can spot the differences of these settings from these simple
+examples:
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ [d''8 a]
+ \property Voice.Beam \set #'dir-function = #beam-dir-mean
+ [d a]
+ \property Voice.Beam \set #'dir-function = #beam-dir-median
+ [d a]
+@end lilypond
+@end quotation
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \time 3/8;
+ [d''8 a a]
+ \property Voice.Beam \set #'dir-function = #beam-dir-mean
+ [d a a]
+ \property Voice.Beam \set #'dir-function = #beam-dir-median
+ [d a a]
+@end lilypond
+@end quotation
+
+These beam direction functions are defined in @file{scm/beam.scm}. If
+your favourite algorithm isn't one of these, you can hook up your own.
+
+
+
+@node Slur attachments
+@section Slur attachments
+
+The ending of a slur should whenever possible be attached to a note
+head. Only in some instances where beams are involved, LilyPond may
+attach a slur to a stem end. In some cases, you may want to override
+LilyPond's decision, e.g., to attach the slur to the stem end. This can
+be done through @code{Voice.Slur}'s grob-property @code{attachment}:
+@c FIXME: make @ref{} to backend doco
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \property Voice.Slur \set #'direction = #1
+ \property Voice.Stem \set #'length = #5.5
+ g''8(g)g4
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+ g8(g)g4
+@end lilypond
+@end quotation
+
+Similarly, slurs can be attached to note heads even when beams are
+involved:
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \property Voice.Slur \set #'direction = #1
+ \property Voice.Slur \set #'attachment = #'(head . head)
+ g''16()g()g()g()d'()d()d()d
+@end lilypond
+@end quotation
+
+If a slur would strike through a stem or beam, LilyPond will move the
+slur away vertically (upward or downward). In some cases, this may
+cause ugly slurs that you may want to correct:
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \property Voice.Stem \set #'direction = #1
+ \property Voice.Slur \set #'direction = #1
+ d'32( d'4 )d8..
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+ d,32( d'4 )d8..
+@end lilypond
+@end quotation
+
+LilyPond will increase the curvature of a slur trying to stay free of
+note heads and stems. However, if the curvature would increase too much,
+the slur will be reverted to its default shape. This decision is based
+on @code{Voice.Slur}'s grob-property @code{beautiful} value. In some
+cases, you may find ugly slurs beautiful, and tell LilyPond so by
+increasing the @code{beautiful} value:
+
+[hoe gedefd?? wat betekent beautiful = X?]
+
+@quotation
+@lilypond[verbatim]
+\score {
+ \notes \context PianoStaff <
+ \time 6/4;
+ \context Staff=up { s1 * 6/4 }
+ \context Staff=down <
+ \clef bass;
+ \autochange Staff \context Voice
+ \notes \relative c {
+ d,8( a' d f a d f d a f d )a
+ }
+ >
+ >
+ \paper {
+ linewidth = -1.;
+ \translator {
+ \VoiceContext
+ Slur \override #'beautiful = #5.0
+ Slur \override #'direction = #1
+ Stem \override #'direction = #-1
+ autoBeamSettings \override #'(end * * * *)
+ = #(make-moment 1 2)
+ }
+ \translator {
+ \PianoStaffContext
+ VerticalAlignment \override #'threshold = #'(5 . 5)
+ }
+ }
+}
+@end lilypond
+@end quotation
+
+
+@node Text spanner
+@section Text spanner
+
+
+
+Have crescendo set a text spanner instead of hairpin
+
+@lilypond[fragment,relative,verbatim]
+ \context Voice {
+ \property Voice.crescendoText = "cresc."
+ \property Voice.crescendoSpanner = #'dashed-line
+ a''2\mf\< a a \!a
+ }
+@end lilypond
+
+@subsection Ottava
+
+@lilypond[fragment,relative,verbatim]
+ a'''' b c a
+ \property Voice.TextSpanner \set #'type = #'dotted-line
+ \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
+ \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
+ \property Staff.centralCPosition = #-13
+ a\spanrequest \start "text" b c a \spanrequest \stop "text"
+@end lilypond
+
+
+
+@node Engraver hacking
+@section Engraver hacking
+
+No time signature, no barlines...
+@lilypond[verbatim]
+\score {
+ \notes \relative c'' {
+ a b c d
+ d c b a
+ }
+ \paper {
+ linewidth = -1.;
+ \translator {
+ \StaffContext
+ whichBar = #""
+ \remove "Time_signature_engraver";
+ }
+ }
+}
+@end lilypond
+
+No staff, no clef, squash pitches
+@lilypond[verbatim]
+\score {
+ \notes { c4 c4 c8 c8 }
+ \paper {
+ linewidth = -1.;
+ \translator {
+ \StaffContext
+ \remove Staff_symbol_engraver;
+ \consists Pitch_squash_engraver;
+ \remove Clef_engraver;
+ }
+ }
+}
+@end lilypond
+
+
+@node Part combiner
+@section Part combiner
+
+@lilypond[verbatim]
+\score{
+ \context Staff = flauti <
+ \time 4/4;
+ \context Voice=one \partcombine Voice
+ \context Thread=one \notes\relative c'' {
+ c4 d e f | b,4 d c d | r2 e4 f | c4 d e f |
+ c4 r e f | c4 r e f | c4 r a r | a a r a |
+ a2 \property Voice.soloADue = ##f a |
+ }
+ \context Thread=two \notes\relative c'' {
+ g4 b d f | r2 c4 d | a c c d | a4. b8 c4 d
+ c r e r | r2 s2 | a,4 r a r | a r r a |
+ a2 \property Voice.soloADue = ##f a |
+ }
+ >
+ \paper{
+ linewidth = 80 * \staffspace;
+ \translator{
+ \ThreadContext
+ \consists Rest_engraver;
+ }
+ \translator{
+ \VoiceContext
+ \remove Rest_engraver;
+ }
+ }
+}
+@end lilypond
+
+
+
+
+@node Markup text
+@section Markup text
+
+Metrome hack...
+
+[todo: hack this into C++, use \tempo]
+
+@lilypond[verbatim]
+#(define note '(rows (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
+#(define eight-note `(rows ,note ((kern . -0.1) (music ((raise . 3.5) "flags-u3")))))
+#(define dotted-eight-note `(rows ,eight-note (music "dots-dot")))
+
+\score {
+ \notes\relative c'' {
+ a1^#`(rows ,dotted-eight-note " = 64")
+ }
+ \paper {
+ linewidth = -1.;
+ \translator{
+ \ScoreContext
+ TextScript \override #'font-shape = #'upright
+ }
+ }
+}
+@end lilypond
+
+
+@node Output property
+@section Output property
+
+@lilypond[fragment,relative,verbatim]
+ \outputproperty #(make-type-checker 'note-head-interface)
+ #'extra-offset = #'(2 . 3)
+ c''2 c
+@end lilypond
+
+Don't move the finger 2, only text "m.d." ...
+@lilypond[verbatim]
+#(define (make-text-checker text)
+ (lambda (grob) (equal? text (ly-get-elt-property grob 'text))))
+
+\score {
+ \notes\relative c''' {
+ \property Voice.Stem \set #'direction = #1
+ \outputproperty #(make-text-checker "m.d.")
+ #'extra-offset = #'(-3.5 . -4.5)
+ a^2^"m.d."
+ }
+ \paper { linewidth = -1.; }
+}
+@end lilypond
+
+
+@c equalizer
+
+
+@node Apply hacking
+@section Apply hacking
+
+@lilypond[verbatim]
+music = \notes { c'4 d'4( e'4 f'4 }
+
+#(define (reverse-music music)
+ (let* ((elements (ly-get-mus-property music 'elements))
+ (reversed (reverse elements))
+ (span-dir (ly-get-mus-property music 'span-direction)))
+
+ (ly-set-mus-property music 'elements reversed)
+
+ (if (dir? span-dir)
+ (ly-set-mus-property music 'span-direction (- span-dir)))
+
+ (map reverse-music reversed)
+
+ music))
+
+\score {
+ \context Voice {
+ \music
+ \apply #reverse-music \music
+ }
+ \paper { linewidth = -1.; }
+}
+@end lilypond
+
+@node Embedded TeX
+@section Embedded TeX
+@lilypond[fragment,relative,verbatim]
+ a''^"3 $\\times$ \\`a deux"
+@end lilypond
+
+@node Embedded PostScript
+@section Embedded PostScript
+
+Arbitrary lines and curves not supported...
+
+[TODO:] Make a direct postscript command?
+
+@lilypond[verbatim]
+\score {
+ \notes \relative c'' {
+ a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
+ -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
+ b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
+ s2
+ a'1
+ }
+ \paper { linewidth = 70 * \staffspace; }
+}
+@end lilypond
+
+@ignore
+@node Index
+@section Checking Feature index
+
+@printindex cp
+
+
+@bye
+@end ignore
+
+
@menu
* Introduction:: Introduction
+* Running LilyPond:: Getting started
* The first tune:: The first tune
* Lyrics and chords:: Lyrics and chords
* More movements:: More than one movement in a file
LilyPond prints music from a specification that you, the user, supply.
You have to give that specification using a @emph{language}. This
-document is a gentle introduction to that language, which is called
-Lilypond, an acronym of Music Definition Language.
+chapter is a gentle introduction to that language.
This tutorial will demonstrate how to use Lilypond by presenting
examples of input along with resulting output. We will use English
terms for notation. In case you are not familiar with those, you may
consult the glossary that is distributed with LilyPond.
+@cindex examples, tutorial
+
The examples discussed are included in the distribution, in the
-subdirectory @file{input/tutorial/}. It is recommended that you
-experiment with writing Lilypond input yourself, to get a feel for
-how LilyPond behaves.
+subdirectory @file{input/tutorial/}.@footnote{When we refer
+to filenames, they are relative to the top directory of the source
+package.
+@cindex file names
+} We recommend that you experiment with writing Lilypond input yourself,
+to get a feel for how the program behaves.
+
+
+@node Running LilyPond
+@section Running LilyPond
+
+Before we dive into describing the input language of LilyPond, we first
+show you through the procedure for getting notes on your screen and out
+of your printer.
+
+The first step is creating an input file. Using your favorite
+text-editor, create @file{test.ly} containing
+
+@example
+\header @{
+ title = "Test";
+@}
+
+\score @{
+ \notes @{ c'4 e'4 g'4 @}
+ \paper @{ @}
+@}
+@end example
+
+@unnumberedsubsec Unix
+
+@cindex Unix, Running lilypond on
+
+If you run Unix, proceed as follows: run lilypond on the file, i.e.,
+@example
+ lilypond test
+@end example
+You will the following on your screen:
+@example
+GNU LilyPond 1.3.125.
+Now processing: `input/tutorial/test.ly'
+Parsing...
+Interpreting music...[1]
+Preprocessing elements...
+Calculating column positions... [2]
+paper output to test.tex...
+@end example
+
+Now, run @TeX{}@footnote{@TeX{} is a text-typesetting system that is
+especially suited for typesetting mathematics}. The result should
+resemble this:
+@example
+This is TeX, Version 3.14159 (Web2C 7.3.1)
+(test.tex (/home/hanwen/usr/share/lilypond/tex/lilyponddefs.tex
+(/home/hanwen/usr/share/lilypond/tex/lilypond-plaintex.tex
+LilyPond Plain TeX settings) (/home/hanwen/usr/src/ ...
+(/home/hanwen/usr/share/lilypond/tex/lily-ps-defs.tex) [footer empty]
+(/home/hanwen/usr/share/lilypond/tex/fetdefs.tex)) [1] )
+Output written on test.dvi (1 page, 3716 bytes).
+Transcript written on test.log.
+@end example
+The result of the @TeX{} run is a @TeX{} ``DeVice Independent'' file
+(@file{test.dvi}).
+@cindex DVI file
+@cindex @TeX{}
+
+@cindex Viewing music
+@cindex @code{xdvi}
+To view the output, run Xdvi, i.e.
+@example
+ xdvi test
+@end example
+You should will see this
+@lilypond
+\header {
+ title = "Test";
+}
+
+\score {
+ \notes { c'4 e'4 g'4 }
+ \paper { }
+}
+@end lilypond
+along with some buttons in a window.
+
+@cindex postscript, converting to
+When you're satisfied with the result, you can print it. For printing,
+you have to generate a postscript file:
+@example
+ dvips -o test.ps test.dvi
+@end example
+which looks like this:
+@example
+This is dvips(k) 5.86 Copyright 1999 Radical Eye Soft ...
+' TeX output 2001.01.27:1806' -> test.ps
+<texc.pro><special.pro>. [1]
+@end example
+
+@cindex PostScript
+@cindex Printing output
+@cindex GhostScript
+@cindex @code{lpr}
+PostScript is a page description language, similar to PDF. Some printers
+can understand a postscript file directly, but the cheapers need the
+intervention of GhostScript, a PostScript emulator that runs on your
+computer instead of your printer. Most Linux distributions nowadays have
+GhostScript running ``in the background'', so any configured printer
+will act as a PostScript printer. Assuming this, the
+following command will print the file
+@example
+ lpr test.ps
+@end example
+If this does not make your printer produce a page of music, then you
+should look into installing and configuring ghostscript. Refer to
+GhostScript's website at @uref{http://www.ghostscript.com}.
+
+There are two different routes: firstly, you can add titling to the
+output. This is done by a separate program called ly2dvi: this program
+first calls LilyPond to process the @file{.ly} file, and then runs
+@TeX{} on it to produce a @file{.dvi} file with proper margin settings
+and titling.
+
+@cindex titles, adding
+@cindex ly2dvi
+
+@example
+ ly2dvi test.ly
+@end example
+After some disk-activity, you should end up with a @file{.dvi} file.
+6
+Secondly, you can generate PostScript directly. This is not very useful
+currently, but here goes:
+@cindex PostScript output
+@example
+ lilypond -f ps test.ly
+@end example
+
+[treat FAQs here, eg. about env vars.]
+
+
+@unnumberedsubsec Windows
+
+[todo]
+
@node The first tune
@section The first tune
To demonstrate what LilyPond input looks like, we start off with a
-full fledged, yet simple example. It is a convoluted version
-of the famous menuet in J. S. Bach's @emph{Klavierbuechlein}.
+full-fledged, yet simple example. It is a convoluted version
+of the famous menuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
+is included in the distribution as @file{menuet.ly}.
+@cindex Bach, Johann Sebastian
@lilypond[verbatim]
% lines preceded by a percent are comments which
}
@end lilypond
-Enter it (or copy it, the filename is @file{menuet.ly}), compile it
-with LilyPond and view the output. Details of this procedure may vary
-from system to system. To create the output, one would issue the
-command `@code{ly2dvi menuet}'. @file{ly2dvi} is a program that does
-the job of running LilyPond and @TeX{}, handling of titles and
-adjusting of page margins.
-
-If all goes well, the file @file{menuet.dvi} will be created.
-To view this output, issue the command `@code{xdvi menuet}'.
-
-Now that we are familiar with the procedure of producing output, we
-will analyse the input, line by line.
+We will analyse the input, line by line.
@example
- % lines preceded by a percent are comments which
- % are ignored by Lilypond.
+ % lines preceded by a percent are comments which
+ % are ignored by Lilypond.
@end example
-The percent sign, `@code{%}', introduces a line comment. If you want to
+The percent sign, @code{%}, introduces a line comment. If you want to
make larger comments, you can use block comments. These are delimited
-by `@code{%@{}' and `@code{%@}}'
+by @code{%@{} and @code{%@}}
+@cindex comment
+@cindex block comment
+@cindex line comment
+
@example
- \input "paper16.ly"
+ \include "paper16.ly"
-@end example
-By default, LilyPond will use definitions for a 20
-point@footnote{A point is the standard measure of length for
-printing. One point is 1/72.27 inch.} high staff. We want smaller
-output (16 point staff height), so we must import the settings for
-that size, which is done.
+@end example
+@cindex @code{\include}
+@cindex point, printer's
+@cindex staff size setting
+By default, LilyPond will use definitions for a staff that is 20
+point@footnote {A point is the standard measure of length for printing;
+one point is 1/72.27 inch. [TODO: mm vs. pt]} high. We want smaller
+output (16 point staff height), so we must import the settings for that
+size, which is done here.
@example
\score @{
@end example
- A lilypond file combines music with directions for outputting that
+A lilypond file combines music with directions for outputting that
music. The music is combined with the output directions by putting
them into a @code{\score} block.
@example
\relative c''
-@end example
- As we will see, pitches are combinations of octave, note name and
+@end example
+
+@cindex octaves, choosing
+@cindex pitch
+As we will see, pitches are combinations of octave, note name and
chromatic alteration. In this scheme, the octave is indicated by
-using raised quotes (`@code{'}') and ``lowered'' quotes (commas:
-`@code{,}'). The central C is denoted by @code{c'}. The C one octave
+using raised quotes (@code{'}) and ``lowered'' quotes (commas:
+@code{,}). The central C is denoted by @code{c'}. The C one octave
higher is @code{c''}. One and two octaves below the central C is
denoted by @code{c} and @code{c,} respectively.
+@cindex relative
For pitches in a long piece you might have to type many quotes. To
remedy this, LilyPond has a ``relative'' octave entry mode. In this
mode, octaves of notes without quotes are chosen such that a note is
\sequential @{
@end example
- What follows is sequential music, i.e.,
+What follows is sequential music, i.e.,
+@cindex sequential music
notes that are to be played and printed after each other.
@example
\time 3/4;
-@end example
+@end example
+@cindex time signature, setting
+@cindex @code{\time}
This command changes the time signature of the current piece: a 3/4
sign is printed. This command is also used to generate bar lines in
the right spots.
\key g \major;
-@end example
- This command changes the current key to G-major. Although this
+@end example
+@cindex key signature, setting
+@cindex @code{\key}
+ This command changes the current key signature to G-major. Although this
command comes after the @code{\time} command, in the output, the key
signature comes before the time signature: LilyPond knows about music
typesetting conventions.
\repeat "volta" 2
@end example
- This command tells LilyPond that the following piece of music must
-be played twice; @code{"volta"} means that volta brackets should be used
-for alternatives---if there were any.
+ This command tells LilyPond that the following piece of music must be
+played twice. The first argument indicates the type of repeat. In this
+case, @code{"volta"} means that volta brackets are be used for
+alternatives---if there were any.
@example
@{
d4 g, g |
-@end example
- Three more notes. The `@code{|}' character is a `bar check'. When
+@end example
+@cindex bar check
+@cindex @code{|}
+@cindex errors, finding
+ Three more notes. The @code{|} character is a `bar check'. When
processing the music, LilyPond will verify that bar checks are found at
the start of a measure. This can help you track down errors.
- So far, no notes were chromatically altered. Here is the first one
+@cindex alteration, chromatic
+@cindex chromatic alteration
+So far, no notes were chromatically altered. Here is the first one
that is: @code{fis}. Lilypond by default uses Dutch note names, and
``Fis'' is the Dutch note name for ``F sharp''. However, there is no
sharp sign in the output. The program keeps track of key signatures,
c4 d8( )c b a( )b4 c8 b a g |
@end example
- The next line shows how to make a slur:
-the beginning and ending note of the slur is marked with an opening and
-closing parenthesis respectively. In the line shown above, this is
-done for two slurs. Slur markers (parentheses) are put between
-the notes.
+ The next line shows how to make a slur: the beginning and ending note
+of the slur is marked with an opening and closing parenthesis
+respectively. In the line shown above, this is done for two slurs.
+Slur markers (parentheses) are put between the slurred notes.
@example
a4 [b8 a] [g fis]
g2. |
-@end example
+@end example
+@cindex augmentation dot
+@cindex dot
A duration with augmentation dot is notated
with the duration number followed by a period.
@example
a8-. b-. cis-. d-. e-. fis-.
-@end example
+@end example
+@cindex articulation
You can enter articulation signs either in a verbose form using a
shorthand. Here we demonstrate the shorthand: it is formed by a dash
-and the character for the articulation to use, e.g. `@code{-.}' for
+and the character for the articulation to use, e.g. @code{-.} for
staccato as shown above.
@example
@end example
-Rests are denoted by the special notename `@code{r}'. You can also enter
-an invisible rest by using the special notename `@code{s}'.
+Rests are denoted by the special notename @code{r}.
@example
d2.-\fermata
@end example
All articulations have a verbose form, like @code{\fermata}. The
-command `@code{\fermata}' is not part of the core of the language (most
+command @code{\fermata} is not part of the core of the language (most
of the other discussed elements are), but it is a shorthand for a more
complicated description of a fermata. @code{\fermata} names that
-description and is therefore called an @emph{identifier}.
+description and is therefore called an identifier.
+@cindex identifier
+@cindex @code{\fermata}
@example
@}
the details of this conversions (font sizes, dimensions, etc.) have
been taken care of, but to fit the output in this document, it has
to be smaller. We do this by setting the line width to 14 centimeters
-(approximately 6 inches).
+(approximately 5.5 inches).
@example
@}
@end example
The last brace ends the @code{\score} block.
-There are two things to note here. The format contains musical
-concepts like pitches and durations, instead of symbols and positions:
-the input format tries to capture the meaning of @emph{music}, and not
-notation. Second, the format tries to be @emph{context-free}:
-a note will sound the same regardless of the current time signature,
-the key, etc.
-
-The purpose of LilyPond is explained informally by the term `music
-typesetter'. This is not a fully correct name: not only does the
-program print musical symbols, it also makes esthetic decisions. All
-symbols and their placement is @emph{generated} from a high-level musical
-description. In other words, LilyPond would be best
-described by `music compiler' or `music to notation compiler'.
-
@node Lyrics and chords
@section Lyrics and chords
-In this section we show how to typeset a song of unknown
-origin.@footnote{The author would welcome information about the origin
-of this song.}.
+In this section we show how to typeset a song.@footnote{The author would
+welcome information about the origin of this song.}. This file is
+included as @file{flowing.ly}.
@example
\header @{
\include "paper16.ly"
melody = \notes \relative c' @{
\partial 8;
- \key c \minor;
+ \key c \minor;
g8 |
c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
c4 c8 d [es () d] c4 | d4 es8 d c4.
\include "paper16.ly"
melody = \notes \relative c' {
\partial 8;
- \key c \minor;
+ \key c \minor;
g8 |
c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
c4 c8 d [es () d] c4 | d4 es8 d c4.
\header @{
-@end example
+@end example
+@cindex @code{\header}
Information about the music you are about to typeset goes into a
@code{\header} block. The information in this block is not used by
-LilyPond, but it is included in the output. @file{ly2dvi} uses this
+LilyPond, but it is passed into the output. @file{ly2dvi} uses this
information to print titles above the music.
@example
title = "The river is flowing";
composer = "Traditional (?)";
-@end example
+@end example
+@cindex assignments
+@cindex identifier assignment
the @code{\header} block contains assignments. An assignment starts
with a string. (which is unquoted, in this case). Then comes the
-equal sign `@code{=}'. After the equal sign comes the expression you
+equal sign. After the equal sign comes the expression you
want to store. In this case, you want to put in strings. The
information has to be quoted here, because it contains spaces. Each
assignment is finished with a semicolon.
\include "paper16.ly"
-@end example
+@end example
Smaller size for inclusion in a book.
@example
\partial 8;
@end example
+@cindex @code{\partial}
+@cindex anacrusis
The piece starts with an anacrusis of one eighth.
@example
- \key c \minor;
+ \key c \minor;
@end example
The key is C minor: we have three flats.
@end example
+@cindex manual beaming
+@cindex automatic beaming, turning off
We use explicit beaming. Since this is a song, we will turn automatic
beams off, and use explicit beaming where needed.
@example
text = \lyrics @{
-@end example
+@end example
+@cindex lyrics
+@cindex identifier assignment
+@cindex syllables, entering
Another identifier assignment. This one is for the lyrics.
Lyrics are formed by syllables that have duration, and not by
notes. To make LilyPond parse words as syllables, switch it into
ri- ver is flo- __ wing down to the sea.
@}
-@end example
+@end example
+@cindex extenders, lyric
+@cindex hyphens, lyric
The syllables themselves are separated by spaces. You can get syllable
-extenders by entering `@code{__}', and centered hyphens with
+extenders by entering @code{__}, and centered hyphens with
`@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
in length (hence the @code{4}), and use a feature to align the
syllables to the music (which obviously isn't all quarter notes.)
accompaniment =\chords @{
-@end example
-We'll put chords over the music. There is a special mode (analogous
+@end example
+@cindex chords
+@cindex mode, chords
+We'll put chords over the music, to enter them, there is a special mode,
+called @code{\chords}. There is a special mode (analogous
to @code{\lyrics} and @code{\notes} mode) where you can give the names
of the chords you want, instead of the notes comprising the chord.
@example
c2:3- f:3-.7
-@end example
+@end example
+
+@cindex tonic
+@cindex chord modifier
+@cindex modifier, chord
A chord is started by the tonic of the chord. The
first one lasts a half note. An unadorned note creates a major
triad, while a minor triad is wanted. @code{3-} modifies the third to
d:min es4 c8:min r8
-@end example
+@end example
+
Some modifiers have predefined names, eg. @code{min} is the same as
@code{3-}, so @code{d-min} is a minor @code{d} chord.
@example
c2:min f:min7 g:7^3.5 c:min @}
-@end example
+@end example
+@cindex named modifier
+
A named modifier @code{min} and a normal modifier @code{7} do not have
to be separated by a dot. Tones from a chord are removed with chord
subtractions. Subtractions are started with a caret, and they are
We assemble the music in the @code{\score} block. Melody, lyrics and
accompaniment have to sound at the same time, so they should be
@code{\simultaneous}.
+@cindex @code{\simultaneous}
@example
%\accompaniment
\context ChordNames \accompaniment
-@end example
+@end example
+@cindex context
+@cindex interpretation context
+@cindex notation context
Normally, the notes that you enter are transformed into note heads.
The note heads alone make no sense, they need surrounding information:
a key signature, a clef, staff lines, etc. They need @emph{context}. In
removed the @code{%} sign in the previous line, you would see that
mechanism in action.
-We don't want default contexts here, because we want chord names, not
-note heads. An interpretation context can also created upon explicit
-request. The keyword for such a request is @code{\context}. It takes
-two arguments. The first is the name of an interpretation context.
-The name is a string, it can be quoted with double quotes). The
-second argument is the music that should be interpreted in this
-context. For the previous line, we could have written @code{\context
-Staff \accompaniment}, and get the same effect.
+We don't want that default here, because we want chord names, not note heads.
+An interpretation context can also created upon explicit request. The
+keyword for such a request is @code{\context}. It takes two arguments.
+The first is the name of an interpretation context. The name is a
+string, it can be quoted with double quotes). The second argument is
+the music that should be interpreted in this context. For the previous
+line, we could have written @code{\context Staff \accompaniment}, and
+get the same effect.
@example
\addlyrics
-@end example
+@end example
+@cindex @code{\addlyrics}
+@cindex lyrics and melody, combining
+@cindex combining lyrics and melody
+
The lyrics need to be aligned with the melody. This is done by
combining both with @code{\addlyrics}. @code{\addlyrics} takes two
pieces of music (usually a melody and lyrics, in that order) and
\context Staff = mel @{
-@end example
+@end example
+
This is the argument of @code{\addlyrics}. We instantiate a
@code{Staff} context explicitly: should you chose to remove the comment
before the ``note heads'' version of the accompaniment, the
\property Staff.noAutoBeaming = ##t
-@end example
-An interpretation context has variables that tune its behaviour. One
-of the variables is @code{noAutoBeaming}. If set and non-zero (i.e.,
-true) LilyPond will not try to put automatic beaming on the current
-staff.
+@end example
+@cindex \property
+@cindex context variables
+@cindex setting context variables
+An interpretation context has variables that tune its behaviour. One of
+the variables is @code{noAutoBeaming}. If set to @code{##t}, which is
+the boolean value @var{true}, LilyPond will not try to put automatic beaming
+on the current staff.
+
+@cindex GUILE
+@cindex Scheme
+@cindex accessinng Scheme
+@cindex evaluating Scheme
+@cindex LISP
+
+LilyPond internally uses GUILE, a Scheme-interpreter@footnote{Scheme is
+a language from the LISP family. You can learn more about Scheme at
+@uref{http://www.scheme.org}.} to represent data throughout the whole
+program. The hash-sign (@code{#}) accesses GUILE directly: the code
+following the hash-sign is evaluated as Scheme. The boolean value
+@var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
+@code{##t}
+
@example
\property Staff.automaticMelismata = ##t
-@end example
+@end example
+@cindex automaticMelismata
+@cindex melismata
+@cindex @code{\addlyrics} and slurs
Similarly, we don't want to print a syllable when there is
-a slur. This sets up the Staff context to signal slurs while
-@code{\addlyrics} is processed.
+a slur. This sets up @code{\addlyrics} to not put lyrics under notes
+while there is a slur.
@example
\melody
\midi @{ \tempo 4=72;@}
@end example
-This makes the music go to a MIDI file. MIDI is great for
-checking music you enter. You listen to the MIDI file: if you hear
-something unexpected, it's probably a typing error. @code{\midi} is an
-`output definition', a declaration that specifies how to output music
-analogous to @code{\paper @{ @}}. You can specify the tempo using the
-@code{\tempo} command, in this case the tempo of quarter notes is set
-to 72 beats per minute.
+This makes the music go to a MIDI file. MIDI is great for checking
+music you enter. You listen to the MIDI file: if you hear something
+unexpected, it's probably a typing error. @code{\midi} starts an output
+definition, a declaration that specifies how to output music analogous
+to @code{\paper @{ @}}. You can specify the tempo using the
+@code{\tempo} command, in this case the tempo of quarter notes is set to
+72 beats per minute.
@example
\paper @{ linewidth = 10.0\cm; @}
You probably ran @file{ly2dvi} on the last example, and ended up with a
viewable @file{.dvi} file. However, between there are a few steps of
which LilyPond is only one. To enhance your understanding of what's
-happening under the hood when you run ly2dvi, we explain what programs
-are run.
+happening under the hood when you run @code{ly2dvi}, we explain what
+programs are run.
@code{ly2dvi} is a program that calls a number of programs in sequence.
The first thing it does, is running LilyPond on the input file. After
-some calculations, lily comes up with a @file{.tex} file. The contents
+some calculations, a @file{.tex} is produced. The contents
of this file are very low-level instructions.
-For example, if you'd put the following in a file called
-@file{layout.ly},
+For example, the following file (@file{layout.ly})
@example
\version "1.3.124";
\score @{
\notes @{ c'4 d'4 @}
\header @{
- opus = "Opus 1.";
- piece = "Up"; @}
+ opus = "Opus 1.";
+ piece = "Up"; @}
@}
\score @{
\notes @{ d'4 c'4 @}
\header @{
- opus = "Opus 2.";
- piece = "Down"; @}
+ opus = "Opus 2.";
+ piece = "Down"; @}
@}
@end example
-
-The result should look somewhat like this@footnote{The titling in this
-manual was not generated by ly2dvi, so details will differ.}
+ results in something like this@footnote{The titling in this manual was
+not generated by ly2dvi, so details will differ.}
@center @strong{Two miniatures}
@flushright
#(set! point-and-click #t)
@end example
+This is Scheme code. It sets the variable @code{point-and-click} to the
+value @var{true}.
+
Editing input files can be quite complicated if you're working with
large files: if you're digitizing existing music, you have to
synchronize the .ly file, the sheet music on your lap and the sheet
music on the screen. The point-and-click mechanism makes it easy to
find the origin of an error in the .ly file: @footnote{This feature is
-presently only available on X-windows using a patched version of xdvi
+presently only available on X-windows using patched versions of Xdvi
and emacs} when you view the file with Xdvi and click on a note using
control-right button, [checkme], you editor will jump to the spot where
that note was entered.
\paper @{
@end example
-The @code{\score} blocks that follow in the file, don't have
+The @code{\score} blocks that follow in the file don't have
@code{\paper} sections, so the settings of this block are substituted: A
paper block, at top-level, i.e. not in a @code{\score} block sets the
default page layout.
The variable @code{linewidth} normally sets the length of the systems on
-the page. However, a negative value has a special meaning here. If
+the page. However, a negative value has a special meaning. If
@code{linewidth} is less than 0, no line breaks are inserted into the
score, and the spacing is set to natural length: a short phrase takes up
little space, a longer phrase more space.
When you're copying music from existing sheet music, relative octaves
are probably the easiest to use: it's less typing work and errors are
easily spotted. However, if you write LilyPond input, either by hand
-(ie. composing) or by computer, absolute octaves is probably less work.
+(ie. composing) or by computer, absolute octaves are probably less work.
@example
The @code{\header} is normally at the top of the file, where it sets
values for the rest of the file. If you want to typeset different pieces
-from one file (eg. if there are multiple movements, or if you're making
-a etude-book), you can put different @code{\score}
-blocks into the input file. ly2dvi will assemble all LilyPond
-output files into a big document. The contents of \header blocks
-specified within each score, are used for the titling of each movement.
+from one file (for example, if there are multiple movements, or if
+you're making a etude-book), you can put different @code{\score} blocks
+into the input file. ly2dvi will assemble all LilyPond output files into
+a big document. The contents of \header blocks specified within each
+score, are used for the titling of each movement.
@example
- opus = "Opus 1.";
- piece = "Up"; @}
+ opus = "Opus 1.";
+ piece = "Up"; @}
@end example
For example, the Opus number is put at the right, and the piece string
will be at the left.
Our third subject is a piece of piano music. The fragment in the input
file is a piano reduction of the G major Sinfonia by Giovanni Battista
-Sammartini. It was composed around 1740.
+Sammartini. It was composed around 1740. It's in the source package
+under the name @file{sammartini.ly}.
@lilypond[verbatim]
\include "paper16.ly";
stemboth = \property Voice.Stem \revert #'direction
viola = \notes \relative c' \context Voice = viola {
- <c4-\f g' c>
+ <c4-\f-\arpeggio g' c>
\stemdown g'8. b,16
s1 s2. r4
g
}
oboes = \notes \relative c'' \context Voice = oboe {
- \stemup s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
+ \stemup s4 g8. b,16 c8 r <e'8.^\p g> <f16 a>
\grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
<
{ \times 2/3 { a8 g c } \! c2 }
[<c16( e> < )e8. g>] <c8 e,>
}
-hoomPah = \notes \repeat unfold 8 \transpose c' { c8 \stemdown c'8 \stemup }
+hoomPah = \repeat unfold 8
+ \notes \transpose c' { c8 \stemdown c'8 \stemup }
bassvoices = \notes \relative c' {
c4 g8. b,16
- \autochange Staff \hoomPah
+ \autochange Staff \hoomPah
\translator Staff = down
\stemdown [c8 c'8] r4
<g d'> r4
@end lilypond
If it looks like incomprehensible gibberish to you, then you are right.
-This example has been doctored this example to have as many quirks as
-possible.
+This example has been doctored to have as many quirks as possible.
@example
-stemdown = \property Voice.Stem \override #'direction = #-1
-stemup = \property Voice.Stem \override #'direction = #1
-stemboth = \property Voice.Stem \revert #'direction
+ stemdown = \property Voice.Stem \override #'direction = #-1
+@end example
+
+As you can see, this example features more voices on one staff. To make
+room for those voices, their notes have to be stemmed in opposite
+directions. These are the commands to make that happen.
+
+The symbols that are printed, are internally represented by so-called
+Graphical Objects (or more colloquially: Grobs). These statements
+concern the grob called `Stem'. Each grob is described by a bunch of
+settings. These setting determine the fonts, offsets, sub-routines to be
+called on the grob, etc. The initial values of these settings are set
+in the Scheme file @file{scm/grob-description.scm}.
+
+This statement adds a the setting for all Stem grobs in the current
+Voice: @code{direction} is set to @code{-1}, which encodes down. The
+setting remains in effect until it is reverted.
+
+@example
+ \property Voice.Stem \revert #'direction
@end example
-[explain grob push/pop]
+This statement reverts the old setting. If you do this, the effect of a
+@code{\stemdown} or @code{\stemup} is neutralised.
+
+@code{\override} and @code{\revert} function like a stack: you can push
+values onto the grob-setting-stack with @code{\override} and you pop
+them with @code{\revert}.
+
+LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
+with some more often used formatting instructions, but to explain how it
+works, we wrote our own here. Of course, you should use predefined
+identifiers like these if possible: then you will be affected less by
+the implementation changes we occasionally make.
@example
viola = \notes \relative c' \context Voice = viola @{
associated with one notation context. This notation context handles
stems and dynamics (among others). The name of this context is
@code{Voice}. For each part we have to make sure that there is
-precisely one Voice context.
+precisely one @code{Voice} context, so we give it an unique name
+(`@code{viola}').
+
@example
-<c4-\f g' c>
+<c4-\f-\arpeggio g' c>
@end example
-@code{<} and @code{>} are short hands for @code{\simultaneous @{} and
-@code{@}}. So the expression enclosed in @code{<} and @code{>} is a
-chord. @code{\f} places a forte symbol under the chord.
+The delimiters @code{<} and @code{>} are shorthands for
+@code{\simultaneous @{} and @code{@}}. The expression enclosed in
+@code{<} and @code{>} is a chord.
+
+@cindex dynamics
+@cindex loudness
+@cindex forte
+@cindex arpeggio
+
+@code{\f} places a forte symbol under the chord. The forte applies to
+the whole chord, but the syntax requires that commands like forte and
+arpeggio are attached to a note, so here we attach them to the first
+note.
+
+@code{\arpeggio} draws an vertical wavy line before the chord,
+signifying an arpeggio.
@example
\stemdown
@example
s1 s2. r4
@end example
-@code{s} is a `spacer' rest. It does not print anything, but it does
-have the duration of a rest.
+@code{s} is a spacer rest. It does not print anything, but it does have
+the duration of a rest. It is useful for filling up voices that
+temporarily don't play. In this case, the viola doesn't come until one
+and a half measure later.
+
@example
oboes = \notes \relative c'' \context Voice = oboe @{
@end example
these notes are indeed processed by precisely one context with
@code{\context}.
@example
-\stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
+\stemup s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
@end example
-@code{\stemUp} is an identifier reference. It is shorthand for
-@code{\property Voice.Stem \override #'direction = #1}. If possible, you
-should use predefined identifiers like these for setting properties.
-Your input will be less dependent upon the implementation of LilyPond.
+@code{\stemup} is a reference to the @code{\property \override} command
+defined above. .
@example
-\grace <e8( g> < )d4 f> <c2 e>
-@end example
+\grace <e8 g> < d4 f> <c2 e>
+@end example
+@cindex @code{\grace}
+@cindex ornaments
+@cindex grace notes
+
@code{\grace} introduces grace notes. It takes one argument, in this
-case a chord. The slur started on the @code{e} of the chord
+case a chord.
+
+@ignore
+The slur started on the @code{e} of the chord
will be attached to the next note.@footnote{LilyPond will squirm
about unended Slurs. In this case, you can ignore the warning}.
+@end ignore
@example
\times 2/3
-@end example
+@end example
+@cindex tuplet
+@cindex triplets
Tuplets are made with the @code{\times} keyword. It takes two
-arguments: a fraction and a piece of music. The duration of the
-second argument is multiplied by the first argument. Triplets make
-notes occupy 2/3 of their notated duration, so in this case the
-fraction is 2/3.
+arguments: a fraction and a piece of music. The duration of the piece
+of music is multiplied by the fraction. Triplets make notes occupy 2/3
+of their notated duration, so in this case the fraction is 2/3.
@example
@{ <d8 \< f> <e g> <f a> @}
@end example
The piece of music to be `tripletted' is sequential music containing
-three notes. On the first chord (the @code{d}), a crescendo is started
-with @code{\<}.
+three notes. On the first chord, a crescendo is started with
+@code{\<}. To be precise, the crescendo start is syntactically attached
+to the preceding note, the @code{d}.
+
+@cindex dynamics
+@cindex crescendo
+@cindex @code{\<}
+
@example
<
@end example
voice, which continues with upward stems:
@example
@{ \times 2/3 @{ a8 g c @} \! c2 @}
-@end example
+@end example
+
+@cindex @code{\!}
+
The crescendo is ended at the half note by the escaped exclamation
-mark `@code{\!}'.
+mark @code{\!}.
@example
\context Voice = oboeTwo @{
\stemDown
it from the other context. Stems go down in this voice.
@example
\grace @{
-@end example
+@end example
+@cindex Grace context
When a grace section is processed, a @code{Grace} context is
created. This context acts like a miniature score of its own. It has
its own time bookkeeping, and you can make notes, beams, slurs
@end example
This ends the two-part section.
@example
-\stemBoth
+\stemboth
\grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
-@end example
+@end example
+@cindex trill
+@cindex stemboth
+
@code{\stemBoth} ends the forced stem directions. From here, stems are
positioned as if it were single part music.
The bass has a little hoom-pah melody to demonstrate parts switching
between staffs. Since it is repetitive, we use repeats:
@example
-hoomPah = \notes \repeat unfold 8
+hoomPah = \repeat unfold 8
@end example
-
+@cindex unfolded @code{\repeat}
+This repeat print the following sequence notes eight times.
@example
-\transpose c' @{
+\notes \transpose c' @{
@end example
-Transposing can be done with @code{\transpose}. It takes two
-arguments; the first specifies what central C should be transposed to.
-The second is the to-be-transposed music. As you can see, in this
-case, the transposition is a no-op, as central C would be transposed to
-central C.
+@cindex transposing
+@cindex relative mode and transposing
+
+Transposing can be done with @code{\transpose}. It takes two arguments;
+the first specifies what central C should be transposed to. The second
+is the to-be-transposed music. As you can see, in this case, the
+transposition is a no-op, as central C stay at central C.
The purpose of this no-op is circumventing relative mode. Relative mode
-can not be used in conjunction with transposition, so relative mode will
+can not be used together with transposition, so @code{\relative} will
leave the contents of @code{\hoomPah} alone. We can use it without
having to worry about getting the motive in a wrong octave.
@example
bassvoices = \notes \relative c' @{
c4 g8. b,16
\autochange Staff \hoomPah
-@end example
-Entering the bass part is easy: the hoomPahHoomPah variable is
-repeated four times; @code{unfold} means that all four repetitions
-should be written out.
-
+@end example
+@cindex staff switch, automatic
+@cindex cross staff voice, automatic
+@cindex @code{\autochange}
+
+Voices can switch between staffs. The easiest way to get this, is to use
+@code{\autochange}. This command looks at the pitch of each note, and if
+necessary, will cross to the other staff. For this to work, the two
+staffs must be called @code{"up"} and @code{"down"}.
@example
- \translator Staff = down
+ \translator Staff = down
@end example
+@cindex staff switch
+@cindex cross staff voice
+The rest of this melody must be in the lower staff, so we do a manual
+staff switch here.
+
@example
\context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
-@end example
+@end example
+@cindex tie
+@cindex @code{~}
After skipping some lines, we see @code{~}. This mark makes ties.
@example
\context PianoStaff
@end example
-For piano music, a special context is needed to get cross staff
-beaming right. It is called @code{PianoStaff}.
+ A special context is needed to get cross staff beaming right. This
+context is called @code{PianoStaff}.
@example
\context Staff = bottom < \time 2/2; \clef bass;
@end example
line is not indented. The line still looks very cramped, but that is due
to the page layout of this document.
+
[TODO:
-Split piano in 2
+* arpeggio, glissando,
+
+* \apply, \outputproperty, \translator @{@}, \molecule hacking.
-* Piano I: autochange, simple chords, arpeggio, glissando, tuplets
-unfolded repeat, space rests.
+* font-size, cadenza. rhythmic staff, multi-stanza.
-* Piano II: property push/pop, grace notes, multiple voices,
-dynamics, stem up/stem down,
* Orchestral: demonstrate Hara-Kiri, part combining, part extraction,
scores, transposition, instrument names,
PACKAGE_NAME=LilyPond
MAJOR_VERSION=1
MINOR_VERSION=3
-PATCH_LEVEL=125
-MY_PATCH_LEVEL=jcn5
+PATCH_LEVEL=126
+MY_PATCH_LEVEL=
# use the above to send patches: MY_PATCH_LEVEL is always empty for a
# released version.
title = "Two miniatures";
}
- #(set! point-and-click #t)
+ #(set point-and-click #t)
\paper { linewidth = -1.0; }
stemboth = \property Voice.Stem \revert #'direction
viola = \notes \relative c' \context Voice = viola {
- <c4-\f g' c>
+ <c4-\f-\arpeggio g' c>
\stemdown g'8. b,16
s1 s2. r4
g
}
oboes = \notes \relative c'' \context Voice = oboe {
- \stemup s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
+ \stemup s4 g8. b,16 c8 r <e'8.^\p g> <f16 a>
\grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
<
{ \times 2/3 { a8 g c } \! c2 }
[<c16( e> < )e8. g>] <c8 e,>
}
-hoomPah = \notes \repeat unfold 8 \transpose c' { c8 \stemdown c'8 \stemup }
+hoomPah = \repeat unfold 8
+ \notes \transpose c' { c8 \stemdown c'8 \stemup }
bassvoices = \notes \relative c' {
c4 g8. b,16
- \autochange Staff \hoomPah o
+ \autochange Staff \hoomPah
\translator Staff = down
\stemdown [c8 c'8] r4
<g d'> r4
--- /dev/null
+
+\header {
+ title = "Test";
+}
+
+
+\score {
+ \notes { c'4 e'4 g'4 }
+ \paper { }
+}
cerr << _ ("white expected") << endl;
exit (1);
}
+
<INITIAL,chords,lyrics,notes># { //embedded scm
//char const* s = YYText () + 1;
char const* s = here_ch_C ();
Begin3
Title: LilyPond
-Version: 1.3.125
-Entered-date: 25JAN01
+Version: 1.3.126
+Entered-date: 28JAN01
Description:
Keywords: music notation typesetting midi fonts engraving
Author: hanwen@cs.uu.nl (Han-Wen Nienhuys)
janneke@gnu.org (Jan Nieuwenhuizen)
Maintained-by: hanwen@stack.nl (Han-Wen Nienhuys)
Primary-site: sunsite.unc.edu /pub/Linux/apps/sound/convert
- 1000k lilypond-1.3.125.tar.gz
+ 1000k lilypond-1.3.126.tar.gz
Original-site: ftp.cs.uu.nl /pub/GNU/LilyPond/development/
- 1000k lilypond-1.3.125.tar.gz
+ 1000k lilypond-1.3.126.tar.gz
Copying-policy: GPL
End
%define info yes
Name: lilypond
-Version: 1.3.125
+Version: 1.3.126
Release: 1
License: GPL
Group: Applications/Publishing
-Source0: ftp.cs.uu.nl:/pub/GNU/LilyPond/development/lilypond-1.3.125.tar.gz
+Source0: ftp.cs.uu.nl:/pub/GNU/LilyPond/development/lilypond-1.3.126.tar.gz
Summary: A program for printing sheet music.
URL: http://www.cs.uu.nl/~hanwen/lilypond
# Icon: lilypond-icon.gif
dvips -O 5mm,0mm -o coriolan.ps coriolan
%}
-#(set! point-and-click #t)
+#(set point-and-click #t)
\header{
filename = "coriolan.ly";
\property VoiceCombineVoice.crescendoText = #"cresc."
\property VoiceCombineVoice.crescendoSpanner = #'dashed-line
r4 r8 ges'\< f4 r8 c|
- \!des4 r r2|
+ des4 r r2|
R1*5|
f4 r r r8 es|
des4 r r r8 c|
bes4 r8 e f4 r8 f|
g4 r8 g e4 r8 e|
R1*4|
- as,4\ff r8 des8 c4 r8 g|
+ \!as,4\ff r8 des8 c4 r8 g|
f4 r8 bes as4 r8 es|
des4 r8 g f4 r8 f'|
f4 r8 f e4 r8 e|
projects / lilypond.git / commitdiff