accomplish the various stages of the process, is described in this section. A
more complete description of the LilyPond architecture and internal program
execution is found in Erik Sandberg's
-@uref{http://lilypond.org/web/images/thesis-erik-sandberg.pdf, master's
+@uref{http://lilypond.org/website/pdf/thesis-erik-sandberg.pdf, master's
thesis}.
The first stage of LilyPond processing is @emph{parsing}. In the parsing
PostScript is used to generate graphical output. A brief PostScript tutorial
is @uref{http://local.wasp.uwa.edu.au/~pbourke/dataformats/postscript/,
available online}. The
-@uref{http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf, PostScript Language
+@uref{http://www.adobe.com/products/postscript/pdfs/PLRM.pdf, PostScript Language
Reference} is available online in PDF format.
@subsection Python
(ps), grobs (pgrob), and parsed music expressions (pmusic).
@example
-file lily/out/lilypond
+file $LILYPOND_GIT/build/out/bin/lilypond
b programming_error
b Grob::programming_error
short, single-issue regression tests are preferred to a single, long,
multiple-issue regression test.
+If the change in the output is small or easy to overlook, use bigger
+staff size -- 40 or more (up to 100 in extreme cases). Size 30 means
+"pay extra attention to details in general".
+
Use existing regression tests as templates to demonstrate the type of
header information that should be included in a regression test.
considered to function successfully.
Developers on Windows who are unable to build LilyPond should
-get help from a Linux or OSX developer to do the make tests.
+get help from a GNU/Linux or OSX developer to do the make tests.
@node Verify regression tests
@subheading Typical developer's edit/compile/test cycle
-TODO: is @code{[-j@var{X} CPU_COUNT=@var{X}]} useful for
-@code{test-baseline}, @code{check}, @code{clean},
-@code{test-redo}? Neil Puttock says it is useful for
-everything but @code{clean}, which is disk-limited.
-Need to check formally.
-
@itemize
@item
Initial test:
@example
make [-j@var{X}]
-make test-baseline
+make [-j@var{X} CPU_COUNT=@var{X}] test-baseline
make [-j@var{X} CPU_COUNT=@var{X}] check
@end example
@example
@emph{## edit source files, then...}
-make clean @emph{## only if needed (see below)}
-make [-j@var{X}] @emph{## only if needed (see below)}
-make test-redo @emph{## redo files differing from baseline}
-make [-j@var{X} CPU_COUNT=@var{X}] check @emph{## CPU_COUNT here?}
+make clean @emph{## only if needed (see below)}
+make [-j@var{X}] @emph{## only if needed (see below)}
+make [-j@var{X} CPU_COUNT=@var{X}] test-redo @emph{## redo files differing from baseline}
+make [-j@var{X} CPU_COUNT=@var{X}] check
@end example
@item
like those in the @file{scm/} and @file{ly/} directories, then
@command{make} is not needed before @command{make test-redo}.
-TODO: Fix the following paragraph. You can do @command{rm mf/out/*}
-instead of make clean, and you can probably do
-@command{make -C mf/ clean} as well, but I haven't checked it -- cds
-
Also, if you modify any font definitions in the @file{mf/}
directory then you must run @command{make clean} and
@command{make} before running @command{make test-redo}. This will
important differences that your change introduced, whether in the
layout, MIDI, performance or error reporting.
+You only need to use @command{make test-clean} to start from
+scratch, prior to running @command{make@tie{}test-baseline}. To
+check new modifications, all that is needed is to repeat
+@command{make@tie{}test-redo} and @command{make@tie{}test-check}
+(not forgetting @command{make} if needed).
+
and sent the music events to the appropriate engravers and/or
performers.
+See a short example discussing iterators and their duties in
+@ref{Articulations on EventChord}.
+
@node Engraver tutorial
@section Engraver tutorial
during line breaking, for example, when we want to estimate the Y-extent
of a spanner broken at given starting and ending columns.
-If the pure function you're writing takes more than three arguments
-(say, for example, a chained offset callback), this is not a problem:
-just make sure that the grob is the first argument and that start and
-end are the last two arguments.
-
@node How purity is defined and stored
@subsection How purity is defined and stored
* Spacing algorithms::
* Info from Han-Wen email::
* Music functions and GUILE debugging::
+* Articulations on EventChord::
@end menu
@node Spacing algorithms
A C(++) object that is encapsulated so it can be used as a Scheme
object. See GUILE info, "19.3 Defining New Types (Smobs)"
-@@subheading When is each C++ class constructed and used
+@subheading When is each C++ class constructed and used?
@itemize
@file{parser.yy}, run_music_function(). The function is called directly from
C++, without going through the GUILE evaluator, so I think that is why
there is no debugger trap.
+
+@node Articulations on EventChord
+@subsection Articulations on EventChord
+
+From David Kastrup's email
+@uref{http://lists.gnu.org/archive/html/lilypond-devel/2012-02/msg00189.html}:
+
+LilyPond's typesetting does not act on music expressions and music
+events. It acts exclusively on stream events. It is the act of
+iterators to convert a music expression into a sequence of stream events
+played in time order.
+
+The EventChord iterator is pretty simple: it just takes its "elements"
+field when its time comes up, turns every member into a StreamEvent and
+plays that through the typesetting process. The parser currently
+appends all postevents belonging to a chord at the end of "elements",
+and thus they get played at the same point of time as the elements of
+the chord. Due to this design, you can add per-chord articulations or
+postevents or even assemble chords with a common stem by using parallel
+music providing additional notes/events: the typesetter does not see a
+chord structure or postevents belonging to a chord, it just sees a
+number of events occuring at the same point of time in a Voice context.
+
+So all one needs to do is let the EventChord iterator play articulations
+after elements, and then adding to articulations in EventChord is
+equivalent to adding them to elements (except in cases where the order
+of events matters).