From c7ac91598ed6ce3217bc104a52a24c951a385e98 Mon Sep 17 00:00:00 2001 From: Trevor Daniels Date: Wed, 2 Dec 2009 14:43:35 +0000 Subject: [PATCH] Docs: CG 8: Add a little about engravers --- .../contributor/programming-work.itexi | 33 +++++++++++++------ 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi index e9784a54ce..df0280c03b 100644 --- a/Documentation/contributor/programming-work.itexi +++ b/Documentation/contributor/programming-work.itexi @@ -1090,17 +1090,28 @@ 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_TRANSLATOR_LISTENER (event)} +@item @code{IMPLEMENT_TRANSLATOR_LISTENER (Engraver_name, event)} +@end itemize + +@noindent +where @var{event} is the type of event required to provide the input +the engraver needs and @code{Engraver_name} is the name of the +engraver. These macros set up the mechanism and declare the +methods for passing the information in events of this kind to the +engraver. + +Some engravers also need information from grobs as they are created +and as they terminate. The mechanism and methods to obtain this +information are set up by the macros: + @itemize @item @code{DECLARE_ACKNOWLEDGER (grob)} -@item @code{DECLARE_TRANSLATOR_LISTENER (grob)} @item @code{DECLARE_END_ACKNOWLEDGER (grob)} @end itemize -@noindent -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. +where @var{grob} is the type of grob of interest. An engraver will also generally have a public macro @@ -1109,10 +1120,12 @@ An engraver will also generally have a public macro @end itemize @noindent -where @code{Engraver_name} is the name of the engraver. +where @code{Engraver_name} is the name of the engraver. This +defines the common variables and methods used by every engraver. -At the end of the engraver file, the following macros are generally -called: +At the end of the engraver file, one or both of the following +macros are generally called to document the engraver in the +Internals Reference: @itemize @item @code{ADD_ACKNOWLEDGER (Engraver_name, grob)} @@ -1122,7 +1135,7 @@ called: @noindent where @code{Engraver_name} is the name of the engraver, @code{grob} -is a placeholder for a grob that will be acknowledged, +is the name of those grobs that will be acknowledged, @code{Engraver_doc} is a docstring for the engraver, @code{Engraver_creates} is the grob created by the engraver, @code{Engraver_reads} is the set of properties read by the engraver, -- 2.39.2