tioga 1.4

data/split/Tioga/lib/Strokes.rb

@@ -0,0 +1,129 @@
+#  Strokes.rb
+
+module Tioga
+
+# These are the attributes for doing stroked lines in PDF graphics.
+# The methods for strokes include #stroke, stroke_line, stroke_rect, stroke_frame, stroke_circle, stroke_oval, and stroke_polyline.
+
+class Strokes < Doc < FigureMaker
+
+# Calls move_to_point, append_point_to_path, and #stroke.
+   def stroke_line(x0, y0, x1, y1)
+   end
+
+# :call-seq:
+#               miter_limit                                     
+#               miter_limit = a_float
+#
+# Sets a maximum for the ratio of the miter length to the line width (default is 2).  When the limit is
+# exceeded, the line join is converted from a miter to a bevel.  This limit
+# is needed since when two line segments meet at a sharp angle and mitered joins have been
+# specified as the line_join, it is possible for the miter to extend far beyond the
+# thickness of the line stroking the path.
+   def miter_limit
+   end
+   
+# :call-seq:
+#               default_line_scale                                     
+#               default_line_scale = a_float
+#
+# Scaling factor for the width of stroked lines (default is 1).  The #stroke operations produce lines with
+# a width determined by the product of the line_width times the default_line_scale.
+   def default_line_scale
+   end
+   
+# :call-seq:
+#               line_width                                     
+#               line_width = a_float
+#
+# The width of stroked lines.  A line width of 0 denotes the thinnest line that can be rendered at device
+# resolution: 1 device pixel wide. However, some devices cannot reproduce 1-pixel lines, and on high-resolution
+# devices, they are nearly invisible. Since the results of rendering such "zero-width" lines are device-dependent,
+# their use is not recommended.  The actual line width is adjusted according to the current value 
+# of the default_line_scale.
+   def line_width
+   end
+   
+# :call-seq:
+#               stroke_width                                     
+#               stroke_width = a_float
+#
+# Alias for line_width.
+   def stroke_width
+   end
+   
+# :call-seq:
+#               line_cap                                     
+#               line_cap = a_line_cap
+#
+# The line cap style specifies the shape to be used at the ends of open subpaths (and
+# dashes, if any) when they are stroked.   Valid values are the predefined
+# constants: +LINE_CAP_BUTT+, +LINE_CAP_ROUND+, and +LINE_CAP_SQUARE+.  For +LINE_CAP_BUTT+, the
+# stroke is squared off at the endpoint of the path.  There is no projection beyond the end of the path.
+# For +LINE_CAP_ROUND+, a semicircular arc with a diameter equal to the line width is drawn around the endpoint and filled in.
+# For +LINE_CAP_SQUARE+, the stroke continues beyond the endpoint of the path for a distance equal to half the
+# line width and is then squared off.  See also line_join.
+#
+# http://theory.kitp.ucsb.edu/~paxton/tioga_jpegs/Caps_and_Joins.jpg
+   def line_cap
+   end
+   
+# :call-seq:
+#               line_join                                     
+#               line_join = a_line_join
+#
+# The line join style specifies the shape to be used at the corners of paths that are
+# stroked.  Join styles are significant only at points where consecutive segments of a
+# path connect at an angle; segments that meet or intersect fortuitously receive no special
+# treatment.  Valid values are the predefined constants: +LINE_JOIN_MITER+, +LINE_JOIN_ROUND+,
+# and +LINE_JOIN_BEVEL+.  For +LINE_JOIN_MITER+, the outer edges of the strokes for the two
+# segments are extended until they meet at an angle, as in a picture frame. If the segments
+# meet at too sharp an angle (as defined by the miter limit parameter), a bevel join is used
+# instead.  For +LINE_JOIN_ROUND+, an arc of a circle with a diameter equal to the line width
+# is drawn around the point where the two segments meet, connecting the outer edges of the
+# strokes for the two segments. This pieslice-shaped figure is filled in, producing a rounded
+# corner.  For +LINE_JOIN_BEVEL+, the two segments are finished with butt caps and the resulting
+# notch beyond the ends of the segments is filled with a triangle.  See also line_cap.
+   def line_join
+   end
+
+# :call-seq:
+#               line_type                                     
+#               line_type = a_line_type
+#
+# The line type controls the pattern of dashes and gaps used to stroke paths.
+# It is specified by a dash array and a dash phase. The dash array's elements are
+# numbers that specify the lengths of alternating dashes and gaps; the dash phase
+# specifies the distance into the dash pattern at which to start the dash. The elements
+# of both the dash array and the dash phase are expressed in user space units.
+# An empty dash array and zero phase can be used to set
+# the dash pattern to a solid line.
+# 
+# Dashed lines wrap around curves and corners just as solid stroked lines do. The
+# ends of each dash are treated with the current line cap style, and corners within
+# dashes are treated with the current line join style. A stroking operation takes no
+# measures to coordinate the dash pattern with features of the path; it simply dispenses
+# dashes and gaps along the path in the pattern defined by the dash array.
+# 
+# When a path consisting of several subpaths is stroked, each subpath is treated independently -- 
+# that is, the dash pattern is restarted and the dash phase is reapplied
+# to it at the beginning of each subpath.
+# http://theory.kitp.ucsb.edu/~paxton/tioga_jpegs/Line_Types.jpg
+   def line_type
+   end
+
+
+# Adjust default_line_scale by multiplying it by the given _scale_ and adjust the current line_width accordingly.
+   def rescale_lines(scale)
+   end
+   
+# Calls #context, then, inside the new context, changes line_type and stroke_color (if those arguments are not +nil+),
+# calls append_points_with_gaps_to_path, calls #stroke, and then saves the legend information (if _legend_
+# is not +nil+).  Alias for show_polyline.
+    def stroke_polyline(xs, ys, color = nil, legend = nil, type = nil, gaps = nil, close_subpaths = nil)
+    end
+        
+
+
+end # class
+end # module Tioga

data/split/Tioga/lib/TeX_Text.rb

@@ -0,0 +1,454 @@
+#  TeX_Text.rb
+
+module Tioga
+=begin rdoc
+
+Text in tioga goes to TeX for typesetting: you aren't using a partial emulation that is sort-of-like TeX, you are
+using the real thing.
+
+Since text strings in tioga are passed directly to TeX, you can basically do anything in the text of figures that
+you can do with text in TeX.  The text string can include embedded commands to change font size, family, or whatever.
+However, more commonly the text string will leave the font selection to a higher level in the document.
+In tioga it is easy for you to use the "NFSS", TeX's "New Font Selection Scheme" that specifies
+the font by independently setting family, series, shape, and size.  Families include roman, sans serif, and typewriter.  
+Series include medium and bold face.  Shapes include upright, italic, slant, and small caps.  All these, and the size, are
+set in the SetTiogaFontInfo command in the TeX file preamble.  The tioga defaults for size, family, series, and shape are
+10 point roman, medium, and upright.  You can change these by means of the attributes
+tex_fontfamily, tex_fontseries, tex_fontshape, and tex_fontsize.  Just like for
+the tex_preview page and figure sizes, these are given as strings to be copied to the TeX preview file as part
+of the SetTiogaFontInfo definition.
+
+Text is
+sized by giving a scale factor relative to a base size.  The base size is given by the attribute default_font_size,
+that is initialized to 10 and can be changed using set_default_font_size.  The scale factor is called default_text_scale, is 
+initialized to 1.0, and is changed by rescale_text.  When you do a show_text command in tioga, the call can include an additional scale factor.
+The product of this extra factor times the default_text_scale times the default_font_size determines the size
+in big points on the output page.  At least that's the size the text will have if the output page doesn't get scaled up or down,
+and the TeX document doesn't decide to change things!  With text that is being passed to TeX for typesetting, the final
+decisions aren't made until the last moment.  See Page_Frame_Bounds for more details.
+
+See Tutorial::TextForTeX for information about how to add packages and how (and how not) to enter text for TeX.
+
+=end
+
+class TeX_Text < Doc < FigureMaker
+
+=begin rdoc
+This routine takes care of text that is being sent to TeX for typesetting (see also show_marker
+for text being used as graphics and sent directly to PDF).
+
+The location of the reference point for the text can be given either in figure coordinates ('x' and 'y', or 'at')
+or relative to an edge of the frame ('side', 'position', and 'shift').
+
+You can optionally provide a color as an RGB triple which will be used in a 'textcolor' command for TeX
+enclosing the rest of the text.
+
+The text is scaled by the product of the 'scale' entry times the current value of the
+default_text_scale attribute.  It is rotated by the given 'angle'.
+
+The reference point can be specified horizontally ('justification') and vertically ('alignment').
+
+The 'text' to be sent to TeX can contain anything that TeX will let you put in a box.  In addition to
+the usual text and inline math, you can also do display math, lists, tables, etc.
+
+You can even define your own commands in your TeX preamble and then use those commands as part of the text in 
+the figure.
+
+NOTE: When entering text for TeX in your Ruby program, you'll generally want to use single quotes around the
+string rather than double quotes.  With single quotes, backslashes are treated as normal characters (except
+for the two special cases of \' and \\), so TeX commands using backslashes don't cause trouble.  
+With double quotes, Ruby uses backslash for a variety of escape characters such as newline (\n) and tab (\t),
+so the backslashes for TeX need to be entered as \\ pairs to be safe.
+Compare '$\nu\sim\tau$' to the equivalent form "$\\\\nu\\\\sim\\\\tau$" and the incorrect form "$\nu\sim\tau$".
+
+Dictionary Entries
+    'text'            => a_string        # to be processed by TeX
+    'side'            => a_side          # TOP, BOTTOM, LEFT, or RIGHT
+    'loc'                                # alias for 'side'
+    'position'        => a_float         # fractional distance along side from bottom left
+    'pos'                                # alias for 'position'
+    'shift'           => a_float         # distance away from side in units of text height
+    'at'              => [ x, y ]        # figure coordinates for text reference point
+    'point'                              # alias for 'at'
+    'x'               => a_float         # x location for reference point
+    'y'               => a_float         # y location for reference point
+    'color'           => a_color         # default is to omit color specification
+    'scale'           => a_float         # scale relative to default_text_scale.  default 1
+    'angle'           => a_float         # degrees to rotate.  default 0
+    'alignment'       => an_alignment    # see discussion of alignment
+    'justification'   => a_justification # see discussion of justification
+
+Examples
+
+    def math_typesetting
+        centerx = t.bounds_xmin + 0.5 * t.bounds_width
+        equation =
+            '\int_{-\infty}^{\infty} e^{\color{Red}-x^{2}}\, ' +
+            '\! dx = \color{Green}\sqrt{\pi}'
+        t.justification = CENTERED
+        t.rescale_text(0.8)
+        t.show_text(
+            'text'=>'Inline Math Mode',
+            'x'=>centerx,
+            'y' => t.bounds_ymin + 0.88 * t.bounds_height)
+        t.show_text(
+            'text'=>'Display Math Mode',
+            'x'=> centerx, 
+            'y' => t.bounds_ymin + 0.46 * t.bounds_height)
+        t.rescale_text(0.8)
+        t.show_text(
+            'text'=>'$' + equation + '$',
+            'x'=> centerx,
+            'y' => t.bounds_ymin + 0.78 * t.bounds_height,
+            'scale'=>1.3)
+        t.show_text(
+            'text'=>'$' + equation + '$',
+            'x'=> centerx,
+            'y' => t.bounds_ymin + 0.64 * t.bounds_height,
+            'angle' => 10, 'scale'=>1.3)
+        equation = '\begin{displaymath}' + equation + '\end{displaymath}'
+        equation = '\parbox{15em}{' + equation + '}'
+        t.show_text(
+            'text'=>equation,
+            'x'=> centerx,
+            'y' => t.bounds_ymin + 0.33 * t.bounds_height,
+            'scale'=>1.3)
+        t.show_text(
+            'text'=>equation,
+            'x' => centerx,
+            'y' => t.bounds_ymin + 0.16 * t.bounds_height,
+            'angle' => 10,
+            'scale'=>1.3)
+    end
+    
+http://theory.kitp.ucsb.edu/~paxton/tioga_jpegs/Math_Typesetting.jpg
+
+    def strings
+        t.stroke_rect(0,0,1,1)
+        center_x = 0.5; center_y = 0.5; len = 0.125
+        hls = t.rgb_to_hls(Red)
+        angles = 10
+        delta = 360.0/angles
+        equation = '\int_{-\infty}^{\infty} \! e^{-x^{2}}\, \! dx = \sqrt{\pi}'
+        text =
+            '\parbox{15em}{\begin{displaymath}' + 
+            equation + '\end{displaymath}}'
+        angles.times do |angle|
+            angle *= delta
+            dx = len*cos(angle*RADIANS_PER_DEGREE)
+            dy = len*sin(angle*RADIANS_PER_DEGREE)
+            x = center_x + 2*dx; y = center_y + 2*dy;
+            text_color = t.hls_to_rgb([angle/1.8 + 200, hls[1], hls[2]])
+            t.show_text('text' => text, 'color' => text_color, 'x' => x, 'y' => y,
+                'alignment' => ALIGNED_AT_MIDHEIGHT,
+                'scale' => 0.7, 'angle' => t.convert_to_degrees(dx,dy)) 
+        end
+    end
+
+http://theory.kitp.ucsb.edu/~paxton/tioga_jpegs/Strings.jpg
+
+    def minipages
+        centerx = t.bounds_xmin + 0.5 * t.bounds_width
+        t.show_text(
+            'text' => 'Examples using paragraph boxes',
+            'x' => centerx,
+            'y' => 0.9)
+        t.rescale_text(0.5)
+        t.justification = CENTERED
+        str2 =
+            'The \textcolor{Red}{minipage} is a vertical alignment ' +
+            'environment with a \textcolor{Red}{specified width}.  ' +
+            'It can contain paragraphs, lists, tables, ' +
+            'and equations.  Hyphenation and formatting is automatic.'
+        str2 = '\parbox{15em}{' + str2 + '}'
+        t.show_text(
+            'text' => str2,
+            'x'=> centerx,
+            'y' => t.bounds_ymin + 0.68 * t.bounds_height)
+        t.show_text(
+            'text' => str2,
+            'x'=> centerx,
+            'y' => t.bounds_ymin + 0.30 * t.bounds_height, 'angle' => 20)
+    end
+    
+http://theory.kitp.ucsb.edu/~paxton/tioga_jpegs/Minipages.jpg
+
+    def framebox
+        centerx = t.bounds_xmin + 0.5 * t.bounds_width
+        t.justification = CENTERED
+        t.show_text(
+            'text' => 'Examples using \textbackslash framebox',
+            'x' => centerx, 'y' =>0.8)
+        dx = 0.05; y = 0.6; dy = -0.15; t.line_width = 0.7; t.stroke_color = Blue
+        t.rescale_text(0.75)
+        t.show_text(
+            'text' => '\framebox[20em][c]{\textbackslash framebox[20em][c]\{ a, b, c \}}',
+            'at' => [centerx, y])
+        y += dy
+        t.show_text(
+            'text' => '\framebox[20em][l]{\textbackslash framebox[20em][l]\{ a, b, c \}}',
+            'at' => [centerx, y])
+        y += dy 
+        t.show_text(
+            'text' => '\framebox[20em][r]{\textbackslash framebox[20em][r]\{ a, b, c \}}',
+            'at' => [centerx, y])
+        y += dy
+        t.show_text(
+            'text' => '\framebox[20em][s]{\textbackslash framebox[20em][s]\{ a, b, c \}}',
+            'at' => [centerx, y])
+    end
+         
+http://theory.kitp.ucsb.edu/~paxton/tioga_jpegs/Framebox.jpg
+
+=end
+    def show_text(dict)
+    end
+
+# Changes the default_text_scale attribute by multiplying it times _scale_.
+# This also updates the default_text_height_dx and default_text_height_dy
+# attributes to match the new setting for default_text_scale.
+# See also #rescale.
+    def rescale_text(scale)
+    end
+    
+# Calls check_label_clip with the location for the text reference point from the _dict_.
+# If check_label_clip returns +false+, this routine simply returns.  Otherwise, it passes
+# the _dict_ to show_text.
+    def show_label(dict)
+    end
+
+# Returns +true+ if the point given by the figure coordinates (_x_, _y_)
+# is inside the current label clipping margins.  The routine show_label
+# uses this to filter out unwanted text by testing the reference point.
+# If the point passes this test, then show_label calls show_text; otherwise,
+# it simply returns without showing the text.
+    def check_label_clip(x, y)
+    end
+
+# :call-seq:
+#               justification                                     
+#               justification = a_justification
+#
+# Default  for text horizontal justification.  Valid settings are predefined
+# constants: +LEFT_JUSTIFIED+, +CENTERED+, and +RIGHT_JUSTIFIED+.
+# See also #alignment.
+# 
+# http://theory.kitp.ucsb.edu/~paxton/tioga_jpegs/Text_J_and_A.jpg
+   def justification
+   end
+
+# :call-seq:
+#               alignment                              
+#               alignment = an_alignment
+#
+# Default  for text vertical alignment.  Valid settings are predefined
+# constants: +ALIGNED_AT_TOP+, +ALIGNED_AT_MIDHEIGHT+, +ALIGNED_AT_BASELINE+, and +ALIGNED_AT_BOTTOM+.
+# See also #justification.
+   def alignment
+   end
+
+# :call-seq:
+#               default_text_height_dx                                     
+#
+# Height of text having the default_text_scale as measured in x figure coordinates.
+   def default_text_height_dx
+   end
+
+# :call-seq:
+#               default_text_height_dy                                     
+#
+# Height of text having the default_text_scale as measured in y figure coordinates.
+   def default_text_height_dy
+   end
+
+# :call-seq:
+#               label_left_margin                                     
+#               label_left_margin = a_float
+#
+# Size of margin on left of frame measured as a fraction of frame width, with positive values
+# corresponding to margins on the inside of the frame, and negative values to margins on
+# the outside.
+# The show_label routine discards text having its reference point to the left of this position.
+   def label_left_margin
+   end
+
+# :call-seq:
+#               label_right_margin                                     
+#               label_right_margin = a_float
+#
+# Size of margin on right of frame measured as a fraction of frame width, with positive values
+# corresponding to margins on the inside of the frame, and negative values to margins on
+# the outside.
+# The show_label routine discards text having its reference point to the right of this position.
+   def label_right_margin
+   end
+
+# :call-seq:
+#               label_top_margin                                     
+#               label_top_margin = a_float
+#
+# Size of margin on top of frame measured as a fraction of frame height, with positive values
+# corresponding to margins on the inside of the frame, and negative values to margins on
+# the outside.
+# The show_label routine discards text having its reference point above this position.
+   def label_top_margin
+   end
+
+# :call-seq:
+#               label_bottom_margin                                     
+#               label_bottom_margin = a_float
+#
+# Size of margin on bottom of frame measured as a fraction of frame height, with positive values
+# corresponding to margins on the inside of the frame, and negative values to margins on
+# the outside.
+# The show_label routine discards text having its reference point below this position.
+   def label_bottom_margin
+   end
+   
+# :call-seq:
+#               text_shift_on_left                                     
+#               text_shift_on_left = a_float
+#
+# Default value for "shift" in show_text when "side" is +LEFT+.
+   def text_shift_on_left
+   end
+   
+# :call-seq:
+#               text_shift_on_right                                     
+#               text_shift_on_right = a_float
+#
+# Default value for "shift" in show_text when "side" is +RIGHT+.
+   def text_shift_on_right
+   end
+   
+# :call-seq:
+#               text_shift_on_top                                    
+#               text_shift_on_top = a_float
+#
+# Default value for "shift" in show_text when "side" is +TOP+.
+   def text_shift_on_top
+   end
+   
+# :call-seq:
+#               text_shift_on_bottom                                     
+#               text_shift_on_bottom = a_float
+#
+# Default value for "shift" in show_text when "side" is +BOTTOM+.
+   def text_shift_on_bottom
+   end
+   
+# :call-seq:
+#               text_shift_from_x_origin                                     
+#               text_shift_from_x_origin = a_float
+#
+# Default value for "shift" in show_yaxis when "loc" is +AT_X_ORIGIN+.
+   def text_shift_from_x_origin
+   end
+   
+# :call-seq:
+#               text_shift_from_y_origin                                     
+#               text_shift_from_y_origin = a_float
+#
+# Default value for "shift" in show_xaxis when "loc" is +AT_Y_ORIGIN+.
+   def text_shift_from_y_origin
+   end
+   
+# :call-seq:
+#               default_text_scale                                     
+#
+# Default factor determining text size (relative to the default font size).
+# Is initialized to 1.0 and changed by rescale_text.
+   def default_text_scale
+   end
+
+   
+# :call-seq:
+#               default_font_size                                    
+#
+# Default font size in points (relative to the default_font_size).
+# Is initialized to 10.0 and changed by set_default_font_size.
+# The intention is that this gets set rarely and most font sizing is done
+# using rescale_text.
+   def default_font_size
+   end
+   
+# :call-seq:
+#               set_default_font_size(size, update_size_string) # size in points                                    
+#
+# Sets the font size in points. If the 'update_size_string' flag is true,
+# then the 'tex_fontsize' attribute will be set to match the new font size.
+# The intention is that set_default_font_size gets called rarely and most font sizing is done
+# using rescale_text.
+   def set_default_font_size(size, update_size_string = true)
+   end
+
+# :call-seq:
+#                tex_fontsize                                     
+#                tex_fontsize = a_string  # giving the font size in points
+# 
+# This string will be used as the basic font size specification in the preview TeX file.
+# Valid strings include things like '10.0' or '12.0'.
+#         
+# See also: tex_fontfamily, tex_fontseries, and tex_fontshape.
+   def tex_fontsize
+   end
+
+
+# :call-seq:
+#                tex_fontfamily                                     
+#                tex_fontfamily = a_string  # giving the font family 
+# 
+# This string will be used as the basic font family specification in the preview TeX file.  Valid strings include
+# 'rmdefault', 'sfdefault', and 'ttdefault', for roman face, sans serif face, and typewriter face, respectively.
+#         
+# See also: tex_fontsize, tex_fontseries, and tex_fontshape.
+   def tex_fontfamily
+   end
+
+# :call-seq:
+#                tex_fontseries                                    
+#                tex_fontseries = a_string  # giving the font series 
+# 
+# This string will be used as the basic font series specification in the preview TeX file.  Valid strings include
+# 'mddefault' and 'bfdefault', for medium and bold face, respectively.
+#         
+# See also: tex_fontsize, tex_fontfamily, and tex_fontshape.  
+   def tex_fontseries
+   end
+
+
+# :call-seq:
+#                tex_fontshape                                   
+#                tex_fontshape = a_string  # giving the font shape 
+# 
+# This string will be used as the basic font shape specification in the preview TeX file.  Valid strings include
+# *'updefault', 'itdefault', 'sldefault', and 'scdefault', for upright, italic, slant, and small caps, respectively.
+#
+# See also: tex_fontsize, tex_fontfamily, and tex_fontseries.
+   def tex_fontshape
+   end
+
+
+# :call-seq:
+#               tex_xaxis_numeric_label
+#               tex_xaxis_numeric_label = a_string
+#
+# The string for a numeric label is put in this TeX command string to be formatted.
+# For example, `$#1$' will give the numbers in math mode, while `$\mathsf{#1}$' will 
+# show the label using the math sans-serif font.   Alias for xaxis_numeric_label_tex.
+   def tex_xaxis_numeric_label
+   end
+
+# :call-seq:
+#               tex_yaxis_numeric_label
+#               tex_yaxis_numeric_label = a_string
+#
+# The string for a numeric label is put in this TeX command string to be formatted.
+# For example, `$#1$' will give the numbers in math mode, while `$\mathsf{#1}$' will 
+# show the label using the math sans-serif font.   Alias for yaxis_numeric_label_tex.
+   def tex_yaxis_numeric_label
+   end
+
+
+end # class
+end # module Tioga