Commits

Anonymous committed 911609d

documentation for png auto-fallback stuff.

Comments (0)

Files changed (3)

 
 \subsection{3D plotting}
 
-3D plotting right now is problematic because there's no convenient way
-to produce vector graphics. We can make PNGs, though, and since the
-\verb|sageplot| command defaults to EPS and PDF, \emph{you must specify
-  a valid format for 3D plotting}. Sage right now (version 4.2.1) can't
-produce EPS or PDF files from \texttt{plot3d} objects, so if you don't
-specify a valid format, things will go badly. You can specify the
-``\texttt{imagemagick}'' option, which will use the Imagemagick
-\texttt{convert} utility to make EPS files. See the documentation for
-details.
+3D plotting right now (Sage version 4.3.4) is problematic because
+there's no convenient way to produce vector graphics. We can make PNGs,
+though, so if you pass \verb|sageplot| a graphics object that cannot be
+saved to EPS or PDF format, we will automatically save to a PNG file,
+which can be used when typesetting a PDF file, but not when creating a
+DVI file. However, you can specify the ``\texttt{imagemagick}'' option,
+which will use the Imagemagick \texttt{convert} utility to make EPS
+files. See the documentation for details.
 
 % FIXME: not sure this works with remote sagetex
 
   x, y = var('x y')
 \end{sagesilent}
 
+Here's a 3D plot whose format we do not specify; it will automatically
+get saved as a PNG file and won't work when using \texttt{latex} to make
+a DVI file.
+
 \sageplot[scale=.5]{plot3d(sin(pi*(x^2+y^2))/2,(x,-1,1),(y,-1,1))}
 
 Here's the (perhaps-not-so-) famous Sage cube graph in 3D.
 %       child {node [box] {Insert ``we're paused'' box}
 %         edge from parent node[left] {yes}}
 %       child {node [box] {Does EXT file exist?}
-%         child {node [box, text width = 2.125cm] {Warn user to rerun Sage}
+%         child {node [box] {Does a PNG file exist?}
+%           child {node [box] {Making a PDF?}
+%             child {node [box] {\texttt{includegraphics} PNG}
+%               edge from parent node[left] {yes}}
+%             child {node [box, text width=2cm] {Warning: DVI, latex incompatible}
+%               edge from parent node[left] {no}}
+%             edge from parent node[left] {yes}}
+%           child {node [box, text width = 2.125cm] {Warn user to rerun Sage}
+%             edge from parent node[left] {no}}
 %           edge from parent node[left] {no}}
 %         child {node [box] {Use \texttt{includegraphics}}
 %           edge from parent node[right] {yes}}
 % to |\sageplot| becomes |_p_| and |**kwargs| below.
 %    \begin{macrocode}
   def plot(self, counter, _p_, format='notprovided', **kwargs):
-    if not self.didinitplot:
-      self.initplot()
-    self.progress('Plot {0}'.format(counter))
+      if not self.didinitplot:
+          self.initplot()
+      self.progress('Plot {0}'.format(counter))
 %    \end{macrocode}
 % If the user says nothing about file formats, we default to producing
 % PDF and EPS. This allows the user to transparently switch between
 % \texttt{pdfsync}, but full support for that is still rare in Linux, so
 % producing EPS and PDF is the best solution for now.}
 %    \begin{macrocode}
-    if format == 'notprovided':
-      formats = ['eps', 'pdf']
-    else:
-      formats = [format]
-    for fmt in formats:
+      if format == 'notprovided':
+          formats = ['eps', 'pdf']
+      else:
+          formats = [format]
+      for fmt in formats:
 %    \end{macrocode}
 % If we're making a PDF and have been told to use |epstopdf|, do so,
 % then skip the rest of the loop.
 %    \begin{macrocode}
-      if fmt == 'pdf' and self.useepstopdf:
-        epsfile = os.path.join(self.plotdir, 'plot-{0}.eps'.format(counter))
-        self.progress('Calling epstopdf to convert plot-{0}.eps to PDF'.format(
-            counter))
-        subprocess.check_call(['epstopdf', epsfile])
-        continue
+          if fmt == 'pdf' and self.useepstopdf:
+              epsfile = os.path.join(self.plotdir, 'plot-{0}.eps'.format(counter))
+              self.progress('Calling epstopdf to convert plot-{0}.eps to PDF'.format(
+                            counter))
+              subprocess.check_call(['epstopdf', epsfile])
+              continue
 %    \end{macrocode}
 % Some plot objects (mostly 3-D plots) do not support saving to EPS or
 % PDF files (yet), but everything can be saved to a PNG file. For the
 % user's convenience, we catch the error when we run into such an
 % object, save it to a PNG file, then exit the loop.
 %    \begin{macrocode}
-      plotfilename = os.path.join(self.plotdir, 'plot-{0}.{1}'.format(counter, fmt))
-      try:
-        _p_.save(filename=plotfilename, **kwargs)
-      except ValueError as inst:
-        if 'filetype not supported by save' in str(inst):
-          newfilename = plotfilename[:-3] + 'png'
-          print '  saving {0} failed; saving to {1} instead.'.format(plotfilename,
-                                                                     newfilename)
-          _p_.save(filename=newfilename, **kwargs)
-          break
-        else:
-          raise
+          plotfilename = os.path.join(self.plotdir, 'plot-{0}.{1}'.format(counter, fmt))
+          try:
+              _p_.save(filename=plotfilename, **kwargs)
+          except ValueError as inst:
+              if 'filetype not supported by save' in str(inst):
+                  newfilename = plotfilename[:-3] + 'png'
+                  print '  saving {0} failed; saving to {1} instead.'.format(
+                                                    plotfilename, newfilename)
+                  _p_.save(filename=newfilename, **kwargs)
+                  break
+              else:
+                  raise
 %    \end{macrocode}
 % If the user provides a format \emph{and} specifies the |imagemagick|
 % option, we try to convert the newly-created file into EPS format.
 %    \begin{macrocode}
-      if format != 'notprovided' and self.useimagemagick:
-        self.progress('Calling Imagemagick to convert plot-{0}.{1} to EPS'.format(
-          counter, format))
-        self.toeps(counter, format)
+          if format != 'notprovided' and self.useimagemagick:
+              self.progress('Calling Imagemagick to convert plot-{0}.{1} to EPS'.format(
+                counter, format))
+              self.toeps(counter, format)
 %    \end{macrocode}
 % \end{macro}
 %

sagetexpackage.dtx

 
 According to the original README file, this system was originally done
 by Gonzalo Tornaria and Joe Wetherell. Later Harald Schilly made some
-improvements and modifications. Almost all the examples in the
+improvements and modifications. Many of the examples in the
 |example.tex| file are from Harald.
 
 Dan Drake rewrote and extended the style file (there is effectively zero
 documentation and extra Python scripts.
 
 Many thanks to Jason Grout for his numerous comments, suggestions, and
-feedback. Thanks to Nicolas Thi\'ery for the initial code for the
-\texttt{sageexample} environment.
+feedback. Thanks to Nicolas Thi\'ery for the initial code and
+contributions to the \texttt{sageexample} environment.
 
 \section{Copying and licenses}
 \label{sec:copying-licenses}
 %   ``|width=.75\textwidth|'' will be used.\\
 %   \meta{fmt} & You can optionally specify a file extension here; Sage
 %   will then try to save the graphics object to a file with extension
-%   \emph{fmt}. If not specified, \ST\ will save to EPS and PDF files.\\
+%   \emph{fmt}. If not specified, \ST\ will save to EPS and PDF files;
+%   if saving to those formats does not work, \ST will save to a PNG file.\\
 %   \meta{graphics obj} & A Sage object on which you can call |.save()|
 %   with a graphics filename.\\
 %   \meta{keyword args} & Any keyword arguments you put here will
 % freely switch between using, say, a DVI viewer (many of which have
 % support for automatic reloading, source specials and make the writing
 % process easier) and creating PDFs for posting on the web or emailing
-% to colleagues.
+% to colleagues. \ST will fall back to creating a PNG file for any
+% graphics object that cannot be saved as an EPS or PDF file; this is
+% useful for three dimensional plot objects, which currently cannot be
+% saved as EPS or PDF files.
 %
-% If you ask for, say, a PNG file, keep in mind that ordinary |latex|
-% and DVI files have no support for PNG files; \ST detects this and will
+% If you ask for, say, a PNG file (or if one is automatically generated
+% for you as described above), keep in mind that ordinary |latex| and
+% DVI files have no support for PNG files; \ST detects this and will
 % warn you that it cannot find a suitable file if using
 % |latex|.\footnote{We use a typewriter font here to indicate the
-% executables which produce DVI and PDF files, respectively, as
-% opposed to ``\LTX'' which refers to the entire typesetting system.}
+%   executables which produce DVI and PDF files, respectively, as
+%   opposed to ``\LTX'' which refers to the entire typesetting system.}
 % If you use |pdflatex|, there will be no problems because PDF files can
 % include PNG graphics.
 %
 % to create invalid PDFs. Ideally, this option should never be
 % necessary; if you do need to use it, file a bug!
 %
+% This option will eventually be removed, so do not use it.
+%
 % \subsubsection{3D plotting}
 %
 % Right now there is, to put it nicely, a bit of tension between the
 % are vector formats. Tachyon, Sage's 3D plotting system, produces
 % bitmap formats like BMP and PNG.
 %
-% Because of this, when producing 3D plots with |\sageplot|, \emph{you
-% must specify a file format}. The PNG format is compressed and lossless
-% and is by far the best choice, so use that whenever possible. (Right
-% now, it is always possible.) If you do not specify a file format, or
-% specify one that Tachyon does not understand, it will produce files in
-% the Targa format with an incorrect extension and \LTX (both |latex|
-% and |pdflatex|) will be profoundly confused. Don't do that.
-%
-% Since |latex| does not support PNGs, when using 3D plotting (and
-% therefore a bitmap format like PNG), \ST will always issue a warning
-% about incompatible graphics if you use |latex|, provided you've
-% processed the |.sage| file and the PNG file exists. The only exception
-% is if you're using the |imagemagick| option below. (Running |pdflatex|
-% on the same file will work, since PDF files can include PNG files.)
+% \ST will automatically fall back to saving plot objects in PNG format
+% if saving to EPS and PDF fails, so it should automatically work with
+% 3D plot objects. However, since |latex| does not support PNGs, when
+% using 3D plotting (and therefore a bitmap format like PNG), \ST will
+% always issue a warning about incompatible graphics if you use |latex|,
+% provided you've processed the |.sage| file and the PNG file exists.
+% The only exception is if you're using the |imagemagick| option below.
 %
 % \paragraph{The imagemagick option} As a response to the above issue,
 % the \ST package has an |imagemagick| option. If you specify this