add a pdf.show(dpi=...) method

src/sage/interfaces/cmdline/tool.py

@@ -65,7 +65,26 @@ def __init__(self, *tools):
             msg.append('* sudo apt-get install {0}'.format(deb))
         super(ToolMissingException, self).__init__('\n'.join(msg))
 
+    def convert_to_warning(self):
+        """
+        Display warning with the same exception message
+
+        EXAMPLES::
 
+            sage: from sage.interfaces.cmdline.tool import ToolMissingException
+            sage: from sage.interfaces.cmdline.posix import cat
+            sage: exc = ToolMissingException(cat)
+            sage: exc.convert_to_warning()
+            doctest:...: UserWarning: One or more of the following required tools is not installed:
+            * cat: Part of GNU coreutils
+            <BLANKLINE>
+            You might be able to install it with:
+            * sudo ...
+        """
+        import warnings
+        warnings.warn(self.message)
+
+
 class CalledToolError(subprocess.CalledProcessError):
 
     def __str__(self):

src/sage/misc/latex.py

@@ -446,26 +446,34 @@ def _latex_(self):
         """
         return str(self)
 
-    def compile(self):
+    def compile(self, trim=True):
         """
         Return PDF output
 
+        INPUT:
+
+        - ``trim`` -- boolean. Whether to cut off margins of the
+          output pdf document.
+
         OUTPUT:
 
         :class:`~sage.repl.portable_document_format.PortableDocumentFormat`.
 
         EXAMPLES:
 
-            sage: latex(1/2).compile()
+            sage: latex(1/2).compile()    # optional - latex
             PDF document (... bytes)
         """
         source = _latex_file_(self, title='{}')
         from sage.interfaces.cmdline.latex import compile_latex
         from sage.interfaces.cmdline.tool import ToolMissingException
         pdf = compile_latex(source)
+        if not trim:
+            return pdf
         try:
             return pdf.trim()
-        except ToolMissingException:
+        except ToolMissingException as exc:
+            exc.convert_to_warning()
             return pdf
 
 

src/sage/repl/portable_document_format.py

@@ -20,7 +20,6 @@
 
 
 import os
-import warnings
 from sage.structure.sage_object import SageObject
 from sage.repl.rich_output.buffer import OutputBuffer
 from sage.misc.cachefunc import cached_method
@@ -159,6 +158,7 @@ def _rich_repr_(self, display_manager, **kwds):
             sage: pdf._rich_repr_(dm)
             OutputImagePdf container
         """
+        dpi = kwds.get('dpi', 150)
         if display_manager.preferences.graphics == 'disable':
             return
         OutputImagePdf = display_manager.types.OutputImagePdf
@@ -170,16 +170,41 @@ def _rich_repr_(self, display_manager, **kwds):
         #    try:
         #        svg = self.to_svg()
         #    except ToolMissingException as exc:
-        #        warnings.warn(exc.message)
+        #        exc.convert_to_warning()
         #    return OutputImageSvg(svg)
         OutputImagePng = display_manager.types.OutputImagePng
         if OutputImagePng in display_manager.supported_output():
             try:
-                png = self.to_png(dpi=150)
+                png = self.to_png(dpi=dpi)
             except ToolMissingException as exc:
-                warnings.warn(exc.message)
+                exc.convert_to_warning()
             return OutputImagePng(png)
 
+    def show(self, dpi=150):
+        """
+        Show this document immediately.
+
+        This method attempts to display the document immediately,
+        without waiting for the currently running code (if any) to
+        return to the command line. Be careful, calling it from within
+        a loop will potentially launch a large number of external
+        viewer programs.
+
+        INPUT:
+
+        - ``dpi`` -- integer. The resolution at which to raster the
+          pdf file if necessary.
+
+        EXAMPLES::
+
+            sage: from sage.repl.portable_document_format import PortableDocumentFormat
+            sage: pdf = PortableDocumentFormat._example()
+            sage: pdf.show(dpi=75)
+        """
+        from sage.repl.rich_output import get_display_manager
+        dm = get_display_manager()
+        dm.display_immediately(self, dpi=dpi)
+
     def trim(self):
         """
         Cut off white margins