+language? C++ is not perfect: type checking is not strict (casting is
+possible), separation between interface and implementation is not
+complete, object oriented design is not enforced. The main reason is
+the often scolded feature of operator overloading in C++. While it may
+be true that operating on classes with a @code{+} operator is rarely
+meaningful, it is perfectly suited for algebraic expressions. Writing
+@math{3x+5y} as @code{3*x+5*y} instead of
+@code{x.times(3).plus(y.times(5))} looks much more natural.
+Furthermore, the main developers are more familiar with C++ than with
+any other programming language.
+
+
+@node Internal Structures, Expressions are reference counted, Why C++? , Top
+@c node-name, next, previous, up
+@appendix Internal Structures
+
+@menu
+* Expressions are reference counted::
+* Internal representation of products and sums::
+@end menu
+
+@node Expressions are reference counted, Internal representation of products and sums, Internal Structures, Internal Structures
+@c node-name, next, previous, up
+@appendixsection Expressions are reference counted
+
+@cindex reference counting
+@cindex copy-on-write
+@cindex garbage collection
+An expression is extremely light-weight since internally it works like a
+handle to the actual representation and really holds nothing more than a
+pointer to some other object. What this means in practice is that
+whenever you create two @code{ex} and set the second equal to the first
+no copying process is involved. Instead, the copying takes place as soon
+as you try to change the second. Consider the simple sequence of code:
+
+@example
+#include <ginac/ginac.h>
+using namespace GiNaC;
+
+int main()
+@{
+ symbol x("x"), y("y"), z("z");
+ ex e1, e2;
+
+ e1 = sin(x + 2*y) + 3*z + 41;
+ e2 = e1; // e2 points to same object as e1
+ cout << e2 << endl; // prints sin(x+2*y)+3*z+41
+ e2 += 1; // e2 is copied into a new object
+ cout << e2 << endl; // prints sin(x+2*y)+3*z+42
+ // ...
+@}
+@end example
+
+The line @code{e2 = e1;} creates a second expression pointing to the
+object held already by @code{e1}. The time involved for this operation
+is therefore constant, no matter how large @code{e1} was. Actual
+copying, however, must take place in the line @code{e2 += 1;} because
+@code{e1} and @code{e2} are not handles for the same object any more.
+This concept is called @dfn{copy-on-write semantics}. It increases
+performance considerably whenever one object occurs multiple times and
+represents a simple garbage collection scheme because when an @code{ex}
+runs out of scope its destructor checks whether other expressions handle
+the object it points to too and deletes the object from memory if that
+turns out not to be the case. A slightly less trivial example of
+differentiation using the chain-rule should make clear how powerful this
+can be:
+
+@example
+#include <ginac/ginac.h>
+using namespace GiNaC;
+
+int main()
+@{
+ symbol x("x"), y("y");
+
+ ex e1 = x + 3*y;
+ ex e2 = pow(e1, 3);
+ ex e3 = diff(sin(e2), x); // first derivative of sin(e2) by x
+ cout << e1 << endl // prints x+3*y
+ << e2 << endl // prints (x+3*y)^3
+ << e3 << endl; // prints 3*(x+3*y)^2*cos((x+3*y)^3)
+ // ...
+@}
+@end example
+
+Here, @code{e1} will actually be referenced three times while @code{e2}
+will be referenced two times. When the power of an expression is built,
+that expression needs not be copied. Likewise, since the derivative of
+a power of an expression can be easily expressed in terms of that
+expression, no copying of @code{e1} is involved when @code{e3} is
+constructed. So, when @code{e3} is constructed it will print as
+@code{3*(x+3*y)^2*cos((x+3*y)^3)} but the argument of @code{cos()} only
+holds a reference to @code{e2} and the factor in front is just
+@code{3*e1^2}.
+
+As a user of GiNaC, you cannot see this mechanism of copy-on-write
+semantics. When you insert an expression into a second expression, the
+result behaves exactly as if the contents of the first expression were
+inserted. But it may be useful to remember that this is not what
+happens. Knowing this will enable you to write much more efficient
+code. If you still have an uncertain feeling with copy-on-write
+semantics, we recommend you have a look at the
+@uref{http://www.cerfnet.com/~mpcline/c++-faq-lite/, C++-FAQ lite} by
+Marshall Cline. Chapter 16 covers this issue and presents an
+implementation which is pretty close to the one in GiNaC.
+
+
+@node Internal representation of products and sums, Package Tools, Expressions are reference counted, Internal Structures
+@c node-name, next, previous, up
+@appendixsection Internal representation of products and sums
+
+@cindex representation
+@cindex @code{add}
+@cindex @code{mul}
+@cindex @code{power}
+Although it should be completely transparent for the user of
+GiNaC a short discussion of this topic helps to understand the sources
+and also explain performance to a large degree. Consider the
+unexpanded symbolic expression
+@tex
+$2d^3 \left( 4a + 5b - 3 \right)$
+@end tex
+@ifnottex
+@math{2*d^3*(4*a+5*b-3)}
+@end ifnottex
+which could naively be represented by a tree of linear containers for
+addition and multiplication, one container for exponentiation with base
+and exponent and some atomic leaves of symbols and numbers in this
+fashion:
+
+@image{repnaive}
+
+@cindex pair-wise representation
+However, doing so results in a rather deeply nested tree which will
+quickly become inefficient to manipulate. We can improve on this by
+representing the sum as a sequence of terms, each one being a pair of a
+purely numeric multiplicative coefficient and its rest. In the same
+spirit we can store the multiplication as a sequence of terms, each
+having a numeric exponent and a possibly complicated base, the tree
+becomes much more flat:
+
+@image{reppair}
+
+The number @code{3} above the symbol @code{d} shows that @code{mul}
+objects are treated similarly where the coefficients are interpreted as
+@emph{exponents} now. Addition of sums of terms or multiplication of
+products with numerical exponents can be coded to be very efficient with
+such a pair-wise representation. Internally, this handling is performed
+by most CAS in this way. It typically speeds up manipulations by an
+order of magnitude. The overall multiplicative factor @code{2} and the
+additive term @code{-3} look somewhat out of place in this
+representation, however, since they are still carrying a trivial
+exponent and multiplicative factor @code{1} respectively. Within GiNaC,
+this is avoided by adding a field that carries an overall numeric
+coefficient. This results in the realistic picture of internal
+representation for
+@tex
+$2d^3 \left( 4a + 5b - 3 \right)$:
+@end tex
+@ifnottex
+@math{2*d^3*(4*a+5*b-3)}:
+@end ifnottex
+
+@image{repreal}
+
+@cindex radical
+This also allows for a better handling of numeric radicals, since
+@code{sqrt(2)} can now be carried along calculations. Now it should be
+clear, why both classes @code{add} and @code{mul} are derived from the
+same abstract class: the data representation is the same, only the
+semantics differs. In the class hierarchy, methods for polynomial
+expansion and the like are reimplemented for @code{add} and @code{mul},
+but the data structure is inherited from @code{expairseq}.
+
+
+@node Package Tools, ginac-config, Internal representation of products and sums, Top
+@c node-name, next, previous, up
+@appendix Package Tools
+
+If you are creating a software package that uses the GiNaC library,
+setting the correct command line options for the compiler and linker
+can be difficult. GiNaC includes two tools to make this process easier.
+
+@menu
+* ginac-config:: A shell script to detect compiler and linker flags.
+* AM_PATH_GINAC:: Macro for GNU automake.
+@end menu
+
+
+@node ginac-config, AM_PATH_GINAC, Package Tools, Package Tools
+@c node-name, next, previous, up
+@section @command{ginac-config}
+@cindex ginac-config
+
+@command{ginac-config} is a shell script that you can use to determine
+the compiler and linker command line options required to compile and
+link a program with the GiNaC library.
+
+@command{ginac-config} takes the following flags:
+
+@table @samp
+@item --version
+Prints out the version of GiNaC installed.
+@item --cppflags
+Prints '-I' flags pointing to the installed header files.
+@item --libs
+Prints out the linker flags necessary to link a program against GiNaC.
+@item --prefix[=@var{PREFIX}]
+If @var{PREFIX} is specified, overrides the configured value of @env{$prefix}.
+(And of exec-prefix, unless @code{--exec-prefix} is also specified)
+Otherwise, prints out the configured value of @env{$prefix}.
+@item --exec-prefix[=@var{PREFIX}]
+If @var{PREFIX} is specified, overrides the configured value of @env{$exec_prefix}.
+Otherwise, prints out the configured value of @env{$exec_prefix}.
+@end table
+
+Typically, @command{ginac-config} will be used within a configure
+script, as described below. It, however, can also be used directly from
+the command line using backquotes to compile a simple program. For
+example:
+
+@example
+c++ -o simple `ginac-config --cppflags` simple.cpp `ginac-config --libs`
+@end example
+
+This command line might expand to (for example):
+
+@example
+cc -o simple -I/usr/local/include simple.cpp -L/usr/local/lib \
+ -lginac -lcln -lstdc++
+@end example
+
+Not only is the form using @command{ginac-config} easier to type, it will
+work on any system, no matter how GiNaC was configured.
+
+
+@node AM_PATH_GINAC, Configure script options, ginac-config, Package Tools
+@c node-name, next, previous, up
+@section @samp{AM_PATH_GINAC}
+@cindex AM_PATH_GINAC
+
+For packages configured using GNU automake, GiNaC also provides
+a macro to automate the process of checking for GiNaC.
+
+@example
+AM_PATH_GINAC([@var{MINIMUM-VERSION}, [@var{ACTION-IF-FOUND} [, @var{ACTION-IF-NOT-FOUND}]]])
+@end example
+
+This macro:
+
+@itemize @bullet
+
+@item
+Determines the location of GiNaC using @command{ginac-config}, which is
+either found in the user's path, or from the environment variable
+@env{GINACLIB_CONFIG}.
+
+@item
+Tests the installed libraries to make sure that their version
+is later than @var{MINIMUM-VERSION}. (A default version will be used
+if not specified)
+
+@item
+If the required version was found, sets the @env{GINACLIB_CPPFLAGS} variable
+to the output of @command{ginac-config --cppflags} and the @env{GINACLIB_LIBS}
+variable to the output of @command{ginac-config --libs}, and calls
+@samp{AC_SUBST()} for these variables so they can be used in generated
+makefiles, and then executes @var{ACTION-IF-FOUND}.
+
+@item
+If the required version was not found, sets @env{GINACLIB_CPPFLAGS} and
+@env{GINACLIB_LIBS} to empty strings, and executes @var{ACTION-IF-NOT-FOUND}.
+
+@end itemize
+
+This macro is in file @file{ginac.m4} which is installed in
+@file{$datadir/aclocal}. Note that if automake was installed with a
+different @samp{--prefix} than GiNaC, you will either have to manually
+move @file{ginac.m4} to automake's @file{$datadir/aclocal}, or give
+aclocal the @samp{-I} option when running it.
+
+@menu
+* Configure script options:: Configuring a package that uses AM_PATH_GINAC.
+* Example package:: Example of a package using AM_PATH_GINAC.
+@end menu
+
+
+@node Configure script options, Example package, AM_PATH_GINAC, AM_PATH_GINAC
+@c node-name, next, previous, up
+@subsection Configuring a package that uses @samp{AM_PATH_GINAC}
+
+Simply make sure that @command{ginac-config} is in your path, and run
+the configure script.
+
+Notes:
+
+@itemize @bullet
+
+@item
+The directory where the GiNaC libraries are installed needs
+to be found by your system's dynamic linker.
+
+This is generally done by
+
+@display
+editing @file{/etc/ld.so.conf} and running @command{ldconfig}
+@end display
+
+or by
+
+@display
+setting the environment variable @env{LD_LIBRARY_PATH},
+@end display
+
+or, as a last resort,
+
+@display
+giving a @samp{-R} or @samp{-rpath} flag (depending on your linker) when
+running configure, for instance:
+
+@example
+LDFLAGS=-R/home/cbauer/lib ./configure
+@end example
+@end display
+
+@item
+You can also specify a @command{ginac-config} not in your path by
+setting the @env{GINACLIB_CONFIG} environment variable to the
+name of the executable
+
+@item
+If you move the GiNaC package from its installed location,
+you will need either need to modify @command{ginac-config} script
+manually to point to the new location or rebuild GiNaC.
+
+@end itemize
+
+Advanced note:
+
+@itemize @bullet
+@item
+configure flags
+
+@example
+--with-ginac-prefix=@var{PREFIX}
+--with-ginac-exec-prefix=@var{PREFIX}
+@end example
+
+are provided to override the prefix and exec-prefix that were stored
+in the @command{ginac-config} shell script by GiNaC's configure. You are
+generally better off configuring GiNaC with the right path to begin with.
+@end itemize
+
+
+@node Example package, Bibliography, Configure script options, AM_PATH_GINAC
+@c node-name, next, previous, up
+@subsection Example of a package using @samp{AM_PATH_GINAC}
+
+The following shows how to build a simple package using automake
+and the @samp{AM_PATH_GINAC} macro. The program used here is @file{simple.cpp}:
+
+@example
+#include <ginac/ginac.h>
+using namespace GiNaC;
+
+int main(void)
+@{
+ symbol x("x");
+ ex a = sin(x);
+ cout << "Derivative of " << a << " is " << a.diff(x) << endl;
+ return 0;
+@}
+@end example
+
+You should first read the introductory portions of the automake
+Manual, if you are not already familiar with it.
+
+Two files are needed, @file{configure.in}, which is used to build the
+configure script:
+
+@example
+dnl Process this file with autoconf to produce a configure script.
+AC_INIT(simple.cpp)
+AM_INIT_AUTOMAKE(simple.cpp, 1.0.0)
+
+AC_PROG_CXX
+AC_PROG_INSTALL
+AC_LANG_CPLUSPLUS
+
+AM_PATH_GINAC(0.4.0, [
+ LIBS="$LIBS $GINACLIB_LIBS"
+ CPPFLAGS="$CFLAGS $GINACLIB_CPPFLAGS"
+], AC_MSG_ERROR([need to have GiNaC installed]))
+
+AC_OUTPUT(Makefile)
+@end example
+
+The only command in this which is not standard for automake
+is the @samp{AM_PATH_GINAC} macro.
+
+That command does the following:
+
+@display
+If a GiNaC version greater than 0.4.0 is found, adds @env{$GINACLIB_LIBS} to
+@env{$LIBS} and @env{$GINACLIB_CPPFLAGS} to @env{$CPPFLAGS}. Otherwise, dies
+with the error message `need to have GiNaC installed'
+@end display
+
+And the @file{Makefile.am}, which will be used to build the Makefile.
+
+@example
+## Process this file with automake to produce Makefile.in
+bin_PROGRAMS = simple
+simple_SOURCES = simple.cpp
+@end example
+
+This @file{Makefile.am}, says that we are building a single executable,
+from a single sourcefile @file{simple.cpp}. Since every program
+we are building uses GiNaC we simply added the GiNaC options
+to @env{$LIBS} and @env{$CPPFLAGS}, but in other circumstances, we might
+want to specify them on a per-program basis: for instance by
+adding the lines:
+
+@example
+simple_LDADD = $(GINACLIB_LIBS)
+INCLUDES = $(GINACLIB_CPPFLAGS)
+@end example
+
+to the @file{Makefile.am}.
+
+To try this example out, create a new directory and add the three
+files above to it.
+
+Now execute the following commands:
+
+@example
+$ automake --add-missing
+$ aclocal
+$ autoconf
+@end example
+
+You now have a package that can be built in the normal fashion
+
+@example
+$ ./configure
+$ make
+$ make install
+@end example
+
+
+@node Bibliography, Concept Index, Example package, Top