DOC -- more work on programming in the CG

diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi
index 6c0e3eceff9ac054ac14d8c0980777407afbc5ea..a5d38360de8d514ff8577bf1bd4c0b2b0abf7ccf 100644 (file)
--- a/Documentation/contributor/programming-work.itexi
+++ b/Documentation/contributor/programming-work.itexi
@@ -320,10 +320,13 @@ If you like using font-lock, you can also add this to your
                     ))
 @end verbatim
 
                     ))
 @end verbatim
 

+Some source files may not currently have proper indenting.  If this
+is the case, it is desirable to fix the improper indenting when the
+file is modified, with the hope of continually improving the code.
+

 @subsection Indenting files with emacs in script mode
 
 @c email to wl@gnu.org when I get here.
 @subsection Indenting files with emacs in script mode
 
 @c email to wl@gnu.org when I get here.

-@c should be moved to Indentation section

 
 @warning{this is pending some confirmation on -devel.  July 2009 -gp}
 
 
 @warning{this is pending some confirmation on -devel.  July 2009 -gp}
 


@@ -430,6 +433,28 @@ We reject broken-in-advance on principle.
 
 @subsection Naming
 
 
 @subsection Naming
 

+Variable names should be complete words, rather than abbreviations.
+For example, it is preferred to use @code{thickness} rather than
+@code{th} or @code{t}.
+
+Multi-word variable names in C++ should have the words separated
+by the underscore character (@q{_}).
+
+Multi-word variable names in Scheme should have the words separated
+by a hyphen (@q{-}).
+
+@subsection Comments
+
+Comments may not be needed if descriptive variable names are used
+in the code and the logic is straightforward.  However, if the
+logic is difficult to follow, and particularly if non-obvious
+code has been included to resolve a bug, a comment describing
+the logic and/or the need for the non-obvious code should be included.
+
+There are instances where the current code could be commented better.
+If significant time is required to understand the code as part of
+preparing a patch, it would be wise to add comments reflecting your
+understanding to make future work easier.

 
 @subsection Messages
 
 
 @subsection Messages
 


@@ -475,7 +500,7 @@ output strings (PostScript, TeX, etc.)
 @end itemize
 
 @item
 @end itemize
 
 @item

-Messages to be localised must be encapsulated in `_ (STRING)' or
+Messages to be localized must be encapsulated in `_ (STRING)' or

 `_f (FORMAT, ...)'. E.g.:
 
 @example
 `_f (FORMAT, ...)'. E.g.:
 
 @example


@@ -588,7 +613,7 @@ _f ("Huh?  Not a Request: `%s'.  Ignoring.", request)
 @end example
 
 @item
 @end example
 
 @item

-Do not modularise too much; words frequently cannot be translated
+Do not modularize too much; words frequently cannot be translated

 without context. It is probably safe to treat most occurences of
 words like stem, beam, crescendo as separately translatable words.
 
 without context. It is probably safe to treat most occurences of
 words like stem, beam, crescendo as separately translatable words.
 


@@ -1018,11 +1043,49 @@ the status.
 
 FIXME -- this is a placeholder for a tutorial on iterators
 
 
 FIXME -- 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
+performers.
+

 @node Engraver tutorial
 @section Engraver tutorial
 
 FIXME -- This is a placeholder for a tutorial on how engravers work.
 
 @node Engraver tutorial
 @section Engraver tutorial
 
 FIXME -- 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.  Each different
+type of grob has its own engraver.
+
+A typical engraver has protected functions including some or all
+of the following:
+
+@itemize
+@item @code{start_translation_timestep ()}
+@item @code{process_music ()}
+@item @code{stop_translation_timestep ()}
+@item @code{derived_mark ()}
+@item @code{try_music ()}
+@end itemize
+
+There are also protected functions that are specific to particular
+engraver, as needed by the engraving process.
+
+External interfaces to to the engraver are implemented by protected
+macros including one or more of the following:
+
+@itemize
+@item @code{DECLARE_ACKNOWLEDGER (grob)}
+@item @code{DECLARE_TRANSLATOR_LISTENER (grob)}
+@item @code{DECLARE_END_ACKNOWLEDGER (grob)}
+@end itemize
+
+where @var{grob} is the
+type of grob with which the engraver works.
+These macros declare the kinds of grobs that will be processed by
+the engraver.
+
+
+

 @node Callback tutorial
 @section Callback tutorial
 
 @node Callback tutorial
 @section Callback tutorial