note on opers in resource howto

lib/resource-1.0/doc/Resource-HOWTO.html

@@ -7,7 +7,7 @@
 <P ALIGN="center"><CENTER><H1>Resource grammar writing HOWTO</H1>
 <FONT SIZE="4">
 <I>Author: Aarne Ranta &lt;aarne (at) cs.chalmers.se&gt;</I><BR>
-Last update: Sun Feb  5 15:22:34 2006
+Last update: Tue Feb  7 09:22:12 2006
 </FONT></CENTER>
 
 <P></P>
@@ -354,6 +354,35 @@ package.
 <LI><CODE>Predefined</CODE>: general-purpose operations with hard-coded definitions
 </UL>
 
+<P>
+An important decision is what rules to implement in terms of operations in
+<CODE>ResGer</CODE>. A golden rule of functional programming says that, whenever
+you find yourself programming by copy and paste, you should write a function
+instead. This indicates that an operation should be created if it is to be
+used at least twice. At the same time, a sound principle of vicinity says that
+it should not require too much browsing to understand what a rule does.
+From these two principles, we have derived the following practice:
+</P>
+<UL>
+<LI>If an operation is needed <I>in two different modules</I>, 
+it should be created in <CODE>ResGer</CODE>. An example is <CODE>mkClause</CODE>, 
+used in <CODE>Sentence</CODE>, <CODE>Question</CODE>, and <CODE>Relative</CODE>-
+<LI>If an operation is needed <I>twice in the same module</I>, but never
+outside, it should be created in the same module. Many examples are
+found in <CODE>Numerals</CODE>.
+<LI>If an operation is not needed once, it should not be created (but rather
+inlined). Most functions in phrase category modules are implemented in this
+way.
+</UL>
+
+<P>
+This discipline is very different from the one followed in earlier
+versions of the library (up to 0.9). We then valued the principle of
+abstraction more than vicinity, creating layers of abstraction for
+almost everything. This led in practice to the duplication of almost
+all code on the <CODE>lin</CODE> and <CODE>oper</CODE> levels, and made the code
+hard to understand and maintain.
+</P>
 <A NAME="toc10"></A>
 <H3>Morphology and lexicon</H3>
 <P>
@@ -670,6 +699,6 @@ This chapter will work out an example of how an Estonian grammar
 is constructed from the Finnish grammar through parametrization.
 </P>
 
-<!-- html code generated by txt2tags 2.3 (http://txt2tags.sf.net) -->
+<!-- html code generated by txt2tags 2.0 (http://txt2tags.sf.net) -->
 <!-- cmdline: txt2tags -\-toc -thtml Resource-HOWTO.txt -->
 </BODY></HTML>

lib/resource-1.0/doc/Resource-HOWTO.txt

@@ -297,6 +297,31 @@ package.
 - ``Predefined``: general-purpose operations with hard-coded definitions
 
 
+An important decision is what rules to implement in terms of operations in
+``ResGer``. A golden rule of functional programming says that, whenever
+you find yourself programming by copy and paste, you should write a function
+instead. This indicates that an operation should be created if it is to be
+used at least twice. At the same time, a sound principle of vicinity says that
+it should not require too much browsing to understand what a rule does.
+From these two principles, we have derived the following practice:
+- If an operation is needed //in two different modules//, 
+it should be created in ``ResGer``. An example is ``mkClause``, 
+used in ``Sentence``, ``Question``, and ``Relative``-
+- If an operation is needed //twice in the same module//, but never
+outside, it should be created in the same module. Many examples are
+found in ``Numerals``.
+- If an operation is not needed once, it should not be created (but rather
+inlined). Most functions in phrase category modules are implemented in this
+way.
+
+
+This discipline is very different from the one followed in earlier
+versions of the library (up to 0.9). We then valued the principle of
+abstraction more than vicinity, creating layers of abstraction for
+almost everything. This led in practice to the duplication of almost
+all code on the ``lin`` and ``oper`` levels, and made the code
+hard to understand and maintain.
+
 
 
 ===Morphology and lexicon===