Ticket #5956: trac_5956_figsize_units.patch

sage/plot/graphics.py

@@ -11 +11 @@
 
 - Jeroen Demeyer (2012-04-19): split off this file from plot.py (:trac:`12857`)
 - Punarbasu Purkayastha (2012-05-20): Add logarithmic scale (:trac:`4529`)
+- Emily Chen (2013-01-05): Add documentation for :meth:`~sage.plot.graphics.Graphics.show` figsize parameter (:trac:`5956`)
 
 """
 
@@ -1271 +1272 @@
 
         - ``filename`` - (default: None) string
 
-        - ``dpi`` - dots per inch
-
-        - ``figsize`` - [width, height]
+        - ``dpi`` - (default: 100) dots per inch
+
+        - ``figsize`` - (default: [8.0,6.0]) [width, height] inches
 
         - ``fig_tight`` - (default: True) whether to clip the drawing
           tightly around drawn objects.  If True, then the resulting
@@ -1444 +1445 @@
             sage: c = circle((1,1), 1, color='red')
             sage: c.show(xmin=-1, xmax=3, ymin=-1, ymax=3)
         
-        You could also just make the picture larger by changing ``figsize``::
-
-            sage: c.show(figsize=8, xmin=-1, xmax=3, ymin=-1, ymax=3)
+        You can make the picture larger by changing ``figsize`` with width, height each having a maximum value 
+        of 327 inches at default dpi::
+
+            sage: e = ellipse((0,0),4,1)
+            sage: e.show(figsize=[327,10],dpi=100)
+            sage: e.show(figsize=[328,10],dpi=80)
 
         You can turn off the drawing of the axes::
 
@@ -1721 +1725 @@
             ...
             ValueError: Either expand the range of the dependent variable to allow two different integer powers of your `base`, or change your `base` to a smaller number.
             sage: p.show(scale='loglog', base=8) # this works.
-
+        
+        TESTS::
+        
+        The figsize width and height parameters must be less than 328 inches each.::
+        
+            sage: e = ellipse((0,0),4,1)
+            sage: e.show(figsize=[328,10],dpi=100)
+            Traceback (most recent call last):
+            ...
+            ValueError: width and height must each be below 32768
+            
+        The following test results in a segmentation fault and should not be doctested.::
+        
+            sage: e = ellipse((0,0),4,1)
+            sage: e.show(figsize=[232,232],dpi=100) # not tested
+            Unhandled SIGSEGV: A segmentation fault occurred in Sage.
+            This probably occurred because a *compiled* component of Sage has a bug
+            in it and is not properly wrapped with sig_on(), sig_off(). You might
+            want to run Sage under gdb with 'sage -gdb' to debug this.
+            Sage will now terminate.
+            
+            sage: e.show(figsize=[327,181],dpi=100) # not tested
+            Unhandled SIGSEGV: A segmentation fault occurred in Sage.
+            This probably occurred because a *compiled* component of Sage has a bug
+            in it and is not properly wrapped with sig_on(), sig_off(). You might
+            want to run Sage under gdb with 'sage -gdb' to debug this.
+            Sage will now terminate.
+            
         """
 
         # This option should not be passed on to save().