Source

SageTeX / sagetexpackage.dtx

Diff from to

sagetexpackage.dtx

 % Copyright (C) 2009 by Dan Drake <ddrake (at) member (dot) ams (dot) org>
 % -------------------------------------------------------
 %
-% See the "Copying and licenses" section at the end of this file for the
-% terms under which this source code and documentation may be modified
-% and distributed.
+% See the "Copying and licenses" section in this file for the terms
+% under which this source code and documentation may be modified and
+% distributed.
 %
 % This package is not licensed under the LPPL, but it seems reasonable
 % to say:
 %<latex>\NeedsTeXFormat{LaTeX2e}
 %<latex>\ProvidesPackage{sagetex}
 %<*latex>
-  [2009/04/21 v2.0.2 embedding Sage into LaTeX documents]
+  [2009/05/12 v2.1 embedding Sage into LaTeX documents]
 %</latex>
 %<*driver>
 \documentclass{ltxdoc}
 feedback.
 
 \section{Copying and licenses}
+\label{sec:copying-licenses}
 
 If you are unnaturally curious about the current state of the \ST
 package, you can visit \url{http://www.bitbucket.org/ddrake/sagetex/}.
 %</driver>
 % \fi
 %
-% \CheckSum{275}
+% \CheckSum{313}
 %
 % \CharacterTable
 %  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
 % SageTeX-ified documents, tons of documentation improvements,
 % sagetex.py refactored, include in Sage as spkg}
 % \changes{v2.0}{2009/01/09}{Miscellaneous fixes, final 2.0 version.}
+% \changes{v2.1}{2009/05/12}{Add pausing support.}
 %
 % \GetFileInfo{sagetex.sty}
 %
 % \tikzstyle{box}=[draw, shape=rectangle, thick]
 %
 % \title{The \ST{} package\thanks{This document corresponds to
-%     \ST~\fileversion, dated \filedate.}}
+%     \ST \fileversion, dated \filedate.}}
 %
 % \author{Dan Drake and others\thanks{Author's website:
 %     \href{http://mathsci.kaist.ac.kr/~drake/}
 %
 %
 % \section{Installation}
+% \label{sec:installation}
 % \changes{v2.0}{2009/01/14}{Fixed up installation section, final
 % \emph{final} 2.0.}
 %
 % |.sage| file.
 %
 % \subsection{Inline Sage}
+% \label{sec:sagemacro-usage}
 %
 % \DescribeMacro{sage}
 % \fbox{\texttt{\bslash sage}\marg{Sage code}}
 % will get confused. The |\percent| macro makes everyone happy.
 %
 % Note that using |\percent| inside the verbatim-like environments
-% described in \autoref{s:codeblockenv} isn't necessary; a literal
+% described in \autoref{sec:codeblockenv} isn't necessary; a literal
 % ``\percent'' inside such an environment will get written, uh, verbatim
 % to the |.sage| file.
 %
 % \subsection{Graphics and plotting}
+% \label{sec:graphics-plotting}
 %
 % \noindent \DescribeMacro{\sageplot}
 % \fbox{\texttt{\bslash sageplot}\oarg{ltx opts}\oarg{fmt}\{\meta{graphics
 % turn off anything in \LTX, so you can always do things manually.
 %
 % \subsection{Verbatim-like environments}
-% \label{s:codeblockenv}
+% \label{sec:codeblockenv}
 %
 % The \ST package provides several environments for typesetting and
 % executing blocks of Sage code.\\
 % verbatim-like environments: the indentation. The \ST package defines a
 % length |\sagetexindent|, which controls how much the Sage code is
 % indented when typeset. You can change this length however you like
-% with |\setlength|: do |\setlength{\sagetexindent}{6ex}| or whatever.
-% 
+% with |\setlength|: do |\setlength{\sagetexindent}{6ex}| or whatever. 
+%
+% \subsection{Pausing \ST}
+% \label{sec:pausing-st-usage}
+%
+% Sometimes when you are writing a document, you may wish to temporarily
+% turn off or pause \ST to concentrate more on your document than on the
+% Sage computations, or to simply have your document typeset faster. You
+% can do this with the following commands.
+%
+% \DescribeMacro{sagetexpause} \DescribeMacro{sagetexunpause} Use these
+% macros to ``pause'' and ``unpause'' \ST. After issuing this macro, \ST
+% will simply skip over the corresponding calculations. Anywhere a
+% |\sage| macro is used while paused, you will simply see \sagetexpause
+% ``\sage{dummy call to sage to illustrate
+%   pausing}'', and anywhere a |\sageplot| macro is used, you will see:\\
+%
+% \noindent
+% \sageplot{dummy call to sageplot to illustrate pausing}
+% \sagetexunpause\\
+%
+% \noindent Anything in the verbatim-like environments of
+% \autoref{sec:codeblockenv} will be typeset or not as usual, but none
+% of the Sage code will be executed.
+%
+% Obviously, you use |\sagetexunpause| to unpause \ST and return to the
+% usual state of affairs. Both commands are idempotent; issuing them
+% twice or more in a row is the same as issuing them once. This means
+% you don't need to precisely match pause and unpause commands: once
+% paused, \ST stays paused until it sees |\sagetexunpause| and
+% vice versa.
 %
 % \section{Other notes}
 %