## Ploticus config files

Version 2.32

Manual page for Ploticus_config_files(PL)

A "config file" is a different thing from a "ploticus script file"!`` They are two different things!`` A configuration file is usually not required (it is required when running in cgi mode).`` It may be used to make certain settings that will apply to all ploticus invocations, kind of like a `.profile` or `.cshrc` file.`` If no config file is found, standard defaults will be used.`` Upon execution, ploticus checks for an environment variable called PLOTICUS_CONFIG, which should contain the full path name of your config file.``

If a config file is found, it will be read and processed before command line arguments are evaluated, and before script interpretation begins.``

Typical uses of a config file are to set up non-English month and weekday names, to set default date or numeric notations, or to use cm instead of inch as the absolute unit.``

Many (but not all) of these settings can also be made from within a script using proc settings.`` A few can also be set from the pl command line.`` Presidence (from highest to lowest) is: proc settings, command line, config file.``

## Examples

Examples of config files set up for Spanish and Russian are located in the gallery directory, named plconfig.spanish and plconfig.russian

## Syntax

One parameter is specified per line (see the example below).`` Parameters are case-insensitive and must begin in the first column of the line.`` Lines beginning with `//` or `#` are taken as comments; blank lines are skipped.``

## Debugging

If you're using a config file (but not in direct CGI mode) and want to confirm that it's being read, put the following line at the top of your config file: `option: -debug` (this is because the config file is processed before command line args are evaluated, so a `-debug` on the command line won't take effect in time).``

## Parameters

The following parameters may be set.`` Parameters that are not set assume the default value, which is shown in (parentheses).``

projectroot: dirname

  The directory from which ploticus will operate. This must be specified when using pl in cgi mode.``

option: option [arg]

  Set a pl command line option (see pl(1) for discussion of supported command line options) or a prefab parameter.`` The given command line option will be in effect for all invocations of pl.`` This parameter may be used as many times as necessary.`` The only command line args that cannot be set this way are -prefab, -f, and -ver.`` Any quoting should be omitted on parameters that have embedded white space, such as `rectangle=`.``
  Examples:

        option: -gif
        option: -viewer xv
        option: delim=comma
        option: rectangle= 1 1 5 5

varvalue: varname=value

  Preset a variable to a value.`` This may be used as many times as desired within the config file to set various variables.`` This may also be used to set a variable that will be referenced later in the config file.``
  Example: `varvalue: MODE=normal`

putenv: varname=value

  Set an environment variable for current process and all subprocesses.`` This may be used as many times as desired within the config file to set various environment variables. Especially useful when operating in cgi mode since a CGI process often inherits an environment that is not under the developer's control.``
  Example: `putenv: ERRMODE=normal`

tmpdir: dirname

  The directory that ploticus uses for temporary files.`` By default this is `/tmp`.`` This can also be set in `pl.h`.``
  Example: `tmpdir: /var/tmp`

The remaining parameters, from here to end of page, can be set using a config file, or within a script using proc settings.``

units `in | cm`

  The measurement unit to be used for ploticus absolute units. Either `in` (inches) or `cm` (centimeters).`` Default is `in`.`` If this is set in the config file, it will be in effect when command line arguments are evaluated. If set in proc settings, it will not have any effect on command line argument evaluation.``
  Example: `units: cm`

encodenames `yes | no`

  If `yes`, spaces and commas can be represented in field names using an encoding scheme where a space is represented using an underscore (_) and a comma is represented using a vertical bar (|).`` Useful in situations where field names will be visible directly as legend labels or axis stubs.`` For scripts, the default is `no` for backward compatibility. For prefabs the default is `yes`.`` (2.30+) Example: students

enable_suscripts `yes | no`

  If `yes`, inline superscripts and subscripts capability is turned on. (2.30+). For scripts, the default is `no` for backward compatibility. For prefabs the default is `yes`.`` Here's an example.``

errmsgpre `tag`

  Allows developer to set the first portion of all ploticus error messages to `tag` (it will stay in effect until explicitly set again).`` For example, where a web page generates multiple plots it may be useful in identifying which plot had the error.``

font fontname

  Make fontname the default font. Font names having embedded spaces will be parsed correctly (but may still be problematic).`` For more information see fonts.``

numbernotation `standard | us | euro`

  Specifies how decimal point and thousands separators will be displayed. Default is `standard`.`` The following table illustrates:

       standard           us             euro
      ----------    ------------    -------------
           79              79               79
           79.5            79.5             79,5
         4321.79         4321.79          4321,79
        54321          54,321           54.321
       654321.07      654,321.07       654.321,07
      1987654321    1,987,654,321    1.987.654.321

numberspacerthreshold n

  Specifies at what numeric magnitude thousands separators will begin to be inserted.`` Default is 4, and this is used in the above table. If it were set to `3`, the third entry in the above table would appear like this:

         4321.79         4,321.79          4.321,79

## PostScript / EPS settings

ps_latin1_encoding `yes | no`

  A latin1 encoding scheme has been added to the postscript driver to make extended ascii characters consistent with other graphical formats, and this encoding is in effect by default. To disenable feature set this to `no`.`` You may want to try this if other applications are having trouble with your EPS files.`` (2.30+)

## SVG / XML settings

Overall settings affecting SVG graphics.``

xml_declaration `yes | no`

  The default (`yes`) causes the first line of the SVG result to contain the XML declaration `<?xml .. >` .`` Use `no` to suppress the XML declaration line if the SVG result is to be embedded into a larger XML document. This may also be done using the `-omit_xml_declaration` command line argument.``

xml_encoding method

  This may be used to set the XML character encoding method. It has no effect when `xml_declaration` is `no`.`` The default is `iso-8859-1` which provides Latin and Western European character sets.`` For Unicode fonts this should be set to `utf-8` (for more discussion see the Unicode section in fonts ). Equivalent to the `-xml_encoding` command line argument.``

svg_tagparms `text`

  Allows allows arbitrary `text` to be inserted into the opening `<svg>` tag.``
  Example: `svg_tagparms: height="5cm" width="8cm"`

svg_mouseover_js `method1 | generic`

  Specifies the method to use for SVG mouseover. The default is `method1`, which provides standalone SVG mouseover support (the SVG result will contain embedded references to javascript files `GraphPopups.js` and `ViewBox.js`).`` Specify `generic` here if you're using some other javascript strategy such as overlibmws ("method #2").`` For more discussion, see the ploticus SVG manual page, mouseover section.``

svg_linkparms `text`

  When generating SVG clickmap-enabled results, this allows additional attributes to be supplied to SVG's <a .. > construct.`` Example:

      #proc settings
      svg_linkparms: target="new"

## System environment

cpulimit nseconds

  Number of seconds of CPU time that will be allowed to the pl process or any spawned subprocesses. Default is 30 seconds.`` Any process exceeding this will abort.``

## Date-related

dateformat format

  Set the current date format.`` format must be a date format from the dates manual page that includes month, day, and year, for which arithmetic is supported.`` To use other arithmetic date formats (such as quarter notation) specify the format in the proc areadef xscaletype or yscaletype attribute.``
  Example: `dateformat: dd-mmm-yyyy`

omitweekends `omit | adjust | yes | no`

  Allows date plotting as if Saturdays and Sundays did not exist.`` Mondays will follow Fridays directly. Useful in certain business and work-related plots.``
  If `omit`, any Saturday or Sunday dates encountered will be considered invalid and omitted; however they will not be reported unless the -showbad command line option is used.`` If `omit` is set then Saturday or Sunday dates can generate a bad date error in some circumstances, such as when given in an axis range.``
  If `adjust` or `yes`, any Saturday or Sunday dates encountered will be silently adjusted to the nearest weekday. This is more lenient than `omit`, and avoids the possibility of a bad date error.``

pivotyear yy

  Set the two digit year that should be used to convert two-digit years to four-digit years. If two-digit years are used, year values that are less than the pivot year are assumed to be 21st century years. Default is 77.``
  Example: `pivotyear: 50`

months list

  Specify the three-character month abbreviations to be used, all in lower case, beginning with the first month.`` Default is the English (`jan feb mar apr may jun jul aug sep oct nov dec`).``
  Example (Spanish) (must all be on one line):
  `months: ene feb mar abr pue jun jul ago sep oct nov dic`

months.abbrev list

  short month names, capitalized for presentation, begining with the first month.`` Default is English (`Jan Feb Mar Apr May June July Aug Sept Oct Nov Dec`).``
  Example (Spanish) (must all be on one line):
  `months.abbrev: Ene Feb Mar Abr Pue Jun Jul Ago Sep Oct Nov Dic`

months.full list

  full month names, capitalized for presentation.``
  Example (Spanish) (must all be on one line):
  `months.full: Enero Febrero Marcha Abril Pueda Junio Julio Agosto Septiembre Octubre Noviembre Diciembre`

weekdays list

  three-character weekday abbreviations, capitalized for presentation, beginning with Sunday.``
  Example (French): `weekdays: Dim Lun Mar Mer Jeu Ven Sam`
  Example (Spanish): `weekdays: Dom Lun Mar Mie Jue Vie Sab`

lazydates `month | day | both`

  Allow handling of dates where the day component or the month component is not known. See dates for further discussion of lazy dates.``

strictdatelengths `yes | no`

  Default is `no`.`` Use `yes` to ensure that malformed date values will be detected-- for example, if the date format is `mm/dd/yyyy` a date value such as `03/04/2001` would be ok but `3/4/2001` would result in an error.`` If this attribute is `no`, format checking is relaxed, and the latter case above would be ok.``

dtsep character

  Date / time separator character for datetime data items.`` By default this is dot `.`. However ISO8601 uses `T`, eg. 29Mar03T03:16:00 ..`` This character should be one that never appears in the dates or times themselves.``
  Example: `dtsep: T`
  data display engine
  Copyright Steve Grubb

Markup created by unroff 1.0, `` `` August 23, 2005.