Merge branch 'translation' into staging

[lilypond.git] / Documentation / contributor / programming-work.itexi

diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi
index 1ff0247a731a2fd725ae08507a12fca73fa9a3cd..205783513f87d0b0e5d5a61fcff6481b790fdf94 100644 (file)
--- a/Documentation/contributor/programming-work.itexi
+++ b/Documentation/contributor/programming-work.itexi
@@ -135,7 +135,7 @@ METAFONT tutorial page}.
 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
@@ -1311,6 +1311,10 @@ Regression tests should generally cover one issue per test.  Several
 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.
 
@@ -1567,6 +1571,9 @@ Iterators are routines written in C++ that process music expressions
 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
@@ -1877,11 +1884,6 @@ slice of the spanner than considering it on the whole.  This is useful
 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
@@ -2248,6 +2250,7 @@ would become zero as items are moved to other homes.
 * Spacing algorithms::
 * Info from Han-Wen email::
 * Music functions and GUILE debugging::
+* Articulations on EventChord::
 @end menu
 
 @node Spacing algorithms
@@ -2319,7 +2322,7 @@ classes because they play a special role in the linebreaking process.
 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
 
@@ -2653,3 +2656,30 @@ The breakpoint failing may have to do with the call sequence.  See
 @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).