Dan Drake  committed f536583

User documentation for; version 2.2

  • Participants
  • Parent commits 1f4b289
  • Branches default
  • Tags v2.2

Comments (0)

Files changed (5)

 dtxs=$(wildcard *.dtx)
 # the subdir stuff makes the tarball have the directory correct
 srcs=../sagetex/example.tex ../sagetex/README ../sagetex/sagetexpackage.dtx ../sagetex/sagetexpackage.ins
 ( into LaTeX documents.
-To use SageTeX, you need the files sagetex.sty and If those
-haven't been extracted from the .dtx file, you'll need to do:
+The recommended way to acquire and install SageTeX is by installing the
+Sage spkg; visit, find the
+current version number, and run "sage -i sagetex-[version]" in a
+terminal. Then you'll need to make the file sagetex.sty known to TeX;
+that file will be in SAGE_ROOT/local/share/texmf/tex/generic/sagetex,
+along with documentation and examples.
+If you can't or don't want to install SageTeX by using Sage, you can use
+this CTAN package. If and sagetex.sty haven't been extracted
+from the .dtx file, you'll need to do:
   0. Run `latex sagetexpackage.ins'
 If a PDF file of the documentation wasn't included with this
-distribution of SageTex, you will need to build the documentation
+distribution of SageTeX, you will need to build the documentation
 yourself. To do that:
   1. Run `latex sagetexpackage.dtx'

File remote-sagetex.dtx

 % \section{The \texttt{remote-sagetex} script}
 % \label{sec:remote-sagetex-code}
 % Here we describe the Python code for ||. Since its
 % job is to replicate the functionality of using Sage and ||,
 % there is some overlap with the Python module.
 from contextlib import closing
-# You can fill in your information here, or you can set any of these to #
-# None and the script will ask you to provide them if you don't specify #
-# them as command-line arguments.                                       #
+# You can provide a filename here and the script will read your login   #
+# information from that file. The format must be:                       #
+#                                                                       #
+# server = ''                                        #
+# username = 'my_name'                                                  #
+# password = 's33krit'                                                  #
+#                                                                       #
+# You can omit one or more of those lines, use " quotes, and put hash   #
+# marks at the beginning of a line for comments. Command-line args      #
+# take precedence over information from the file.                       #
-server = None       # '', https works too
-username = None     # 'my_name'
-password = None     # 's33krit'
+login_info_file = None       # e.g. '/home/foo/Private/sagetex-login.txt'
 usage = """Process a SageTeX-generated .sage file using a remote Sage server.
     -s, --server:       the Sage server to contact
     -u, --username:     username on the server
     -p, --password:     your password
+    -f, --file:         get login information from a file
 If the server does not begin with the four characters `http', then
 `https://' will be prepended to the server name.
-You can hard-code the server, username, and password values in the
-remote-sagetex script. If any are omitted, you will be asked to provide
+You can hard-code the filename from which to read login information into
+the remote-sagetex script. Command-line arguments take precedence over
+the contents of that file. See the SageTeX documentation for formatting
+If any of the server, username, and password are omitted, you will be
+asked to provide them.
 See the SageTeX documentation for more details on usage and limitations
 of remote-sagetex.""".format(sys.argv[0])
+server, username, password = (None,) * 3
-    opts, args = getopt.getopt(sys.argv[1:], 'hs:u:p:',
-                               ['help', 'server=', 'user=', 'password='])
+    opts, args = getopt.getopt(sys.argv[1:], 'hs:u:p:f:',
+                    ['help', 'server=', 'user=', 'password=', 'file='])
 except getopt.GetoptError as err:
     print(str(err), usage, sep='\n\n')
         username = a
     elif o in ('-p', '--password'):
         password = a
+    elif o in ('-f', '--file'):
+        login_info_file = a
 if len(args) != 1:
     print('Error: must specify exactly one file. Please specify options first.',
 print('Processing Sage code for {0}.tex using remote Sage server.'.format(
+if login_info_file:
+    with open(login_info_file, 'r') as f:
+        print('Reading login information from {0}.'.format(login_info_file))
+        get_val = lambda x: x.split('=')[1].strip().strip('\'"')
+        for line in f:
+            print(line)
+            if not line.startswith('#'):
+                if line.startswith('server') and not server:
+                    server = get_val(line)
+                if line.startswith('username') and not username:
+                    username = get_val(line)
+                if line.startswith('password') and not password:
+                    password = get_val(line)
 if not server:
     server = raw_input('Enter server: ')
+if not server.startswith('http'):
+    server = 'https://' + server
 if not username:
     username = raw_input('Enter username: ')
     password = getpass('Please enter password for user {0} on {1}: '.format(
         username, server))
-if not server.startswith('http'):
-    server = 'https://' + server
 printc('Parsing {0}.sage...'.format(jobname))
 cmds = parsedotsage(jobname + '.sage')

File sagetexpackage.dtx

 %<python>__version__ = """
-  [2009/05/14 v2.1.1 embedding Sage into LaTeX documents]
+  [2009/06/17 v2.2 embedding Sage into LaTeX documents]
 % \changes{v2.0}{2009/01/09}{Miscellaneous fixes, final 2.0 version}
 % \changes{v2.1}{2009/05/12}{Add pausing support}
 % \changes{v2.1}{2009/05/12}{Get version written to .py file}
+% \changes{v2.2}{2009/06/17}{Add script}
 % \GetFileInfo{sagetex.sty}
 % The easiest way to install \ST is by using Sage's own spkg
 % installation facility; visit the
 % \href{}{optional packages page}
-% and run \texttt{sage -i} with the appropriate version. This will let
+% and run \texttt{sage -i} with the appropriate file name. This will let
 % Sage know about \ST; you still need to let \LTX know about it.
 % The simplest way to ``install'' \ST for \LTX is to copy the file
 % To copy the files that \LTX needs into your |texmf| directory, simply
 % do
 % \begin{quote}
-%   \texttt{cp -r \sageroot/local/share/texmf/* \$HOMEPREFIX/texmf/}
+%   \texttt{cp -r \sageroot/local/share/texmf/* HOMEPREFIX/texmf/}
 % \end{quote}
-% where |$HOMEPREFIX| is the appropriate prefix for your own |texmf|
+% where |HOMEPREFIX| is the appropriate prefix for your own |texmf|
 % tree. Then you need to make \TeX{} aware of the new files by running
 % \begin{quote}
-%   \texttt{texhash \$HOMEPREFIX/texmf/}
+%   \texttt{texhash HOMEPREFIX/texmf/}
 % \end{quote}
 % \subsection{From CTAN}
 % \label{sec:inst-other-scripts}
 % \ST includes several Python files which may be useful for working with
-% ``\ST-ified'' documents: || and || are
+% ``\ST-ified'' documents. The || script allows you to
+% use \ST on a computer that doesn't have Sage installed; see
+% \autoref{sec:remote-sagetex} for more information.
+% Also included are || and ||, which are
 % convenience scripts that you can use after you've written your
 % document. See \autoref{sec:makestatic-usage} and
 % \autoref{sec:extractsagecode} for information on using those scripts.
 % will pull in all the results of Sage's computation.
 % All you really need to know is that to typeset your document, you need
-% to run \LTX, then run Sage, then run \LTX again.
+% to run \LTX, then run Sage, then run \LTX again. You can even ``run
+% Sage'' on a computer that doesn't have Sage installed by using the
+% || script; see \autoref{sec:remote-sagetex}. Whenever
+% this manual says ``run Sage'', you can either directly run Sage, or
+% use the || script.
 % Also keep in mind that everything you send to Sage is done within one
 % Sage session. This means you can define variables and reuse them
 % document should compile to something identical, or very nearly so, to
 % the original file.
+% One large limitation of this script is that it can't change anything
+% while \ST is paused, since Sage doesn't compute anything for such
+% parts of your document. It also doesn't check to see if pause and
+% unpause commands are inside comments or verbatim environments. If
+% you're going to use ||, just remove all pause/unpause
+% statements.
 % The parsing that || does is pretty good, but not perfect.
 % Right now it doesn't support having a comma-separated list of
 % packages, so you can't have |\usepackage{sagetex, foo}|. You need to
 % \section{Using \ST without Sage installed}
 % \label{sec:remote-sagetex}
-% foo
+% You may want to edit and typeset a \ST-ified file on a computer that
+% doesn't have Sage installed. How can you do that? We need to somehow
+% run Sage on the |.sage| file. The included script
+% \texttt{} takes advantage of Sage's network
+% transparency and will use a remote server to do all the computations.
+% Anywhere in this manual where you are told to ``run Sage'', instead of
+% actually running Sage, you can run
+% \begin{center}
+%   \texttt{python filename.sage}
+% \end{center}
+% The script will ask you for a server, username, and password, then
+% process all your code and write a |.sout| file and graphics files
+% exactly as if you had used a local copy of Sage to process the |.sage|
+% script. (With some minor limitations and differences; see below.)
+% One important point: \emph{the script requires Python 2.6}. It will
+% not work with earlier versions. (It will work with Python 3.0 or later
+% with some trivial changes.)
+% You can provide the server, username and password with the
+% command-line switches |--server|, |--username|, and |--password|, or
+% you can put that information into a file and use the |--file| switch
+% to specify that file. The format of the file must be like the
+% following:
+% \begin{verbatim}
+    # hash mark at beginning of line marks a comment
+    server = ""
+    username = 'my_user_name'
+    password = 's33krit'\end{verbatim}
+% As you can see, it's really just like assigning a string to a variable
+% in Python. You can use single or double quotes and use hash marks to
+% start comments. You can't have comments on the same line as an
+% assignment, though. You can omit any of those pieces of information
+% information; the script will ask for anything it needs to know.
+% Information provided as a command line switch takes precedence over
+% anything found in the file.
+% You can keep this file separate from your \LTX documents in a secure
+% location; for example, on a USB thumb drive or in an automatically
+% encrypted directory (like |~/Private| in Ubuntu). This makes it much
+% harder to accidentally upload your private login information to the
+% arXiv, put it on a website, send it to a colleague, or otherwise make
+% your private information public.
+% \subsection{Limitations of \texttt{}}
+% \label{sec:remote-sagetex-limitations}
+% The || script has several limitations. It completely
+% ignores the |epstopdf| and |imagemagick| flags. The |epstopdf| flag is
+% not a big deal, since it was originally introduced to work around a
+% matplotlib bug which has since been fixed. Not having |imagemagick|
+% support means that you cannot automatically convert 3D graphics to eps
+% format; using |pdflatex| to make PDFs works around this issue.
+% \subsection{Other caveats}
+% \label{sec:remote-sagetex-caveats}
+% Right now, the ``simple server API'' that || uses is
+% not terribly robust, and if you interrupt the script, it's possible to
+% leave an idle session running on the server. If many idle sessions
+% accumulate on the server, it can use up a lot of memory and cause the
+% server to be slow, unresponsive, or maybe even crash. For now, I
+% recommend that you only run the script manually. It's probably best to
+% not configure your \TeX{} editing environment to automatically run
+% || whenever you typeset your document, at least not
+% without showing you the output or alerting you about errors.
 % \iffalse
 % Local Variables:
       long_description="""The SageTeX package allows you to embed code,
   results of computations, and plots from the Sage mathematics
   software suite ( into LaTeX documents.""",
-      version='2.1.1',
+      version='2.2',
       author='Dan Drake',