hplot -- two-dimensional "hyper" plots

------------------------------------------------------------

files:

  hplot.m -- Octave function (m-file)
  hplot_data_structure.txt -- this file
  hplot_example.html -- complete and functioning html/js file
                        which is used as a template by hplot.m
  hplot_example_overview.txt -- memorandum for the author
  hplot_test7.m -- m-file with tests of hplot.m
  
------------------------------------------------------------
                        
The features of hplot are mainly:

-- drawing of one or more two-dimensional plots which are
   presented and stored in different ways: on screen, in
   graphic files and/or in a html/js file.
-- many ordinary "series" plots on x and y axes are possible:
   -- a plot consists of one or more series.
   -- each series is drawn with a specified line type, marker
      and colour.
   -- the line of a series can be interrupted, e.g. to 
      represent missing data.
-- one special plot type is available: a psychrometric chart,
   similar to charts according to Mollier or ASHRAE.  
-- all content and presentation information for the plot or 
   the series of plots are contained in a single hierarchal 
   structure.
-- the output html/js file contains all the information as
   wel as the javascript codes, and it results in an 
   interactive presentation of the plots in a web browser:
   -- the user can e.g. select an interval on the x axis, or 
      zoom out.
   -- values of the closest points near the mouse pointer
      are displayed in the legend.
   -- the display of series in a plot can be switched on and
      off. 
   -- plots can be virtually connected, so that an x axis
      selection on one of the connected plots results in the
      same selection on the other connected plots.
   -- based on the template hplot_example.html, one can 
      write html pages with interactive plots.
-- the graphic file output is consistent with the on-screen
   display:
   -- each on-screen plot results in a graphic file in a 
      chosen format, or in multiple files in different 
      formats, if multiple formats are chosen.
   -- the series of plots are combined into a single pdf
      file via latex.
   -- a single figure may result in multiple (sub)plots to
      prevent that too many series in a single plot would 
      make the plot inreadable.
   -- a single figure may result in multiple (sub)plots by 
      different predefined selections.

------------------------------------------------------------

A plot is also called "figure", and contains one or more 
"tables". 

Each table contains (or refers to) a column of x data and one 
or more columns of corresponding y data. A series, which is 
drawn as a line and/or markers in the figure, consists of
a column of x data and a column of corresponding y data. 
A table thus may contain one or more series which all have
the same x data. 

The allocation of series into different tables depends on 
what is thought to be practical. E.g. a table in a figure 
may be dedicated to auxiliary lines, or a table contains 
data which must be repeated in each subplot, when the 
figure is printed in multiple (sub)plots to prevent 
inreadable plots.

For html/js output, tables may also contain (or refer to)
so-called common data. These are only relevant to connected
figures. Figure groups consist of connected figures; 
multiple figure groups may be defined. There are two types
of figures in a figure group:
-- figures with x data (which is common data too) and y data.
-- figures with x data, y data and (distinct) common data.

User selection of an interval on the x axis of in a figure
of the first type result in the same selection on the common
data of all figures in the figure group. Thus, the x axis 
limits change in the same way for all figures of the first
type; and the displayed points are selected (and not the x
axis limits are changed) in the figures of the second type.

User selection of an interval on the x axis of in a figure
of the second type only affects the x axis limits of the
same figure, and does not affect any other figure in the
figure group.

The x data, y data and common data are defined per table.
They, within the table, must correspond to each other. They 
must have the same number of rows. The common data of one
table does not have to correspond to those of other tables
in the figure group, because user selection on the x axis
affects only the upper and lower limits, by which the common
data are eventually selected.

A figure in a figure group may also have tables without
common data, which contain series e.g. for auxiliary lines.

------------------------------------------------------------

The values of x data, y data and common data are usually 
reals (and sometimes integers). There are special values
with special meanings:

-- line break    indicated by Inf in Octave, null         in Javascript and null  in JSON.
-- ignored point indicated by NaN in Octave, NaN or false in Javascript and false in JSON.

Note that the values NaN, NA, Inf and -Inf cause an 
interruption of the line and markers drawn by the standard 
Octave function plot(). Function hplot() will treat NaN 
values differently from Inf values.

Note that in JSON code, the values NaN and Inf are not 
allowed, but the values null, false and true are valid.

------------------------------------------------------------

All data is packed into one variable, which we call here data. 
It is an "object" in javascript, and a "struct" in Octave. 
In general, it is organised like this in js code:

  data[field] = ...;
  data["fig"][ifig][field] = ...;
  data["fig"][ifig]["tab"][itab][field] = ...;
  
were field is a string for the field name, and 
ifig and itab are integers for the array indices
to the figure count and its table count.

In Octave code, the general organisation looks like this: 

  data.(field) = ...;
  data.fig{ifig}.(field) = ...;
  data.fig{ifig}.tab{itab}.(field) = ...;
  
There is also an internal variable defaults, which is not
available to the user:

  defaults[field] = ...;

When a figure or one of its tabs is processed, a field may
be missing at the deepest level. In some cases, the field
with the same name is searched for gradually from the deepest
to the shallowest level. This procedure we indicate like this:

  data["fig"][ifig]["tab"][itab][field] ifnot:
  data["fig"][ifig][field] ifnot:
  data[field] ifnot:
  defaults[field]
  
And sometimes we use this short notation:

  data.....[field]

------------------------------------------------------------

The following types of output are generated:

-- screen prints.
-- graphic files.
-- latex file.
-- html/js file.

The latex file contains references to the graphic files. By
running pdflatex, we can create a single pdf with all plots. 

Not all fields in the data structure are relevant to all types of 
output. A graphic file is generated on basis of the screen print;
therefore, when we say that a field is relevant to screen prints,
it is also relevant to graphic file output. 

------------------------------------------------------------

The data structure, in the form of an Octave struct, is fed
as the single argument to function hplot(). Depending of 
the values of some options, the above-mentioned types of 
output are generated within Octave.

Note that a JSON representation of the data structure is not
easily translated into an Octave struct, because Octave 
distinguishes matrices from cell arrays, while Javascript 
and JSON have basically only one type of arrays. (Perhaps
in a future version, we will make hplot() insensitive to
the distinction between matrices and cell arrays at input.) 

------------------------------------------------------------

  data["fig"][ifig]["name"]

    -- only relevant to the html/js output
    -- string for identification
    -- if not given: value = fignameprefix + String(ifig) + ":svg";
       where fignameprefix = data["fig"][ifig]["fignameprefix"] ifnot:
                             data["fignameprefix"] ifnot:
                             defaults["fignameprefix"]
    -- if given: the figure is put within <div id="[name]"></div> when such html tag is found in the html file
    
  data["fig"][ifig]["id"] = value;

    -- only relevant to the html/js output
    -- FIXME: not yet implemented (instead of data["fig"][ifig]["name"] ?)

  data["fig"][ifig]["special"] ifnot:
  data["special"] ifnot:
  defaults["special"] = ""

    -- not (yet) for user input

  data["fig"][ifig]["xaxisprojection"] ifnot:
  data["xaxisprojection"] ifnot:
  defaults["xaxisprojection"] = "lin"

  data["fig"][ifig]["yaxisprojection"] ifnot:
  data["yaxisprojection"] ifnot:
  defaults["yaxisprojection"] = "lin"

   -- string to indicate x and y axis projection methods
   -- provisionnally one possible value: "lin"
   -- not yet fully implemented

  data["fig"][ifig]["group"] ifnot:
  data["group"] ifnot:
  defaults["group"] = ""

    -- only relevant to the html/js output
    -- string
    -- if empty string, the figure constitutes its own group

  data["fig"][ifig]["xlabel"] ifnot:
  data["xlabel"] ifnot:
  defaults["xlabel"] = "x"

  data["fig"][ifig]["ylabel"] ifnot:
  data["ylabel"] ifnot:
  defaults["ylabel"] = "y"

  data["fig"][ifig]["xunit"] ifnot:
  data["xunit"] ifnot:
  defaults["xunit"] = ""

  data["fig"][ifig]["yunit"] ifnot:
  data["yunit"] ifnot:
  defaults["yunit"] = ""

    -- string for the x and y axis labels and their units
    -- use a subset of html code (for bold, italic, super/subscript, some symbols)

  data["fig"][ifig]["tab"][itab]["xdatakey"] ifnot:
  data["fig"][ifig]["xdatakey"] ifnot:
  data["xdatakey"] ifnot:
  defaults["xdatakey"] = "x"

  data["fig"][ifig]["tab"][itab]["xdatakey"] ifnot:
  data["fig"][ifig]["xdatakey"] ifnot:
  data["xdatakey"] ifnot:
  defaults["xdatakey"] = "y"
  
    -- string for the field name where the x and y data are stored
    -- if the string is represented by variable field, the x and y
       data are searched for in:
         data["fig"][ifig]["tab"][itab][field] ifnot:
         data["fig"][ifig][field] ifnot:
         data[field]

  data["fig"][ifig]["tab"][itab]["commondatakey"] ifnot:
  data["fig"][ifig]["commondatakey"] ifnot:
  data["commondatakey"] ifnot:
  defaults["commondatakey"] = ""
  
    -- string for the field name where the common data are stored
    -- if "=xdata", the values of data.....["xdatakey"] and data.....["xdatacolumn"] 
       are taken instead
    -- if empty, no common data is intended
       
  data["fig"][ifig]["tab"][itab]["datetimeonxaxis"] ifnot:
  data["fig"][ifig]["datetimeonxaxis"] ifnot:
  data["datetimeonxaxis"]
  
  data["fig"][ifig]["tab"][itab]["datetimecommon"] ifnot:
  data["fig"][ifig]["datetimecommon"] ifnot:
  data["datetimecommon"]

    -- value 0 or 1
    -- value 0 by default (defaults["datetimeonxaxis"] and defaults["datetimecommon"] do not exist)
    -- must be set to 1, if x axis or common data are in ms since 1970-01-01 00:00:00.0000 (unix epoch)
    -- may be set to 1, if x axis or common data are given by separate columns for year, month etc.
    -- in the latter case, it is needed to input: 
         data.....["xdatacolumn"] = { ye: icolye, mo: icolmo, ... }
       or
         data.....["commondatacolumn"] = { ye: icolye, mo: icolmo, ... }

  data["fig"][ifig]["tab"][itab][field] ifnot:
  data["fig"][ifig][field] ifnot:
  data[field]

    -- if field == "xdatacolumn", "ydatacolumn" and "commondatacolumn":
       -- note that a table consists of just one column of x data 
          and one or more columns of corresponding y data
       -- one integer for the column index to the x and common data, respectively
       -- array of integers for the column indices to the y data
       -- value [ 0 ] by default
       -- only needed if the x, y and/or common data are in a shared data array
       -- defaults[field] do not exist
    -- for field == "xdatacolumn" and "commondatacolumn", there is an alternative:
       -- record on the storage of date-times by separate columns for year, month etc.:
          { ye: icol, mo: icol, da: icol, ho: icol, mi: icol, se: icol, ms: icol };
       -- needed if x axis data or common data are given by separate columns for year, month etc.
       -- if icol is an integer number, the value of the date-time element will found in column icol
       -- if icol is a string, the number obtained by parsing the string will be filled in as fixed value for the respective date-time element
    -- field "commondatacolumn" is only relevant to the html/js output

  data["fig"][ifig]["tab"][itab]["xyprofile"] ifnot:
  data["fig"][ifig]["xyproflie"] ifnot:
  data["xyprofile"]

    -- value 0 or 1
    -- value 0 by default (defaults["xyprofile"] does not exist)
    -- if 0, a line is drawn "longitudally", for given column vectors: 
         from (x(k),y(k)) to (x(k+1),y(k+1)) etc. along row index k
    -- if 1, a line is drawn "transversally", per row r in given matrices: 
         from (x(r,j(1)),y(r,k(1))) to (x(r,j(2)),y(r,k(2))) etc. to (x(r,j(n)),y(r,k(n))), 
         along series of column indices j and k
    -- if 1, data.....["xdatacolumn"] and data.....["ydatacolumn"] should have the same 
       number of elements (column indices)
       -- evidently, this number should >>1
       -- note this exception on data.....["xdatacolumn"]

  data["fig"][ifig]["tab"][itab]["xdataconversion"] ifnot:
  data["fig"][ifig]["xdataconversion"] ifnot:
  data["xdataconversion"] ifnot:
  defaults["xdataconversion"] = ""

  data["fig"][ifig]["tab"][itab]["ydataconversion"] ifnot:
  data["fig"][ifig]["ydataconversion"] ifnot:
  data["ydataconversion"] ifnot:
  defaults["ydataconversion"] = ""

    -- empty string, or string with one of the values:
           "temp<temp"
           "hum<relhum"
           "hum<abshum"
           "hum<vappres"
           "temp<relhum"
           "temp<abshum"
           "temp<vappres"
           "hum<temp"
       indicating in the second part the quantity stored in the x or y data
       and in the first part the quantity to be presented in the x or y axis of the plot
    -- needed when psychro data is plotted

  data["fig"][ifig]["tab"][itab]["Pbdatakey"] ifnot:
  data["fig"][ifig]["Pbdatakey"] ifnot:
  data["Pbdatakey"] ifnot:
  defaults["Pbdatakey"] = "Pb"

    -- string for the field name where the barometric pressure data are stored,
       similar to data.....["ydatakey"]
    -- the eventual data for the barometric pressure may well be:
       -- given as a single value
       -- given as a one-dimensional array
       -- given in a column of a two-dimensional array
    -- the unit for the barometric pressure is pascals
    -- default value for the barometric pressure in pascals: defaults["Pb"] = 101325

  data["fig"][ifig]["tab"][itab]["Pbdatacolumn"] ifnot:
  data["fig"][ifig]["Pbdatacolumn"] ifnot:
  data["Pbdatacolumn"]

    -- integer for the column index
    -- 1 at default
    -- needed if the barometric pressure is given in a two-dimensional array

  data["fig"][ifig]["tab"][itab]["legend"]
  
    -- array of strings for a description of each series isr in tab itab of figure ifig
    -- default value "(tab" + String(itab) + ",col" + String(isr) + ")"
    -- use a subset of html code (for bold, italic, super/subscript, some symbols)

  data["fig"][ifig]["tab"][itab]["style"]
  
    -- array of records for the drawing style of each series isr in tab itab of figure ifig
    -- each record may have the following fields:

         data["fig"][ifig]["tab"][itab]["style"][isr]["colour"]
            -- string for the colour name
            -- default colours are defined by:
               -- colour ordre in:
                    data["fig"][ifig]["tab"][itab]["colours"] ifnot:
                    data["fig"][ifig]["colours"] ifnot:
                    data["colours"] ifnot:
                    defaults["colours"] = [ "k", "r", "g", "b", "m", "c", "y" ]
               -- colour names in:
                    data.....["colourdef"] ifnot:
                    defaults["colourdef"]

         data["fig"][ifig]["tab"][itab]["style"][isr]["line"]
            -- string for the line style name
            -- only if empty, no line is drawn
            -- if not given, a default line is drawn
            -- line styles are defined by:
               -- line style ordre in:
                    data.....["lines"] ifnot:
                    defaults["lines"] = [ "-" ,"--" ,":" ,"-." ]
               -- line style names in:
                    data.....["linedef"] ifnot:
                    defaults["linedef"]

         data["fig"][ifig]["tab"][itab]["style"][isr]["linewidth"]
            -- real for the line width
            -- default in:
                    data.....["linewidth"] ifnot:
                    defaults["linewidth"] = 2
           -- only relevant to the html/js output

         data["fig"][ifig]["tab"][itab]["style"][isr]["step"]
            -- value 0 or 1, whether the line is drawn stepwise
            -- default in:
                    data.....["step"] ifnot:
                    defaults["step"] = 0

         data["fig"][ifig]["tab"][itab]["style"][isr]["marker"]
            -- string for the marker name
            -- if empty, or if not given, no markers are drawn
            -- markers are defined by:
               -- marker ordre in:
                    data.....["markers"] ifnot:
                    defaults["markers"] = [ "+", "o", ".", "x", "s", "d", "^", "v", ">", "<" ]
               -- marker names in:
                    data.....["markerdef"] ifnot:
                    defaults["markerdef"]

         data["fig"][ifig]["tab"][itab]["style"][isr]["markerskip"]
            -- integer for the number of data points to skip at drawing markers
            -- default in:
                    data.....["markerskip"] ifnot:
                    defaults["markerskip"] = 0

         data["fig"][ifig]["tab"][itab]["style"][isr]["markernumber"]
            -- integer for the total number of markers drawn along
               the series
            -- markers will be distribured evenly along the series
            -- a value >= 1 will take this feature into effect
            -- a value == 0 will take the above feature of markerskip
               into effect
            -- default in:
                    data.....["markernumber"] ifnot:
                    defaults["markernumber"] = 10
            -- only relevant to the screen and pdf output
            -- FIXME: add pro forma in hplot_example.html ?

         data["fig"][ifig]["tab"][itab]["style"][isr]["markerscale"]
            -- real for the marker scaling
            -- default in:
                    data.....["markerscale"] ifnot:
                    defaults["markerscale"] = 1
           -- only relevant to the html/js output

  data["fig"][ifig]["tab"][itab]["mstyle"]
  
    -- array of strings for the drawing style of each series isr in tab itab of figure ifig
    -- automatically converted and put into data["fig"][ifig]["tab"][itab]["style"] by
       Octave function hplot().
    -- if both data["fig"][ifig]["tab"][itab]["mstyle"] and data["fig"][ifig]["tab"][itab]["style"]
       exist, the latter will be overwritten by the information from the first one
    -- only relevant to Octave input

  data["fig"][ifig]["tab"][itab]["mstep"]

    -- array of values 0 or 1, whether each series isr in tab itab of figure ifig is drawn stepwise
    -- alternative in companion with data["fig"][ifig]["tab"][itab]["mstyle"]
    -- automatically converted and put into data["fig"][ifig]["tab"][itab]["style"] by 
       Octave function hplot().
    -- if both data["fig"][ifig]["tab"][itab]["mstyle"] and data["fig"][ifig]["tab"][itab]["style"]
       exist, the latter will be overwritten by the information from the first one
    -- only relevant to Octave input

  data["fig"][ifig]["tab"][itab]["stylecombination"]
  data["fig"][ifig]["stylecombination"] ifnot:
  data["stylecombination"] ifnot:
  defaults["stylecombination"] = "colourfirst"

    -- string for the method by which line colours and line styles are combined and ordred
    -- one of the following values:
         "colourfirst"
         "stylefirst"
         "independent"

  data["fig"][ifig]["Taxis"] ifnot:
  data["Taxis"] ifnot:
  defaults["Taxis"] = { label : "dry-bulb temperature", unit : "&deg;C" }

  data["fig"][ifig]["Xaxis"] ifnot:
  data["Xaxis"] ifnot:
  defaults["Xaxis"] = { label : "absolute humidity of air", unit : "kg/kg" }
  
    -- record for the labels and units if a psychro figure is drawn

  data["fig"][ifig]["rotated"] ifnot:
  data["rotated"] ifnot:
  defaults["rotated"] = 0
  
    -- value 0 or 1, whether the figure is rotated 90 degrees clockwise
    -- only relevant to the html/js output
    
  data["fig"][ifig]["axisboxwidth"] ifnot:
  data["axisboxwidth"] ifnot:
  defaults["axisboxwidth"] = 700

  data["fig"][ifig]["axisboxheight"] ifnot:
  data["axisboxheight"] ifnot:
  defaults["axisboxheight"] = 400

    -- only relevant to the html/js output
    -- real for the width and height of the axis box in pixels

  data["fig"][ifig]["margins"] ifnot:
  data["margins"] ifnot:
  defaults["margins"]
  
    -- only relevant to the html/js output
    -- see variable defaults in the javascript code
  
  data["fig"][ifig]["xthreshold"] ifnot:
  data["xthreshold"] ifnot:
  defaults["xthreshold"]
  
    -- only relevant to the html/js output
    -- see variable defaults in the javascript code

  data["fig"][ifig]["veil"] ifnot:
  data["veil"] ifnot:
  defaults["veil"]
  
    -- only relevant to the html/js output
    -- see variable defaults in the javascript code

  data["fig"][ifig]["seriespointer"] ifnot:
  data["seriespointer"] ifnot:
  defaults["seriespointer"]
  
    -- only relevant to the html/js output
    -- see variable defaults in the javascript code

  data["fig"][ifig]["xaxis"] ifnot:
  data["xaxis"] ifnot:
  defaults["xaxis"]
  
  data["fig"][ifig]["yaxis"] ifnot:
  data["yaxis"] ifnot:
  defaults["yaxis"]

    -- only relevant to the html/js output
    -- see variable defaults in the javascript code

  data["fig"][ifig]["legend"] ifnot:
  data["legend"] ifnot:
  defaults["legend"]
  
    -- only relevant to the html/js output
    -- see variable defaults in the javascript code

  data["fig"][ifig]["air"] ifnot:
  data["air"] ifnot:
  defaults["air"]

  data["fig"][ifig]["Faxis"] ifnot:
  data["Faxis"] ifnot:
  defaults["Faxis"]
  
  data["fig"][ifig]["Haxis"] ifnot:
  data["Haxis"] ifnot:
  defaults["Haxis"]

    -- only relevant to the html/js output
    -- see variable defaults in the javascript code

  data["fig"][ifig]["figurebackground"] ifnot:
  data["figurebackground"] ifnot:
  defaults["figurebackground"]

  data["fig"][ifig]["axisbackground"] ifnot:
  data["axisbackground"] ifnot:
  defaults["axisbackground"]

    -- only relevant to the html/js output
    -- see variable defaults in the javascript code

  data["fig"][ifig]["unitbrackets"] ifnot:
  data["unitbrackets"] ifnot:
  defaults["unitbrackets"] = [" [", "]"]

    -- array of two strings, which are written just before and after the unit of a quantity
    
  data["fig"][ifig]["mousepointer"] ifnot:
  data["mousepointer"] ifnot:
  defaults["mousepointer"]

    -- only relevant to the html/js output
    -- see variable defaults in the javascript code

  data["fig"][ifig]["title"] ifnot:
  data["title"] ifnot:
  defaults["title"] = ""
  
    -- string for the title

  data["fig"][ifig]["legendtabletext"] ifnot:
  data["legendtabletext"] ifnot:
  defaults["legendtabletext"]

    -- only relevant to the html/js output
    -- see variable defaults in the javascript code

  data["fig"][ifig]["buttonpaneltext"] ifnot:
  data["buttonpaneltext"] ifnot:
  defaults["buttonpaneltext"]

    -- only relevant to the html/js output
    -- see variable defaults in the javascript code

  data["fig"][ifig]["viewperiod"] ifnot:
  data["viewperiod"] ifnot:
  defaults["viewperiod"]

    -- only relevant to the html/js output
    -- see variable defaults in the javascript code

  data["fig"][ifig]["fignameprefix"] ifnot:
  data["fignameprefix"] ifnot:
  defaults["fignameprefix"]

    -- only relevant to the html/js output
    -- see variable defaults in the javascript code

  data["fig"][ifig]["numero"]

    -- string for the numero (number as identifier) of the figure
    -- default value is the string representation of ifig

  data["fig"][ifig]["caption"] ifnot:
  data["caption"] ifnot:
  defaults["caption"] = ""

    -- string for the title
    -- keep the title text short, because octave figure titles do not have much space

  data["fig"][ifig]["numeroprefixsuffix"] ifnot:
  data["numeroprefixsuffix"] ifnot:
  defaults["numeroprefixsuffix"] = ["Figure ", ": ", "."]

    -- array of three strings
    -- the first element is put before the numero text of a figure.
    -- the second element is put after the numero, if data["fig"][ifig]["caption"} is non-empty.
    -- the third element is put after the numero, if data["fig"][ifig]["caption"} is empty.
    -- only used in html/js output

------------------------------------------------------------

  data["fig"][ifig]["tab"][itab]["octave"]["rowselectionkey"] ifnot:
  data["fig"][ifig]["octave"]["rowselectionkey"] ifnot:
  data["octave"]["rowselectionkey"]
  
    -- array of strings for the field names where the 
       row selection information is stored
    -- if the string is represented by variable field, 
       the row selection information is searched for in:
         data["fig"][ifig]["tab"][itab]["octave"][field] ifnot:
         data["fig"][ifig]["octave"][field] ifnot:
         data["octave"][field]
         
       this field contains an array of three elements:
       -- a string for a arbitrary code or short description
       -- a string for the description
       -- an array of row indices by which the x, y 
          and common data are selected
    -- there is no default
    -- only relevant to the screen and pdf output
    -- only relevant to Octave function hplot()
    
  data["octave"]["screenprint"] ifnot:
  defaults["octave"]["screenprint"] = 1

    -- value 0 or 1, whether screen prints are made
    -- only relevant to Octave function hplot()

  data["octave"]["printformat"] ifnot:
  defaults["octave"]["printformat"] = ["pdf"]

    -- array of strings for print format id's
    -- an empty array means that no figure
       files are produced
    -- if property "screenprint" is zero,
       no figure files are produced
    -- only relevant to Octave function hplot()

  data["octave"]["figurefilepath"] ifnot:
  defaults["octave"]["figurefilepath"] = ""

  data["octave"]["figurefilebase"] ifnot:
  defaults["octave"]["figurefilebase"] = "output"

    -- strings for the file path and the base
       of the file names of the figure files 
    -- only relevant to Octave function hplot()

  data["octave"]["htmloutput"] ifnot:
  defaults["octave"]["htmloutput"] = 1

    -- value 0 or 1, whether a html/js file is made
    -- only relevant to Octave function hplot()

  data["octave"]["htmlfilepath"] ifnot:
  defaults["octave"]["htmlfilepath"] = ""

  data["octave"]["htmlfilename"] ifnot:
  defaults["octave"]["htmlfilename"] = "output.html"

    -- strings for the file path and file name of
       the html/js output 
    -- only relevant to Octave function hplot()

  data["octave"]["templatepath"]

    -- string for the file path of the template for
       the html/js output 
    -- the default value is ["share" filesep "hplot"]
    -- the file name of the template is always
       "html_example.html"
    -- only relevant to Octave function hplot()

  data["octave"]["ifigs"] ifnot:
  defaults["octave"]["ifigs"] = []

    -- array of indices of figures which are plotted
       on screen and in pdf
    -- indices as ifig in data["fig"][ifig]
    -- an empty array means that _all_ figures
       are plotted
    -- only relevant to the screen and pdf output
    -- only relevant to Octave function hplot()

  data["fig"][ifig]["octave"]["nseriesmax"] ifnot:
  data["octave"]["nseriesmax"] ifnot:
  defaults["octave"]["nseriesmax"] = 4
  
    -- integer for the maximum number of series 
       which are plotted in one figure window 
       on screen and in pdf
    -- if the number of series of a figure exceeds
       this maximum, multiple (sub)figures are
       plotted
    -- this feature is to prevent that a figure
       is filled with many lines and becomes
       unreadable
    -- only relevant to the screen and pdf output
    -- only relevant to Octave function hplot()

  data["fig"][ifig]["octave"]["itabs_repeat"] ifnot:
  data["octave"]["itabs_repeat"] ifnot:
  defaults["octave"]["itabs_repeat"] = []
  
    -- array of indices to tables of which the
       series are repeated/copied on each possible
       (sub)figure due to the maximum number
       of series in a (sub)figure
    -- the number of series of the indicated
       tables are not counted to decide whether 
       the maximum number of series in a 
       (sub)figure is exceeded
    -- indices as itab in data["fig"][ifig]["tab"][itab]
    -- only relevant to the screen and pdf output
    -- only relevant to Octave function hplot()

  data["fig"][ifig]["octave"]["axislimits"] ifnot:
  data["octave"]["axislimits"] ifnot:
  defaults["octave"]["axislimits"] = ["auto","auto","auto","auto"]
  
    -- array to set the lower and upper limits
       of the x axis values, and the lower and
       upper limits of the y axis values, 
       respectively
    -- if an element in the array is not numeric,
       the respective limit is derived 
       automatically by Octave plot() from the 
       data in the plot
    -- only relevant to the screen and pdf output
    -- only relevant to Octave function hplot()

  data["fig"][ifig]["octave"]["legendoptions"] ifnot:
  data["octave"]["legendoptions"] ifnot:
  defaults["octave"]["legendoptions"] = ["location","northwest"]
  
    -- array of options to be fed as extra 
       arguments for Octave function legend()
    -- see help legend
    -- only relevant to the screen and pdf output
    -- only relevant to Octave function hplot()

  data["fig"][ifig]["octave"]["plotTXoptions"] ifnot:
  data["octave"]["plotTXoptions"] ifnot:
  defaults["octave"]["plotTXoptions"] = struct()
  
    -- struct of options to be fed to as extra 
       argument for Octave function mollier_plotTX()
    -- see help mollier_plotTX
    -- only relevant to the screen and pdf output
    -- only relevant to Octave function hplot()

------------------------------------------------------------
