Commits

Anonymous committed 1ddaf75

checkpoint some work; sageexample env does *not* work at the moment

Comments (0)

Files changed (3)

   \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}
 %    \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

sagetexpackage.dtx

 % 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