# HG changeset patch
# User Dan Drake
# Date 1268535192 -32400
# Node ID 1ddaf75204cceb13fd0035c97827824835b17768
# Parent a66fade6bc2d6d29322b055019d26737ea68ffe4
checkpoint some work; sageexample env does *not* work at the moment
diff --git a/example.tex b/example.tex
--- a/example.tex
+++ b/example.tex
@@ -321,4 +321,62 @@
\sagestr{pascals_triangle(n)}
\end{center}
+\section{Include doctest-like examples in your document}
+
+Here are some examples of using the \texttt{sageexample} environment:
+\begin{sageexample}
+ sage: 1+1
+ 2
+ sage: factor(x^2 + 2*x + 1)
+ (x + 1)^2
+\end{sageexample}
+If you want to see the plain-text output as well as the typeset
+output, renew the \texttt{sageexampleincludetextoutput} variable to
+True:
+\renewcommand{\sageexampleincludetextoutput}{True}
+\begin{sageexample}
+ sage: 1+1
+ 2
+ sage: factor(x^2 + 2*x + 1)
+ (x + 1)^2
+\end{sageexample}
+Multiline statements are support, as are triple-quoted strings
+delimited by single quotes:
+\renewcommand{\sageexampleincludetextoutput}{False}
+\begin{sageexample}
+ sage: def f(a):
+ ....: '''This function is really quite nice,
+ ....: although perhaps not very useful.'''
+ ....: print "f called with a = ", a
+ ....: y = integrate(SR(cyclotomic_polynomial(10)) + a, x)
+ ....: return y + 1
+ sage: f(x)
+ f called with a = x
+ 1/5*x^5 - 1/4*x^4 + 1/3*x^3 + x + 1
+\end{sageexample}
+When typesetting your document, the validity of the outputs is not
+checked (go ahead and try changing something above) but it should be
+possible to run the usual Sage doctest mechanism on the generated
+\texttt{.sage} file---or perhaps the \texttt{.py} file. Running
+doctests on files outside the main Sage library does not always work,
+so contact sage-support if you run into troubles.
+
+Some more examples. This environment is implemented a little bit
+differently than the other environments, so it's good to make sure
+that definitions are preserved across multiple uses:
+\begin{sageexample}
+ sage: 1; 2; a=4; 3; a
+ 1
+ 2
+ 3
+ 4
+\end{sageexample}
+After that, Sage should remember that $a = \sage{a}$, and be able to
+use that in future \texttt{sageexample} blocks:
+\begin{sageexample}
+ sage: f(a)
+ 1/5*x^5 - 1/4*x^4 + 1/3*x^3 - 1/2*x^2 + 5*x + 1
+\end{sageexample}
+
+
\end{document}
diff --git a/py-and-sty.dtx b/py-and-sty.dtx
--- a/py-and-sty.dtx
+++ b/py-and-sty.dtx
@@ -726,6 +726,7 @@
% \begin{macrocode}
version = ' '.join(__version__.strip('[').split()[0:2])
from sage.misc.latex import latex
+from sage.misc.preparser import preparse
import os
import os.path
import hashlib
diff --git a/sagetexpackage.dtx b/sagetexpackage.dtx
--- a/sagetexpackage.dtx
+++ b/sagetexpackage.dtx
@@ -745,6 +745,38 @@
% environment: |comment|. Another way to do this is to put stuff between
% |\iffalse| and |\fi|.\\
%
+% \DescribeEnv{sageexample} This environment allow you to include
+% doctest-like snippets in your document that will be nicely typeset.
+% For example,
+% \begin{quote}
+% |\begin{sageexample}|\\
+% | sage: 1+1|\\
+% | 2|\\
+% | sage: factor(x^2 + 2*x + 1)|\\
+% | (x + 1)^2|\\
+% |\end{sageexample}|
+% \end{quote}
+% in your document will be typeset with the Sage inputs in the usual
+% fixed-width font, and the outputs will be typeset as if given to a
+% |\sage| macro. When typesetting the document, there is no test of
+% the validity of the outputs (that is, typesetting with a typical
+% \LTX-Sage-\LTX cycle does not do doctesting), but you should be able
+% to doctest your document with ``|sage -t my_file.sage|''. (This does
+% not always work; if this fails for you, please contact the
+% sage-support group.)
+%
+% If you would like to see both the original text input and the
+% typeset output, you can issue
+% |\renewcommand{\sageexampleincludetextoutput}{True}| in your
+% document. You can do the same thing with ``False'' to later turn it
+% off. In the above example, this would cause \ST to output both
+% |(x + 1)^2| and $(x + 1)^{2}$ in your typeset document.
+%
+% Just as in doctests, multiline statements are acceptable. The only
+% limitation is that triple-quoted strings delimited by |"""| cannot be used in
+% a |sageexample| environment; instead, you can use triple-quoted
+% strings delimited by |'''|.\\
+%
% \DescribeMacro{\sagetexindent} There is one final bit to our
% verbatim-like environments: the indentation. The \ST package defines a
% length |\sagetexindent|, which controls how much the Sage code is