-@node Internals, , , top
+@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::
-* Molecule:: Molecule are stand-alone descriptions of output
+* Molecules:: Molecules are stand-alone descriptions of output
+* Font metrics:: Font metrics
@end menu
-
-@node Conversion stages, , , Internals
+@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:
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
@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.
@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
-@node Grobs, , , Internals
+@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
* Setting grob properties::
* Items and Spanners::
* Pointer substitution::
+* Grob Scheme functions::
@end menu
-@node What is a grob?, , , Grobs
+@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
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}
-@ref{(lilypond-internals)Element Line_of_score}, and it represents a
-system (ie. a line of music).
+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
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 NoteCollision
-@ref{(lilypond-internals)Element NoteCollision} is another example of
-an abstract grob. It only moves around chords, but doesn't print
-anything.
+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)Elements}
+@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
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{Molecule}) is extracted from
+description in the form of Molecules (@ref{Molecules}) is extracted from
the network. These are then dumped into the output file
-@node Callbacks, , , Grobs
+@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
hard-codes the extent in that coordinate.
-@node Setting grob properties, , , Grobs
+@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
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, , , Grobs
+@node Items and Spanners
@unnumberedsubsec Items and Spanners
Grobs can also be distinguished in their role in the horizontal spacing.
direction (-1, 0 or 1) and returns a cons of booleans, signifying wether
this grob should be transparent and invisible.
-@node Pointer substitution, , , Grobs
+@node Pointer substitution
@unnumberedsubsec Pointer substitution
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 Engraver, , , Internals
+@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 Music_iterator, , , Internals
-@node Music, , , Internals
+@node Engraver
+@section Engraver
-@node Molecule, , , Internals
+@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
what-to-print-where.
Conceptually, Molecules can be constructed from Scheme code, by
-translating a Molecule and by combining two molecules. In BNF notation:
+translating a Molecule and by combining two molecules. In BNF
+notation:
@example
Molecule = COMBINE Molecule Molecule
;
@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-transparent, grobs have a callback to create a Molecule. The
+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, , , top
+
+@node Development
@chapter Development
@menu
-* Coding standards::
+* CodingStyle::
* Making patches::
* Localisation::
+* Helping with development::
@end menu
+@node CodingStyle
@section CodingStyle - standards while programming for GNU LilyPond
As a general rule, you should always try to continue computations, even
Use them.
-@node Making patches, , , Top
-
+@node Making patches
+@section Making patches
@unnumberedsec Track and distribute your code changes
@end example
-@node Localisation, , , Top
-
-@chapter Localisation - User messages in LilyPond
-
-@section Introduction
+@node Localisation
+@section Localisation - User messages in LilyPond
This document provides some guidelines for uniformising user messages.
In the absence of other standards, we'll be using these rules when coding
Not-preferred messages are marked with @code{+}. By convention,
agrammatical examples are marked with @code{*}.
-@section Guidelines
+@subsection Guidelines
@itemize @bullet
Please don't run make po/po-update with GNU gettext < 0.10.35
@end itemize
+
+@node Helping with development
+@section Getting involved
+
+If you want to help developing LilyPond your efforts are appreciated.
+You can help LilyPond in several ways. Not all tasks requiring
+programming or understanding the full source code.
+
+Please don't expect us to give you instructions on what you should
+do. We're just a bunch of simple hackers, and we're absolutely
+incompetent about management, design in advance, delegating work.
+Some people write to us "I want to help, what should I do?", but we
+never know what to answer them.
+
+If you want to hack, just start hacking. You can send us the result as
+a patch, and we'll gladly incorporate it.
+
+If you need some hints on where to get started: there are a number of
+specific areas where you could do work.
+
+@unnumberedsubsec Users
+
+Mutopia needs your help. The mutopia project is a collection of public
+domain sheet music. You can help the project by entering music (either
+by hand, or by converting from scans or MIDI) and submitting it. Point
+your browser to the @uref{http://sca.uwaterloo.ca/Mutopia, Mutopia
+webpage}.
+
+@unnumberedsubsec Writers
+
+The documentation of LilyPond and related utilities needs a lot of
+work. The documentation is written in
+@uref{http://www.gnu.org/software/texinfo,texinfo}. The documentation of
+LilyPond is sorely lacking in terms of completeness, depth and
+organisation.
+
+Write if you know how to write english documentation in texinfo, and
+know about music and music notation. You must also know how to use
+LilyPond (or be prepared to learn using it). The task is not especially
+hard, but it is a lot of work, and you must be familiar with LilyPond.
+
+@unnumberedsubsec Translators
+
+LilyPond is completely ready for internationalized messages, but there
+are only a few translations so far (dutch, italian, german, japanese,
+french, russian). Translation involves writing a .po file, which is
+relatively easy, and does not even require running LilyPond.
+
+@unnumberedsubsec Hackers
+
+There are lots of possibilities of improving the program itself. There
+are both small projects and big ones. Most of them are listed in our
+TODO file, listed on the homepage of Jan and
+@uref{http://www.cs.uu.nl/~hanwen/lily-devel,Han-Wen}. Modifying
+LilyPond almost always requires patches to the C++ part.
+
+If you still don't have any idea what to do, you might want to browse
+the mailing lists; Users do lots of feature requests, and you could
+implement any of them.
+
+
+There are also numerous other interesting projects that are more or less
+related to LilyPond
+
+@itemize @bullet
+@item Writing convertors, eg. from NIFF and MIDI (we tried writing one with
+limited success: midi2ly, included with lilypond.)
+
+We found that writing them in Python is the easiest.
+
+@item Writing a GUI frontend to
+LilyPond. At the moment @uref{denemo,denemo.sourceforge.net} is the most
+advanced.
+
+@item Helping write @uref{http://solfege.sourceforge.net/,solfege
+tools}
+
+@item Helping @uref{primrose.sourceforge.net,primrose}, a tool for
+scanning sheet music.
+@end itemize
projects / lilypond.git / blobdiff