Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(3843)

Delta Between Two Patch Sets: Documentation/contributor/programming-work.itexi

Issue 160048: Make define-builtin-markup{,-list}-command #:category #:properties keywords (Closed)
Left Patch Set: This is an attempt to deal with the reported memory leak problem that I can't reproduce myself Created 14 years, 4 months ago
Right Patch Set: Fix module system description in CG to better match current situation. Created 14 years, 3 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « no previous file | no next file » | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 @c -*- coding: us-ascii; mode: texinfo; -*- 1 @c -*- coding: us-ascii; mode: texinfo; -*-
2 @node Programming work 2 @node Programming work
3 @chapter Programming work 3 @chapter Programming work
4 4
5 @menu 5 @menu
6 * Overview of LilyPond architecture:: 6 * Overview of LilyPond architecture::
7 * LilyPond programming languages:: 7 * LilyPond programming languages::
8 * Programming without compiling:: 8 * Programming without compiling::
9 * Finding functions:: 9 * Finding functions::
10 * Code style:: 10 * Code style::
11 * Debugging LilyPond:: 11 * Debugging LilyPond::
12 * Adding or modifying features:: 12 * Adding or modifying features::
13 * Iterator tutorial:: 13 * Iterator tutorial::
14 * Engraver tutorial:: 14 * Engraver tutorial::
15 * Callback tutorial:: 15 * Callback tutorial::
16 * LilyPond scoping::
16 @end menu 17 @end menu
17 18
18 @node Overview of LilyPond architecture 19 @node Overview of LilyPond architecture
19 @section Overview of LilyPond architecture 20 @section Overview of LilyPond architecture
20 21
21 LilyPond processes the input file into graphical and musical output in a 22 LilyPond processes the input file into graphical and musical output in a
22 number of stages. This process, along with the types of routines that 23 number of stages. This process, along with the types of routines that
23 accomplish the various stages of the process, is described in this section. A 24 accomplish the various stages of the process, is described in this section. A
24 more complete description of the LilyPond architecture and internal program 25 more complete description of the LilyPond architecture and internal program
25 execution is found in Erik Sandberg's 26 execution is found in Erik Sandberg's
(...skipping 19 matching lines...) Expand all
45 music event is assigned a moment, or a time in the music when the event 46 music event is assigned a moment, or a time in the music when the event
46 begins. 47 begins.
47 48
48 Each type of music event has an associated iterator. Iterators are defined in 49 Each type of music event has an associated iterator. Iterators are defined in
49 *-iterator.cc. During iteration, an 50 *-iterator.cc. During iteration, an
50 event's iterator is called to deliver that music event to the appropriate 51 event's iterator is called to deliver that music event to the appropriate
51 context(s). 52 context(s).
52 53
53 The final stage of LilyPond processing is @emph{translation}. During 54 The final stage of LilyPond processing is @emph{translation}. During
54 translation, music events are prepared for graphical or midi output. The 55 translation, music events are prepared for graphical or midi output. The
55 translation step is accomplished by translators or engravers (the distinction 56 translation step is accomplished by the polymorphic base class Translator
56 is unclear). 57 through its two derived classes: Engraver (for graphical output) and
57 58 Performer (for midi output).
58 Translators are defined in C++ files named *-engraver.cc. In *-engraver.cc, a 59
59 C++ class of Engraver type is created. The Engraver is also declared as a 60 Translators are defined in C++ files named *-engraver.cc and *-performer.cc.
60 translator. Much of the work of translating is handled by Scheme functions, 61 Much of the work of translating is handled by Scheme functions,
61 which is one of the keys to LilyPond's exceptional flexibility. 62 which is one of the keys to LilyPond's exceptional flexibility.
63
64 @sourceimage{architecture-diagram,,,png}
62 65
63 66
64 @node LilyPond programming languages 67 @node LilyPond programming languages
65 @section LilyPond programming languages 68 @section LilyPond programming languages
66 69
67 Programming in LilyPond is done in a variety of programming languages. Each 70 Programming in LilyPond is done in a variety of programming languages. Each
68 language is used for a specific purpose or purposes. This section describes 71 language is used for a specific purpose or purposes. This section describes
69 the languages used and provides links to reference manuals and tutorials for 72 the languages used and provides links to reference manuals and tutorials for
70 the relevant language. 73 the relevant language.
71 74
72 @subsection C++ 75 @subsection C++
73 76
74 The core functionality of LilyPond is implemented in C++. 77 The core functionality of LilyPond is implemented in C++.
75 78
76 C++ is so ubiquitous that it is difficult to identify either a reference 79 C++ is so ubiquitous that it is difficult to identify either a reference
77 manual or a tutorial. Programmers unfamiliar with C++ will need to spend some 80 manual or a tutorial. Programmers unfamiliar with C++ will need to spend some
78 time to learn the language before attempting to modify the C++ code. 81 time to learn the language before attempting to modify the C++ code.
79 82
80 The C++ code calls Scheme/GUILE through the GUILE interface, which is 83 The C++ code calls Scheme/GUILE through the GUILE interface, which is
81 documented in the 84 documented in the
82 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE 85 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE
83 Reference Manual}. 86 Reference Manual}.
87
88 @subsection Flex
89
90 The LilyPond lexer is implemented in Flex, an implementation of the Unix lex
91 lexical analyser generator. Resources for Flex can be found
92 @uref{http://flex.sourceforge.net/, here}.
84 93
85 @subsection GNU Bison 94 @subsection GNU Bison
86 95
87 The LilyPond parser is implemented in Bison, a GNU parser generator. The 96 The LilyPond parser is implemented in Bison, a GNU parser generator. The
88 Bison homepage is found at @uref{http://www.gnu.org/software/bison/, 97 Bison homepage is found at @uref{http://www.gnu.org/software/bison/,
89 gnu.org}. The manual (which includes both a reference and tutorial) is 98 gnu.org}. The manual (which includes both a reference and tutorial) is
90 @uref{http://www.gnu.org/software/bison/manual/index.html, available} in a 99 @uref{http://www.gnu.org/software/bison/manual/index.html, available} in a
91 variety of formats. 100 variety of formats.
92 101
93 @subsection GNU Make 102 @subsection GNU Make
94 103
95 GNU Make is used to control the compiling process and to build the 104 GNU Make is used to control the compiling process and to build the
96 documentation and the website. GNU Make documentation is available at 105 documentation and the website. GNU Make documentation is available at
97 @uref{http://www.gnu.org/software/make/manual/, the GNU website}. 106 @uref{http://www.gnu.org/software/make/manual/, the GNU website}.
98 107
99 @subsection GUILE or Scheme 108 @subsection GUILE or Scheme
100 109
101 GUILE is the dialect of Scheme that is used as LilyPond's extension language. M any extensions to LilyPond are written entirely in GUILE. The 110 GUILE is the dialect of Scheme that is used as LilyPond's extension language.
111 Many extensions to LilyPond are written entirely in GUILE. The
102 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, 112 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
103 GUILE Reference Manual} is available online. 113 GUILE Reference Manual} is available online.
104 114
105 @uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and 115 @uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and
106 Interpretation of Computer Programs}, a popular textbook used to teach 116 Interpretation of Computer Programs}, a popular textbook used to teach
107 programming in Scheme is available in its entirety online. 117 programming in Scheme is available in its entirety online.
108 118
109 An introduction to Guile/Scheme as used in LilyPond can be found in the 119 An introduction to Guile/Scheme as used in LilyPond can be found in the
110 Learning Manual, see @rlearning{Scheme tutorial}. 120 Learning Manual, see @rlearning{Scheme tutorial}.
111 121
(...skipping 639 matching lines...) Expand 10 before | Expand all | Expand 10 after
751 In order to experiment with Scheme programming in the LilyPond 761 In order to experiment with Scheme programming in the LilyPond
752 environment, it is convenient to have a Guile interpreter that 762 environment, it is convenient to have a Guile interpreter that
753 has all the LilyPond modules loaded. This requires the following 763 has all the LilyPond modules loaded. This requires the following
754 steps. 764 steps.
755 765
756 First, define a Scheme symbol for the active module 766 First, define a Scheme symbol for the active module
757 in the .ly file: 767 in the .ly file:
758 768
759 @example 769 @example
760 #(module-define! (resolve-module '(guile-user)) 770 #(module-define! (resolve-module '(guile-user))
761 'lilypond-module (current-module)) 771 'lilypond-module (current-module))
762 @end example 772 @end example
763 773
764 Second, place a Scheme function in the .ly file that gives an interactive Guile 774 Second, place a Scheme function in the .ly file that gives an interactive Guile
765 prompt: 775 prompt:
766 776
767 @example 777 @example
768 #(top-repl) 778 #(top-repl)
769 @end example 779 @end example
770 780
771 When the .ly file is compiled, this causes the compilation to be interrupted 781 When the .ly file is compiled, this causes the compilation to be interrupted
(...skipping 128 matching lines...) Expand 10 before | Expand all | Expand 10 after
900 The comment @qq{% begin verbatim} should be removed. The syntax of 910 The comment @qq{% begin verbatim} should be removed. The syntax of
901 the snippet should then be manually edited. 911 the snippet should then be manually edited.
902 912
903 Where snippets in Documentation/snippets are made obsolete, the snippet 913 Where snippets in Documentation/snippets are made obsolete, the snippet
904 should be copied to Documentation/snippets/new. The comments and 914 should be copied to Documentation/snippets/new. The comments and
905 texidoc strings should be removed as described above. Then the body 915 texidoc strings should be removed as described above. Then the body
906 of the snippet should be changed to: 916 of the snippet should be changed to:
907 917
908 @example 918 @example
909 \markup @{ 919 \markup @{
910 "This snippet is deprecated as of version X.Y.Z and 920 This snippet is deprecated as of version X.Y.Z and
911 will be removed from the documentation." 921 will be removed from the documentation.
912 @} 922 @}
913 @end example 923 @end example
914 924
915 @noindent 925 @noindent
916 where X.Y.Z is the version number for which the convert-ly rule was 926 where X.Y.Z is the version number for which the convert-ly rule was
917 written. 927 written.
918 928
919 Update the snippet files by running: 929 Update the snippet files by running:
920 930
921 @example 931 @example
922 scripts\auxiliar\makelsr.py 932 scripts/auxiliar/makelsr.py
923 @end example 933 @end example
924 934
925 Where the convert-ly rule is not able to automatically update regression 935 Where the convert-ly rule is not able to automatically update regression
926 tests, the regression tests in input/regression should be manually 936 tests, the regression tests in input/regression should be manually
927 edited. 937 edited.
928 938
929 Although it is not required, it is helpful if the developer 939 Although it is not required, it is helpful if the developer
930 can write relevant material for inclusion in the Notation 940 can write relevant material for inclusion in the Notation
931 Reference. If the developer does not feel qualified to write 941 Reference. If the developer does not feel qualified to write
932 the documentation, a documentation editor will be able to 942 the documentation, a documentation editor will be able to
933 write it from the regression tests. The text that is added to 943 write it from the regression tests. The text that is added to
934 or removed from the documentation should be changed only in 944 or removed from the documentation should be changed only in
935 the English version. 945 the English version.
936 946
937 @subsection Write NEWS entry 947 @subsection Edit changes.tely
938 948
939 An entry should be added to the NEWS file to describe the feature 949 An entry should be added to Documentation/changes.tely to describe
940 changes to be implemented. This is especially important for changes 950 the feature changes to be implemented. This is especially important
941 that change input file syntax. 951 for changes that change input file syntax.
942 952
943 Hints for NEWS file entries are given at the top of the NEWS file. 953 Hints for changes.tely entries are given at the top of the file.
944 954
945 New entries in NEWS go at the top of the file. 955 New entries in changes.tely go at the top of the file.
946 956
947 The NEWS entry should be written to show how the new change 957 The changes.tely entry should be written to show how the new change
948 improves LilyPond, if possible. 958 improves LilyPond, if possible.
949 959
950 @subsection Verify successful build 960 @subsection Verify successful build
951 961
952 When the changes have been made, successful completion must be 962 When the changes have been made, successful completion must be
953 verified by doing 963 verified by doing
954 964
955 @example 965 @example
956 make all 966 make all
957 make doc 967 make doc
958 @end example 968 @end example
959 969
960 When these commands complete without error, the patch is 970 When these commands complete without error, the patch is
961 considered to function successfully. 971 considered to function successfully.
962 972
963 Developers on Windows who are unable to build LilyPond should 973 Developers on Windows who are unable to build LilyPond should
964 get help from a Linux or OSX developer to do the make tests. 974 get help from a Linux or OSX developer to do the make tests.
965 975
966 @subsection Verify regression test 976 @subsection Verify regression test
967 977
968 In order to avoid breaking LilyPond, it is important to verify that 978 In order to avoid breaking LilyPond, it is important to verify that
969 the regression tests all succeed. This process is described in 979 the regression tests all succeed. This process is described in
970 @ref{Regression tests}. 980 @ref{Regression tests}.
971 981
972 @subsection Post patch for comments 982 @subsection Post patch for comments
973 983
974 For any change other than a minor change, a patch set should be 984 For any change other than a minor change, a patch set should be
975 posted on Rietveld for comment. This requires the use of an 985 posted on @uref{http://codereview.appspot.com/, Rietveld} for comment.
976 external package, git-cl. 986 This requires the use of an external package, git-cl, and an email
987 account on Google.
977 988
978 git-cl is installed by: 989 git-cl is installed by:
979 990
980 @example 991 @example
981 git clone git://neugierig.org/git-cl.git 992 git clone git://neugierig.org/git-cl.git
982 @end example 993 @end example
983 994
984 Then, add the git-cl directory to your PATH, or create a 995 Then, add the git-cl directory to your PATH, or create a
985 symbolic link to the git-cl and upload.py in one of your 996 symbolic link to the git-cl and upload.py in one of your
986 PATH directories (like usr/bin). git-cl will is then 997 PATH directories (like usr/bin). git-cl is then
987 configured by 998 configured by entering the command
988 999
989 @example 1000 @example
990 git-cl config 1001 git cl config
991 @end example 1002 @end example
992 1003
993 @noindent 1004 @noindent
994 and answering the questions that are asked. 1005 in the LilyPond git directory and answering the questions that
995 1006 are asked. If you do not understand the question answer with just
996 The patch set is posted by issuing the following command, after 1007 a newline (CR).
997 first committing all changes: 1008
998 1009 The patch set is posted to Rietveld as follows. Ensure your changes
999 @example 1010 are committed in a separate branch, which should differ from the
1000 git-cl upload <reference SHA1 ID> 1011 reference branch to be used by just the changes to be uploaded.
1012 If the reference branch is to be origin/master, ensure this is
1013 up-to-date. If necessary, use git rebase to rebase the branch
1014 containing the changes to the head of origin/master. Finally,
1015 check out branch with the changes and enter the command:
1016
1017 @example
1018 git cl upload <reference SHA1 ID>
1001 @end example 1019 @end example
1002 1020
1003 @noindent 1021 @noindent
1004 where <reference SHA1 ID> is the SHA1 ID of the commit to be used 1022 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1005 as a reference source for the patch (generally, this will be the 1023 as a reference source for the patch. Generally, this will be the
1006 SHA1 ID of origin/master). 1024 SHA1 ID of origin/master, and in that case the command
1007 1025
1008 After prompting for an email and a password, the patch set will be 1026 @example
1009 posted to Rietveld. 1027 git cl upload origin/master
1010 1028 @end example
1011 An email should then be sent to lilypond-devel, with a subject line 1029
1030 @noindent
1031 can be used.
1032
1033 After prompting for your Google email address and password, the
1034 patch set will be posted to Rietveld.
1035
1036 You should then announce the patch by sending
1037 an email to lilypond-devel, with a subject line
1012 starting with PATCH:, asking for comments on the patch. 1038 starting with PATCH:, asking for comments on the patch.
1013 1039
1014 As revisions are made in response to comments, successive patch sets 1040 As revisions are made in response to comments, successive patch sets
1015 for the same issue can be uploaded by reissuing the git-cl command. 1041 for the same issue can be uploaded by reissuing the git-cl command
1042 with the modified branch checked out.
1016 1043
1017 @subsection Push patch 1044 @subsection Push patch
1018 1045
1019 Once all the comments have been addressed, the patch can be pushed. 1046 Once all the comments have been addressed, the patch can be pushed.
1020 1047
1021 If the author has push privileges, the author will push the patch. 1048 If the author has push privileges, the author will push the patch.
1022 Otherwise, a developer with push privileges will push the patch. 1049 Otherwise, a developer with push privileges will push the patch.
1023 1050
1024 @subsection Closing the issues 1051 @subsection Closing the issues
1025 1052
1026 Once the patch has been pushed, all the relevant issues should be 1053 Once the patch has been pushed, all the relevant issues should be
1027 closed. 1054 closed.
1028 1055
1029 On Rietveld, the author should log in an close the issue either by 1056 On Rietveld, the author should log in an close the issue either by
1030 using the @q{Edit Issue} link, or by clicking the circled x icon 1057 using the @q{Edit Issue} link, or by clicking the circled x icon
1031 to the left of the issue name. 1058 to the left of the issue name.
1032 1059
1033 If the changes were in response to a feature request on the Google 1060 If the changes were in response to a feature request on the Google
1034 issue tracker for LilyPond, the author should change the status to 1061 issue tracker for LilyPond, the author should change the status to
1035 @q{Fixed_x_y_z} where the patch was fixed in version x.y.z. If 1062 Fixed and a tag @q{fixed_x_y_z} should be added, where the patch was
1063 fixed in version x.y.z. If
1036 the author does not have privileges to change the status, an email 1064 the author does not have privileges to change the status, an email
1037 should be sent to bug-lilypond requesting the BugMeister to change 1065 should be sent to bug-lilypond requesting the BugMeister to change
1038 the status. 1066 the status.
1039 1067
1040 @node Iterator tutorial 1068 @node Iterator tutorial
1041 @section Iterator tutorial 1069 @section Iterator tutorial
1042 1070
1043 FIXME -- this is a placeholder for a tutorial on iterators 1071 FIXME -- this is a placeholder for a tutorial on iterators
1044 1072
1045 Iterators are routines written in C++ that process music expressions 1073 Iterators are routines written in C++ that process music expressions
1046 and sent the music events to the appropriate engravers and/or 1074 and sent the music events to the appropriate engravers and/or
1047 performers. 1075 performers.
1048 1076
1049 @node Engraver tutorial 1077 @node Engraver tutorial
1050 @section Engraver tutorial 1078 @section Engraver tutorial
1051 1079
1052 FIXME -- This is a placeholder for a tutorial on how engravers work. 1080 FIXME -- This is a placeholder for a tutorial on how engravers work.
1053 1081
1054 Engravers are C++ classes that catch music events and 1082 Engravers are C++ classes that catch music events and
1055 create the appropriate grobs for display on the page. Each different 1083 create the appropriate grobs for display on the page. Though the
1056 type of grob has its own engraver. 1084 majority of engravers are responsible for the creation of a single grob,
1057 1085 in some cases (e.g. @code{New_fingering_engraver}), several different grobs
1058 A typical engraver has protected functions including some or all 1086 may be created.
1059 of the following: 1087
1088 @subsection Useful methods for information processing
1089
1090 An engraver inherits the following public methods from the Translator
1091 base class, which can be used to process listened events and acknowledged
1092 grobs:
1060 1093
1061 @itemize 1094 @itemize
1062 @item @code{start_translation_timestep ()} 1095 @item @code{virtual void initialize ()}
1063 @item @code{process_music ()} 1096 @item @code{void start_translation_timestep ()}
1064 @item @code{stop_translation_timestep ()} 1097 @item @code{void process_music ()}
1065 @item @code{derived_mark ()} 1098 @item @code{void process_acknowledged ()}
1066 @item @code{try_music ()} 1099 @item @code{void stop_translation_timestep ()}
1067 @item @code{finalize ()} 1100 @item @code{virtual void finalize ()}
1068 @end itemize 1101 @end itemize
1069 1102
1070 There are also protected functions that are specific to particular 1103 These methods are listed in order of translation time, with
1071 engraver, as needed by the engraving process. 1104 @code{initialize ()} and @code{finalize ()} bookending the whole
1105 process. @code{initialize ()} can be used for one-time initialization
1106 of context properties before translation starts, whereas
1107 @code{finalize ()} is often used to tie up loose ends at the end of
1108 translation: for example, an unterminated spanner might be completed
1109 automatically or reported with a warning message.
1110
1111 @subsection Translation process
1112
1113 At each timestep in the music, translation proceeds by calling the
1114 following methods in turn:
1115
1116 @code{start_translation_timestep ()} is called before any user information enter s
1117 the translators, i.e., no property operations (\set, \override, etc.) or events
1118 have been processed yet.
1119
1120 @code{process_music ()} and @code{process_acknowledged ()} are called after even ts
1121 have been heard, or grobs have been acknowledged. The latter tends to be used
1122 exclusively with engravers which only acknowledge grobs, whereas the former is
1123 the default method for main processing within engravers.
1124
1125 @code{stop_translation_timestep ()} is called after all user information has bee n
1126 processed prior to beginning the translation for the next timestep.
1127
1128 @subsection Preventing garbage collection for SCM member variables
1129
1130 In certain cases, an engraver might need to ensure private Scheme variables
1131 (with type SCM) do not get swept away by Guile's garbage collector: for example,
1132 a cache of the previous key signature which must persist persist between timeste ps.
1133 The method @code{virtual derived_mark () const} can be used in such cases to mar k
1134 such objects as follows:
1135
1136 @example
1137 Engraver_name::derived_mark ()
1138 @{
1139 scm_gc_mark (private_scm_member_)
1140 @}
1141 @end example
1142
1143
1144 @subsection Listening to music events
1072 1145
1073 External interfaces to to the engraver are implemented by protected 1146 External interfaces to to the engraver are implemented by protected
1074 macros including one or more of the following: 1147 macros including one or more of the following:
1075 1148
1076 @itemize 1149 @itemize
1077 @item @code{DECLARE_ACKNOWLEDGER (grob)} 1150 @item @code{DECLARE_TRANSLATOR_LISTENER (event_name)}
1078 @item @code{DECLARE_TRANSLATOR_LISTENER (grob)} 1151 @item @code{IMPLEMENT_TRANSLATOR_LISTENER (Engraver_name, event_name)}
1079 @item @code{DECLARE_END_ACKNOWLEDGER (grob)}
1080 @end itemize 1152 @end itemize
1081 1153
1082 @noindent 1154 @noindent
1083 where @var{grob} is the 1155 where @var{event_name} is the type of event required to provide the
1084 type of grob with which the engraver works. 1156 input the engraver needs and @var{Engraver_name} is the name of the
1085 These macros declare the kinds of grobs that will be processed by 1157 engraver.
1086 the engraver. 1158
1087 1159 Following declaration of a listener, the method is implemented as follows:
1088 An engraver will also generally have a public macro 1160
1161 @example
1162 IMPLEMENT_TRANSLATOR_LISTENER (Engraver_name, event_name)
1163 void
1164 Engraver_name::listen_event_name (Stream event *event)
1165 @{
1166 ...body of listener method...
1167 @}
1168 @end example
1169
1170 @subsection Acknowledging grobs
1171
1172 Some engravers also need information from grobs as they are created
1173 and as they terminate. The mechanism and methods to obtain this
1174 information are set up by the macros:
1175
1176 @itemize
1177 @item @code{DECLARE_ACKNOWLEDGER (grob_interface)}
1178 @item @code{DECLARE_END_ACKNOWLEDGER (grob_interface)}
1179 @end itemize
1180
1181 where @var{grob_interface} is an interface supported by the
1182 grob(s) which should be acknowledged. For example, the following
1183 code would declare acknowledgers for a @code{NoteHead} grob (via the
1184 @code{note-head-interface}) and any grobs which support the
1185 @code{side-position-interface}:
1186
1187 @example
1188 @code{DECLARE_ACKNOWLEDGER (note_head)}
1189 @code{DECLARE_ACKNOWLEDGER (side_position)}
1190 @end example
1191
1192 The @code{DECLARE_END_ACKNOWLEDGER ()} macro sets up a spanner-specific
1193 acknowledger which will be called whenever a spanner ends.
1194
1195 Following declaration of an acknowledger, the method is coded as follows:
1196
1197 @example
1198 void
1199 Engraver_name::acknowledge_interface_name (Grob_info info)
1200 @{
1201 ...body of acknowledger method...
1202 @}
1203 @end example
1204
1205 @subsection Engraver declaration/documentation
1206
1207 An engraver must have a public macro
1089 1208
1090 @itemize 1209 @itemize
1091 @item @code{TRANSLATOR_DECLARATIONS (Engraver_name)} 1210 @item @code{TRANSLATOR_DECLARATIONS (Engraver_name)}
1092 @end itemize 1211 @end itemize
1093 1212
1094 @noindent 1213 @noindent
1095 where @code{Engraver_name} is the name of the engraver. 1214 where @code{Engraver_name} is the name of the engraver. This
1096 1215 defines the common variables and methods used by every engraver.
1097 At the end of the engraver file, the following macros are generally 1216
1098 called: 1217 At the end of the engraver file, one or both of the following
1218 macros are generally called to document the engraver in the
1219 Internals Reference:
1099 1220
1100 @itemize 1221 @itemize
1101 @item @code{ADD_ACKNOWLEDGER (Engraver_name, grob)} 1222 @item @code{ADD_ACKNOWLEDGER (Engraver_name, grob_interface)}
1102 @item @code{ADD_TRANSLATOR (Engraver_name, Engraver_doc, 1223 @item @code{ADD_TRANSLATOR (Engraver_name, Engraver_doc,
1103 Engraver_creates, Engraver_reads, Engraver_writes)} 1224 Engraver_creates, Engraver_reads, Engraver_writes)}
1104 @end itemize 1225 @end itemize
1105 1226
1106 @noindent 1227 @noindent
1107 where @code{Engraver_name} is the name of the engraver, @code{grob} 1228 where @code{Engraver_name} is the name of the engraver, @code{grob_interface}
1108 is a placeholder for a grob that will be acknowledged, 1229 is the name of the interface that will be acknowledged,
1109 @code{Engraver_doc} is a docstring for the engraver, 1230 @code{Engraver_doc} is a docstring for the engraver,
1110 @code{Engraver_creates} is the grob created by the engraver, 1231 @code{Engraver_creates} is the set of grobs created by the engraver,
1111 @code{Engraver_reads} is the set of properties read by the engraver, 1232 @code{Engraver_reads} is the set of properties read by the engraver,
1112 and @code{Engraver_writes} is the set of properties written by 1233 and @code{Engraver_writes} is the set of properties written by
1113 the engraver. 1234 the engraver.
1114 1235
1115 @node Callback tutorial 1236 @node Callback tutorial
1116 @section Callback tutorial 1237 @section Callback tutorial
1117 1238
1118 FIXME -- This is a placeholder for a tutorial on callback functions. 1239 FIXME -- This is a placeholder for a tutorial on callback functions.
1119 1240
1241 @node LilyPond scoping
1242 @section LilyPond scoping
1243
1244 The Lilypond language has a concept of scoping, ie you can do
Ian Hulin 2009/12/26 20:05:16 "The Lilyond language has a concept of scoping, i.
1245
1246 @example
1247 foo = 1
1248
1249 #(begin
1250 (display (+ foo 2)))
1251 @end example
1252
1253 @noindent with @code{\paper}, @code{\midi} and @code{\header} being
Ian Hulin 2009/12/26 20:05:16 @noindent. @code{\paper}, @code{\midi} and @code{
1254 nested scope inside the @file{.ly} file-level scope. @w{@code{foo = 1}}
Ian Hulin 2009/12/26 20:05:16 "nested scope" --> "scope definitions nested"
1255 is translated in to a scheme variable definition.
1256
1257 This implemented using modules, with each scope being an anonymous
Ian Hulin 2009/12/26 20:05:16 "This is implemented using modules; each of these
1258 module that imports its enclosing scope's module.
Ian Hulin 2009/12/26 20:05:16 See comment for above line.
1259
1260 Lilypond's core, loaded from @file{.scm} files, is usually placed in the
1261 @code{lily} module, outside the @file{.ly} level. In the case of
Ian Hulin 2009/12/26 20:05:16 Lilypond's core, loaded from various @file{.scm} f
1262
1263 @example
1264 lilypond a.ly b.ly
1265 @end example
1266
1267 @noindent
1268 we want to reuse the built-in definitions, without changes effected in
Ian Hulin 2009/12/26 20:05:16 Here we want to re-use the built-in definitions wi
1269 user-level @file{a.ly} leaking into the processing of @file{b.ly}.
1270
1271 The user-accessible definition commands have to take care to avoid
1272 memory leaks that could occur when running multiple files. All
Ian Hulin 2009/12/26 20:05:16 "memory leaks which could occur when compiling mor
1273 information belonging to user-defined commands and markups is stored in
1274 a manner that allows it to be garbage-collected when the module is
1275 dispersed, either by being stored module-locally, or in weak hash
1276 tables.
LEFTRIGHT
« no previous file | no next file » | Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Toggle Comments ('s')

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b