Index: tools/swilena/ChangeLog
from Astrid Wang <astrid(a)lrde.epita.fr>
* doc/swilena.texi: Fix body.
Index: tools/swilena/doc/swilena.texi
--- tools/swilena/doc/swilena.texi Sat, 03 Jan 2004 17:25:53 +0100 burrus_n
(oln/n/40_swilena.te 1.1.1.3 600)
+++ tools/swilena/doc/swilena.texi Fri, 23 Jan 2004 17:47:58 +0100 astrid
(oln/n/40_swilena.te 1.1.1.3 600)
@@ -32,7 +32,7 @@
@node Top
@top Swilena
@end ifnottex
-This documents is intended to describe Swilena, a simplified set of
+This document is intended to describe Swilena, a simplified set of
wrappers around the image processing library Olena.
@menu
@@ -82,9 +82,9 @@
The primary target language for Swilena is Python, because Python is
the best supported back-end for SWIG. However, the SWIG definition
files of Swilena are not bound to a particular interpreted language:
-any SWIG target language @emph{providing enough expressivity} can be
+any SWIG target language @emph{providing enough expressiveness} can be
used. Ruby modules are defined too, they are not documented here but
-they work almost the same way than Python modules. Here are the
+they work almost the same way as Python modules. Here are the
required features from the interpreted language:
@itemize @bullet
@@ -102,29 +102,29 @@
Scheme.
Currently, the source tree only knows about Python and Ruby, but this
-may evolute in the future.
+may evolve in the future.
@unnumberedsubsec Using Swilena for Olena development
Obviously, Swilena provides the developer with a programming framework
around Olena that has much shorter development cycles: new algorithms
-can be tested in python without waiting for the compilation of test
-C++ sources.
+can be tested in Python without waiting for the compilation of C++ test
+sources.
-Moreover, because compiling Swilena actually means instanciating Olena
-templates for a nearly complete cartesian product of types, the success
+Moreover, because compiling Swilena actually means instantiating Olena
+templates for a nearly complete Cartesian product of types, the success
of the Swilena build process proves Olena's completeness.
@node Of SWIG and Swilena principles
@chapter Of SWIG and Swilena principles
As already suggested, Swilena and SWIG are closely related. In fact,
-SWIG is a wrapper generator, and Swilena is a set of input files for SWIG,
-bundled in a package providing appropriate @file{Makefile}'s to ease
+SWIG is a wrapper generator, and Swilena is a set of input files for SWIG
+bundled in a package providing appropriate @file{Makefile}s to ease
their handling.
-This sections provides some information about SWIG itself and presents
-the general guidelines that guided Swilena's development.
+This section provides some information about SWIG itself and presents
+the general guidelines that directed Swilena's development.
@menu
* Introduction to SWIG::
@@ -146,7 +146,7 @@
double My_variable = 3.0;
-/* Compute factorial of n */
+/* Compute n factorial */
int fact(int n) @{
if (n <= 1) return 1;
else return n*fact(n-1);
@@ -154,7 +154,7 @@
/* Compute n mod m */
int my_mod(int n, int m) @{
- return(n % m);
+ return n % m;
@}
@end cartouche
@end example
@@ -294,20 +294,23 @@
@item
SWIG knows about class constructors and references and treats them trivially.
@item
-The SWIG description need not follow exactly the strict C++ definition. In the previous
example,
-the Olena class @code{window2d} is far more complex than what is expressed in the SWIG
declaration;
-however, for a SWIG description to be valid, it only needs to describe a class more
@emph{general}
-than the real one.
+The SWIG description need not follow exactly the strict C++
+definition. In the previous example, the Olena class @code{window2d}
+is far more complex than what is expressed in the SWIG declaration;
+however, for a SWIG description to be valid, it only needs to describe
+a class more @emph{general} than the real one.
@item
-Although it is possible to do so, the SWIG description need not express class
inheritance.
+Although it is possible to do so, the SWIG description need not
+express class inheritance.
@end itemize
@node Operators and class extensions
@subsection Operators and class extensions
-When the target interpreted language allows overloading arithmetical operators for
classes, SWIG
-can propagate this C++ feature. However, if it does not, it is needed to provide an
artificial
- method-like interface to the class operators.
+When the target interpreted language allows overloading arithmetical
+operators for classes, SWIG can propagate this C++ feature. However,
+if it does not, it is needed to provide an artificial method-like
+interface to the class operators.
Here is a demonstration:
@@ -369,24 +372,28 @@
@end example
Here are the key points exhibited by this example:
-
@itemize @minus
@item
-When the interpreted language allows so, SWIG understands C++ operator overloading and
treats it trivially.
+When the interpreted language allows so, SWIG understands C++ operator
+overloading and treats it trivially.
@item
-The @code{%extend} SWIG sections allows adding pseudo-methods to interfaced classes. It
can be used to provide
-function names to C++ operators for interpreted languages that do no not cope with
operator overloading (e.g. Perl).
+The @code{%extend} SWIG sections allows adding pseudo-methods to
+interfaced classes. It can be used to provide function names to C++
+operators for interpreted languages that do no not cope with operator
+overloading (e.g. Perl).
@item
-When the description file includes @file{std_string.i}, SWIG knows about the C++ standard
type @code{std::string},
-and knows how to convert it to and from the interpreted language's native string
type.
+When the description file includes @file{std_string.i}, SWIG knows
+about the C++ standard type @code{std::string}, and knows how to
+convert it to and from the interpreted language's native string type.
@end itemize
@node SWIG and C++ templates
@subsection SWIG and C++ templates
-
-In addition to function, variables, structures and classes, SWIG knows about templates.
However, because scripting languages
-do not support templates and template instanciation, information must be provided to SWIG
to explain
-what template instances must be available to the scripting language.
+In addition to function, variables, structures and classes, SWIG knows
+about templates. However, because scripting languages do not support
+templates and template instanciation, information must be provided to
+SWIG to explain what template instances must be available to the
+scripting language.
Here is a demonstration:
@@ -450,9 +457,11 @@
@itemize @minus
@item
-SWIG can only wrap template @emph{instances}. The instanciation must be made explicit.
+SWIG can only wrap template @emph{instances}. The instantiation must
+be made explicit.
@item
-However, when instanciating a template class, all its methods are instanciated at the
same time.
+However, when instantiating a template class, all its methods are
+instantiated at the same time.
@item
Template instances must be given a unique identifier
(e.g. @code{w_win2d_int}), because C++ template instance names
@@ -467,18 +476,19 @@
@itemize @minus
@item
-SWIG collates all C++ namespaces in the global module namespace. Therefore, beware
-of wrapped function or class names that appear simultaneously in several namespaces with
-different definitions: they are not handled properly by SWIG.
-
+SWIG collates all C++ namespaces in the global module
+namespace. Therefore, beware of wrapped function or class names that
+appear simultaneously in several namespaces with different
+definitions: they are not handled properly by SWIG.
@item
-The C++ parser in SWIG cannot deal with C++ template partial specialization. Therefore,
-C++ tricks such as static hierarchies and virtual types cannot be exposed to SWIG.
Consider
-hiding the static inheritance tree and exposing the most derived classes instead.
-
+The C++ parser in SWIG cannot deal with C++ template partial
+specialization. Therefore, C++ tricks such as static hierarchies and
+virtual types cannot be exposed to SWIG. Consider hiding the static
+inheritance tree and exposing the most derived classes instead.
@item
-Families of similar template functions cannot be instanciated with a single SWIG
directive.
-Use SWIG macros and appropriate naming conventions for this purpose:
+Families of similar template functions cannot be instantiated with a
+single SWIG directive. Use SWIG macros and appropriate naming
+conventions for this purpose:
@example
@cartouche
@@ -488,15 +498,15 @@
template<typename T>
void bar(T x);
-%define Instanciate_Templates_For(Type)
+%define Instantiate_Templates_For(Type)
%template (foo_ ## Type) foo<Type >;
%template (bar_ ## Type) bar<Type >;
%enddef
-Instanciate_Templates_For(int);
+Instantiate_Templates_For(int);
// yields foo_int and bar_int
-Instanciate_Templates_For(float);
+Instantiate_Templates_For(float);
// yields foo_float and bar_float
@end cartouche
@@ -523,13 +533,13 @@
@end example
The @code{>>>} text is the Python standard prompt, where
-you can enter python statements.
+you can enter Python statements.
You can also write Python programs as scripts, using the following
script template:
@example
-#! /usr/bin/python
+#! /usr/bin/env python
... your program here ...
@end example
@@ -537,9 +547,9 @@
@section Python Basics
-Python does not have mandatory statement terminators. Statements end at the end
-of the line. However, you can use the semicolon (@samp{;}) as
-a command separator.
+Python does not have mandatory statement terminators. Statements end
+at the end of the line. However, you can use the semicolon (@samp{;})
+as a command separator.
@example
>> @kbd{print "hello"}
@@ -550,7
+560,8 @@
@end example
-Python data types are the integer (signed), the float (C @samp{double}), and the
character string.
+Python data types are the integer (signed), the float (C
+@samp{double}), and the character string.
Constants can be expressed intuitively:
@example
@@ -626,7 +637,7 @@
@subsection Python Objects
By convention, standard Python Classes have names that start with
-a capital. This helps disambiguise class names and module names:
+a capital. This helps disambiguate class names and module names:
@example
>> @kbd{import random}
@@ -710,9 +721,12
@@
@item set
set the value of the indicated pixel.
@item ncols
-return the number of columns in the image. This method is valid for 1D, 2D and 3D
images.
+return the number of columns in the image. This method is valid for
+1D, 2D and 3D images.
+
@item nrows
-return the number of rows in the image. This method is only valid for 2D and 3D images.
+return the number of rows in the image. This method is only valid for
+2D and 3D images.
@item nslices
return the number of slices of a 3D image.
@end table
--
astrid