LSR: Update.

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

diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi
index 676cecac06b89163d1f9581d5af9c41090aaecf7..ace1646b1bc546e03ff87b8d17b89027e035a518 100644 (file)
--- a/Documentation/contributor/programming-work.itexi
+++ b/Documentation/contributor/programming-work.itexi
@@ -1,4 +1,4 @@
-@c -*- coding: us-ascii; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
 @node Programming work
 @chapter Programming work
 
@@ -117,7 +117,7 @@ Interpretation of Computer Programs}, a popular textbook used to teach
 programming in Scheme is available in its entirety online.
 
 An introduction to Guile/Scheme as used in LilyPond can be found in the
-Learning Manual, see @rlearning{Scheme tutorial}.
+@rextend{Scheme tutorial}.
 
 @subsection MetaFont
 
@@ -715,16 +715,27 @@ out/bin/lilypond
 @end example
 
 This is important as you will need to let gdb know where to find the
-image.  You can invoke gdb from the command line using
+image containing the symbol tables.  You can invoke gdb from the
+command line using
 
 @example
-$ gdb out/bin/lilypond
+gdb out/bin/lilypond
 @end example
+@noindent
+This loads the LilyPond symbol tables into gdb.  Then, to run
+LilyPond on @code{test.ly} under the debugger, enter
+
+@example
+run test.ly
+@end example
+@noindent
+at the gdb prompt.
 
-or you may use a graphical interface to gdb such as ddd
+As an alternative to running gdb at the command line you may try
+a graphical interface to gdb such as ddd
 
 @example
-$ ddd out/bin/lilypond
+ddd out/bin/lilypond
 @end example
 
 You can also use sets of standard gdb commands stored in a .gdbinit
@@ -1187,7 +1198,7 @@ the status.
 @node Iterator tutorial
 @section Iterator tutorial
 
-FIXME -- this is a placeholder for a tutorial on iterators
+TODO -- this is a placeholder for a tutorial on iterators
 
 Iterators are routines written in C++ that process music expressions
 and sent the music events to the appropriate engravers and/or
@@ -1196,7 +1207,7 @@ performers.
 @node Engraver tutorial
 @section Engraver tutorial
 
-FIXME -- This is a placeholder for a tutorial on how engravers work.
+TODO -- This is a placeholder for a tutorial on how engravers work.
 
 Engravers are C++ classes that catch music events and
 create the appropriate grobs for display on the page.  Though the
@@ -1248,8 +1259,8 @@ processed prior to beginning the translation for the next timestep.
 
 In certain cases, an engraver might need to ensure private Scheme variables
 (with type SCM) do not get swept away by Guile's garbage collector: for example,
-a cache of the previous key signature which must persist persist between timesteps.
-The method @code{virtual derived_mark () const} can be used in such cases to mark
+a cache of the previous key signature which must persist between timesteps.  The
+method @code{virtual derived_mark () const} can be used in such cases to mark
 such objects as follows:
 
 @example
@@ -1262,7 +1273,7 @@ Engraver_name::derived_mark ()
 
 @subsection Listening to music events
 
-External interfaces to to the engraver are implemented by protected
+External interfaces to the engraver are implemented by protected
 macros including one or more of the following:
 
 @itemize
@@ -1355,7 +1366,7 @@ the engraver.
 @node Callback tutorial
 @section Callback tutorial
 
-FIXME -- This is a placeholder for a tutorial on callback functions.
+TODO -- This is a placeholder for a tutorial on callback functions.
 
 @node LilyPond scoping
 @section LilyPond scoping
@@ -1401,6 +1412,31 @@ This is a place to dump information that may be of use to developers
 but doesn't yet have a proper home.  Ideally, the length of this section
 would become zero as items are moved to other homes.
 
+@subsection Spacing algorithms
+
+Here is information from an email exchange about spacing algorithms.
+
+On Thu, 2010-02-04 at 15:33 -0500, Boris Shingarov wrote:
+I am experimenting with some modifications to the line breaking code,
+and I am stuck trying to understand how some of it works.  So far my
+understanding is that Simple_spacer operates on a vector of Grobs, and
+it is a well-known Constrained-QP problem (rods = constraints, springs
+= quadratic function to minimize).  What I don't understand is, if the
+spacer operates at the level of Grobs, which are built at an earlier
+stage in the pipeline, how are the changes necessitated by differences
+in line breaking, taken into account?  in other words, if I take the
+last measure of a line and place it on the next line, it is not just a
+matter of literally moving that graphic to where the start of the next
+line is, but I also need to draw a clef, key signature, and possibly
+other fundamental things -- but at that stage in the rendering
+pipeline, is it not too late??
+
+Joe Neeman answered:
+
+We create lots of extra grobs (eg. a BarNumber at every bar line) but
+most of them are not drawn. See the break-visibility property in
+item-interface.
+
 @subsection Info from Han-Wen Email
 
 In 2004, Douglas Linhardt decided to try starting a document that would