write_xlsx 0.62.0 → 0.64.0

data/lib/write_xlsx/worksheet.rb

@@ -4,9 +4,12 @@
 require 'write_xlsx/colors'
 require 'write_xlsx/format'
 require 'write_xlsx/drawing'
+require 'write_xlsx/sparkline'
 require 'write_xlsx/compatibility'
 require 'write_xlsx/utility'
 require 'write_xlsx/package/conditional_format'
+require 'write_xlsx/worksheet/cell_data'
+require 'write_xlsx/worksheet/print_style'
 require 'tempfile'
 
 module Writexlsx
@@ -18,48 +21,48 @@ module Writexlsx
   #
   # The following methods are available through a new worksheet:
   #
-  #     write
-  #     write_number
-  #     write_string
-  #     write_rich_string
-  #     write_blank
-  #     write_row
-  #     write_col
-  #     write_date_time
-  #     write_url
-  #     write_url_range
-  #     write_formula
-  #     write_comment
-  #     show_comments
-  #     set_comments_author
-  #     insert_image
-  #     insert_chart
-  #     insert_shape
-  #     data_validation
-  #     conditional_formatting
-  #     add_sparkline
-  #     add_table
-  #     name
-  #     activate
-  #     select
-  #     hide
-  #     set_first_sheet
-  #     protect
-  #     set_selection
-  #     set_row
-  #     set_column
-  #     outline_settings
-  #     freeze_panes
-  #     split_panes
-  #     merge_range
-  #     merge_range_type
-  #     set_zoom
-  #     right_to_left
-  #     hide_zero
-  #     set_tab_color
-  #     autofilter
-  #     filter_column
-  #     filter_column_list
+  # * write
+  # * write_number
+  # * write_string
+  # * write_rich_string
+  # * write_blank
+  # * write_row
+  # * write_col
+  # * write_date_time
+  # * write_url
+  # * write_formula
+  # * write_comment
+  # * show_comments
+  # * comments_author=()
+  # * insert_image
+  # * insert_chart
+  # * insert_shape
+  # * insert_button
+  # * data_validation
+  # * conditional_formatting
+  # * add_sparkline
+  # * add_table
+  # * name
+  # * activate
+  # * select
+  # * hide
+  # * set_first_sheet
+  # * protect
+  # * set_selection
+  # * set_row
+  # * set_column
+  # * outline_settings
+  # * freeze_panes
+  # * split_panes
+  # * merge_range
+  # * merge_range_type
+  # * zoom=()
+  # * right_to_left
+  # * hide_zero
+  # * tab_color=()
+  # * autofilter
+  # * filter_column
+  # * filter_column_list
   #
   # ==Cell notation
   #
@@ -105,35 +108,38 @@ module Writexlsx
   # following sections are given in terms of row-column notation. In all cases
   # it is also possible to use A1 notation.
   #
+  # Note: in Excel it is also possible to use a R1C1 notation. This is not
+  # supported by WriteXLSX.
+  #
   # == PAGE SET-UP METHODS
   #
   # Page set-up methods affect the way that a worksheet looks
   # when it is printed. They control features such as page headers and footers
   # and margins. These methods are really just standard worksheet methods.
-  # They are documented here in a separate section for the sake of clarity.
   #
   # The following methods are available for page set-up:
   #
-  #   set_landscape()
-  #   set_portrait()
-  #   set_page_view()
-  #   set_paper()
-  #   center_horizontally()
-  #   center_vertically()
-  #   set_margins()
-  #   set_header()
-  #   set_footer()
-  #   repeat_rows()
-  #   repeat_columns()
-  #   hide_gridlines()
-  #   print_row_col_headers()
-  #   print_area()
-  #   print_across()
-  #   fit_to_pages()
-  #   set_start_page()
-  #   set_print_scale()
-  #   set_h_pagebreaks()
-  #   set_v_pagebreaks()
+  #  * set_landscape
+  #  * set_portrait
+  #  * set_page_view
+  #  * set_paper
+  #  * center_horizontally
+  #  * center_vertically
+  #  * set_margins
+  #  * set_header
+  #  * set_footer
+  #  * repeat_rows
+  #  * repeat_columns
+  #  * hide_gridlines
+  #  * print_row_col_headers
+  #  * print_area
+  #  * print_across
+  #  * fit_to_pages
+  #  * set_start_page
+  #  * set_print_scale
+  #  * set_h_pagebreaks
+  #  * set_v_pagebreaks
+  #
   # A common requirement when working with WriteXLSX is to apply the same
   # page set-up features to all of the worksheets in a workbook. To do this
   # you can use the sheets() method of the workbook class to access the array
@@ -143,182 +149,134 @@ module Writexlsx
   #     worksheet.set_landscape
   #   end
   #
+  # == FORMULAS AND FUNCTIONS IN EXCEL
+  #
+  # === Introduction
+  #
+  # The following is a brief introduction to formulas and functions in Excel
+  # and WriteXLSX.
+  #
+  # A formula is a string that begins with an equals sign:
+  #
+  #     '=A1+B1'
+  #     '=AVERAGE(1, 2, 3)'
+  #
+  # The formula can contain numbers, strings, boolean values, cell references,
+  # cell ranges and functions. Named ranges are not supported. Formulas should
+  # be written as they appear in Excel, that is cells and functions must be
+  # in uppercase.
+  #
+  # Cells in Excel are referenced using the A1 notation system where the column
+  # is designated by a letter and the row by a number. Columns range from +A+
+  # to +XFD+ i.e. 0 to 16384, rows range from 1 to 1048576.
+  # The Writexlsx::Utility module that is included in the distro contains
+  # helper functions for dealing with A1 notation, for example:
+  #
+  #     require 'write_xlsx'
+  #
+  #     include Writexlsx::Utility
+  #
+  #     row, col = xl_cell_to_rowcol('C2')    # (1, 2)
+  #     str      = xl_rowcol_to_cell(1, 2)    # C2
+  #
+  # The Excel +$+ notation in cell references is also supported. This allows
+  # you to specify whether a row or column is relative or absolute. This only
+  # has an effect if the cell is copied. The following examples show relative
+  # and absolute values.
+  #
+  #     '=A1'   # Column and row are relative
+  #     '=$A1'  # Column is absolute and row is relative
+  #     '=A$1'  # Column is relative and row is absolute
+  #     '=$A$1' # Column and row are absolute
+  #
+  # Formulas can also refer to cells in other worksheets of the current
+  # workbook. For example:
+  #
+  #     '=Sheet2!A1'
+  #     '=Sheet2!A1:A5'
+  #     '=Sheet2:Sheet3!A1'
+  #     '=Sheet2:Sheet3!A1:A5'
+  #     %Q{='Test Data'!A1}
+  #     %Q{='Test Data1:Test Data2'!A1}
+  #
+  # The sheet reference and the cell reference are separated by +!+ the
+  # exclamation mark symbol. If worksheet names contain spaces, commas or
+  # parentheses then Excel requires that the name is enclosed in single
+  # quotes as shown in the last two examples above. In order to avoid using
+  # a lot of escape characters you can use the quote operator +%Q{}+ to
+  # protect the quotes. Only valid sheet names that have been added using the
+  # add_worksheet() method can be used in formulas. You cannot reference
+  # external workbooks.
+  #
+  # The following table lists the operators that are available in Excel's
+  # formulas. The majority of the operators are the same as Ruby's,
+  # differences are indicated:
+  #
+  #     Arithmetic operators:
+  #     =====================
+  #     Operator  Meaning                   Example
+  #        +      Addition                  1+2
+  #        -      Subtraction               2-1
+  #        *      Multiplication            2*3
+  #        /      Division                  1/4
+  #        ^      Exponentiation            2^3      # Equivalent to **
+  #        -      Unary minus               -(1+2)
+  #        %      Percent (Not modulus)     13%
+  #
+  #
+  #     Comparison operators:
+  #     =====================
+  #     Operator  Meaning                   Example
+  #         =     Equal to                  A1 =  B1 # Equivalent to ==
+  #         <>    Not equal to              A1 <> B1 # Equivalent to !=
+  #         >     Greater than              A1 >  B1
+  #         <     Less than                 A1 <  B1
+  #         >=    Greater than or equal to  A1 >= B1
+  #         <=    Less than or equal to     A1 <= B1
+  #
+  #
+  #     String operator:
+  #     ================
+  #     Operator  Meaning                   Example
+  #         &     Concatenation             "Hello " & "World!" # [1]
+  #
+  #
+  #     Reference operators:
+  #     ====================
+  #     Operator  Meaning                   Example
+  #         :     Range operator            A1:A4               # [2]
+  #         ,     Union operator            SUM(1, 2+2, B3)     # [3]
+  #
+  #
+  #     Notes:
+  #     [1]: Equivalent to "Hello " + "World!" in Ruby.
+  #     [2]: This range is equivalent to cells A1, A2, A3 and A4.
+  #     [3]: The comma behaves like the list separator in Perl.
+  #
+  # The range and comma operators can have different symbols in non-English
+  # versions of Excel. These may be supported in a later version of WriteXLSX.
+  # In the meantime European users of Excel take note:
+  #
+  #     worksheet.write('A1', '=SUM(1; 2; 3)')   # Wrong!!
+  #     worksheet.write('A1', '=SUM(1, 2, 3)')   # Okay
+  #
+  # For a general introduction to Excel's formulas and an explanation of the
+  # syntax of the function refer to the Excel help files or the following:
+  # http://office.microsoft.com/en-us/assistance/CH062528031033.aspx.
+  #
+  # If your formula doesn't work in Excel::Writer::XLSX try the following:
+  #
+  #     1. Verify that the formula works in Excel.
+  #     2. Ensure that cell references and formula names are in uppercase.
+  #     3. Ensure that you are using ':' as the range operator, A1:A4.
+  #     4. Ensure that you are using ',' as the union operator, SUM(1,2,3).
+  #     5. If you verify that the formula works in Gnumeric, OpenOffice.org
+  #        or LibreOffice, make sure to note items 2-4 above, since these
+  #        applications are more flexible than Excel with formula syntax.
+  #
   class Worksheet
     include Writexlsx::Utility
 
-    class CellData   # :nodoc:
-      include Writexlsx::Utility
-
-      attr_reader :row, :col, :token, :xf
-      attr_reader :result, :range, :link_type, :url, :tip
-
-      #
-      # attributes for the <cell> element. This is the innermost loop so efficiency is
-      # important where possible.
-      #
-      def cell_attributes #:nodoc:
-        xf_index = xf ? xf.get_xf_index : 0
-        attributes = ['r', xl_rowcol_to_cell(row, col)]
-
-        # Add the cell format index.
-        if xf_index != 0
-          attributes << 's' << xf_index
-        elsif @worksheet.set_rows[row] && @worksheet.set_rows[row][1]
-          row_xf = @worksheet.set_rows[row][1]
-          attributes << 's' << row_xf.get_xf_index
-        elsif @worksheet.col_formats[col]
-          col_xf = @worksheet.col_formats[col]
-          attributes << 's' << col_xf.get_xf_index
-        end
-        attributes
-      end
-
-      def display_url_string?
-        true
-      end
-    end
-
-    class NumberCellData < CellData # :nodoc:
-      def initialize(worksheet, row, col, num, xf)
-        @worksheet = worksheet
-        @row, @col, @token, @xf = row, col, num, xf
-      end
-
-      def data
-        @token
-      end
-
-      def write_cell
-        @worksheet.writer.tag_elements('c', cell_attributes) do
-          @worksheet.write_cell_value(token)
-        end
-      end
-    end
-
-    class StringCellData < CellData # :nodoc:
-      def initialize(worksheet, row, col, index, xf)
-        @worksheet = worksheet
-        @row, @col, @token, @xf = row, col, index, xf
-      end
-
-      def data
-        { :sst_id => token }
-      end
-
-      def write_cell
-        attributes = cell_attributes
-        attributes << 't' << 's'
-        @worksheet.writer.tag_elements('c', attributes) do
-          @worksheet.write_cell_value(token)
-        end
-      end
-
-      def display_url_string?
-        false
-      end
-    end
-
-    class FormulaCellData < CellData # :nodoc:
-      def initialize(worksheet, row, col, formula, xf, result)
-        @worksheet = worksheet
-        @row, @col, @token, @xf, @result = row, col, formula, xf, result
-      end
-
-      def data
-        @result || 0
-      end
-
-      def write_cell
-        attributes = cell_attributes
-        if @result &&  !(@result.to_s =~ /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/)
-          attributes << 't' << 'str'
-        end
-        @worksheet.writer.tag_elements('c', attributes) do
-          @worksheet.write_cell_formula(token)
-          @worksheet.write_cell_value(result || 0)
-        end
-      end
-    end
-
-    class FormulaArrayCellData < CellData # :nodoc:
-      def initialize(worksheet, row, col, formula, xf, range, result)
-        @worksheet = worksheet
-        @row, @col, @token, @xf, @range, @result = row, col, formula, xf, range, result
-      end
-
-      def data
-        @result || 0
-      end
-
-      def write_cell
-        @worksheet.writer.tag_elements('c', cell_attributes) do
-          @worksheet.write_cell_array_formula(token, range)
-          @worksheet.write_cell_value(result)
-        end
-      end
-    end
-
-    class BlankCellData < CellData # :nodoc:
-      def initialize(worksheet, row, col, index, xf)
-        @worksheet = worksheet
-        @row, @col, @xf = row, col, xf
-      end
-
-      def data
-        ''
-      end
-
-      def write_cell
-        @worksheet.writer.empty_tag('c', cell_attributes)
-      end
-    end
-
-    class PrintStyle # :nodoc:
-      attr_accessor :margin_left, :margin_right, :margin_top, :margin_bottom  # :nodoc:
-      attr_accessor :margin_header, :margin_footer                            # :nodoc:
-      attr_accessor :repeat_rows, :repeat_cols, :print_area                   # :nodoc:
-      attr_accessor :hbreaks, :vbreaks, :scale                                # :nodoc:
-      attr_accessor :fit_page, :fit_width, :fit_height, :page_setup_changed   # :nodoc:
-      attr_accessor :across                                                   # :nodoc:
-      attr_accessor :orientation  # :nodoc:
-
-      def initialize # :nodoc:
-        @margin_left = 0.7
-        @margin_right = 0.7
-        @margin_top = 0.75
-        @margin_bottom = 0.75
-        @margin_header = 0.3
-        @margin_footer = 0.3
-        @repeat_rows   = ''
-        @repeat_cols   = ''
-        @print_area    = ''
-        @hbreaks = []
-        @vbreaks = []
-        @scale = 100
-        @fit_page = false
-        @fit_width  = nil
-        @fit_height = nil
-        @page_setup_changed = false
-        @across = false
-        @orientation = true
-      end
-
-      def attributes    # :nodoc:
-        [
-         'left',   @margin_left,
-         'right',  @margin_right,
-         'top',    @margin_top,
-         'bottom', @margin_bottom,
-         'header', @margin_header,
-         'footer', @margin_footer
-        ]
-      end
-
-      def orientation?
-        !!@orientation
-      end
-    end
-
     attr_reader :index # :nodoc:
     attr_reader :charts, :images, :tables, :shapes, :drawing # :nodoc:
     attr_reader :external_hyper_links, :external_drawing_links # :nodoc:
@@ -390,7 +348,6 @@ def initialize(workbook, index, name) #:nodoc:
       @shapes                 = []
       @shape_hash             = {}
 
-      @zoom = 100
       @outline_row_level = 0
       @outline_col_level = 0
 
@@ -662,7 +619,7 @@ def protect_default_settings  # :nodoc:
     #
     # It is also possible, and generally clearer, to specify a column range
     # using the form of A1 notation used for columns. See the note about
-    # "Cell notation".
+    # {"Cell notation"}[#label-Cell+notation].
     #
     # Examples:
     #
@@ -798,7 +755,7 @@ def set_column(*args)
     # in which case last_row and last_col can be omitted. The active cell
     # within a selected range is determined by the order in which first and
     # last are specified. It is also possible to specify a cell or a range
-    # using A1 notation. See the note about "Cell notation".
+    # using A1 notation. See the note about {"Cell notation"}[#label-Cell+notation].
     #
     # Examples:
     #
@@ -969,20 +926,27 @@ def set_page_view(flag = true)
     #
     # Set the colour of the worksheet tab.
     #
-    # The set_tab_color() method is used to change the colour of the worksheet
+    # The tab_color=() method is used to change the colour of the worksheet
     # tab. This feature is only available in Excel 2002 and later. You can use
     # one of the standard colour names provided by the Format object or a
-    # colour index. See "COLOURS IN EXCEL" and the set_custom_color() method.
+    # colour index.
+    # See "COLOURS IN EXCEL" and the set_custom_color() method.
     #
-    #     worksheet1.set_tab_color('red')
-    #     worksheet2.set_tab_color(0x0C)
+    #     worksheet1.tab_color = 'red'
+    #     worksheet2.tab_color = 0x0C
     #
     # See the tab_colors.rb program in the examples directory of the distro.
     #
-    def set_tab_color(color)
+    def tab_color=(color)
       @tab_color = Colors.new.get_color(color)
     end
 
+    # This method is deprecated. use tab_color=().
+    def set_tab_color(color)
+      put_deprecate_message("#{self}.set_tab_color")
+      self.tab_color = color
+    end
+
     #
     # Set the paper type. Ex. 1 = US Letter, 9 = A4
     #
@@ -1448,7 +1412,7 @@ def print_repeat_rows   # :nodoc:
     # method. The parameters first_column and last_column are zero based.
     # The last_column parameter is optional if you only wish to specify
     # one column. You can also specify the columns using A1 column
-    # notation, see the note about "Cell notation".
+    # notation, see the note about {"Cell notation"}[#label-Cell+notation].
     #
     #     worksheet1.repeat_columns(0)        # Repeat the first column
     #     worksheet2.repeat_columns(0, 1)     # Repeat the first two columns
@@ -1477,7 +1441,7 @@ def print_repeat_cols  # :nodoc:
     #
     # This method is used to specify the area of the worksheet that will
     # be printed. All four parameters must be specified. You can also use
-    # A1 notation, see the note about "Cell notation".
+    # A1 notation, see the note about {"Cell notation"}[#label-Cell+notation].
     #
     #     worksheet1.print_area( 'A1:H20' );    # Cells A1 to H20
     #     worksheet2.print_area( 0, 0, 19, 7 ); # The same
@@ -1498,16 +1462,33 @@ def print_area(*args)
     end
 
     #
-    # Set the worksheet zoom factor.
+    # Set the worksheet zoom factor in the range 10 <= $scale <= 400:
+    #
+    #     worksheet1.zoom = 50
+    #     worksheet2.zoom = 75
+    #     worksheet3.zoom = 300
+    #     worksheet4.zoom = 400
     #
-    def set_zoom(scale = 100)
+    # The default zoom factor is 100. You cannot zoom to "Selection" because
+    # it is calculated by Excel at run-time.
+    #
+    # Note, zoom=() does not affect the scale of the printed page.
+    # For that you should use print_scale=().
+    #
+    def zoom=(scale)
       # Confine the scale to Excel's range
       if scale < 10 or scale > 400
         # carp "Zoom factor scale outside range: 10 <= zoom <= 400"
-        scale = 100
+        @zoom = 100
+      else
+        @zoom = scale.to_i
       end
+    end
 
-      @zoom = scale.to_i
+    # This method is deprecated. use zoom=().
+    def set_zoom(scale)
+      put_deprecate_message("#{self}.set_zoom")
+      self.zoom = scale
     end
 
     #
@@ -1521,7 +1502,7 @@ def set_zoom(scale = 100)
     #
     # The default scale factor is 100. Note, print_scale=() does not
     # affect the scale of the visible page in Excel. For that you should
-    # use set_zoom().
+    # use zoom=().
     #
     # Note also that although it is valid to use both fit_to_pages() and
     # print_scale=() on the same worksheet only one of these options
@@ -1639,8 +1620,8 @@ def set_start_page(page_start)
     #     write_row
     #     write_col
     #
-    # The general rule is that if the data looks like a something then
-    # a something is written. Here are some examples in both row-column
+    # The general rule is that if the data looks like a _something_ then
+    # a _something_ is written. Here are some examples in both row-column
     # and A1 notation:
     #
     #                                                     # Same as:
@@ -1664,7 +1645,8 @@ def set_start_page(page_start)
     #     # Write an array formula. Not available in writeexcel gem.
     #     worksheet.write('A16', '{=SUM(A1:B1*A2:B2)}' ) # write_formula()
     #
-    # The format parameter is optional. It should be a valid Format object.
+    # The +format+ parameter is optional. It should be a valid Format object,
+    # See {"CELL FORMATTING"}[Format.html#label-CELL+FORMATTING]:
     #
     #     format = workbook.add_format
     #     format.set_bold
@@ -1673,9 +1655,9 @@ def set_start_page(page_start)
     #
     #     worksheet.write(4, 0, 'Hello', format)    # Formatted string
     #
-    # The write() method will ignore empty strings or nil tokens unless a format
-    # is also supplied. As such you needn't worry about special handling for
-    # empty or nil in your data. See also the write_blank() method.
+    # The write() method will ignore empty strings or +nil+ tokens unless a
+    # format is also supplied. As such you needn't worry about special handling
+    # for empty or nil in your data. See also the write_blank() method.
     #
     # One problem with the write() method is that occasionally data looks like
     # a number but you don't want it treated as a number. For example, zip
@@ -1744,13 +1726,13 @@ def write(*args)
     #     worksheet.write(0, 2, array[2])
     #
     # Note: For convenience the write() method behaves in the same way as
-    # write_row() if it is passed an array reference.
+    # write_row() if it is passed an array.
     # Therefore the following two method calls are equivalent:
     #
     #     worksheet.write_row('A1', array)    # Write a row of data
     #     worksheet.write(    'A1', array)    # Same thing
     #
-    # As with all of the write methods the format parameter is optional.
+    # As with all of the write methods the +format+ parameter is optional.
     # If a format is specified it is applied to all the elements of the
     # data array.
     #
@@ -1764,6 +1746,7 @@ def write(*args)
     #            ]
     #
     #     worksheet.write_row('A1', eec)
+    #
     # Would produce a worksheet as follows:
     #
     #      -----------------------------------------------------------
@@ -1779,16 +1762,11 @@ def write(*args)
     # To write the data in a row-column order refer to the write_col()
     # method below.
     #
-    # Any nil in the data will be ignored unless a format is applied to
+    # Any +nil+ in the data will be ignored unless a format is applied to
     # the data, in which case a formatted blank cell will be written.
     # In either case the appropriate row or column value will still
     # be incremented.
     #
-    # The write_row() method returns the first error encountered when
-    # writing the elements of the data or zero if no errors were
-    # encountered. See the return values described for the write()
-    # method.
-    #
     # See also the write_arrays.rb program in the examples directory
     # of the distro.
     #
@@ -1831,7 +1809,7 @@ def write_row(*args)
     #     worksheet.write(1, 0, array[1])
     #     worksheet.write(2, 0, array[2])
     #
-    # As with all of the write methods the format parameter is optional.
+    # As with all of the write methods the +format+ parameter is optional.
     # If a format is specified it is applied to all the elements of the
     # data array.
     #
@@ -1861,7 +1839,7 @@ def write_row(*args)
     # To write the data in a column-row order refer to the write_row()
     # method above.
     #
-    # Any nil in the data will be ignored unless a format is applied to
+    # Any +nil+ in the data will be ignored unless a format is applied to
     # the data, in which case a formatted blank cell will be written.
     # In either case the appropriate row or column value will still be
     # incremented.
@@ -1875,10 +1853,6 @@ def write_row(*args)
     #     worksheet.write_col('A1', array     ) # Write a column of data
     #     worksheet.write(    'A1', [ array ] ) # Same thing
     #
-    # The write_col() method returns the first error encountered when
-    # writing the elements of the data or zero if no errors were encountered.
-    # See the return values described for the write() method above.
-    #
     # See also the write_arrays.rb program in the examples directory of
     # the distro.
     #
@@ -1899,9 +1873,6 @@ def write_col(*args)
     #
     # Write a comment to the specified row and column (zero indexed).
     #
-    # write_comment methods return:
-    #   Returns  0 : normal termination
-    #
     # The write_comment() method is used to add a comment to a cell.
     # A cell comment is indicated in Excel by a small red triangle in the
     # upper right-hand corner of the cell. Moving the cursor over the red
@@ -1913,15 +1884,15 @@ def write_col(*args)
     #     worksheet.write_comment(2, 2, 'This is a comment.')
     #
     # As usual you can replace the row and column parameters with an A1
-    # cell reference. See the note about "Cell notation".
+    # cell reference. See the note about {"Cell notation"}[#label-Cell+notation].
     #
     #     worksheet.write(        'C3', 'Hello')
     #     worksheet.write_comment('C3', 'This is a comment.')
     #
     # The write_comment() method will also handle strings in UTF-8 format.
     #
-    #     worksheet.write_comment('C3', "\x{263a}")       # Smiley
-    #     worksheet.write_comment('C4', 'Comment ca va?')
+    #     worksheet.write_comment('C3', "日本")
+    #     worksheet.write_comment('C4', 'Comment ça va')
     #
     # In addition to the basic 3 argument form of write_comment() you can
     # pass in several optional key/value pairs to control the format of
@@ -1958,9 +1929,9 @@ def write_col(*args)
     #     worksheet.write_comment('C3', 'Atonement', :author => 'Ian McEwan')
     #
     # The default author for all cell comments can be set using the
-    # set_comments_author() method.
+    # comments_author=() method.
     #
-    #     worksheet.set_comments_author('Ruby')
+    #     worksheet.comments_author = 'Ruby'
     #
     # ===Option: visible
     #
@@ -2057,13 +2028,13 @@ def write_col(*args)
     #
     # You can apply as many of these options as you require.
     #
-    # Note about using options that adjust the position of the cell comment
-    # such as start_cell, start_row, start_col, x_offset and y_offset:
+    # <b>Note about using options that adjust the position of the cell comment
+    # such as start_cell, start_row, start_col, x_offset and y_offset</b>:
     # Excel only displays offset cell comments when they are displayed as
     # "visible". Excel does not display hidden cells as moved when you
     # mouse over them.
     #
-    # Note about row height and comments. If you specify the height of a
+    # <b>Note about row height and comments</b>. If you specify the height of a
     # row that contains a comment then WriteXLSX will adjust the
     # height of the comment to maintain the default or user specified
     # dimensions. However, the height of a row can also be adjusted
@@ -2097,8 +2068,8 @@ def write_comment(*args)
     #     worksheet.write_number(0, 0, 123456)
     #     worksheet.write_number('A2', 2.3451)
     #
-    # See the note about "Cell notation".
-    # The format parameter is optional.
+    # See the note about {"Cell notation"}[#label-Cell+notation].
+    # The +format+ parameter is optional.
     #
     # In general it is sufficient to use the write() method.
     #
@@ -2123,7 +2094,7 @@ def write_number(*args)
     #   write_string(row, column, string [, format ] )
     #
     # Write a string to the specified row and column (zero indexed).
-    # format is optional.
+    # +format+ is optional.
     #
     #     worksheet.write_string(0, 0, 'Your text here')
     #     worksheet.write_string('A2', 'or here')
@@ -2169,9 +2140,7 @@ def write_string(*args)
     # The method receives string fragments prefixed by format objects. The final
     # format object is used as the cell format.
     #
-    # write_rich_string methods return:
-    #
-    # For example to write the string "This is bold and this is italic"
+    # For example to write the string "This is *bold* and this is _italic_"
     # you would use the following:
     #
     #     bold   = workbook.add_format(:bold   => 1)
@@ -2180,7 +2149,7 @@ def write_string(*args)
     #     worksheet.write_rich_string('A1',
     #         'This is ', bold, 'bold', ' and this is ', italic, 'italic')
     #
-    # The basic rule is to break the string into fragments and put a format
+    # The basic rule is to break the string into fragments and put a +format+
     # object before the fragment that you want to format. For example:
     #
     #     # Unformatted string.
@@ -2195,8 +2164,9 @@ def write_string(*args)
     #     # In WriteXLSX.
     #     worksheet.write_rich_string('A1',
     #         'This is an ', format, 'example', ' string')
-    # String fragments that don't have a format are given a default
-    # format. So for example when writing the string "Some bold text"
+    #
+    # String fragments that don't have a format are given a default format.
+    # So for example when writing the string "Some *bold* text"
     # you would use the first example below but it would be equivalent
     # to the second:
     #
@@ -2250,8 +2220,10 @@ def write_string(*args)
     #     worksheet.write_rich_string('A7',
     #         italic, 'j = k', super, '(n-1)', center)
     #
+    # "http://jmcnamara.github.com/excel-writer-xlsx/images/examples/rich_strings.jpg"
+    #
     # As with write_sting() the maximum string size is 32767 characters.
-    # See also the note about "Cell notation".
+    # See also the note about {"Cell notation"}[#label-Cell+notation].
     #
     def write_rich_string(*args)
       # Check for a cell reference in A1 notation and substitute row and column
@@ -2310,6 +2282,11 @@ def write_rich_string(*args)
     # A blank cell is used to specify formatting without adding a string
     # or a number.
     #
+    #     worksheet.write_blank(0, 0, format)
+    #
+    # This method is used to add formatting to cell which doesn't contain a
+    # string or number value.
+    #
     # A blank cell without a format serves no purpose. Therefore, we don't write
     # a BLANK record unless a format is specified. This is mainly an optimisation
     # for the write_row() and write_col() methods.
@@ -2325,9 +2302,9 @@ def write_rich_string(*args)
     #     worksheet.write('A2', nil )            # Ignored
     #
     # This seemingly uninteresting fact means that you can write arrays of
-    # data without special treatment for nil or empty string values.
+    # data without special treatment for +nil+ or empty string values.
     #
-    # See the note about "Cell notation".
+    # See the note about {"Cell notation"}[#label-Cell+notation].
     #
     def write_blank(*args)
       # Check for a cell reference in A1 notation and substitute row and column
@@ -2348,7 +2325,7 @@ def write_blank(*args)
     # :call-seq:
     #   write_formula(row, column, formula [ , format [ , value ] ] )
     #
-    # Write a formula or function to the cell specified by row and column:
+    # Write a formula or function to the cell specified by +row+ and +column+:
     #
     #     worksheet.write_formula(0, 0, '=$B$3 + B4')
     #     worksheet.write_formula(1, 0, '=SIN(PI()/4)')
@@ -2356,19 +2333,21 @@ def write_blank(*args)
     #     worksheet.write_formula('A4', '=IF(A3>1,"Yes", "No")')
     #     worksheet.write_formula('A5', '=AVERAGE(1, 2, 3, 4)')
     #     worksheet.write_formula('A6', '=DATEVALUE("1-Jan-2001")')
+    #
     # Array formulas are also supported:
     #
     #     worksheet.write_formula('A7', '{=SUM(A1:B1*A2:B2)}')
     #
     # See also the write_array_formula() method.
     #
-    # See the note about "Cell notation". For more information about
-    # writing Excel formulas see "FORMULAS AND FUNCTIONS IN EXCEL"
+    # See the note about {"Cell notation"}[#label-Cell+notation].
+    # For more information about writing Excel formulas see
+    # {"FORMULAS AND FUNCTIONS IN EXCEL"}[#label-FORMULAS+AND+FUNCTIONS+IN+EXCEL]
     #
     # If required, it is also possible to specify the calculated value
     # of the formula. This is occasionally necessary when working with
     # non-Excel applications that don't calculate the value of the
-    # formula. The calculated value is added at the end of the argument list:
+    # formula. The calculated +value+ is added at the end of the argument list:
     #
     #     worksheet.write('A1', '=2+2', format, 4)
     #
@@ -2395,16 +2374,13 @@ def write_formula(*args)
     # :call-seq:
     #   write_array_formula(row1, col1, row2, col2, formula [ , format [ , value ] ] )
     #
-    # Write an array formula to the specified row and column (zero indexed).
-    #
-    # format is optional.
-    #
-    # In Excel an array formula is a formula that performs a calculation
-    # on a set of values. It can return a single value or a range of values.
+    # Write an array formula to a cell range. In Excel an array formula is a
+    # formula that performs a calculation on a set of values. It can return
+    # a single value or a range of values.
     #
     # An array formula is indicated by a pair of braces around the
-    # formula: {=SUM(A1:B1*A2:B2)}. If the array formula returns a single
-    # value then the first and last parameters should be the same:
+    # formula: +{=SUM(A1:B1*A2:B2)}+. If the array formula returns a single
+    # value then the +first_+ and +last_+ parameters should be the same:
     #
     #     worksheet.write_array_formula('A1:A1', '{=SUM(B1:C1*B2:C2)}')
     #
@@ -2522,19 +2498,16 @@ def store_formula(string)
 
     #
     # :call-seq:
-    #   write_url(row, column, url [ , format, string, tool_tip ] )
+    #   write_url(row, column, url [ , format, label ] )
     #
-    # Write a hyperlink to a URL in the cell specified by row and column.
+    # Write a hyperlink to a URL in the cell specified by +row+ and +column+.
     # The hyperlink is comprised of two elements: the visible label and
     # the invisible link. The visible label is the same as the link unless
     # an alternative label is specified. The label parameter is optional.
     # The label is written using the write() method. Therefore it is
     # possible to write strings, numbers or formulas as labels.
     #
-    # The hyperlink can be to a http, ftp, mail, internal sheet, or external
-    # directory url.
-    #
-    # The format parameter is also optional, however, without a format
+    # The +format+ parameter is also optional, however, without a format
     # the link won't look like a format.
     #
     # The suggested format is:
@@ -2548,11 +2521,22 @@ def store_formula(string)
     # There are four web style URI's supported:
     # http://, https://, ftp:// and mailto::
     #
-    #     worksheet.write_url(0, 0, 'ftp://www.ruby.org/',  format)
-    #     worksheet.write_url(1, 0, 'http://www.ruby.com/', format, 'Ruby')
-    #     worksheet.write_url('A3', 'http://www.ruby.com/', format)
+    #     worksheet.write_url(0, 0, 'ftp://www.ruby-lang.org/',  format)
+    #     worksheet.write_url('A3', 'http://www.ruby-lang.org/', format)
     #     worksheet.write_url('A4', 'mailto:foo@bar.com', format)
     #
+    # You can display an alternative string using the +label+ parameter:
+    #
+    #     worksheet.write_url(1, 0, 'http://www.ruby-lang.org/', format, 'Ruby')
+    #
+    # If you wish to have some other cell data such as a number or a formula
+    # you can overwrite the cell using another call to write_*():
+    #
+    #     worksheet.write_url('A1', 'http://www.ruby-lang.org/')
+    #
+    #     # Overwrite the URL string with a formula. The cell is still a link.
+    #     worksheet.write_formula('A1', '=1+1', format)
+    #
     # There are two local URIs supported: internal: and external:.
     # These are used for hyperlinks to internal worksheet references or
     # external workbook and worksheet references:
@@ -2571,19 +2555,26 @@ def store_formula(string)
     #
     # Worksheet references are typically of the form Sheet1!A1. You can
     # also refer to a worksheet range using the standard Excel notation:
-    # Sheet1!A1:B2.
+    # +Sheet1!A1:B2+.
     #
     # In external links the workbook and worksheet name must be separated
-    # by the # character: external:Workbook.xlsx#Sheet1!A1'.
+    # by the # character: +external:Workbook.xlsx#Sheet1!A1+.
     #
     # You can also link to a named range in the target worksheet. For
-    # example say you have a named range called my_name in the workbook
-    # c:\temp\foo.xlsx you could link to it as follows:
+    # example say you have a named range called +my_name+ in the workbook
+    # +c:\temp\foo.xlsx+ you could link to it as follows:
     #
     #     worksheet.write_url('A14', 'external:c:\temp\foo.xlsx#my_name')
     #
     # Excel requires that worksheet names containing spaces or non
-    # alphanumeric characters are single quoted as follows 'Sales Data'!A1.
+    # alphanumeric characters are single quoted as follows +'Sales Data'!A1+.
+    #
+    # Note: WriteXLSX will escape the following characters in URLs as required
+    # by Excel: \s " < > \ [ ] ` ^ { } unless the URL already contains +%xx+
+    # style escapes. In which case it is assumed that the URL was escaped
+    # correctly by the user and will by passed directly to Excel.
+    #
+    # See also, the note about {"Cell notation"}[#label-Cell+notation].
     #
     def write_url(*args)
       # Check for a cell reference in A1 notation and substitute row and column
@@ -2701,14 +2692,14 @@ def write_url(*args)
     #
     #     worksheet.write_date_time('A1', '2004-05-13T23:20', date_format)
     #
-    # The date_string should be in the following format:
+    # The +date_string+ should be in the following format:
     #
     #     yyyy-mm-ddThh:mm:ss.sss
     #
     # This conforms to an ISO8601 date but it should be noted that the
     # full range of ISO8601 formats are not supported.
     #
-    # The following variations on the date_string parameter are permitted:
+    # The following variations on the +date_string+ parameter are permitted:
     #
     #     yyyy-mm-ddThh:mm:ss.sss         # Standard format
     #     yyyy-mm-ddT                     # No time
@@ -2719,8 +2710,10 @@ def write_url(*args)
     #
     # Note that the T is required in all cases.
     #
-    # A date should always have a format, otherwise it will appear
-    # as a number, see "DATES AND TIME IN EXCEL" and "CELL FORMATTING".
+    # A date should always have a +format+, otherwise it will appear
+    # as a number, see
+    # {"DATES AND TIME IN EXCEL"}[#method-i-write_date_time-label-DATES+AND+TIME+IN+EXCEL]
+    # and {"CELL FORMATTING"}[#label-CELL+FORMATTING].
     # Here is a typical example:
     #
     #     date_format = workbook.add_format(:num_format => 'mm/dd/yy')
@@ -2732,6 +2725,105 @@ def write_url(*args)
     #
     # See also the date_time.rb program in the examples directory of the distro.
     #
+    #
+    # == DATES AND TIME IN EXCEL
+    #
+    # There are two important things to understand about dates and times in Excel:
+    #
+    # 1 A date/time in Excel is a real number plus an Excel number format.
+    # 2 WriteXLSX doesn't automatically convert date/time strings in write() to an Excel date/time.
+    #
+    # These two points are explained in more detail below along with some
+    # suggestions on how to convert times and dates to the required format.
+    #
+    # === An Excel date/time is a number plus a format
+    #
+    # If you write a date string with write() then all you will get is a string:
+    #
+    #     worksheet.write('A1', '02/03/04')   # !! Writes a string not a date. !!
+    #
+    # Dates and times in Excel are represented by real numbers, for example
+    # "Jan 1 2001 12:30 AM" is represented by the number 36892.521.
+    #
+    # The integer part of the number stores the number of days since the epoch
+    # and the fractional part stores the percentage of the day.
+    #
+    # A date or time in Excel is just like any other number. To have the number
+    # display as a date you must apply an Excel number format to it.
+    # Here are some examples.
+    #
+    #     #!/usr/bin/ruby -w
+    #
+    #     require 'write_xlsx'
+    #
+    #     workbook  = WriteXLSX.new('date_examples.xlsx')
+    #     worksheet = workbook>add_worksheet
+    #
+    #     worksheet.set_column('A:A', 30)    # For extra visibility.
+    #
+    #     number = 39506.5
+    #
+    #     worksheet.write('A1', number)             #   39506.5
+    #
+    #     format2 = workbook.add_format(:num_format => 'dd/mm/yy')
+    #     worksheet.write('A2', number, format2)    #  28/02/08
+    #
+    #     format3 = workbook.add_format(:num_format => 'mm/dd/yy')
+    #     worksheet.write('A3', number, format3)    #  02/28/08
+    #
+    #     format4 = workbook.add_format(:num_format => 'd-m-yyyy')
+    #     worksheet.write('A4', number, format4)    #  28-2-2008
+    #
+    #     format5 = workbook.add_format(:num_format => 'dd/mm/yy hh:mm')
+    #     worksheet.write('A5', number, format5)    #  28/02/08 12:00
+    #
+    #     format6 = workbook.add_format(:num_format => 'd mmm yyyy')
+    #     worksheet.write('A6', number, format6)    # 28 Feb 2008
+    #
+    #     format7 = workbook.add_format(:num_format => 'mmm d yyyy hh:mm AM/PM')
+    #     worksheet.write('A7', number , format7)   #  Feb 28 2008 12:00 PM
+    #
+    # WriteXLSX doesn't automatically convert date/time strings
+    #
+    # WriteXLSX doesn't automatically convert input date strings into Excel's
+    # formatted date numbers due to the large number of possible date formats
+    # and also due to the possibility of misinterpretation.
+    #
+    # For example, does 02/03/04 mean March 2 2004, February 3 2004 or
+    # even March 4 2002.
+    #
+    # Therefore, in order to handle dates you will have to convert them to
+    # numbers and apply an Excel format. Some methods for converting dates are
+    # listed in the next section.
+    #
+    # The most direct way is to convert your dates to the ISO8601
+    # yyyy-mm-ddThh:mm:ss.sss date format and use the write_date_time()
+    # worksheet method:
+    #
+    #     worksheet.write_date_time('A2', '2001-01-01T12:20', format)
+    #
+    # See the write_date_time() section of the documentation for more details.
+    #
+    # A general methodology for handling date strings with write_date_time() is:
+    #
+    # 1. Identify incoming date/time strings with a regex.
+    # 2. Extract the component parts of the date/time using the same regex.
+    # 3. Convert the date/time to the ISO8601 format.
+    # 4. Write the date/time using write_date_time() and a number format.
+    # For a slightly more advanced solution you can modify the write() method
+    # to handle date formats of your choice via the add_write_handler() method.
+    # See the add_write_handler() section of the docs and the
+    # write_handler3.rb and write_handler4.rb programs in the examples
+    # directory of the distro.
+    #
+    # Converting dates and times to an Excel date or time
+    #
+    # The write_date_time() method above is just one way of handling dates and
+    # times.
+    #
+    # You can also use the convert_date_time() worksheet method to convert
+    # from an ISO8601 style date string to an Excel date and time number.
+    #
     def write_date_time(*args)
       # Check for a cell reference in A1 notation and substitute row and column
       row, col, str, xf = row_col_notation(args)
@@ -2755,10 +2847,6 @@ def write_date_time(*args)
     # :call-seq:
     #   insert_chart(row, column, chart [ , x, y, x_scale, y_scale ] )
     #
-    # Insert a chart into a worksheet. The chart argument should be a Chart
-    # object or else it is assumed to be a filename of an external binary file.
-    # The latter is for backwards compatibility.
-    #
     # This method can be used to insert a Chart object into a worksheet.
     # The Chart must be created by the add_chart() Workbook method and
     # it must have the embedded option set.
@@ -2775,10 +2863,10 @@ def write_date_time(*args)
     # Writexlsx::Chart for details on how to configure it. See also the
     # chart_*.rb programs in the examples directory of the distro.
     #
-    # The x, y, x_scale and y_scale parameters are optional.
+    # The +x+, +y+, +x_scale+ and +y_scale+ parameters are optional.
     #
-    # The parameters x and y can be used to specify an offset from the top
-    # left hand corner of the cell specified by row and column. The offset
+    # The parameters +x+ and +y+ can be used to specify an offset from the top
+    # left hand corner of the cell specified by +row+ and +column+. The offset
     # values are in pixels.
     #
     #     worksheet1.insert_chart('E2', chart, 3, 3)
@@ -2813,11 +2901,10 @@ def insert_chart(*args)
 
     #
     # :call-seq:
-    #   insert_image(row, column, filename [ , x, y, x_scale, y_scale ] )
+    #   insert_image(row, column, filename, x=0, y=0, x_scale=1, y_scale=1)
+    #
+    # Partially supported. Currently only works for 96 dpi images.
     #
-    # Partially supported. Currently only works for 96 dpi images. This
-    # will be fixed in an upcoming release.
-    #--
     # This method can be used to insert a image into a worksheet. The image
     # can be in PNG, JPEG or BMP format. The x, y, x_scale and y_scale
     # parameters are optional.
@@ -2826,8 +2913,8 @@ def insert_chart(*args)
     #     worksheet2.insert_image('A1', '../images/ruby.bmp')
     #     worksheet3.insert_image('A1', '.c:\images\ruby.bmp')
     #
-    # The parameters x and y can be used to specify an offset from the top
-    # left hand corner of the cell specified by row and column. The offset
+    # The parameters +x+ and +y+ can be used to specify an offset from the top
+    # left hand corner of the cell specified by +row+ and +column+. The offset
     # values are in pixels.
     #
     #     worksheet1.insert_image('A1', 'ruby.bmp', 32, 10)
@@ -2836,14 +2923,12 @@ def insert_chart(*args)
     # cell. This can be occasionally useful if you wish to align two or more
     # images relative to the same cell.
     #
-    # The parameters x_scale and y_scale can be used to scale the inserted
+    # The parameters +x_scale+ and +y_scale+ can be used to scale the inserted
     # image horizontally and vertically:
     #
     #     # Scale the inserted image: width x 2.0, height x 0.8
     #     worksheet.insert_image('A1', 'perl.bmp', 0, 0, 2, 0.8)
     #
-    # See also the images.rb program in the examples directory of the distro.
-    #
     # Note: you must call set_row() or set_column() before insert_image()
     # if you wish to change the default dimensions of any of the rows or
     # columns that the image occupies. The height of a row can also change
@@ -2854,7 +2939,6 @@ def insert_chart(*args)
     #
     # BMP images must be 24 bit, true colour, bitmaps. In general it is
     # best to avoid BMP images since they aren't compressed.
-    #++
     #
     def insert_image(*args)
       # Check for a cell reference in A1 notation and substitute row and column.
@@ -3777,9 +3861,267 @@ def add_table(*args)
       table
     end
 
+    #
+    # :call-seq:
+    #    add_sparkline(properties)
     #
     # Add sparklines to the worksheet.
     #
+    # Sparklines are a feature of Excel 2010+ which allows you to add small
+    # charts to worksheet cells. These are useful for showing visual trends
+    # in data in a compact format.
+    #
+    # In WriteXLSX Sparklines can be added to cells using the add_sparkline()
+    # worksheet method:
+    #
+    #     worksheet.add_sparkline(
+    #         {
+    #             :location => 'F2',
+    #             :range    => 'Sheet1!A2:E2',
+    #             :type     => 'column',
+    #             :style    => 12
+    #         }
+    #     )
+    #
+    # Note: Sparklines are a feature of Excel 2010+ only. You can write them
+    # to an XLSX file that can be read by Excel 2007 but they won't be
+    # displayed.
+    #
+    # The add_sparkline() worksheet method is used to add sparklines to a
+    # cell or a range of cells.
+    #
+    # The parameters to add_sparkline() must be passed in a hash.
+    # The main sparkline parameters are:
+    #
+    #     :location        (required)
+    #     :range           (required)
+    #     :type
+    #     :style
+    #
+    #     :markers
+    #     :negative_points
+    #     :axis
+    #     :reverse
+    # Other, less commonly used parameters are:
+    #
+    #     :high_point
+    #     :low_point
+    #     :first_point
+    #     :last_point
+    #     :max
+    #     :min
+    #     :empty_cells
+    #     :show_hidden
+    #     :date_axis
+    #     :weight
+    #
+    #     :series_color
+    #     :negative_color
+    #     :markers_color
+    #     :first_color
+    #     :last_color
+    #     :high_color
+    #     :low_color
+    #
+    # These parameters are explained in the sections below:
+    #
+    # ===:location
+    #
+    # This is the cell where the sparkline will be displayed:
+    #
+    #     location => 'F1'
+    # The location should be a single cell. (For multiple cells see "Grouped Sparklines" below).
+    #
+    # To specify the location in row-column notation use the xl_rowcol_to_cell() function from the Excel::Writer::XLSX::Utility module.
+    #
+    #     use Excel::Writer::XLSX::Utility ':rowcol';
+    #     ...
+    #     location => xl_rowcol_to_cell( 0, 5 ), # F1
+    # range
+    #
+    # This specifies the cell data range that the sparkline will plot:
+    #
+    #     $worksheet->add_sparkline(
+    #         {
+    #             location => 'F1',
+    #             range    => 'A1:E1',
+    #         }
+    #     );
+    # The range should be a 2D array. (For 3D arrays of cells see "Grouped Sparklines" below).
+    #
+    # If range is not on the same worksheet you can specify its location using the usual Excel notation:
+    #
+    #             range => 'Sheet1!A1:E1',
+    # If the worksheet contains spaces or special characters you should quote the worksheet name in the same way that Excel does:
+    #
+    #             range => q('Monthly Data'!A1:E1),
+    # To specify the location in row-column notation use the xl_range() or xl_range_formula() functions from the Excel::Writer::XLSX::Utility module.
+    #
+    #     use Excel::Writer::XLSX::Utility ':rowcol';
+    #     ...
+    #     range => xl_range( 1, 1,  0, 4 ),                   # 'A1:E1'
+    #     range => xl_range_formula( 'Sheet1', 0, 0,  0, 4 ), # 'Sheet1!A2:E2'
+    # type
+    #
+    # Specifies the type of sparkline. There are 3 available sparkline types:
+    #
+    #     line    (default)
+    #     column
+    #     win_loss
+    # For example:
+    #
+    #     {
+    #         location => 'F1',
+    #         range    => 'A1:E1',
+    #         type     => 'column',
+    #     }
+    # style
+    #
+    # Excel provides 36 built-in Sparkline styles in 6 groups of 6. The style parameter can be used to replicate these and should be a corresponding number from 1 .. 36.
+    #
+    #     {
+    #         location => 'A14',
+    #         range    => 'Sheet2!A2:J2',
+    #         style    => 3,
+    #     }
+    # The style number starts in the top left of the style grid and runs left to right. The default style is 1. It is possible to override colour elements of the sparklines using the *_color parameters below.
+    #
+    # markers
+    #
+    # Turn on the markers for line style sparklines.
+    #
+    #     {
+    #         location => 'A6',
+    #         range    => 'Sheet2!A1:J1',
+    #         markers  => 1,
+    #     }
+    # Markers aren't shown in Excel for column and win_loss sparklines.
+    #
+    # negative_points
+    #
+    # Highlight negative values in a sparkline range. This is usually required with win_loss sparklines.
+    #
+    #     {
+    #         location        => 'A21',
+    #         range           => 'Sheet2!A3:J3',
+    #         type            => 'win_loss',
+    #         negative_points => 1,
+    #     }
+    # axis
+    #
+    # Display a horizontal axis in the sparkline:
+    #
+    #     {
+    #         location => 'A10',
+    #         range    => 'Sheet2!A1:J1',
+    #         axis     => 1,
+    #     }
+    # reverse
+    #
+    # Plot the data from right-to-left instead of the default left-to-right:
+    #
+    #     {
+    #         location => 'A24',
+    #         range    => 'Sheet2!A4:J4',
+    #         type     => 'column',
+    #         reverse  => 1,
+    #     }
+    # weight
+    #
+    # Adjust the default line weight (thickness) for line style sparklines.
+    #
+    #      weight => 0.25,
+    # The weight value should be one of the following values allowed by Excel:
+    #
+    #     0.25  0.5   0.75
+    #     1     1.25
+    #     2.25
+    #     3
+    #     4.25
+    #     6
+    # high_point, low_point, first_point, last_point
+    #
+    # Highlight points in a sparkline range.
+    #
+    #         high_point  => 1,
+    #         low_point   => 1,
+    #         first_point => 1,
+    #         last_point  => 1,
+    # max, min
+    #
+    # Specify the maximum and minimum vertical axis values:
+    #
+    #         max         => 0.5,
+    #         min         => -0.5,
+    # As a special case you can set the maximum and minimum to be for a group of sparklines rather than one:
+    #
+    #         max         => 'group',
+    # See "Grouped Sparklines" below.
+    #
+    # empty_cells
+    #
+    # Define how empty cells are handled in a sparkline.
+    #
+    #     empty_cells => 'zero',
+    # The available options are:
+    #
+    #     gaps   : show empty cells as gaps (the default).
+    #     zero   : plot empty cells as 0.
+    #     connect: Connect points with a line ("line" type  sparklines only).
+    # show_hidden
+    #
+    # Plot data in hidden rows and columns:
+    #
+    #     show_hidden => 1,
+    # Note, this option is off by default.
+    #
+    # date_axis
+    #
+    # Specify an alternative date axis for the sparkline. This is useful if the data being plotted isn't at fixed width intervals:
+    #
+    #     {
+    #         location  => 'F3',
+    #         range     => 'A3:E3',
+    #         date_axis => 'A4:E4',
+    #     }
+    # The number of cells in the date range should correspond to the number of cells in the data range.
+    #
+    # series_color
+    #
+    # It is possible to override the colour of a sparkline style using the following parameters:
+    #
+    #     series_color
+    #     negative_color
+    #     markers_color
+    #     first_color
+    #     last_color
+    #     high_color
+    #     low_color
+    # The color should be specified as a HTML style #rrggbb hex value:
+    #
+    #     {
+    #         location     => 'A18',
+    #         range        => 'Sheet2!A2:J2',
+    #         type         => 'column',
+    #         series_color => '#E965E0',
+    #     }
+    # Grouped Sparklines
+    #
+    # The add_sparkline() worksheet method can be used multiple times to write as many sparklines as are required in a worksheet.
+    #
+    # However, it is sometimes necessary to group contiguous sparklines so that changes that are applied to one are applied to all. In Excel this is achieved by selecting a 3D range of cells for the data range and a 2D range of cells for the location.
+    #
+    # In Excel::Writer::XLSX, you can simulate this by passing an array refs of values to location and range:
+    #
+    #     {
+    #         location => [ 'A27',          'A28',          'A29'          ],
+    #         range    => [ 'Sheet2!A5:J5', 'Sheet2!A6:J6', 'Sheet2!A7:J7' ],
+    #         markers  => 1,
+    #     }
+    # Sparkline examples
+    #
+    # See the sparklines1.pl and sparklines2.pl example programs in the examples directory of the distro.
+    #
     # The add_sparkline worksheet method is used to add sparklines to a cell or a range of cells.
     #
     #    worksheet.add_sparkline(
@@ -3800,112 +4142,91 @@ def add_table(*args)
     # These are useful for showing visual trends in data in a compact format.
     #
     def add_sparkline(param)
-      sparkline = {}
-
-      # Check for valid input parameters.
-      param.each_key do |k|
-        unless valid_sparkline_parameter[k]
-          raise "Unknown parameter '#{k}' in add_sparkline()"
-        end
-      end
-      [:location, :range].each do |required_key|
-        unless param[required_key]
-          raise "Parameter '#{required_key}' is required in add_sparkline()"
-        end
-      end
-
-      # Handle the sparkline type.
-      type = param[:type] || 'line'
-      unless ['line', 'column', 'win_loss'].include?(type)
-        raise "Parameter ':type' must be 'line', 'column' or 'win_loss' in add_sparkline()"
-      end
-      type = 'stacked' if type == 'win_loss'
-      sparkline[:_type] = type
-
-      # We handle single location/range values or array refs of values.
-      sparkline[:_locations] = [param[:location]].flatten
-      sparkline[:_ranges]    = [param[:range]].flatten
-
-      if sparkline[:_ranges].size != sparkline[:_locations].size
-        raise "Must have the same number of location and range parameters in add_sparkline()"
-      end
-
-      # Store the count.
-      sparkline[:_count] = sparkline[:_locations].size
-
-      # Get the worksheet name for the range conversion below.
-      sheetname = quote_sheetname(@name)
-
-      # Cleanup the input ranges.
-      sparkline[:_ranges].collect! do |range|
-        # Remove the absolute reference $ symbols.
-        range = range.gsub(/\$/, '')
-        # Convert a simple range into a full Sheet1!A1:D1 range.
-        range = "#{sheetname}!#{range}" unless range =~ /!/
-        range
-      end
-
-      # Cleanup the input locations.
-      sparkline[:_locations].collect! { |location| location.gsub(/\$/, '') }
-
-      # Map options.
-      sparkline[:_high]      = param[:high_point]
-      sparkline[:_low]       = param[:low_point]
-      sparkline[:_negative]  = param[:negative_points]
-      sparkline[:_first]     = param[:first_point]
-      sparkline[:_last]      = param[:last_point]
-      sparkline[:_markers]   = param[:markers]
-      sparkline[:_min]       = param[:min]
-      sparkline[:_max]       = param[:max]
-      sparkline[:_axis]      = param[:axis]
-      sparkline[:_reverse]   = param[:reverse]
-      sparkline[:_hidden]    = param[:show_hidden]
-      sparkline[:_weight]    = param[:weight]
-
-      # Map empty cells options.
-      empty = param[:empty_cells] || ''
-      sparkline[:_empty] = case empty
-      when 'zero'
-        0
-      when 'connect'
-        'span'
-      else
-        'gap'
-      end
-
-      # Map the date axis range.
-      date_range = param[:date_axis]
-      if ptrue?(date_range) && !(date_range =~ /!/)
-        date_range = "#{sheetname}!#{date_range}"
-      end
-      sparkline[:_date_axis] = date_range
-
-      # Set the sparkline styles.
-      style_id = param[:style] || 0
-      style = spark_styles[style_id]
-
-      sparkline[:_series_color]   = style[:series]
-      sparkline[:_negative_color] = style[:negative]
-      sparkline[:_markers_color]  = style[:markers]
-      sparkline[:_first_color]    = style[:first]
-      sparkline[:_last_color]     = style[:last]
-      sparkline[:_high_color]     = style[:high]
-      sparkline[:_low_color]      = style[:low]
-
-      # Override the style colours with user defined colors.
-      set_spark_color(sparkline, param, :series_color)
-      set_spark_color(sparkline, param, :negative_color)
-      set_spark_color(sparkline, param, :markers_color)
-      set_spark_color(sparkline, param, :first_color)
-      set_spark_color(sparkline, param, :last_color)
-      set_spark_color(sparkline, param, :high_color)
-      set_spark_color(sparkline, param, :low_color)
-
-      @sparklines << sparkline
+      @sparklines << Sparkline.new(self, param, quote_sheetname(@name))
     end
 
     #
-    # Insert a button form object into the worksheet.
+    # :call-seq:
+    #   insert_button(row, col, properties)
+    #
+    # The insert_button() method can be used to insert an Excel form button
+    # into a worksheet.
+    #
+    # This method is generally only useful when used in conjunction with
+    # the Workbook add_vba_project() method to tie the button to a macro
+    # from an embedded VBA project:
+    #
+    #     workbook  = WriteXLSX.new('file.xlsm')
+    #     ...
+    #     workbook.add_vba_project('./vbaProject.bin')
+    #
+    #     worksheet.insert_button('C2', { :macro => 'my_macro' } )
+    #
+    # The properties of the button that can be set are:
+    #
+    #     :macro
+    #     :caption
+    #     :width
+    #     :height
+    #     :x_scale
+    #     :y_scale
+    #     :x_offset
+    #     :y_offset
+    #
+    # === Option: macro
+    # This option is used to set the macro that the button will invoke when
+    # the user clicks on it. The macro should be included using the
+    # Workbook#add_vba_project() method shown above.
+    #
+    #     worksheet.insert_button('C2', { :macro => 'my_macro' } )
+    #
+    # The default macro is +ButtonX_Click+ where X is the button number.
+    #
+    # ===Option: caption
+    # This option is used to set the caption on the button. The default is
+    # <tt>Button X</tt> where X is the button number.
+    #
+    #     worksheet.insert_button('C2', { :macro => 'my_macro', :caption => 'Hello' })
+    #
+    # ===Option: width
+    # This option is used to set the width of the button in pixels.
+    #
+    #     worksheet.insert_button('C2', { :macro => 'my_macro', :width => 128 })
+    #
+    # The default button width is 64 pixels which is the width of a default cell.
+    #
+    # ===Option: height
+    # This option is used to set the height of the button in pixels.
+    #
+    #     worksheet.insert_button('C2', { :macro => 'my_macro', :height => 40 })
+    #
+    # The default button height is 20 pixels which is the height of a default cell.
+    #
+    # ===Option: x_scale
+    # This option is used to set the width of the button as a factor of the
+    # default width.
+    #
+    #     worksheet.insert_button('C2', { :macro => 'my_macro', :x_scale => 2.0 })
+    #
+    # ===Option: y_scale
+    # This option is used to set the height of the button as a factor of the
+    # default height.
+    #
+    #     worksheet.insert_button('C2', { :macro => 'my_macro', y_:scale => 2.0 } )
+    #
+    # ===Option: x_offset
+    # This option is used to change the x offset, in pixels, of a button
+    # within a cell:
+    #
+    #     worksheet.insert_button('C2', { :macro => 'my_macro', :x_offset => 2 })
+    #
+    # ===Option: y_offset
+    # This option is used to change the y offset, in pixels, of a comment
+    # within a cell.
+    #
+    # Note: Button is the only Excel form element that is available in
+    # WriteXLSX. Form elements represent a lot of work to implement and the
+    # underlying VML syntax isn't very much fun.
     #
     def insert_button(*args)
       @buttons_array << button_params(*(row_col_notation(args)))
@@ -3959,7 +4280,8 @@ def insert_button(*args)
     #
     #     worksheet.data_validation( 'A1',       {...} )
     #     worksheet.data_validation( 'A1:B5',    {...} )
-    # See also the note about "Cell notation" for more information.
+    #
+    # See also the note about {"Cell notation"}[#label-Cell+notation] for more information.
     #
     # The last parameter in data_validation() must be a hash ref containing
     # the parameters that describe the type and style of the data validation.
@@ -4729,8 +5051,6 @@ def set_v_pagebreaks(*args)
       @print_style.vbreaks += args
     end
 
-    #
-    # Make any comments in the worksheet visible.
     #
     # This method is used to make all cell comments visible when a worksheet
     # is opened.
@@ -4738,7 +5058,7 @@ def set_v_pagebreaks(*args)
     #     worksheet.show_comments
     #
     # Individual comments can be made visible using the visible parameter of
-    # the write_comment method (see above):
+    # the write_comment method:
     #
     #     worksheet.write_comment('C3', 'Hello', :visible => 1)
     #
@@ -4752,12 +5072,10 @@ def show_comments(visible = true)
       @comments_visible = visible
     end
 
-    #
-    # Set the default author of the cell comments.
     #
     # This method is used to set the default author of all cell comments.
     #
-    #     worksheet.set_comments_author('Ruby')
+    #     worksheet.comments_author = 'Ruby'
     #
     # Individual comment authors can be set using the author parameter
     # of the write_comment method.
@@ -4765,8 +5083,14 @@ def show_comments(visible = true)
     # The default comment author is an empty string, '',
     # if no author is specified.
     #
-    def set_comments_author(author = '')
-      @comments_author = author if author
+    def comments_author=(author)
+      @comments_author = author || ''
+    end
+
+    # This method is deprecated. use comments_author=().
+    def set_comments_author(author)
+      put_deprecate_message("#{self}.set_comments_author")
+      self.comments_author = author
     end
 
     def comments_count # :nodoc:
@@ -5428,44 +5752,6 @@ def position_object_emus(col_start, row_start, x1, y1, width, height, is_drawing
       [col_start, row_start, x1, y1, col_end, row_end, x2, y2, x_abs, y_abs]
     end
 
-    #
-    # Calculate the vertices that define the position of a shape object within
-    # the worksheet in EMUs.  Save the vertices with the object.
-    #
-    # The vertices are expressed as English Metric Units (EMUs). There are 12,700
-    # EMUs per point. Therefore, 12,700 * 3 /4 = 9,525 EMUs per pixel.
-    #
-    def position_shape_emus(shape)
-      col_start, row_start, x1, y1, col_end, row_end, x2, y2, x_abs, y_abs =
-        position_object_pixels(
-                               shape[:column_start],
-                               shape[:row_start],
-                               shape[:x_offset],
-                               shape[:y_offset],
-                               shape[:width] * shape[:scale_x],
-                               shape[:height] * shape[:scale_y],
-                               shape[:drawing]
-                               )
-
-      # Now that x2/y2 have been calculated with a potentially negative
-      # width/height we use the absolute value and convert to EMUs.
-      shape[:width_emu]  = (shape[:width]  * 9_525).abs.to_i
-      shape[:height_emu] = (shape[:height] * 9_525).abs.to_i
-
-      shape[:column_start] = col_start.to_i
-      shape[:row_start]    = row_start.to_i
-      shape[:column_end]   = col_end.to_i
-      shape[:row_end]      = row_end.to_i
-
-      # Convert the pixel values to EMUs. See above.
-      shape[:x1]    = (x1 * 9_525).to_i
-      shape[:y1]    = (y1 * 9_525).to_i
-      shape[:x2]    = (x2 * 9_525).to_i
-      shape[:y2]    = (y2 * 9_525).to_i
-      shape[:x_abs] = (x_abs * 9_525).to_i
-      shape[:y_abs] = (y_abs * 9_525).to_i
-    end
-
     #
     # Convert the width of a cell from user's units to pixels. Excel rounds the
     # column width to the nearest pixel. If the width hasn't been set by the user
@@ -5550,6 +5836,9 @@ def prepare_image(index, image_id, drawing_id, width, height, name, image_type)
     end
     public :prepare_image
 
+    #
+    # :call-seq:
+    #   insert_shape(row, col, shape [ , x, y, x_scale, y_scale ] )
     #
     # Insert a shape into the worksheet.
     #
@@ -5566,22 +5855,23 @@ def prepare_image(index, image_id, drawing_id, width, height, name, image_type)
     #   worksheet.insert_shape('E2', shape)
     #
     # See add_shape() for details on how to create the Shape object
-    # and Excel::Writer::XLSX::Shape for details on how to configure it.
+    # and Writexlsx::Shape for details on how to configure it.
     #
-    # The x, y, x_scale and y_scale parameters are optional.
+    # The +x+, +y+, +x_scale+ and +y_scale+ parameters are optional.
     #
-    # The parameters x and y can be used to specify an offset
-    # from the top left hand corner of the cell specified by row and col.
+    # The parameters +x+ and +y+ can be used to specify an offset
+    # from the top left hand corner of the cell specified by +row+ and +col+.
     # The offset values are in pixels.
     #
     #   worksheet1.insert_shape('E2', chart, 3, 3)
     #
-    # The parameters x_scale and y_scale can be used to scale the
+    # The parameters +x_scale+ and +y_scale+ can be used to scale the
     # inserted shape horizontally and vertically:
     #
     #   # Scale the width by 120% and the height by 150%
     #   worksheet.insert_shape('E2', shape, 0, 0, 1.2, 1.5)
-    # See also the shape*.pl programs in the examples directory of the distro.
+    #
+    # See also the shape*.rb programs in the examples directory of the distro.
     #
     def insert_shape(*args)
       # Check for a cell reference in A1 notation and substitute row and column.
@@ -5591,20 +5881,13 @@ def insert_shape(*args)
         raise "Insufficient arguments in insert_shape()"
       end
 
-      # Set the shape properties
-      shape[:row_start]    = row_start
-      shape[:column_start] = column_start
-      shape[:x_offset]     = x_offset || 0
-      shape[:y_offset]     = y_offset || 0
-
-      # Override shape scale if supplied as an argument. Otherwise, use the
-      # existing shape scale factors.
-      shape[:scale_x] = x_scale if x_scale
-      shape[:scale_y] = y_scale if y_scale
-
+      shape.set_position(
+                           row_start, column_start, x_offset, y_offset,
+                           x_scale, y_scale
+                           )
       # Assign a shape ID.
       while true
-        id = shape[:id] || 0
+        id = shape.id || 0
         used = @shape_hash[id]
 
         # Test if shape ID is already used. Otherwise assign a new one.
@@ -5612,38 +5895,29 @@ def insert_shape(*args)
           break
         else
           @last_shape_id += 1
-          shape[:id] = @last_shape_id
+          shape.id = @last_shape_id
         end
       end
 
-      shape[:element] = @shapes.size
-
       # Allow lookup of entry into shape array by shape ID.
-      @shape_hash[shape[:id]] = shape[:element]
+      @shape_hash[shape.id] = shape.element = @shapes.size
 
-      # Create link to Worksheet color palette.
-      shape[:palette] = @workbook.palette
-
-      if ptrue?(shape[:stencil])
+      if ptrue?(shape.stencil)
         # Insert a copy of the shape, not a reference so that the shape is
         # used as a stencil. Previously stamped copies don't get modified
         # if the stencil is modified.
         insert = shape.dup
-
-        # For connectors change x/y coords based on location of connected shapes.
-        auto_locate_connectors(insert)
-
-        @shapes << insert
-        insert
       else
-        # For connectors change x/y coords based on location of connected shapes.
-        auto_locate_connectors(shape)
-
-        # Insert a link to the shape on the list of shapes. Connection to
-        # the parent shape is maintained.
-        @shapes << shape
-        return shape
+        insert = shape
       end
+
+      # For connectors change x/y coords based on location of connected shapes.
+      insert.auto_locate_connectors(@shapes, @shape_hash)
+
+      # Insert a link to the shape on the list of shapes. Connection to
+      # the parent shape is maintained.
+      @shapes << insert
+      insert
     end
     public :insert_shape
 
@@ -5652,7 +5926,6 @@ def insert_shape(*args)
     #
     def prepare_shape(index, drawing_id)
       shape = @shapes[index]
-      drawing_type = 3
 
       # Create a Drawing object to use with worksheet unless one already exists.
       unless drawing?
@@ -5662,121 +5935,14 @@ def prepare_shape(index, drawing_id)
       end
 
       # Validate the he shape against various rules.
-      validate_shape(shape, index)
-      position_shape_emus(shape)
-
-      dimensions = [
-                    shape[:column_start], shape[:row_start],
-                    shape[:x1],           shape[:y1],
-                    shape[:column_end],   shape[:row_end],
-                    shape[:x2],           shape[:y2],
-                    shape[:x_abs],        shape[:y_abs],
-                    shape[:width_emu],    shape[:height_emu]
-                   ]
+      shape.validate(index)
+      shape.calc_position_emus(self)
 
-      drawing.add_drawing_object(drawing_type, dimensions, shape[:name], shape)
+      drawing_type = 3
+      drawing.add_drawing_object(drawing_type, shape.dimensions, shape.name, shape)
     end
     public :prepare_shape
 
-    #
-    # Re-size connector shapes if they are connected to other shapes.
-    #
-    def auto_locate_connectors(shape)
-      # Valid connector shapes.
-      connector_shapes = {
-        :straightConnector => 1,
-        :Connector         => 1,
-        :bentConnector     => 1,
-        :curvedConnector   => 1,
-        :line              => 1
-      }
-
-      shape_base = shape[:type].chop.to_sym # Remove the number of segments from end of type.
-      shape[:connect] = connector_shapes[shape_base] ? 1 : 0
-      return if shape[:connect] == 0
-
-      # Both ends have to be connected to size it.
-      return if shape[:start] == 0 && shape[:end] == 0
-
-      # Both ends need to provide info about where to connect.
-      return if shape[:start_side] == 0 && shape[:end_side] == 0
-
-      sid = shape[:start]
-      eid = shape[:end]
-
-      slink_id = @shape_hash[sid] || 0
-      sls      = @shapes.fetch(slink_id, Hash.new(0))
-      elink_id = @shape_hash[eid] || 0
-      els      = @shapes.fetch(elink_id, Hash.new(0))
-
-      # Assume shape connections are to the middle of an object, and
-      # not a corner (for now).
-      connect_type = shape[:start_side] + shape[:end_side]
-      smidx        = sls[:x_offset] + sls[:width] / 2
-      emidx        = els[:x_offset] + els[:width] / 2
-      smidy        = sls[:y_offset] + sls[:height] / 2
-      emidy        = els[:y_offset] + els[:height] / 2
-      netx         = (smidx - emidx).abs
-      nety         = (smidy - emidy).abs
-
-      if connect_type == 'bt'
-        sy = sls[:y_offset] + sls[:height]
-        ey = els[:y_offset]
-
-        shape[:width] = (emidx - smidx).to_i.abs
-        shape[:x_offset] = [smidx, emidx].min.to_i
-        shape[:height] =
-          (els[:y_offset] - (sls[:y_offset] + sls[:height])).to_i.abs
-        shape[:y_offset] =
-          [sls[:y_offset] + sls[:height], els[:y_offset]].min.to_i
-        shape[:flip_h] = smidx < emidx ? 1 : 0
-        shape[:rotation] = 90
-
-        if sy > ey
-          shape[:flip_v] = 1
-
-          # Create 3 adjustments for an end shape vertically above a
-          # start shape. Adjustments count from the upper left object.
-          if shape[:adjustments].empty?
-            shape[:adjustments] = [-10, 50, 110]
-          end
-          shape[:type] = 'bentConnector5'
-        end
-      elsif connect_type == 'rl'
-        shape[:width] =
-          (els[:x_offset] - (sls[:x_offset] + sls[:width])).to_i.abs
-        shape[:height] = (emidy - smidy).to_i.abs
-        shape[:x_offset] =
-          [sls[:x_offset] + sls[:width], els[:x_offset]].min
-        shape[:y_offset] = [smidy, emidy].min
-
-        shape[:flip_h] = 1 if smidx < emidx && smidy > emidy
-        shape[:flip_h] = 1 if smidx > emidx && smidy < emidy
-
-        if smidx > emidx
-          # Create 3 adjustments for an end shape to the left of a
-          # start shape.
-          if shape[:adjustments].empty?
-            shape[:adjustments] = [-10, 50, 110]
-          end
-          shape[:type] = 'bentConnector5'
-        end
-      end
-    end
-
-    #
-    # Check shape attributes to ensure they are valid.
-    #
-    def validate_shape(shape, index)
-      unless %w[l ctr r just].include?(shape[:align])
-        raise "Shape #{index} (#{shape[:type]}) alignment (#{shape[:align]}) not in ['l', 'ctr', 'r', 'just']\n"
-      end
-
-      unless %w[t ctr b].include?(shape[:valign])
-        raise "Shape #{index} (#{shape[:type]}) vertical alignment (#{shape[:valign]}) not in ['t', 'ctr', 'v']\n"
-      end
-    end
-
     #
     # This method handles the parameters passed to insert_button as well as
     # calculating the comment object position and vertices.
@@ -6969,385 +7135,6 @@ def write_table_part(id)
       @writer.empty_tag('tablePart', attributes)
     end
 
-    def spark_styles  # :nodoc:
-      [
-       {   # 0
-         :series   => { :_theme => "4", :_tint => "-0.499984740745262" },
-         :negative => { :_theme => "5" },
-         :markers  => { :_theme => "4", :_tint => "-0.499984740745262" },
-         :first    => { :_theme => "4", :_tint => "0.39997558519241921" },
-         :last     => { :_theme => "4", :_tint => "0.39997558519241921" },
-         :high     => { :_theme => "4" },
-         :low      => { :_theme => "4" }
-       },
-       {   # 1
-         :series   => { :_theme => "4", :_tint => "-0.499984740745262" },
-         :negative => { :_theme => "5" },
-         :markers  => { :_theme => "4", :_tint => "-0.499984740745262" },
-         :first    => { :_theme => "4", :_tint => "0.39997558519241921" },
-         :last     => { :_theme => "4", :_tint => "0.39997558519241921" },
-         :high     => { :_theme => "4" },
-         :low      => { :_theme => "4" }
-       },
-       {   # 2
-         :series   => { :_theme => "5", :_tint => "-0.499984740745262" },
-         :negative => { :_theme => "6" },
-         :markers  => { :_theme => "5", :_tint => "-0.499984740745262" },
-         :first    => { :_theme => "5", :_tint => "0.39997558519241921" },
-         :last     => { :_theme => "5", :_tint => "0.39997558519241921" },
-         :high     => { :_theme => "5" },
-         :low      => { :_theme => "5" }
-       },
-       {   # 3
-         :series   => { :_theme => "6", :_tint => "-0.499984740745262" },
-         :negative => { :_theme => "7" },
-         :markers  => { :_theme => "6", :_tint => "-0.499984740745262" },
-         :first    => { :_theme => "6", :_tint => "0.39997558519241921" },
-         :last     => { :_theme => "6", :_tint => "0.39997558519241921" },
-         :high     => { :_theme => "6" },
-         :low      => { :_theme => "6" }
-       },
-       {   # 4
-         :series   => { :_theme => "7", :_tint => "-0.499984740745262" },
-         :negative => { :_theme => "8" },
-         :markers  => { :_theme => "7", :_tint => "-0.499984740745262" },
-         :first    => { :_theme => "7", :_tint => "0.39997558519241921" },
-         :last     => { :_theme => "7", :_tint => "0.39997558519241921" },
-         :high     => { :_theme => "7" },
-         :low      => { :_theme => "7" }
-       },
-       {   # 5
-         :series   => { :_theme => "8", :_tint => "-0.499984740745262" },
-         :negative => { :_theme => "9" },
-         :markers  => { :_theme => "8", :_tint => "-0.499984740745262" },
-         :first    => { :_theme => "8", :_tint => "0.39997558519241921" },
-         :last     => { :_theme => "8", :_tint => "0.39997558519241921" },
-         :high     => { :_theme => "8" },
-         :low      => { :_theme => "8" }
-       },
-       {   # 6
-         :series   => { :_theme => "9", :_tint => "-0.499984740745262" },
-         :negative => { :_theme => "4" },
-         :markers  => { :_theme => "9", :_tint => "-0.499984740745262" },
-         :first    => { :_theme => "9", :_tint => "0.39997558519241921" },
-         :last     => { :_theme => "9", :_tint => "0.39997558519241921" },
-         :high     => { :_theme => "9" },
-         :low      => { :_theme => "9" }
-       },
-       {   # 7
-         :series   => { :_theme => "4", :_tint => "-0.249977111117893" },
-         :negative => { :_theme => "5" },
-         :markers  => { :_theme => "5", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "5", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "5", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "5", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "5", :_tint => "-0.249977111117893" }
-       },
-       {   # 8
-         :series   => { :_theme => "5", :_tint => "-0.249977111117893" },
-         :negative => { :_theme => "6" },
-         :markers  => { :_theme => "6", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "6", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "6", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "6", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "6", :_tint => "-0.249977111117893" }
-       },
-       {   # 9
-         :series   => { :_theme => "6", :_tint => "-0.249977111117893" },
-         :negative => { :_theme => "7" },
-         :markers  => { :_theme => "7", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "7", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "7", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "7", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "7", :_tint => "-0.249977111117893" }
-       },
-       {   # 10
-         :series   => { :_theme => "7", :_tint => "-0.249977111117893" },
-         :negative => { :_theme => "8" },
-         :markers  => { :_theme => "8", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "8", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "8", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "8", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "8", :_tint => "-0.249977111117893" }
-       },
-       {   # 11
-         :series   => { :_theme => "8", :_tint => "-0.249977111117893" },
-         :negative => { :_theme => "9" },
-         :markers  => { :_theme => "9", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "9", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "9", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "9", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "9", :_tint => "-0.249977111117893" }
-       },
-       {   # 12
-         :series   => { :_theme => "9", :_tint => "-0.249977111117893" },
-         :negative => { :_theme => "4" },
-         :markers  => { :_theme => "4", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "4", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "4", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "4", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "4", :_tint => "-0.249977111117893" }
-       },
-       {   # 13
-         :series   => { :_theme => "4" },
-         :negative => { :_theme => "5" },
-         :markers  => { :_theme => "4", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "4", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "4", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "4", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "4", :_tint => "-0.249977111117893" }
-       },
-       {   # 14
-         :series   => { :_theme => "5" },
-         :negative => { :_theme => "6" },
-         :markers  => { :_theme => "5", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "5", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "5", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "5", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "5", :_tint => "-0.249977111117893" }
-       },
-       {   # 15
-         :series   => { :_theme => "6" },
-         :negative => { :_theme => "7" },
-         :markers  => { :_theme => "6", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "6", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "6", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "6", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "6", :_tint => "-0.249977111117893" }
-       },
-       {   # 16
-         :series   => { :_theme => "7" },
-         :negative => { :_theme => "8" },
-         :markers  => { :_theme => "7", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "7", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "7", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "7", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "7", :_tint => "-0.249977111117893" }
-       },
-       {   # 17
-         :series   => { :_theme => "8" },
-         :negative => { :_theme => "9" },
-         :markers  => { :_theme => "8", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "8", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "8", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "8", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "8", :_tint => "-0.249977111117893" }
-       },
-       {   # 18
-         :series   => { :_theme => "9" },
-         :negative => { :_theme => "4" },
-         :markers  => { :_theme => "9", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "9", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "9", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "9", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "9", :_tint => "-0.249977111117893" }
-       },
-       {   # 19
-         :series   => { :_theme => "4", :_tint => "0.39997558519241921" },
-         :negative => { :_theme => "0", :_tint => "-0.499984740745262" },
-         :markers  => { :_theme => "4", :_tint => "0.79998168889431442" },
-         :first    => { :_theme => "4", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "4", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "4", :_tint => "-0.499984740745262" },
-         :low      => { :_theme => "4", :_tint => "-0.499984740745262" }
-       },
-       {   # 20
-         :series   => { :_theme => "5", :_tint => "0.39997558519241921" },
-         :negative => { :_theme => "0", :_tint => "-0.499984740745262" },
-         :markers  => { :_theme => "5", :_tint => "0.79998168889431442" },
-         :first    => { :_theme => "5", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "5", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "5", :_tint => "-0.499984740745262" },
-         :low      => { :_theme => "5", :_tint => "-0.499984740745262" }
-       },
-       {   # 21
-         :series   => { :_theme => "6", :_tint => "0.39997558519241921" },
-         :negative => { :_theme => "0", :_tint => "-0.499984740745262" },
-         :markers  => { :_theme => "6", :_tint => "0.79998168889431442" },
-         :first    => { :_theme => "6", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "6", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "6", :_tint => "-0.499984740745262" },
-         :low      => { :_theme => "6", :_tint => "-0.499984740745262" }
-       },
-       {   # 22
-         :series   => { :_theme => "7", :_tint => "0.39997558519241921" },
-         :negative => { :_theme => "0", :_tint => "-0.499984740745262" },
-         :markers  => { :_theme => "7", :_tint => "0.79998168889431442" },
-         :first    => { :_theme => "7", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "7", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "7", :_tint => "-0.499984740745262" },
-         :low      => { :_theme => "7", :_tint => "-0.499984740745262" }
-       },
-       {   # 23
-         :series   => { :_theme => "8", :_tint => "0.39997558519241921" },
-         :negative => { :_theme => "0", :_tint => "-0.499984740745262" },
-         :markers  => { :_theme => "8", :_tint => "0.79998168889431442" },
-         :first    => { :_theme => "8", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "8", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "8", :_tint => "-0.499984740745262" },
-         :low      => { :_theme => "8", :_tint => "-0.499984740745262" }
-       },
-       {   # 24
-         :series   => { :_theme => "9", :_tint => "0.39997558519241921" },
-         :negative => { :_theme => "0", :_tint => "-0.499984740745262" },
-         :markers  => { :_theme => "9", :_tint => "0.79998168889431442" },
-         :first    => { :_theme => "9", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "9", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "9", :_tint => "-0.499984740745262" },
-         :low      => { :_theme => "9", :_tint => "-0.499984740745262" }
-       },
-       {   # 25
-         :series   => { :_theme => "1", :_tint => "0.499984740745262" },
-         :negative => { :_theme => "1", :_tint => "0.249977111117893" },
-         :markers  => { :_theme => "1", :_tint => "0.249977111117893" },
-         :first    => { :_theme => "1", :_tint => "0.249977111117893" },
-         :last     => { :_theme => "1", :_tint => "0.249977111117893" },
-         :high     => { :_theme => "1", :_tint => "0.249977111117893" },
-         :low      => { :_theme => "1", :_tint => "0.249977111117893" }
-       },
-       {   # 26
-         :series   => { :_theme => "1", :_tint => "0.34998626667073579" },
-         :negative => { :_theme => "0", :_tint => "-0.249977111117893" },
-         :markers  => { :_theme => "0", :_tint => "-0.249977111117893" },
-         :first    => { :_theme => "0", :_tint => "-0.249977111117893" },
-         :last     => { :_theme => "0", :_tint => "-0.249977111117893" },
-         :high     => { :_theme => "0", :_tint => "-0.249977111117893" },
-         :low      => { :_theme => "0", :_tint => "-0.249977111117893" }
-       },
-       {   # 27
-         :series   => { :_rgb => "FF323232" },
-         :negative => { :_rgb => "FFD00000" },
-         :markers  => { :_rgb => "FFD00000" },
-         :first    => { :_rgb => "FFD00000" },
-         :last     => { :_rgb => "FFD00000" },
-         :high     => { :_rgb => "FFD00000" },
-         :low      => { :_rgb => "FFD00000" }
-       },
-       {   # 28
-         :series   => { :_rgb => "FF000000" },
-         :negative => { :_rgb => "FF0070C0" },
-         :markers  => { :_rgb => "FF0070C0" },
-         :first    => { :_rgb => "FF0070C0" },
-         :last     => { :_rgb => "FF0070C0" },
-         :high     => { :_rgb => "FF0070C0" },
-         :low      => { :_rgb => "FF0070C0" }
-       },
-       {   # 29
-         :series   => { :_rgb => "FF376092" },
-         :negative => { :_rgb => "FFD00000" },
-         :markers  => { :_rgb => "FFD00000" },
-         :first    => { :_rgb => "FFD00000" },
-         :last     => { :_rgb => "FFD00000" },
-         :high     => { :_rgb => "FFD00000" },
-         :low      => { :_rgb => "FFD00000" }
-       },
-       {   # 30
-         :series   => { :_rgb => "FF0070C0" },
-         :negative => { :_rgb => "FF000000" },
-         :markers  => { :_rgb => "FF000000" },
-         :first    => { :_rgb => "FF000000" },
-         :last     => { :_rgb => "FF000000" },
-         :high     => { :_rgb => "FF000000" },
-         :low      => { :_rgb => "FF000000" }
-       },
-       {   # 31
-         :series   => { :_rgb => "FF5F5F5F" },
-         :negative => { :_rgb => "FFFFB620" },
-         :markers  => { :_rgb => "FFD70077" },
-         :first    => { :_rgb => "FF5687C2" },
-         :last     => { :_rgb => "FF359CEB" },
-         :high     => { :_rgb => "FF56BE79" },
-         :low      => { :_rgb => "FFFF5055" }
-       },
-       {   # 32
-         :series   => { :_rgb => "FF5687C2" },
-         :negative => { :_rgb => "FFFFB620" },
-         :markers  => { :_rgb => "FFD70077" },
-         :first    => { :_rgb => "FF777777" },
-         :last     => { :_rgb => "FF359CEB" },
-         :high     => { :_rgb => "FF56BE79" },
-         :low      => { :_rgb => "FFFF5055" }
-       },
-       {   # 33
-         :series   => { :_rgb => "FFC6EFCE" },
-         :negative => { :_rgb => "FFFFC7CE" },
-         :markers  => { :_rgb => "FF8CADD6" },
-         :first    => { :_rgb => "FFFFDC47" },
-         :last     => { :_rgb => "FFFFEB9C" },
-         :high     => { :_rgb => "FF60D276" },
-         :low      => { :_rgb => "FFFF5367" }
-       },
-       {   # 34
-         :series   => { :_rgb => "FF00B050" },
-         :negative => { :_rgb => "FFFF0000" },
-         :markers  => { :_rgb => "FF0070C0" },
-         :first    => { :_rgb => "FFFFC000" },
-         :last     => { :_rgb => "FFFFC000" },
-         :high     => { :_rgb => "FF00B050" },
-         :low      => { :_rgb => "FFFF0000" }
-       },
-       {   # 35
-         :series   => { :_theme => "3" },
-         :negative => { :_theme => "9" },
-         :markers  => { :_theme => "8" },
-         :first    => { :_theme => "4" },
-         :last     => { :_theme => "5" },
-         :high     => { :_theme => "6" },
-         :low      => { :_theme => "7" }
-       },
-       {   # 36
-         :series   => { :_theme => "1" },
-         :negative => { :_theme => "9" },
-         :markers  => { :_theme => "8" },
-         :first    => { :_theme => "4" },
-         :last     => { :_theme => "5" },
-         :high     => { :_theme => "6" },
-         :low      => { :_theme => "7" }
-       }
-      ]
-    end
-
-    def valid_sparkline_parameter  # :nodoc:
-      {
-        :location        => 1,
-        :range           => 1,
-        :type            => 1,
-        :high_point      => 1,
-        :low_point       => 1,
-        :negative_points => 1,
-        :first_point     => 1,
-        :last_point      => 1,
-        :markers         => 1,
-        :style           => 1,
-        :series_color    => 1,
-        :negative_color  => 1,
-        :markers_color   => 1,
-        :first_color     => 1,
-        :last_color      => 1,
-        :high_color      => 1,
-        :low_color       => 1,
-        :max             => 1,
-        :min             => 1,
-        :axis            => 1,
-        :reverse         => 1,
-        :empty_cells     => 1,
-        :show_hidden     => 1,
-        :date_axis       => 1,
-        :weight          => 1
-      }
-    end
-
-    #
-    #
-    #
-    def set_spark_color(sparkline, param, user_color)  # :nodoc:
-      spark_color = "_#{user_color}".to_sym
-
-      return unless ptrue?(param[user_color])
-
-      sparkline[spark_color] =
-        { :_rgb => get_palette_color(param[user_color]) }
-    end
     #
     # Write the <extLst> element and sparkline subelements.
     #
@@ -7372,31 +7159,31 @@ def write_ext_sparklines  # :nodoc:
         write_sparkline_group(sparkline)
 
         # Write the x14:colorSeries element.
-        write_color_series(sparkline[:_series_color])
+        write_color_series(sparkline.series_color)
 
         # Write the x14:colorNegative element.
-        write_color_negative(sparkline[:_negative_color])
+        write_color_negative(sparkline.negative_color)
 
         # Write the x14:colorAxis element.
         write_color_axis
 
         # Write the x14:colorMarkers element.
-        write_color_markers(sparkline[:_markers_color])
+        write_color_markers(sparkline.markers_color)
 
         # Write the x14:colorFirst element.
-        write_color_first(sparkline[:_first_color])
+        write_color_first(sparkline.first_color)
 
         # Write the x14:colorLast element.
-        write_color_last(sparkline[:_last_color] )
+        write_color_last(sparkline.last_color)
 
         # Write the x14:colorHigh element.
-        write_color_high(sparkline[:_high_color])
+        write_color_high(sparkline.high_color)
 
         # Write the x14:colorLow element.
-        write_color_low(sparkline[:_low_color])
+        write_color_low(sparkline.low_color)
 
-        if sparkline[:_date_axis]
-          @writer.data_element('xm:f', sparkline[:_date_axis])
+        if sparkline.date_axis
+          @writer.data_element('xm:f', sparkline.date_axis)
         end
 
         write_sparklines(sparkline)
@@ -7416,9 +7203,9 @@ def write_sparklines(sparkline)  # :nodoc:
       # Write the sparkline elements.
       @writer.tag_elements('x14:sparklines') do
 
-        (0 .. sparkline[:_count]-1).each do |i|
-          range    = sparkline[:_ranges][i]
-          location = sparkline[:_locations][i]
+        (0 .. sparkline.count-1).each do |i|
+          range    = sparkline.ranges[i]
+          location = sparkline.locations[i]
 
           @writer.tag_elements('x14:sparkline') do
             @writer.data_element('xm:f',     range)
@@ -7480,46 +7267,7 @@ def write_sparkline_groups  # :nodoc:
     #     rightToLeft="1">
     #
     def write_sparkline_group(sparkline)  # :nodoc:
-      @writer.start_tag(
-                        'x14:sparklineGroup',
-                        attributes_from_sparkline(sparkline)
-                        )
-    end
-
-    def attributes_from_sparkline(opts)  # :nodoc:
-      opts[:_cust_max] = cust_max_min(opts[:_max]) if opts[:_max]
-      opts[:_cust_min] = cust_max_min(opts[:_min]) if opts[:_min]
-
-      opts[:_cust_max] = cust_max_min(opts[:_max]) if opts[:_max]
-      opts[:_cust_min] = cust_max_min(opts[:_min]) if opts[:_min]
-
-      a = []
-      a << 'manualMax' << opts[:_max] if opts[:_max] && opts[:_max] != 'group'
-      a << 'manualMin' << opts[:_min] if opts[:_min] && opts[:_min] != 'group'
-
-      # Ignore the default type attribute (line).
-      a << 'type'          << opts[:_type]   if opts[:_type] != 'line'
-
-      a << 'lineWeight'    << opts[:_weight] if opts[:_weight]
-      a << 'dateAxis'      << 1              if opts[:_date_axis]
-      a << 'displayEmptyCellsAs' << opts[:_empty]    if ptrue?(opts[:_empty])
-
-      a << 'markers'       << 1                if opts[:_markers]
-      a << 'high'          << 1                if opts[:_high]
-      a << 'low'           << 1                if opts[:_low]
-      a << 'first'         << 1                if opts[:_first]
-      a << 'last'          << 1                if opts[:_last]
-      a << 'negative'      << 1                if opts[:_negative]
-      a << 'displayXAxis'  << 1                if opts[:_axis]
-      a << 'displayHidden' << 1                if opts[:_hidden]
-      a << 'minAxisType'   << opts[:_cust_min] if opts[:_cust_min]
-      a << 'maxAxisType'   << opts[:_cust_max] if opts[:_cust_max]
-      a << 'rightToLeft'   << 1                if opts[:_reverse]
-      a
-    end
-
-    def cust_max_min(max_min)  # :nodoc:
-      max_min == 'group' ? 'group' : 'custom'
+      @writer.start_tag('x14:sparklineGroup', sparkline.group_attributes)
     end
 
     #