+2002-07-02 Han-Wen Nienhuys <hanwen@cs.uu.nl>
+
+ * lily/bar-check-iterator.cc (process): change
+ barbarCheckNoSynchronize to barCheckSynchronize
+
+ * Documentation/user/bugs.itexi: move to introduction, remove.
+
+ * Documentation/user/*.itexi: general carnage/cleanage.
+
+ * Documentation/user/internals.itely: split most of file into
+ internal documentation (.scm and .cc)
+
+ * buildscripts/make-font-dir.py: put designsize in to X font
+ sWidth field
+
+ * make/lilypond.redhat.spec.in: postinstall bugfix
+
2002-07-02 Juergen Reuter <reuter@ipd.uka.de>
* lily/ambitus-engraver.cc, lily/ambitus.cc: Various bugfixes:
@item @email{matsb@@s3.kth.se, Mats Bengtsson},
@uref{http://www.s3.kth.se/~matsb/}
lots of testing, fixes, general comments and contributions.
-@item @email{eric@@aut.ee.ethz.ch, Eric Bullinger},
- accidental transposition.
@item Laura Conrad (lconrad@@world.std.com)
fixes to abc2ly
@item @email{Jan.A.Fagertun@@trondheim.online.no, Jan Arne Fagertun},
+++ /dev/null
-@node Bug reports
-@chapter Bug reports
-@cindex bugs
-@cindex bug reports
-@cindex reporting bugs
-
-LilyPond development moves quickly, so if you have a problem, it is
-wise to check if it has been fixed in a newer release. If you think
-you found a bug, please send in a bugreport including the following
-information:
-
-@itemize @bullet
-
-@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. Without this, we can not verify
-your problem.
-
-@item A description of the platform you use (i.e., operating system,
-system libraries, whether you downloaded a binary release)
-
-@item If necessary, send a description of the bug itself.
-
-@end itemize
-
-
-You can send the report to @email{bug-lilypondg@@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://www.lilypond.org/wiki?LilyPondBugs}.
-
@c -*-texinfo-*-
-@node convert-ly
-@chapter convert-ly
+@node Upgrading from older LilyPond versions
+@chapter Upgrading from older LilyPond versions
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.
-
-@unnumberedsubsec Invoking convert-ly
+detect the old version number. For example, to upgrade all lilypond
+files in the current directory and its subdirectories, use
+@example
+ convert-ly -e --to=1.3.150 `find . -name '*.ly' -print`
+@end example
+The program is invoked as follows:
@example
- convert-ly [OPTION]... [FILE]...
+ convert-ly [@var{options}] @var{files}
@end example
+The following options can be given:
+
@table @code
@item -a,--assume-old
If version number cannot be determined, apply all conversions.
Print usage help
@end table
-@unnumberedsubsec Example
-
-Upgrade all lilypond files to 1.3.150:
-@example
- convert-ly -e --to=1.3.150 `find -name '*.ly'`
-@end example
-
-@unnumberedsubsec Bugs
-
-Not all language changes are handled. Multiple output options won't
-work.
-
-@unnumberedsubsec Authors
-@code{convert-ly} is written in @uref{http://www.python.org,Python}. It
-was written by @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}. Report bugs
-to @code{bug-lilypond@@gnu.org}
+@refbugs Bugs
+Not all language changes are handled. Only one output options can be specified.
@c -*-texinfo-*-
-@node Conversion tools
-@chapter Converting to LilyPond format.
-
+@node Importing other formats
+@chapter Importing other formats
@menu
-* midi2ly::
-* etf2ly::
-* abc2ly::
-* pmx2ly::
-* musedata2ly::
-* mup2ly::
+* Importing MIDI::
+* Importing Finale ::
+* Importing ABC::
+* Importing PMX::
+* Importing Musedata ::
+* Importing MUP::
@end menu
-@node midi2ly
-@section midi2ly
+@node Importing MIDI
+@section Importing MIDI
@cindex MIDI
-@cindex importing MIDI
Midi2ly translates a MIDI input file to a LilyPond source file. MIDI
(Music Instrument Digital Interface) is a standard for digital
convert it to @file{.ly}. However, human players are not rhythmically
exact enough to make a MIDI to LY conversion trivial. midi2ly tries to
compensate for these timing errors, but is not very good at this. It is
-therefore not recommended to use midi2ly for human-generated midi
-files. Correcting the quantization mistakes of the human player takes a
-lot of time.
+therefore not recommended to use midi2ly for human-generated midi files.
Hackers who know about signal processing are invited to write a more
robust midi2ly. midi2ly is written in Python, using a module written in
C to parse the MIDI files.
-
-@subsection Invoking midi2ly
-
+It is invoked as follows:
@example
- midi2ly [@var{OPTION}]@dots{} @var{MIDI-FILE}
+ midi2ly [@var{option}]@dots{} @var{midi-file}
@end example
-@unnumberedsubsec Options
+The following options are supported by midi2ly:
@table @code
@item -b, --no-quantify,
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
+@item -I, --include=@var{dir},
+ Add @var{dir} to search path.
+@item -k, --key=@var{acc}[:@var{minor}],
+ Set default key. @var{acc} > 0 sets number of sharps; @var{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 -o, --output=@var{file},
+ Set @var{file} as default output.
@item -p, --no-plets,
Assume no plets.
@item -q, --quiet,
@end table
-@node etf2ly
-@section etf2ly
+@node Importing Finale
+@section Importing Finale
@cindex ETF
@cindex enigma
@cindex Coda Technology
ETF (Enigma Transport Format) is a format used by Coda Music
-Technology's Finale product. This program will convert part of an ETF
+Technology's Finale product. etf2ly will convert part of an ETF
file to a ready-to-use LilyPond file.
-@subsection Invoking etf2ly
-Usage:
-
+It is invoked as follows:
@example
- etf2ly [@var{OPTION}]@dots{} @var{ETF-FILE}
+ etf2ly [@var{option}]@dots{} @var{etf-file}
@end example
-Convert ETF to LilyPond.
-
-@unnumberedsubsec Options
+The following options are supported by etf2ly.
@table @code
@item -h,--help
this help
etf2ly.
-@node abc2ly
-@section abc2ly
-
-ABC is a fairly simple ASCII based format. It is described at
-@uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}.
+@node Importing ABC
+@section Importing ABC
@cindex ABC
-@cindex Importing ABC
-@subsection Invoking abc2ly
+ABC is a fairly simple ASCII based format. It is described at
+@uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}. abc2ly
+translates from ABC to LilyPond. It is invoked as follows:
@example
- abc2ly [@var{OPTION}]@dots{} @var{ABC-FILE}
+ abc2ly [@var{option}]@dots{} @var{abc-file}
@end example
-Convert ABC to LilyPond.
+The following options are supported by abc2ly:
+
+@table @code
+@item -h,--help
+this help
+@item -o,--output=@var{file}
+set output filename to @var{file}.
+@item -v,--version
+print version information.
+@end table
There is a rudimentary facility for adding lilypond code to the ABC
source file. If you say:
will cause the text following the ``slyrics'' keyword to be inserted
into the current line of lyrics.
-@unnumberedsubsec Options
-@table @code
-@item -h,--help
-this help
-@item -o,--output=FILE
-set output filename to FILE
-@item -v,--version
-version information
-@end table
@refbugs
-The ABC standard is not very "standard". For extended features
+The ABC standard is not very ``standard''. For extended features
(eg. polyphonic music) different conventions exist.
Multiple tunes in one file cannot be converted.
abc2ly ignores the ABC beaming.
-@node pmx2ly
-@section pmx2ly
+@node Importing PMX
+@section Importing PMX
-PMX is a MusiXTeX preprocessor written by Don Simons, see
+PMX is a MusiXTeX preprocessor written by Don Simons. More information
+on PMX is available from the following site:
+
+@quotation
@uref{http://icking-music-archive.sunsite.dk/Misc/Music/musixtex/software/pmx/}.
+@end quotation
@cindex PMX
@cindex MusiXTeX
@cindex Simons, Don
-@subsection Invoking pmx2ly
+pmx2ly converts from PMX to LilyPond input. The program is invoked as
+follows:
@example
- pmx2ly [@var{OPTION}]@dots{} @var{PMX-FILE}
+ pmx2ly [@var{option}]@dots{} @var{pmx-file}
@end example
-Convert PMX to LilyPond.
-
-@unnumberedsubsec Options
+The following options are supported by pmx2ly:
@table @code
@item -h,--help
@end table
-@node musedata2ly
-@section musedata2ly
+@node Importing Musedata
+@section Importing Musedata
@cindex Musedata
@cindex CCARH
Musedata (@uref{http://www.musedata.org/}) is an electronic library of
classical music scores, currently comprising about 800 composition
dating from 1700 to 1825. The music is encoded in so-called Musedata
-format
-(@uref{http://www.ccarh.org/publications/books/beyondmidi/online/musedata}).
-musedata2ly converts a set of musedata files to one .ly file, and will
-include a @code{\header} field if a @file{.ref} file is supplied
-
-@subsection Invoking musedata2ly
+format. musedata2ly converts a set of musedata files to one .ly file,
+and will include a @code{\header} field if a @file{.ref} file is
+supplied. It is invoked as follows:
@example
- musedata2ly [@var{OPTION}]@dots{} @var{MUSEDATA-FILE}
+ musedata2ly [@var{option}]@dots{} @var{musedata-files}
@end example
-Convert Musedata to LilyPond.
-
-@unnumberedsubsec Options
+The following options are supported by musedata2ly:
@table @code
@item -h,--help
version information
@item -r,--ref=@var{reffile}
read background information from ref-file
-@var{REFFILE}
+@var{reffile}
@end table
+@refbugs
+
+musedata2ly converts only a small subset musedata.
-@node mup2ly
-@section mup2ly
+@node Importing MUP
+@section Importing MUP
MUP (Music Publisher) is a shareware music notation program by Arkkra
Enterprises. It is also the name of the input format. Mup2ly will
-convert part of a Mup file to a ready-to-use LilyPond file.
+convert part of a Mup file to a ready-to-use LilyPond file. Mup2ly is
+invoked as follows:
+@cindex Music Publisher
@cindex MUP
@cindex Arkkra
-@subsection Invoking mup2ly
-
@example
- mup2ly [@var{OPTION}]@dots{} @var{MUP-FILE}
+ mup2ly [@var{option}]@dots{} @var{mup-file}
@end example
-Convert Mup to LilyPond.
-
-@unnumberedsubsec Options
+The following options are supported by mup2ly:
@table @code
@item -d,--debug
show what constructs are not converted, but skipped.
-@item D, --define=@var{NAME}[=@code{EXP}]
-define macro @var{NAME} with opt expansion @code{EXP}
+@item D, --define=@var{name}[=@code{exp}]
+define macro @var{name} with opt expansion @code{exp}
@item -E,--pre-process
only run the pre-processor
@item -h,--help
print help
-@item -o,--output=FILE
-write output to @var{FILE}
+@item -o,--output=@var{file}
+write output to @var{file}
@item -v,--version
version information
@item -w,--warranty
-print warranty and copyright. Mup2ly comes with absolutely @strong{NO WARRANTY}.
+print warranty and copyright.
@end table
When translating the input to notation, there are number of distinct
phases. We list them here:
-
@c todo: moved from refman.
The purpose of LilyPond is explained informally by the term `music
During these stages different types of data play the the main role:
during parsing, @strong{Music} objects are created. During the
-interpretation, @strong{contexts} are constructed, and with these contexts
-a network of @strong{graphical objects} (``grobs'') is created. These
-grobs contain unknown variables, and the network forms a set of
-equations. After solving the equations and filling in these variables,
-the printed output (in the form of @strong{molecules}) is written to an
-output file.
+interpretation, @strong{contexts} are constructed, and with these
+contexts a network of @strong{graphical objects} (``grobs'') is
+created. These grobs contain unknown variables, and the network forms a
+set of equations. After solving the equations and filling in these
+variables, the printed output is written to an output file.
These threemanship of tasks (parsing, translating, typesetting) and
data-structures (music, context, graphical objects) permeates the entire
The data types that are mentioned here are all discussed in this
section.
-@menu
-* Grobs:: Graphical object
-* Molecules:: Molecules are stand-alone descriptions of output
-@end menu
-
-@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 definition
-of the `Stem' grob with the setting @code{direction := 1}.
-
-@menu
-* What is a grob?::
-* Callbacks::
-* Setting grob properties::
-* Grob interfaces::
-* Items and Spanners::
-* 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 a node in that graph.
-The directed edges in the graph are formed by references to other grobs
-(i.e. pointers).
-This big graph of grobs specifies the notation problem. The solution of
-this problem is a description of the printout in closed form, i.e. 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 (a.k.a. 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. When 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 @code{Line_of_score}, and it
-represents a system (i.e. 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.
-
-A grob is often associated with a symbol, but some grobs do not print
-any symbols. They take care of grouping objects. For example, there is a
-separate grob that stacks staves vertically. The @code{NoteCollision}
-is also an abstract grob: it only moves around chords, but doesn't print
-anything.
-
-A complete list of grob types is found in the generated documentation.
-
-
-@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-grob-property gr '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: @code{Y-offset-callbacks} is also a property)
-
-
-
-Offset callbacks can be stacked, i.e.
-
-@example
- \property .... \override #'Y-offset-callbacks = #(list
- callback1 callback2 callback3)
-
-@end example
-
-The callbacks will be executed in the order @code{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, the staccato dot has two callbacks: one that positions the
-grob above or below the note head, and one 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 (Scheme value @code{#f}) means: "empty in this
-direction". If you fill in a pair of numbers, 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. In GUILE you can access these using functions described in
-Section @ref{Grob Scheme functions}. From C++, grob properties can be
-accessed using these 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
-
-All lookup functions identify undefined properties with end-of-list
-(i.e. @code{'()} in Scheme or @code{SCM_EOL} in C)
-
-Properties are stored in two ways:
-@itemize @bullet
-@item mutable properties.
-Grob properties that change from object to object. The storage of
-these are private to a grob. For example pointers to other grobs are
-always stored in the mutable properties.
-
-@item immutable properties.
-Grob 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 default settings. They are
-initially read from @file{scm/grob-description.scm}.
-@end itemize
-
-You can change immutable grob properties 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/grob-description.scm}. This can be undone by
-
-@example
- \property Voice.stem \revert #'direction
-@end example
-
-There is also a shorthand,
-
-@example
- \property Context.GrobType \set #'prop = #VAL
-@end example
-
-this does a @code{\revert} followed by a @code{\override}
-
-You can change mutable properties with \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 grob property
- @var{sym} is set to @var{val}. For example
-
-@example
- \outputproperty
- #(lambda (gr) (string? (ly-get-grob-property gr
- 'text)))
- #'extra-offset = #'(-1.0 . 0.0)
-@end example
-
-This shifts all grobs 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 Grob interfaces
-@unnumberedsubsec Grob interfaces
-
-Grob properties form a name space where you can set variables per
-object. Each object however, may have multiple functions. For example,
-consider a dynamic symbol, such @code{\ff} (fortissimo). It is printed
-above or below the staff, it is a dynamic sign, and it is a kind of
-text.
-
-To reflect this different functions of a grob, procedures and variables
-are grouped into so-called interfaces. The dynamic text for example
-supports the following interfaces:
-@table @code
-@item font-interface
- The glyph is built from characters from a font, hence the
-@code{font-interface}. For objects supporting @code{font-interface}, you
-can select alternate fonts by setting @code{font-style},
-@code{font-point-size}, etc.
-
-@item dynamic-interface
- Dynamic interface is not associated with any variable or function in
-particular, but this makes it possible to distinguish this grob from
-other similar grobs (like @code{TextScript}), that have no meaning of
-dynamics.
-
-@item text-interface
- This interface is for texts that are to be set using special routines
-to stack text into lines, using kerning, etc.
-
-@item general-grob-interface
- This interface is supported by all grob types.
-@end table
-
-
-
-@node Items and Spanners
-@unnumberedsubsec Items and Spanners
-
-Grobs can also be distinguished in their role in the horizontal spacing.
-Many 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 of the spanner.
-
-Some items need special treatment for line breaking. For example, a
-clef is normally only printed at the start of a line (i.e. 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 @code{visibility-lambda}. This grob property is a
-function taking a direction (-1, 0 or 1) as argument. It returns a cons
-of booleans, signifying whether this grob should be transparent and have
-no extent.
-
-@node Grob Scheme functions
-@unnumberedsubsec Grob Scheme functions
-
-Grob properties can be manipulated from Scheme. In practice, most
-manipulations are coded in C++ because of tradition.
-
-
-
-@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
-what-to-print-where information that also contains dimension information
-(how large is this glyph?).
-
-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 in the output file.
-
-All visible, i.e. non-transparent, 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. Most molecule callbacks are written in C++, but
-you can also write them in Scheme. An example is provided in
-@code{input/regression/molecule-hacking.ly}.
-
-
-
* Semantic input format::
* A programming approach::
* About this manual::
+* Bug reports::
+* Web site::
@end menu
@node Why LilyPond
blabla
+
+@node Bug reports
+@section Bug reports
+
+@cindex bugs
+@cindex reporting bugs
+
+
+Since there is no finder's fee which doubles every year, there is no
+need to wait for the prize money to grow. So send a bug report today!
+
+LilyPond development moves quickly, so if you have a problem, it is
+wise to check if it has been fixed in a newer release. If you think
+you found a bug, please send in a bugreport. When you send us a
+bugreport, we have to diagnose the problem and if possible, duplicate
+it. To make this possible, it is important that you include the
+following information in your report:
+
+@itemize @bullet
+
+@item A sample input which causes the error. Please have mercy on the
+developers, send a @emph{small} sample file.
+
+@item The version number of lilypond.
+
+@item A description of the platform you use (i.e., operating system,
+system libraries, whether you downloaded a binary release)
+
+@item If necessary, send a description of the bug itself. If you
+include output a ly2dvi run, please use @code{--verbose} option of
+ly2dvi.
+
+@end itemize
+
+You can send the report to @email{bug-lilypond@@gnu.org}. This is a
+mailinglist, but you don't have to be subscribed to it to post.
+
+
+@node Web site
+@section Web site
+
+If you are reading this manual in print, it is possible that the
+website contains updates to the manual. You can find the lilypond
+website at @uref{http://www.lilypond.org/}.
Usage:
@example
- lilypond [@var{OPTION}@dots{} @var{FILE}@dots{}
+ lilypond [@var{options}] @var{file}@dots{}
@end example
-To have LilyPond read from stdin, use a dash @code{-} for @var{FILE}.
-@unnumberedsec Options
+
+When invoked with a filename that has no extension, LilyPond will try
+to add @file{.ly} as an extension first. To have LilyPond read from
+stdin, use a dash @code{-} for @var{file}.
+
+When LilyPond processes @file{filename.ly} it will produce
+@file{filename.tex} as output (or @file{filename.ps} for PostScript
+output). If @file{filename.ly} contains more than one @code{\score}
+block, then LilyPond will output the rest in numbered files, starting
+with @file{filename-1.tex}. Several files can be specified; they will
+each be processed independently. @footnote{The status of GUILE is not
+reset across invocations, so be careful not to change any default
+settings from within Scheme .}
+
+@section Command line options
+
+The following options are supported:
@table @code
files. Multiple @code{-e} options may be given. They will be evaluated
sequentially.
-@item -f,--format=@var{format}
-Output format for sheet music. Choices are @code{tex} (for @TeX{}
-output), @code{pdftex} for PDF@TeX{} input, @code{ps} (for PostScript), @code{scm} (for a Scheme
-dump), and @code{as} (for ASCII-art).
+@item -f,--format=@var{format} Output format for sheet music. Choices
+are @code{tex} (for @TeX{} output, to be processed with plain @TeX{},
+or through ly2dvi), @code{pdftex} for PDF@TeX{} input, @code{ps} (for
+PostScript), @code{scm} (for a Scheme dump), and @code{as} (for
+ASCII-art).
Unless you have special requirements, you should use @TeX{}
output. All other options are experimental.
-
-@c TODO: TFMFONTS
-
-For processing both the @TeX{} and the PostScript output, you must
-have appropriate environment variables set. For @TeX{}, you have to
-set @code{MFINPUTS} and @code{TEXINPUTS} to point to the directory
-containing LilyPond metafont and @file{.tex} files. For processing
-PostScript output with Ghostscript you have to set @code{GS_FONTPATH}
-to point to the directory containing LilyPond PFA files. When you
-print direct PS output, remember to send the PFA files to the printer
-as well.
-
-Scripts to do this are included in
-@file{buildscripts/out/lilypond-profile} (for sh shells) and
-@file{buildscripts/out/lilypond-login} (for C-shells), and should
-normally be run as part of your login process.
-
-
@item -h,--help
Show a summary of usage.
@item --include, -I=@var{directory}
Scheme evaluation, backslashes in @TeX{}, code.
@strong{WARNING}: the @code{--safe} option has not been reviewed for a
-long time; do not rely on it for automatic invocation (e.g. over the
+long time. Do not rely on it for automatic invocation (e.g. over the
web). Volunteers are welcome to do a new audit.
-
@item -v,--version
Show version information
@item -V,--verbose
@strong{NO WARRANTY}!)
@end table
+@section Environment variables
-When invoked with a filename that has no extension, LilyPond will try to
-add @file{.ly} as an extension first.
-When LilyPond processes @file{filename.ly} it will produce
-@file{filename.tex} as output (or @file{filename.ps} for PostScript
-output). If @file{filename.ly} contains more than one @code{\score}
-block, then LilyPond will output the rest in numbered files, starting
-with @file{filename-1.tex}. Several files can be specified; they will
-each be processed independently. @footnote{The status of GUILE is not
-reset across invocations, so be careful not to change any default
-settings from within Scheme .}
+For processing both the @TeX{} and the PostScript output, you must
+have appropriate environment variables set. Scripts to do this are
+included in @file{buildscripts/out/lilypond-profile} (for sh shells)
+and @file{buildscripts/out/lilypond-login} (for C-shells), and should
+normally be sourced as part of your login process. If these scripts
+are not run from the system wide login process, then you must run it
+yourself.
-@section Environment variables
+@cindex installing LilyPond
+
+If you use sh, bash, or a similar shell, then add the following to
+your @file{.profile}
+@example
+ . lilypond-profile
+@end example
+
+If you use csh, tcsh or a similar shell, then add the following to
+your @file{~/.login}
+@example
+ source lilypond-login
+@end example
+These scripts set the following variables
+@table @code
+@item TEXMF
+This is to make sure that @TeX{} and lilypond find data files (among
+others @file{.tex}, @file{.mf} and @file{.tfm}). A typical setting would be
+@example
+@{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
+@end example
+
+you have to set @code{TEXMF} to point to the lilypond data
+file tree.
+
+@item GS_LIB
+For processing PostScript output (obtained with
+@code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
+point to the directory containing LilyPond PS files.
+
+@item GS_FONTPATH
+For processing PostScript output (obtained with
+@code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
+point to the directory containing LilyPond PFA files.
+
+When you print direct PS output, remember to send the PFA files to the
+printer as well.
+@end table
+
+
+@cindex ghostscript
+@cindex PostScript
+@cindex GS_FONTPATH
+@cindex GS_LIB
+@cindex TEXMF
+@cindex printing postscript
+
+The LilyPond binary itself recognizes the following environment variables
@table @code
@item LILYPONDPREFIX
This specifies a directory where locale messages and
subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
@item LANG
-selects the language for the warning messages of LilyPond.
+This selects the language for the warning messages of LilyPond.
@end table
+@cindex LANG
+@cindex LILYPONDPREFIX
+
@c -*-texinfo-*-
-@node lilypond-book
-@chapter lilypond-book
+@node Merging text and music with lilypond-book
+@chapter Merging text and music with lilypond-book
@command{lilypond-book} runs Lilypond on fragments of lilypond in a
-La@TeX{} or texinfo file, and includes the results into a document that
+La@TeX{} or Texinfo file, and includes the results into a document that
can be processed with La@TeX{}, @command{makeinfo} or
@command{texi2dvi}. The result is a text document containing formatted
music integrated.
\lilypond[options, go,here]@{ .. @}
@end example
-In the texinfo version, bitmaps of the music are also generated, so you
+In the Texinfo version, bitmaps of the music are also generated, so you
can make a HTML document with embedded music.
-@section TeXinfo reference
+@section Texinfo reference
You specify the lilypond code like this:
@example
@end itemize
@code{@@pagesizes} are not yet supported.
-@subsection Examples
-
-Two simple examples. First a complete block:
-
+We show two simple examples here. First a complete block:
@example
@@lilypond[26pt]
c' d' e' f' g'2 g'
defined to nothing by default, and the user can redefine them
to whatever he wants.
-@subsection Examples
+We show some examples here.
@example
\begin[26pt]@{lilypond@}
For latex input, the file to give to latex has extension @file{.latex}.
-TeXinfo input will be written to a file with extension @file{.texi}.
+Texinfo input will be written to a file with extension @file{.texi}.
If you use @code{--outdir}, you should also @code{cd} to that directory
before running LaTeX or makeinfo. This may seem a little kludgey, but
\def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
@end example
-
-
-@subsection Command line options
-
+lilypond-book accepts the following command-line options:
@table @code
-
@item @option{-f}, @option{--format=}
Specify the document type to process, @code{latex} or @code{texi}.
@command{lilypond-book} usually figure this out automatically.
@item --no-music
strip all lilypond blocks from the file.
@item --no-pictures
- don't generate pictures when processing texinfo.
+ don't generate pictures when processing Texinfo.
@item --read-lys
don't write ly files. This way you can do
@example
The La@TeX{} \includeonly@{...@} command is ignored.
-The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4,
-but changing the linewidth in other ways will not give you a straight
-right margin.
+The Texinfo command @code{pagesize} is on the TODO list for Lilypond
+1.6, but changing the linewidth in other ways will not give you a
+straight right margin.
-Almost all La@TeX{} commands that change margins and line widths are ignored.
+Almost all La@TeX{} commands that change margins and line widths are
+ignored.
There is no way to automatically apply convert-ly to fragments inside a
lilypond-book file.
-
-Since there is no finder's fee which doubles every year, there is no
-need to wait for the prize money to grow. So send a bug report today if
-you need this one of these options.
-
-
-@section Authors
-
-@email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/~hanwen}
-
-@email{tca@@gnu.org, Tom Cato Amundsen}
-
* Tutorial:: A tutorial introduction to LilyPond.
* Reference Manual:: Reference Manual.
* Invoking LilyPond:: Operation.
-* Bug reports:: Where to report bugs.
-* ly2dvi:: Generating nice output with titles.
-* convert-ly:: Upgrading input files.
-* Conversion tools:: Converting to lilypond source format.
-* lilypond-book:: Interleaving text with music.
+* Titling LilyPond scores:: Generating nice output with titles
+ using ly2dvi.
+* Upgrading from older LilyPond versions::
+ Upgrading input files.
+* Importing other formats:: Converting to lilypond source format.
+* Merging text and music with lilypond-book::
+ The lilypond-book manual.
* Internals:: How it all works.
-* Literature:: Additional reading
+* Literature:: Additional reading material.
* Index:: Unified index.
-* Function Index:: Function index.
* Refman appendix::
* GNU Free Documentation License:: FDL.
@end menu
@mbinclude refman.itely
@mbinclude internals.itely
@mbinclude invoking.itexi
-@mbinclude bugs.itexi
@mbinclude ly2dvi.itexi
@mbinclude convert-ly.itexi
@mbinclude lilypond-book.itely
@printindex cp
-@node Function Index
-@unnumbered Function Index
-
-@printindex fn
-
@mbinclude appendices.itely
@mbinclude fdl.itexi
@c -*-texinfo-*-
-@node ly2dvi
-@chapter ly2dvi
+@node Titling LilyPond scores
+@chapter Titling LilyPond scores
-@file{ly2dvi} is a Python script that creates a nicely titled output file
-from an input file for La@TeX{}. It can create a DVI or PS file. It
-works by running LilyPond on the input files, creating a La@TeX{}
-wrapper around the output, and running La@TeX{} (and optionally
-@code{dvips}).
+Nicely titled output is created through a separate program:
+@file{ly2dvi} is a script that uses LilyPond and La@TeX{} to create a
+nicely titled piece of sheet music, in DVI format or PostScript.
@unnumberedsubsec Invoking ly2dvi
@c ly2dvi needs at least one FILE, can't act as filter yet
@example
- ly2dvi [@var{OPTION}]@dots{} @var{FILE}@dots{}
+ ly2dvi [@var{option}]@dots{} @var{file}@dots{}
@end example
-@unnumberedsec Options
+Ly2dvi supports the following options:
@table @code
@item -k,--keep
Write makefile dependencies for every input file.
@item -h,--help
Print usage help.
-@item -I,--include=@var{DIR}
- Add @var{DIR} to LilyPond's include path.
+@item -I,--include=@var{dir}
+ Add @var{dir} to LilyPond's include path.
@item -m,--no-paper
Produce MIDI output only.
@item --no-lily
Do not run LilyPond; useful for debugging ly2dvi.
-@item -o,--output=@var{FILE}
- Generate output to @var{FILE}. The extension of @var{FILE} is ignored.
+@item -o,--output=@var{file}
+ Generate output to @var{file}. The extension of @var{file} is ignored.
@item -P,--postscript
Also generate PostScript output, using dvips.
@item --preview
Also generate a picture of the first system of the score.
-@item -s,--set=@var{KEY}=@var{VAL}
- Add @var{KEY}= @var{VAL} to the settings, overriding those specified
+@item -s,--set=@var{key}=@var{val}
+ Add @var{key}= @var{val} to the settings, overriding those specified
in the files. Possible keys: @code{language}, @code{latexheaders},
@code{latexpackages}, @code{latexoptions}, @code{papersize},
@code{pagenumber}, @code{linewidth}, @code{orientation},
selects the language for the warning messages of Ly2dvi and LilyPond.
@end table
-@unnumberedsubsec Bugs
-
-Cannot generate @TeX{} or @code{PostScript} only. Send bugreports to to
-@email{bug-lilypond@@gnu.org}.
-
-@unnumberedsubsec Authors
-
-@email{hanwen@@cs.uu.nl,Han-Wen Nienhuys}.
-
-Earlier incarnations of ly2dvi were written by
-@email{daboys@@austin.rr.com, Jeffrey B. Reed} (Python version), and
-@email{Jan.A.Fagertun@@energy.sintef.no, Jan Arne Fagertun} (Bourne
-shell version)
-
1996. This time, Jan got sucked into Han-Wen's new project. The rest
is, as they say, history.
-You're reading the preface of the manual for LilyPond 1.4, which is in
-all honesty, the first release of LilyPond that combines stability,
-flexibility and good documentation. We hope you will have as much fun
-in using LilyPond as we have when hacking it.
+@c some more here.
+
+LilyPond would have been a far less useful program without the input
+of incountable number of individuals. We would like to thank all users
+that sent bugreports, gave suggestions or contributed code. We would
+especially like to thank the following people: Jean-Baptiste Lamy for
+providing Tablature support, Mats Bengtsson for the incountable newbie
+questions that he answered on the mailing list. Chris Jackson for
+various piano support code, Heikki Junes for taking care of the
+Emacs-mode, Glen Prideaux for implementing lyric-phrasing. Juergen
+Reuter for the ancient notation support, Rune Zedeler for many code
+improvements All translators that helped translate the error messages.
+
+@ignore
+ should mention many more people, these are from AUTHORS
+@end ignore
-This manual was written to help you learn LilyPond, but as you might
-imagine, we ourselves don't have much to learn about it. We can't
-really judge whether the manual is helpful for users, but maybe you can!
-Don't hesitate to tell us if you find any part of the manual vague,
-unclear or outdated.
Han-Wen and Jan
-Utrecht/Amsterdam, The Netherlands, March 2001.
+Utrecht/Eindhoven, The Netherlands, July 2002.
@menu
* Note entry::
+* Easier music entry::
* Staff notation::
* Polyphony::
* Beaming::
* Chords::
* Writing parts::
* Ancient notation ::
-* Ancient clefs ::
-* Figured bass::
* Tuning output::
* Page layout::
* Output formats::
* Sound::
-* Music entry::
-* Skipping corrected music::
* Interpretation context::
* Syntactic details::
* Lexical details::
the @code{-f ps} option of lilypond produces the correct result.
+@node Easier music entry
+@section Easier music entry
+@cindex Music entry
+@menu
+* Relative octaves::
+* Bar check::
+* Point and click::
+* Skipping corrected music::
+@end menu
+
+When entering music with LilyPond, it is easy to introduce errors. This
+section deals with tricks and features that help you enter music, and
+find and correct mistakes.
+
+@c . {Relative}
+@node Relative octaves
+@subsection Relative octaves
+@cindex Relative
+@cindex relative octave specification
+
+Octaves are specified by adding @code{'} and @code{,} to pitch names.
+When you copy existing music, it is easy to accidentally put a pitch in
+the wrong octave and hard to find such an error. To prevent these
+errors, LilyPond features octave entry.
+
+@cindex @code{\relative}
+@example
+ \relative @var{startpitch} @var{musicexpr}
+@end example
+
+The octave of notes that appear in @var{musicexpr} are calculated as
+follows: If no octave changing marks are used, the basic interval
+between this and the last note is always taken to be a fourth or less
+(This distance is determined without regarding alterations; a
+@code{fisis} following a @code{ceses} will be put above the
+@code{ceses})
+
+The octave changing marks @code{'} and @code{,} can 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 @var{musicexpr}.
+
+Entering music that changes octave frequently is easy in relative mode.
+@lilypond[fragment,singleline,verbatim,center]
+ \relative c'' {
+ b c d c b c bes a
+ }
+@end lilypond
+
+And octave changing marks are used for intervals greater than a fourth.
+@lilypond[fragment,verbatim,center]
+ \relative c'' {
+ c g c f, c' a, e'' }
+@end lilypond
+
+If the preceding item is a chord, the first note of the chord is used
+to determine the first note of the next chord. However, other notes
+within the second chord are determined by looking at the immediately
+preceding note.
+
+@lilypond[fragment,verbatim,center]
+ \relative c' {
+ c <c e g>
+ <c' e g>
+ <c, e' g>
+ }
+@end lilypond
+@cindex @code{\notes}
+
+The pitch after the @code{\relative} contains a note name. To parse
+the pitch as a note name, you have to be in note mode, so there must
+be a surrounding @code{\notes} keyword (which is not
+shown here).
+
+The relative conversion will not affect @code{\transpose},
+@code{\chords} or @code{\relative} sections in its argument. If you
+want to use relative within transposed music, you must place an
+additional @code{\relative} inside the @code{\transpose}.
+
+
+@c . {Bar check}
+@node Bar check
+@subsection Bar check
+@cindex Bar check
+
+@cindex bar check
+@cindex @code{barCheckNoSynchronize}
+@cindex @code{|}
+
+
+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 find errors in the input. Depending on the value of
+@code{barCheckSynchronize}, the beginning of the measure will be
+relocated, so this can also be used to shorten measures.
+
+A bar check is entered using the bar symbol, @code{|}:
+@example
+ \time 3/4 c2 e4 | g2.
+@end example
+
+
+
+@cindex skipTypesetting
+
+Failed bar checks are most often caused by entering incorrect
+durations. Incorrect durations often completely garble up the score,
+especially if it is polyphonic, so you should start correcting the score
+by scanning for failed bar checks and incorrect durations. To speed up
+this process, you can use @code{skipTypesetting} (See @ref{Skipping
+corrected music})). Bar
+
+
+@c . {Point and click}
+@node Point and click
+@subsection Point and click
+
+Point and click lets you find notes in the input by clicking on them in
+the Xdvi window. This makes it very easy to find input that causes some
+error in the sheet music.
+
+To use it, you need the following software
+
+@itemize @bullet
+@item
+@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
+Xdvi} version 22.36 or newer.
+
+ Note that most @TeX{} distributions ship with xdvik, which is a
+ different and less well maintained program. To find out which xdvi you
+ are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
+@item emacs
+@end itemize
+
+Xdvi must be configured to find the TeX fonts and music
+fonts. Refer to the Xdvi documentation for more information.
+
+
+To use point-and-click, add one of these lines to the top of your .ly
+file. The first one is for line location only. The second one is more
+convenient, but requires patching @code{emacsclient} and
+@code{server.el}.
+
+@example
+#(set! point-and-click line-location)
+@end example
+
+In the emacs startup file (usually @file{~/.emacs}), add the following
+@example
+(server-start)
+@end example
+
+Make sure that the environment variable @code{XEDITOR} is set
+to
+@example
+emacsclient --no-wait +%l %f
+@end example
+The second one, that also specifies the column, only works if you have
+patched your emacsclient and server, and have compiled your @code{.ly}
+file using the @code{line-column-location} setting.
+
+When viewing, control-mousebutton 1 will take you to the originating
+spot in the @file{.ly} file. Control-mousebutton 2 will show all
+clickable boxes.
+
+If you want emacs to jump to the exact spot (and not just the line) on a
+click, you must enable column positioning. To do so, you need to patch
+emacsclient. Apply @file{emacsclient.patch} (included with the source
+package) to @file{emacsclient.c} and @file{server.el} from the emacs
+source code. Recompile and stick the recompiled emacsclient into a bin
+directory, and put @file{server.el} into a elisp directory
+(e.g. @file{~/usr/share/emacs/}). Add the following to your
+@file{.emacs} init file, before invoking server-start.
+
+@example
+ (setq load-path (cons "~/usr/share/emacs" load-path))
+@end example
+
+Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}
+
+At the top of the @code{ly} file, replace the @code{set!} line with the
+following line
+@example
+#(set! point-and-click line-column-location)
+@end example
+
+One final hint: if you correct large files with point-and-click, then
+start correcting at the end of the file. When you start at the top, and
+insert one line, all subsequent locations will be off by a line.
+
+
+@refbugs
+
+When you convert the @TeX{} file to PostScript using @code{dvips}, it
+will complain about not finding @code{src:X:Y} files. Those complaints
+are harmless, and can be ignored.
+
+@node Skipping corrected music
+@subsection Skipping corrected music
+
+The property @code{Score.skipTypesetting} can be used to switch on and
+off typesetting completely during the interpretation phase. When
+typesetting is switched off, the music is processed much more quickly.
+You can use this to skip over the parts of a score that you have already
+checked for errors.
+
+@lilypond[fragment,singleline,verbatim]
+\relative c'' { c8 d
+\property Score.skipTypesetting = ##t
+ e f g a g c, f e d
+\property Score.skipTypesetting = ##f
+c d b bes a g c2 }
+@end lilypond
+
+
+
@node Staff notation
@section Staff notation
c4^"longtext" \fatText c4_"longlongtext" c4 }
@end lilypond
+It is possible to use @TeX{} commands in the strings, but this should be
+avoided because it makes it impossible for LilyPond to compute the
+exact length of the string, which may lead to collisions. Also, @TeX{}
+commands won't work with direct PostScript output (see @ref{PostScript
+output}).
+
Text scripts are created in form of @internalsref{TextScript} grobs, in
@internalsref{Voice} context.
To add an arrow head to explicitly specify the direction of the
arpeggio, you should set the arpeggio grob property
-@code{arpeggio-type}.
+@code{arpeggio-direction}.
@lilypond[fragment,relative,verbatim]
\context Voice {
@lilypond[fragment,relative,verbatim]
\context PianoStaff <
\property PianoStaff.connectArpeggios = ##t
- \property PianoStaff.Arpeggio \override #'molecule-callback = \arpeggioBracket
+ \property PianoStaff.Arpeggio \override
+ #'molecule-callback = \arpeggioBracket
\context Voice = one { <c'\arpeggio e g c> }
\context Voice = other { \clef bass <c,,\arpeggio e g>}
>
@menu
* Ancient note heads::
* Custodes::
+* Ancient clefs ::
+* Figured bass::
@end menu
@end example
@node Ancient clefs
-@section Ancient clefs
+@subsection Ancient clefs
LilyPond supports a variety of clefs, many of them ancient. These can
be selected from the @code{ancient} font family, by setting
@cindex hufnagel clefs
-
-@c . {Figured bass}
@node Figured bass
-@section Figured bass
+@subsection Figured bass
@cindex Basso continuo
@code{<} and @code{>}. The duration is entered after the @code{>}.
@lilypond[fragment]
\context FiguredBass
-\figures { <4 6> }
+\figures { <4 6> }
@end lilypond
@example
<4 6>
Type1 usually come as ``one design fits all sizes''.
@item font-name
- The name of the font, without the design size, e.g. @code{cmr},
-@code{cmti}, etc. Setting this overrides font-family, font-shape and
-font-series.
-
-
+ The name of the font, as a string, e.g. @code{"cmr12"}. This overrides
+all other font-qualifiers.
@end table
A very rigorous way of removing grobs from the whole score is to remove
the engraver that creates them. For example,
-
@lilypond[singleline,verbatim]
\score {\notes { c'4 d'8 e'8 g2 }
\paper { \translator {
} }
}
@end lilypond
+However, as you can see, this can lead to unexpected effects.
@node Dirty tricks
@subsection Dirty tricks
@cindex embedded tex
-It is possible to use @TeX{} commands in the strings, but this should be
-avoided because it makes it impossible for LilyPond to compute the
-exact length of the string, which may lead to collisions. Also, @TeX{}
-commands won't work with direct PostScript output (see @ref{PostScript
-output}).
-
@lilypond[fragment,relative,verbatim]
a'^"3 $\\times$ \\`a deux"
@end lilypond
-You can also use raw PostScript commands embedded in text scripts. This
-offers ultimate flexibility, but requires you to learn PostScript.
-Currently, embedded PostScript will @strong{not} work with direct
-PostScript output. Note that all dimensions that you use are in staff
-space.
-
-@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
-
@node Spacing
@subsection Spacing
TODO: Move this section.
-
@refbugs
* PostScript output::
* Scheme output::
* ASCIIScript output::
+* Sketch output::
@end menu
@node TeX output
usefulness gives ASCII Art output a low priority; it may be
dropped in future versions.
+
+@node Sketch output
+@subsection Sketch output
+
+@uref{http://sketch.sourceforge.net,Sketch} is a Free vector drawing
+program. LilyPond includes bare bones output for Sketch version 0.7.
+
+@cindex Sketch
+@cindex vector drawing
+@cindex drawing program
+
@c . {Sound}
@node Sound
@section Sound
@c FIXME: Note entry vs Music entry at top level menu is confusing.
@c . {Music entry}
-@node Music entry
-@section Music entry
-@cindex Music entry
-@menu
-* Relative::
-* Bar check::
-* Point and click::
-@end menu
-
-When entering music with LilyPond, it is easy to introduce errors. This
-section deals with tricks and features that help you enter music, and
-find and correct mistakes.
-
-@c . {Relative}
-@node Relative
-@subsection Relative
-@cindex Relative
-@cindex relative octave specification
-
-Octaves are specified by adding @code{'} and @code{,} to pitch names.
-When you copy existing music, it is easy to accidentally put a pitch in
-the wrong octave and hard to find such an error. To prevent these
-errors, LilyPond features octave entry.
-
-@cindex @code{\relative}
-@example
- \relative @var{startpitch} @var{musicexpr}
-@end example
-
-The octave of notes that appear in @var{musicexpr} are calculated as
-follows: If no octave changing marks are used, the basic interval
-between this and the last note is always taken to be a fourth or less
-(This distance is determined without regarding alterations; a
-@code{fisis} following a @code{ceses} will be put above the
-@code{ceses})
-
-The octave changing marks @code{'} and @code{,} can 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 @var{musicexpr}.
-
-Entering music that changes octave frequently is easy in relative mode.
-@lilypond[fragment,singleline,verbatim,center]
- \relative c'' {
- b c d c b c bes a
- }
-@end lilypond
-
-And octave changing marks are used for intervals greater than a fourth.
-@lilypond[fragment,verbatim,center]
- \relative c'' {
- c g c f, c' a, e'' }
-@end lilypond
-
-If the preceding item is a chord, the first note of the chord is used
-to determine the first note of the next chord. However, other notes
-within the second chord are determined by looking at the immediately
-preceding note.
-
-@lilypond[fragment,verbatim,center]
- \relative c' {
- c <c e g>
- <c' e g>
- <c, e' g>
- }
-@end lilypond
-@cindex @code{\notes}
-
-The pitch after the @code{\relative} contains a note name. To parse
-the pitch as a note name, you have to be in note mode, so there must
-be a surrounding @code{\notes} keyword (which is not
-shown here).
-
-The relative conversion will not affect @code{\transpose},
-@code{\chords} or @code{\relative} sections in its argument. If you
-want to use relative within transposed music, you must place an
-additional @code{\relative} inside the @code{\transpose}.
-
-
-@c . {Bar check}
-@node Bar check
-@subsection Bar check
-@cindex Bar check
-
-@cindex bar check
-@cindex @code{barCheckNoSynchronize}
-@cindex @code{|}
-
-
-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 find errors in the input. Depending on the value of
-@code{barCheckNoSynchronize}, the beginning of the measure will be
-relocated, so this can also be used to shorten measures.
-
-A bar check is entered using the bar symbol, @code{|}:
-@example
- \time 3/4 c2 e4 | g2.
-@end example
-
-
-
-@cindex skipTypesetting
-
-Failed bar checks are most often caused by entering incorrect
-durations. Incorrect durations often completely garble up the score,
-especially if it is polyphonic, so you should start correcting the score
-by scanning for failed bar checks and incorrect durations. To speed up
-this process, you can use @code{skipTypesetting} (See @ref{Skipping
-corrected music})). Bar
-
-
-@c . {Point and click}
-@node Point and click
-@subsection Point and click
-
-Point and click lets you find notes in the input by clicking on them in
-the Xdvi window. This makes it very easy to find input that causes some
-error in the sheet music.
-
-To use it, you need the following software
-
-@unnumberedsubsec Installation
-
-@itemize @bullet
-@item
-@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
-Xdvi} version 22.36 or newer.
-
- Note that most @TeX{} distributions ship with xdvik, which is a
- different and less well maintained program. To find out which xdvi you
- are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
-@item emacs
-@end itemize
-
-Xdvi must be configured to find the TeX fonts and music
-fonts. Refer to the Xdvi documentation for more information.
-
-
-@unnumberedsubsec Using it
-
-Add one of these lines to the top of your .ly file. The first one is for
-line location only. The second one is more convenient, but requires
-patching @code{emacsclient} and @code{server.el}.
-
-@example
-#(set! point-and-click line-location)
-@end example
-
-In the emacs startup file (usually @file{~/.emacs}), add the following
-@example
-(server-start)
-@end example
-
-Make sure that the environment variable @code{XEDITOR} is set
-to
-@example
-emacsclient --no-wait +%l %f
-@end example
-The second one, that also specifies the column, only works if you have
-patched your emacsclient and server, and have compiled your @code{.ly}
-file using the @code{line-column-location} setting.
-
-When viewing, control-mousebutton 1 will take you to the originating
-spot in the @file{.ly} file. Control-mousebutton 2 will show all
-clickable boxes.
-
-
-@unnumberedsubsec Column location
-
-If you want emacs to jump to the exact spot (and not just the line) on a
-click, you must enable column positioning. To do so, you need to patch
-emacsclient. Apply @file{emacsclient.patch} (included with the source
-package) to @file{emacsclient.c} and @file{server.el} from the emacs
-source code. Recompile and stick the recompiled emacsclient into a bin
-directory, and put @file{server.el} into a elisp directory
-(e.g. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs}
-init file, before invoking server-start.
-
-@example
- (setq load-path (cons "~/usr/share/emacs" load-path))
-@end example
-
-Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}
-
-At the top of the @code{ly} file, replace the @code{set!} line with the
-following line
-@example
-#(set! point-and-click line-column-location)
-@end example
-
-One final hint: if you correct large files with point-and-click, then
-start correcting at the end of the file. When you start at the top, and
-insert one line, all subsequent locations will be off by a line.
-
-
-@refbugs
-
-When you convert the @TeX{} file to PostScript using @code{dvips}, it
-will complain about not finding @code{src:X:Y} files. Those complaints
-are harmless, and can be ignored.
-
-@node Skipping corrected music
-@section Skipping corrected music
-
-The property @code{Score.skipTypesetting} can be used to switch on and
-off typesetting completely during the interpretation phase. When
-typesetting is switched off, the music is processed much more quickly.
-You can use this to skip over the parts of a score that you have already
-checked for errors.
-
-@lilypond[fragment,singleline,verbatim]
-\relative c'' { c8 d
-\property Score.skipTypesetting = ##t
- e f g a g c, f e d
-\property Score.skipTypesetting = ##f
-c d b bes a g c2 }
-@end lilypond
-
-
@node Interpretation context
@section Interpretation context
* Identifiers::
* Music expressions::
* Manipulating music expressions::
+* Span requests::
* Assignments::
* Lexical modes::
* Ambiguities::
during a lilypond run.
@itemize @bullet
-@item Grob: short for Graphical object. See @ref{Grobs}.
+@item Grob: short for Graphical object.
@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.
@end menu
@node Span requests
-@subsubsection Span requests
+@subsection Span requests
@cindex Span requests
Notational constructs that start and end on different notes can be
@menu
* Comments::
* Direct Scheme::
-* Keywords::
-* Integers::
* Reals::
* Strings::
* Main input::
Scheme.
-@node Keywords
-@subsection Keywords
-@cindex Keywords
-
-
-Keywords start with a backslash, followed by a number of lower case
-alphabetic characters. These are all the keywords.
-
-@example
-apply arpeggio autochange spanrequest commandspanrequest
-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 pitch
-time times midi mm name pitchnames notes outputproperty
-override set revert partial paper penalty property pt
-relative remove repeat addlyrics partcombine score
-script stylesheet skip textscript tempo translator
-transpose type
-@end example
-
-@node Integers
-@subsection Integers
-
-@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.
-
@node Reals
@subsection Reals
@cindex real numbers
-
-
-
-
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:
@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. See
-See @ref{convert-ly} for more information on @code{convert-ly}.
+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. See the chapter
+@ref{Upgrading from older LilyPond versions} for more information on
+@code{convert-ly}.
@cindex convert-ly
* A piano excerpt:: Piano music
* Fine tuning a piece::
* An orchestral score:: Conductor's score and individual parts
-* Other ways to run LilyPond:: Other ways to run LilyPond
* Integrating text and music:: Integrating text and music
* End of tutorial:: The end
@end menu
is too old.
This version number is also used by the @code{convert-ly} program (See
-@ref{convert-ly}), which is used to update the file to the latest lily
-version.
+@ref{Upgrading from older LilyPond versions}), which is used to update
+the file to the latest lily version.
@separate
@example
true.
-@node Other ways to run LilyPond
-@section Other ways to run LilyPond
-
-Until now, you have been using @file{ly2dvi} to invoke LilyPond.
-There are three other routes. Firstly, there is a script called
-@code{lilypond-book}, that allows you to freely mix LilyPond input with
-Texinfo or \LaTeX input. For example, this manual was written using
-@code{lilypond-book}. It is discussed below and in @ref{lilypond-book}.
-
-
-Secondly, you can generate PostScript directly. This is useful if you
-can not or do not want to run @TeX{} on your system. To obtain direct
-PostScript output, invoke LilyPond as follows:
-@cindex PostScript output
-@example
-lilypond -f ps test.ly
-@end example
-You have to set some environment variables to view or print this output.
-More information can be found in @ref{Invoking LilyPond}. Since the
-direct Postscript generation has some problems, it is recommended
-to use @file{ly2dvi}.
-
-
-Thirdly, if you want to do special things with your output, you can run
-invoke LilyPond directly:
-@example
-lilypond test.ly
-@end example
-to produce plain @TeX{} output. Note that La@TeX{} will not work on the
-resulting @file{test.tex}. You must run plain @TeX{} on it.
-
-@cindex @TeX{}
-
-
-
-
-
@node Integrating text and music
@section Integrating text and music
hand, simply by importing a PostScript figure into your wordprocessor.
However, there is a also an automated procedure:
-If you use La@TeX{} or texinfo, you can mix text and LilyPond code. A
-script called @code{lilypond-book} will extract the music fragments, run
-LilyPond on them, and put back the resulting notation. lilypond-book is
-described fully in @ref{lilypond-book}, but here we show a small
-example. Since the example also contains explanatory text, we won't
-comment on the contents.
+If you use HTML, La@TeX{} or texinfo, you can mix text and LilyPond
+code. A script called @code{lilypond-book} will extract the music
+fragments, run LilyPond on them, and put back the resulting notation.
+This utility program is described fully in the chapter @ref{Merging text
+and music with lilypond-book}. Here we show a small example. Since the
+example also contains explanatory text, we won't comment on the
+contents.
@example
\documentclass[a4paper]@{article@}
MAJOR_VERSION=1
MINOR_VERSION=5
PATCH_LEVEL=64
-MY_PATCH_LEVEL=uu1
+MY_PATCH_LEVEL=uu2
# Use the above to send patches: MY_PATCH_LEVEL is always empty for a
# released version.
name = re.sub ('\.pf[ab]', '',fn)
name = re.sub ('-', ' ',name)
- print '%s -misc-%s-regular-r-normal--0-0-0-0-p-0-adobe-fontspecific' % (fn, name)
+ m = re.search ("([0-9]+)$", name)
+ designsize = 'normal'
+ if m:
+ designsize = m.group (1)
+ name = re.sub ("([0-9]+)$", "", name)
+
+ print '%s -lilypond-%s-regular-r-%s--0-0-0-0-p-0-adobe-fontspecific' % (fn, name, designsize)
Translator_group *tr = report_to_l ();
SCM mp = tr->get_property ("measurePosition");
- SCM sync= tr->get_property ("barCheckNoSynchronize");
+ SCM sync= tr->get_property ("barCheckSynchronize");
Moment * where =unsmob_moment (mp);
if (!where)
{
music_l ()->origin ()->warning (_f ("barcheck failed at: %s",
where->str ()));
- if (!to_boolean (sync))
+ if (to_boolean (sync))
{
tr = tr->where_defined (ly_symbol2scm("measurePosition"));
Moment zero;
LY_DEFINE(ly_get_grob_property,
"ly-get-grob-property", 2, 0, 0, (SCM grob, SCM sym),
- " Get the value of a value in grob @var{g} of property @var{sym}. It
+ "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.
+
+Grob properties are stored as GUILE association lists, with symbols as
+keys. All lookup functions identify undefined properties with
+end-of-list (i.e. @code{'()} in Scheme or @code{SCM_EOL} in C)
+
+Properties are stored in two ways:
+@itemize @bullet
+@item mutable properties.
+Grob properties that change from object to object. The storage of
+these are private to a grob. For example pointers to other grobs are
+always stored in the mutable properties.
+
+@item immutable properties.
+Grob 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 default settings. They are
+initially read from @file{scm/grob-description.scm}.
+@end itemize
+
")
{
Grob * sc = unsmob_grob (grob);
IMPLEMENT_TYPE_P (Grob, "ly-grob?");
ADD_INTERFACE (Grob, "grob-interface",
- "All grobs support this",
+ "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 a node in that
+graph. The directed edges in the graph are formed by references to
+other grobs (i.e. pointers). This big graph of grobs specifies the
+notation problem. The solution of this problem is a description of the
+printout in closed form, i.e. a list of values. These values are
+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 (a.k.a. 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. When the note head is moved, the staccato dot moves along
+automatically.
+
+A grob is often associated with a symbol, but some grobs do not print
+any symbols. They take care of grouping objects. For example, there is a
+separate grob that stacks staves vertically. The @ref{NoteCollision}
+is also an abstract grob: it only moves around chords, but doesn't print
+anything.
+",
"X-offset-callbacks Y-offset-callbacks X-extent-callback molecule cause
Y-extent-callback molecule-callback extra-offset
spacing-procedure
staff-symbol interfaces dependencies extra-extent-X causes meta
layer before-line-breaking-callback after-line-breaking-callback extra-extent-Y minimum-extent-X minimum-extent-Y transparent");
+
#include "column-x-positions.hh"
#include "spanner.hh"
+/*
+ If you keep following offset reference points, you will always end
+up at the root object. This root object is called @ref{System}, and it
+represents a system (i.e. a line of music).
+
+
+ */
class System : public Spanner
{
public:
ADD_INTERFACE(Item,
"item-interface",
- "",
+ "
+
+Grobs can also be distinguished in their role in the horizontal spacing.
+Many 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}.
+
+",
"no-spacing-rods break-visibility breakable")
LY_DEFINE(ly_make_molecule,
"ly-make-molecule", 3, 0, 0, (SCM expr, SCM xext, SCM yext),
- "")
+ "
+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
+what-to-print-where information that also contains dimension information
+(how large is this glyph?).
+
+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 in the output file.")
{
SCM_ASSERT_TYPE (ly_number_pair_p (xext), xext, SCM_ARG2, __FUNCTION__, "number pair");
SCM_ASSERT_TYPE (ly_number_pair_p (yext), yext, SCM_ARG3, __FUNCTION__, "number pair");
ADD_INTERFACE(Spanner,
"spanner-interface",
- "",
+ "
+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 of the spanner.
+",
"minimum-length");
time-signature
custos
)
-
+ barCheckSynchronize = ##t
\grobdescriptions #all-grob-descriptions
}
%post
touch /tmp/.lilypond-install
-rm `find /var/lib/texmf -name 'feta*pk' -or -name 'feta*tfm' -or -name 'parmesan*pk' -or -name 'parmesan*tfm' -print'` /tmp/.lilypond-install
+rm `find /var/lib/texmf -name 'feta*pk' -or -name 'feta*tfm' -or -name 'parmesan*pk' -or -name 'parmesan*tfm' -print` /tmp/.lilypond-install
%if info=="yes"
/sbin/install-info %{_prefix}/info/lilypond.info.gz %{_prefix}/info/dir
((2 bold italic roman 12) . "cmbxti12")
((1 bold italic roman 12) . "cmbxti12")
((0 bold italic roman 10) . "cmbxti10")
+
((-1 bold italic roman 8) . "cmbxti8")
((-2 bold italic roman 7) . "cmbxti7")
;; put this in an alist?
-(grob-property-description 'X-extent-callback procedure? "procedure taking an grob and axis argument, returning a number-pair. The return value is the extent of the grob.")
-(grob-property-description 'X-offset-callbacks list? "list of functions, each taking an grob and axis argument. The function determine the position relative to this grob's parent. The last one in the list is called first.")
+(grob-property-description 'X-extent-callback procedure? "procedure taking an grob and axis argument, returning a number-pair. The return value is the extent of the grob.
+
+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
+(Scheme value @code{#f}) means: `empty in this direction'. If you fill
+in a pair of numbers, that pair hard-codes the extent in that
+coordinate.
+")
+(grob-property-description 'X-offset-callbacks list? "list of functions, each taking an grob and axis argument. The function determine the position relative to this grob's parent. The last one in the list is called first.
+
+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.
+
+Offset callbacks can be stacked, i.e.
+
+@example
+ \property .... \override #'Y-offset-callbacks = #(list
+ callback1 callback2 callback3)
+
+@end example
+
+The callbacks will be executed in the order @code{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, the staccato dot has two callbacks: one that positions the
+grob above or below the note head, and one that rounds the Y-position of
+the grob to the nearest open space.
+
+
+")
(grob-property-description 'Y-extent-callback procedure? "see @code{X-extent-callback}.")
(grob-property-description 'Y-offset-callbacks list? "see @code{X-offset-callbacks}.")
(grob-property-description 'accidentals list? "Alist with (PITCH
dots. This normal notation for some types of polyphonic music. The
value of this setting is used by @ref{note-collision-interface} .")
-(grob-property-description 'meta list? "Alist of meta information of this grob.")
+(grob-property-description 'meta list? "Alist of meta information of this grob.
+
+The alist contains the following entries: name, interfaces.
+
+
+
+")
(grob-property-description 'minimum-distance number? "minimum distance between notes and rests.")
(grob-property-description 'minimum-distances list? "list of rods (ie. (OBJ . DIST) pairs).")
(grob-property-description 'minimum-extent-X number-pair? "minimum size in X dimension, measured in staff space.")
? (cons LEFT RIGHT)
")
-(grob-property-description 'molecule-callback procedure? "Function taking grob as argument, returning a Scheme encoded Molecule.")
+(grob-property-description 'molecule-callback procedure? "Function
+taking grob as argument, returning a smobbed Molecule.
+
+All visible, i.e. non-transparent, grobs have a callback to create a
+Molecule. The callback should be a Scheme function taking one argument
+(the grob) and returning a Molecule. Most molecule callbacks are
+written in C++, but you can also write them in Scheme. An example is
+provided in @code{input/regression/molecule-hacking.ly}.
+")
(grob-property-description 'molecule molecule? "Cached output of the molecule-callback.")
[FIXME: type is too generic for this doc, move doco to intefrace]
")
-(grob-property-description 'break-visibility procedure? "a function that takes the break direction and returns a cons of booleans containing (TRANSPARENT . EMPTY).")
+
+(grob-property-description 'break-visibility procedure? "a function that takes the break direction and returns a cons of booleans containing (TRANSPARENT . EMPTY).
+
+
+Some items need special treatment for line breaking. For example, a
+clef is normally only printed at the start of a line (i.e. 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 @code{break-visibility}. This grob property is a
+function taking a direction (-1, 0 or 1) as argument. It returns a cons
+of booleans, signifying whether this grob should be transparent and have
+no extent.
+
+")
(grob-property-description 'when moment? "when does this column happen?.")
(grob-property-description 'word-space number? "elongate left by this much (FIXME: cumbersome semantics).")
(grob-property-description 'alignment number? "alignment of lyrics on notehead, -1 is LEFT, 0 is CENTRE, 1 is RIGHT .")
'tablature-interface
"tablature notes"
'())
+
+
+
+;; todo: figure out where to put this doco:
+
+"
+Grob properties form a name space where you can set variables per
+object. Each object however, may have multiple functions. For
+example, consider a dynamic symbol, such @code{\ff} (fortissimo). It
+is printed above or below the staff, it is a dynamic sign, and it is a
+kind of text.
+
+To reflect this different functions of a grob, procedures and variables
+are grouped into so-called interfaces. The dynamic text for example
+supports the following interfaces:
+@table @code
+@item font-interface
+ The glyph is built from characters from a font, hence the
+@code{font-interface}. For objects supporting @code{font-interface}, you
+can select alternate fonts by setting @code{font-style},
+@code{font-point-size}, etc.
+
+@item dynamic-interface
+ Dynamic interface is not associated with any variable or function in
+particular, but this makes it possible to distinguish this grob from
+other similar grobs (like @code{TextScript}), that have no meaning of
+dynamics.
+
+@item text-interface
+ This interface is for texts that are to be set using special routines
+to stack text into lines, using kerning, etc.
+
+@item general-grob-interface
+ This interface is supported by all grob types.
+@end table
+"
projects / lilypond.git / commitdiff