From: Christian Bauer <Christian.Bauer@uni-mainz.de>
Date: Thu, 21 Nov 2002 22:56:49 +0000 (+0000)
Subject: documentation update
X-Git-Tag: release_1-0-13~15
X-Git-Url: https://www.ginac.de/ginac.git//ginac.git?p=ginac.git;a=commitdiff_plain;h=778927a23b7807cb9809047211265000650eda56;ds=inline

documentation update
---

diff --git a/NEWS b/NEWS
index 81f2975f..c25a0867 100644
--- a/NEWS
+++ b/NEWS
@@ -10,6 +10,8 @@ This file records noteworthy changes.
   LaTeX output.
 * Added symbolic_matrix() for the convenient creation of matrices filled
   with symbols.
+* Added collect_common_factors() which collects common factors from the
+  terms of sums.
 
 1.0.12 (30 October 2002)
 * Fixed a bug in power::expand() that could produce invalid expressions.
diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index 98033e40..54414c91 100644
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -3405,6 +3405,7 @@ argument. You can not use functions like @samp{diff()}, @samp{op()},
 @subsection Expanding and collecting
 @cindex @code{expand()}
 @cindex @code{collect()}
+@cindex @code{collect_common_factors()}
 
 A polynomial in one or more variables has many equivalent
 representations.  Some useful ones serve a specific purpose.  Consider
@@ -3463,6 +3464,25 @@ d*sin(x)+(d*sin(x)+sin(y)+d*sin(y)+sin(x))*p+(d*sin(x)+sin(y)+d*sin(y)+sin(x))*q
 (1+q+d*(1+q+p)+p)*sin(y)+(1+q+d*(1+q+p)+p)*sin(x)
 @end example
 
+Polynomials can often be brought into a more compact form by collecting
+common factors from the terms of sums. This is accomplished by the function
+
+@example
+ex collect_common_factors(const ex & e);
+@end example
+
+This function doesn't perform a full factorization but only looks for
+factors which are already explicitly present:
+
+@example
+> collect_common_factors(a*x+a*y);
+(x+y)*a
+> collect_common_factors(a*x^2+2*a*x*y+a*y^2);
+a*(2*x*y+y^2+x^2)
+> collect_common_factors(a*(b*(a+c)*x+b*((a+c)*x+(a+c)*y)*y));
+(c+a)*a*(x*y+y^2+x)*b
+@end example
+
 @subsection Degree and coefficients
 @cindex @code{degree()}
 @cindex @code{ldegree()}