-@node Internals, , , top
+@node Internals, , , Top
@menu
* Conversion stages:: Lilypond is a multi-pass program.
-
* Grobs:: Graphical object
* Engraver::
* Music_iterator::
* Molecules:: Molecules are stand-alone descriptions of output
@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 Grobs, , , Internals
+@node Grobs
@section Grobs
This section is about Grobs (short for Graphical Objects), which are
* Pointer substitution::
@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
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 Engraver
+@section Engraver
-@node Music_iterator, , , Internals
+@node Music_iterator
+@section Music_iterator
-@node Music, , , Internals
+@node Music
+@section Music
-@node Molecules, , , Internals
+@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.
-@node Development, , , top
+@node Development, , , top
@chapter Development
@menu
* CodingStyle::
* Making patches::
* Localisation::
+* Helping with development::
@end menu
@node CodingStyle, , , Development
Use them.
@node Making patches, , , Development
-
+@section Making patches
@unnumberedsec Track and distribute your code changes
@end example
@node Localisation, , , Development
-
-@chapter Localisation - User messages in LilyPond
-
-@section Introduction
+@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, , , Development
+
+@chapter 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.
+
+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
+
+
+@node Invoking LilyPond, , , top
-@node Invoking LilyPond, , , Top
@chapter Invoking LilyPond
@cindex Invoking LilyPond
+@cindex command line options
+@cindex options, command line
+@cindex switches
@example
- @strong{lilypond} [OPTION]... [MUDELA-FILE]...
+ lilypond [OPTION]... [MUDELA-FILE]...
@end example
-@section Options
+@unnumberedsec Lilypond Command Options
@table @samp
@item -f,--format=
Output format for sheet music. Choices are tex (for @TeX{}
- output), ps (for PostScript) and scm (for GUILE)
+ output), ps (for PostScript) and scm (for a direct Scheme
+ dump)
+
@item -h,--help
Show a summary of usage.
@item --include, -I=DIRECTORY
adding `@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 defaults settings from within Scheme .}
+@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 Environment variables
projects / lilypond.git / commitdiff