added docs for to_polynomial()

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index f036986563afa3a4b02881d307e42dd48f95a5b4..664b6abdc055e6238fe896a0473b40c68793fa9a 100644 (file)
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -3946,7 +3946,8 @@ If you need both numerator and denominator, calling @code{numer_denom()} is
 faster than using @code{numer()} and @code{denom()} separately.
 
 
-@subsection Converting to a rational expression
+@subsection Converting to a polynomial or rational expression
+@cindex @code{to_polynomial()}
 @cindex @code{to_rational()}
 
 Some of the methods described so far only work on polynomials or rational
@@ -3954,6 +3955,10 @@ functions. GiNaC provides a way to extend the domain of these functions to
 general expressions by using the temporary replacement algorithm described
 above. You do this by calling
 
+@example
+ex ex::to_polynomial(lst &l);
+@end example
+or
 @example
 ex ex::to_rational(lst &l);
 @end example
@@ -3962,10 +3967,33 @@ on the expression to be converted. The supplied @code{lst} will be filled
 with the generated temporary symbols and their replacement expressions in
 a format that can be used directly for the @code{subs()} method. It can also
 already contain a list of replacements from an earlier application of
-@code{.to_rational()}, so it's possible to use it on multiple expressions
-and get consistent results.
+@code{.to_polynomial()} or @code{.to_rational()}, so it's possible to use
+it on multiple expressions and get consistent results.
+
+The difference betwerrn @code{.to_polynomial()} and @code{.to_rational()}
+is probably best illustrated with an example:
+
+@example
+@{
+    symbol x("x"), y("y");
+    ex a = 2*x/sin(x) - y/(3*sin(x));
+    cout << a << endl;
+
+    lst lp;
+    ex p = a.to_polynomial(lp);
+    cout << " = " << p << "\n   with " << lp << endl;
+     // = symbol3*symbol2*y+2*symbol2*x
+     //   with @{symbol2==sin(x)^(-1),symbol3==-1/3@}
+
+    lst lr;
+    ex r = a.to_rational(lr);
+    cout << " = " << r << "\n   with " << lr << endl;
+     // = -1/3*symbol4^(-1)*y+2*symbol4^(-1)*x
+     //   with @{symbol4==sin(x)@}
+@}
+@end example
 
-For example,
+The following more useful example will print @samp{sin(x)-cos(x)}:
 
 @example
 @{
@@ -3974,13 +4002,11 @@ For example,
     ex b = sin(x) + cos(x);
     ex q;
     lst l;
-    divide(a.to_rational(l), b.to_rational(l), q);
+    divide(a.to_polynomial(l), b.to_polynomial(l), q);
     cout << q.subs(l) << endl;
 @}
 @end example
 
-will print @samp{sin(x)-cos(x)}.
-
 
 @node Symbolic Differentiation, Series Expansion, Rational Expressions, Methods and Functions
 @c    node-name, next, previous, up