[BACK]Return to gnuplot.doc CVS log [TXT][DIR] Up to [local] / OpenXM_contrib / gnuplot / docs

Annotation of OpenXM_contrib/gnuplot/docs/gnuplot.doc, Revision 1.1.1.3

1.1.1.3 ! ohara       1: C RCS $Id: gnuplot.doc,v 1.20.2.10 2002/12/04 19:31:06 lhecking Exp $
1.1       maekawa     2: C 3 December 1998
                      3: C Copyright (C) 1986 - 1993, 1998   Thomas Williams, Colin Kelley
                      4: C
                      5: ^ <h2> An Interactive Plotting Program </h2><p>
                      6: ^ <h2>  Thomas Williams & Colin Kelley</h2><p>
                      7: ^ <h2>   Version 3.7 organized by: David Denholm </h2><p>
                      8: ^ <h2>Major contributors (alphabetic order):</h2>
                      9: ^<ul><h3>
                     10: ^<li>  Hans-Bernhard Broeker
                     11: ^<li>  John Campbell
                     12: ^<li>  Robert Cunningham
                     13: ^<li>  David Denholm
                     14: ^<li>  Gershon Elber
                     15: ^<li>  Roger Fearick
                     16: ^<li>  Carsten Grammes
                     17: ^<li>  Lucas Hart
                     18: ^<li>  Lars Hecking
                     19: ^<li>  Thomas Koenig
                     20: ^<li>  David Kotz
                     21: ^<li>  Ed Kubaitis
                     22: ^<li>  Russell Lang
                     23: ^<li>  Alexander Lehmann
                     24: ^<li>  Alexander Mai
                     25: ^<li>  Carsten Steger
                     26: ^<li>  Tom Tkacik
                     27: ^<li>  Jos Van der Woude
                     28: ^<li>  James R. Van Zandt
                     29: ^<li>  Alex Woo
                     30: ^</h3></ul> <p>
                     31: ^<h2>  Copyright (C) 1986 - 1993, 1998   Thomas Williams, Colin Kelley<p>
                     32: ^   Mailing list for comments: info-gnuplot@dartmouth.edu <p>
                     33: ^   Mailing list for bug reports: bug-gnuplot@dartmouth.edu<p>
                     34: ^</h2><p>
                     35: ^<h3> This manual was prepared by Dick Crawford</h3><p>
                     36: ^<h3> 3 December 1998</h3><p>
                     37: ^<hr>
                     38: 1 gnuplot
                     39: 2 Copyright
                     40: ?copyright
                     41: ?license
                     42:        Copyright (C) 1986 - 1993, 1998   Thomas Williams, Colin Kelley
                     43:
                     44:  Permission to use, copy, and distribute this software and its
                     45:  documentation for any purpose with or without fee is hereby granted,
                     46:  provided that the above copyright notice appear in all copies and
                     47:  that both that copyright notice and this permission notice appear
                     48:  in supporting documentation.
                     49:
                     50:  Permission to modify the software is granted, but not the right to
                     51:  distribute the complete modified source code.  Modifications are to
                     52:  be distributed as patches to the released version.  Permission to
                     53:  distribute binaries produced by compiling modified sources is granted,
                     54:  provided you
                     55:    1. distribute the corresponding source modifications from the
                     56:     released version in the form of a patch file along with the binaries,
                     57:    2. add special version identification to distinguish your version
                     58:     in addition to the base release version number,
                     59:    3. provide your name and address as the primary contact for the
                     60:     support of your modified version, and
                     61:    4. retain our contact information in regard to use of the base
                     62:     software.
                     63:  Permission to distribute the released version of the source code along
                     64:  with corresponding source modifications in the form of a patch file is
                     65:  granted with same provisions 2 through 4 for binary distributions.
                     66:
                     67:  This software is provided "as is" without express or implied warranty
                     68:  to the extent permitted by applicable law.
                     69:
                     70:
                     71:        AUTHORS
                     72:
                     73:        Original Software:
                     74:           Thomas Williams,  Colin Kelley.
                     75:
                     76:        Gnuplot 2.0 additions:
                     77:           Russell Lang, Dave Kotz, John Campbell.
                     78:
                     79:        Gnuplot 3.0 additions:
                     80:           Gershon Elber and many others.
                     81: 2 Introduction
                     82: ?introduction
                     83: ?
                     84:  `gnuplot` is a command-driven interactive function and data plotting program.
                     85:  It is case sensitive (commands and function names written in lowercase are
                     86:  not the same as those written in CAPS).  All command names may be abbreviated
                     87:  as long as the abbreviation is not ambiguous.  Any number of commands may
                     88:  appear on a line (with the exception that `load` or `call` must be the final
                     89:  command), separated by semicolons (;).  Strings are indicated with quotes.
                     90:  They may be either single or double quotation marks, e.g.,
                     91:
                     92:        load "filename"
                     93:        cd 'dir'
                     94:
                     95:  although there are some subtle differences (see `syntax` for more details).
                     96:
                     97:  Any command-line arguments are assumed to be names of files containing
                     98:  `gnuplot` commands, with the exception of standard X11 arguments, which are
                     99:  processed first.  Each file is loaded with the `load` command, in the order
                    100:  specified.  `gnuplot` exits after the last file is processed.  When no load
                    101:  files are named, `gnuplot` enters into an interactive mode.  The special
                    102:  filename "-" is used to denote standard input.  See "help batch/interactive"
                    103:  for more details.
                    104:
                    105:  Many `gnuplot` commands have multiple options.  These options must appear in
                    106:  the proper order, although unwanted ones may be omitted in most cases.  Thus
                    107:  if the entire command is "command a b c", then "command a c" will probably
                    108:  work, but "command c a" will fail.
                    109:
                    110:  Commands may extend over several input lines by ending each line but the last
                    111:  with a backslash (\).  The backslash must be the _last_ character on each
                    112:  line.  The effect is as if the backslash and newline were not there.  That
                    113:  is, no white space is implied, nor is a comment terminated.  Therefore,
                    114:  commenting out a continued line comments out the entire command (see
                    115:  `comment`).  But note that if an error occurs somewhere on a multi-line
                    116:  command, the parser may not be able to locate precisely where the error is
                    117:  and in that case will not necessarily point to the correct line.
                    118:
                    119:  In this document, curly braces ({}) denote optional arguments and a vertical
                    120:  bar (|) separates mutually exclusive choices.  `gnuplot` keywords or `help`
                    121:  topics are indicated by backquotes or `boldface` (where available).  Angle
                    122:  brackets (<>) are used to mark replaceable tokens.  In many cases, a default
                    123:  value of the token will be taken for optional arguments if the token is
                    124:  omitted, but these cases are not always denoted with braces around the angle
                    125:  brackets.
                    126:
                    127:  For on-line help on any topic, type `help` followed by the name of the topic
                    128:  or just `help` or `?` to get a menu of available topics.
                    129:
                    130:  The new `gnuplot` user should begin by reading about `plotting` (if on-line,
                    131:  type `help plotting`).
1.1.1.2   maekawa   132: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/simple.html"> Simple Plots Demo </a>
1.1       maekawa   133: 2 Seeking-assistance
                    134: ?seeking-assistance
                    135:  There is a mailing list for `gnuplot` users.  Note, however, that the
                    136:  newsgroup
                    137:        comp.graphics.apps.gnuplot
                    138:  is identical to the mailing list (they both carry the same set of messages).
                    139:  We prefer that you read the messages through the newsgroup rather than
                    140:  subscribing to the mailing list.  Administrative requests should be sent to
                    141:        majordomo@dartmouth.edu
                    142:  Send a message with the body (not the subject) consisting of the single word
                    143:  "help" (without the quotes) for more details.
                    144:
                    145:  The address for mailing to list members is:
                    146:        info-gnuplot@dartmouth.edu
                    147:
                    148:  Bug reports and code contributions should be mailed to:
                    149:        bug-gnuplot@dartmouth.edu
                    150:
                    151:  The list of those interested in beta-test versions is:
                    152:        info-gnuplot-beta@dartmouth.edu
                    153:
                    154:  There is also a World Wide Web page with up-to-date information, including
                    155:  known bugs:
                    156: ^ <a href="http://www.cs.dartmouth.edu/gnuplot_info.html">
                    157:        http://www.cs.dartmouth.edu/gnuplot_info.html
                    158: ^ </a>
                    159:
                    160:  Before seeking help, please check the
1.1.1.2   maekawa   161: ^ <a href="http://www.ucc.ie/gnuplot/gnuplot-faq.html">
1.1       maekawa   162:  FAQ (Frequently Asked Questions) list.
                    163: ^ </a>
                    164:  If you do not have a copy of the FAQ, you may request a copy by email from
                    165:  the Majordomo address above, ftp a copy from
1.1.1.2   maekawa   166:        ftp://ftp.ucc.ie/pub/gnuplot/faq,
                    167:        ftp://ftp.gnuplot.vt.edu/pub/gnuplot/faq,
1.1       maekawa   168:  or see the WWW `gnuplot` page.
                    169:
                    170:  When posting a question, please include full details of the version of
                    171:  `gnuplot`, the machine, and operating system you are using.  A _small_ script
                    172:  demonstrating the problem may be useful.  Function plots are preferable to
                    173:  datafile plots.  If email-ing to info-gnuplot, please state whether or not
                    174:  you are subscribed to the list, so that users who use news will know to email
                    175:  a reply to you.  There is a form for such postings on the WWW site.
                    176: 2 What's New in version 3.7
                    177: ?new-features
                    178:  Gnuplot version 3.7 contains many new features.  This section gives a partial
                    179:  list and links to the new items in no particular order.
                    180:
                    181:  1. `fit f(x) 'file' via` uses the Marquardt-Levenberg method to fit data.
                    182:  (This is only slightly different from the `gnufit` patch available for 3.5.)
                    183:
                    184:  2. Greatly expanded `using` command.  See `plot using`.
                    185:
                    186:  3. `set timefmt` allows for the use of dates as input and output for time
                    187:  series plots.  See `Time/Date data` and
1.1.1.2   maekawa   188: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/timedat.html">
1.1       maekawa   189:  timedat.dem.
                    190: ^ </a>
                    191:
                    192:  4. Multiline labels and font selection in some drivers.
                    193:
                    194:  5. Minor (unlabeled) tics.  See `set mxtics`.
                    195:
                    196:  6. `key` options for moving the key box in the page (and even outside of the
                    197:  plot), putting a title on it and a box around it, and more.  See `set key`.
                    198:
                    199:  7. Multiplots on a single logical page with `set multiplot`.
                    200:
                    201:  8. Enhanced `postscript` driver with super/subscripts and font changes.
                    202:  (This was a separate driver (`enhpost`) that was available as a patch for
                    203:  3.5.)
                    204:
                    205:  9. Second axes:  use the top and right axes independently of the bottom and
                    206:  left, both for plotting and labels.  See `plot`.
                    207:
                    208:  10. Special datafile names `'-'` and `""`.  See `plot special-filenames`.
                    209:
                    210:  11. Additional coordinate systems for labels and arrows.  See `coordinates`.
                    211:
                    212:  12. `set size` can try to plot with a specified aspect ratio.
                    213:
                    214:  13. `set missing` now treats missing data correctly.
                    215:
                    216:  14. The `call` command: `load` with arguments.
                    217:
1.1.1.3 ! ohara     218:  15. More flexible `range` commands with `reverse`, `writeback` and 'restore'
        !           219:  keywords.
1.1       maekawa   220:
                    221:  16. `set encoding` for multi-lingual encoding.
                    222:
                    223:  17. New `x11` driver with persistent and multiple windows.
                    224:
                    225:  18. New plotting styles: `xerrorbars`, `histeps`, `financebars` and more.
                    226:  See `set style`.
                    227:
                    228:  19. New tic label formats, including `"%l %L"` which uses the mantissa and
                    229:  exponents to a given base for labels.  See `set format`.
                    230:
                    231:  20. New drivers, including `cgm` for inclusion into MS-Office applications
                    232:  and `gif` for serving plots to the WEB.
                    233:
                    234:  21. Smoothing and spline-fitting options for `plot`.  See `plot smooth`.
                    235:
                    236:  22. `set margin` and `set origin` give much better control over where a
                    237:  graph appears on the page.
                    238:
                    239:  23. `set border` now controls each border individually.
                    240:
                    241:  24. The new commands `if` and `reread` allow command loops.
                    242:
                    243:  25. Point styles and sizes, line types and widths can be specified on the
                    244:  `plot` command.  Line types and widths can also be specified for grids,
                    245:  borders, tics and arrows.  See `plot with`.  Furthermore these types may be
                    246:  combined and stored for further use.  See `set linestyle`.
                    247:
                    248:  26. Text (labels, tic labels, and the time stamp) can be written vertically
                    249:  by those terminals capable of doing so.
                    250: 2 Batch/Interactive Operation
                    251: ?batch/interactive
                    252:  `gnuplot` may be executed in either batch or interactive modes, and the two
                    253:  may even be mixed together on many systems.
                    254:
                    255:  Any command-line arguments are assumed to be names of files containing
                    256:  `gnuplot` commands (with the exception of standard X11 arguments, which are
                    257:  processed first).  Each file is loaded with the `load` command, in the order
                    258:  specified.  `gnuplot` exits after the last file is processed.  When no load
                    259:  files are named, `gnuplot` enters into an interactive mode.  The special
                    260:  filename "-" is used to denote standard input.
                    261:
                    262:  Both the `exit` and `quit` commands terminate the current command file and
                    263:  `load` the next one, until all have been processed.
                    264:
                    265:  Examples:
                    266:
                    267:  To launch an interactive session:
                    268:        gnuplot
                    269:
                    270:  To launch a batch session using two command files "input1" and "input2":
                    271:        gnuplot input1 input2
                    272:
                    273:  To launch an interactive session after an initialization file "header" and
                    274:  followed by another command file "trailer":
                    275:        gnuplot header - trailer
                    276: 2 Command-line-editing
                    277: ?line-editing
                    278: ?editing
                    279: ?history
                    280: ?command-line-editing
                    281:  Command-line editing is supported by the Unix, Atari, VMS, MS-DOS and OS/2
                    282:  versions of `gnuplot`.  Also, a history mechanism allows previous commands to
                    283:  be edited and re-executed.  After the command line has been edited, a newline
                    284:  or carriage return will enter the entire line without regard to where the
                    285:  cursor is positioned.
                    286:
                    287:  (The readline function in `gnuplot` is not the same as the readline used in
                    288:  GNU Bash and GNU Emacs.  If the GNU version is desired, it may be selected
                    289:  instead of the `gnuplot` version at compile time.)
                    290:
                    291:
                    292:  The editing commands are as follows:
                    293:
                    294: @start table - first is interactive cleartext form
                    295:        `Line-editing`:
                    296:
                    297:        ^B    moves back a single character.
                    298:        ^F    moves forward a single character.
                    299:        ^A    moves to the beginning of the line.
                    300:        ^E    moves to the end of the line.
                    301:        ^H    and DEL delete the previous character.
                    302:        ^D    deletes the current character.
                    303:        ^K    deletes from current position to the end of line.
                    304:        ^L,^R redraws line in case it gets trashed.
                    305:        ^U    deletes the entire line.
1.1.1.3 ! ohara     306:        ^W    deletes from the current word to the end of line.
1.1       maekawa   307:
                    308:        `History`:
                    309:
                    310:        ^P    moves back through history.
                    311:        ^N    moves forward through history.
                    312: #\begin{tabular}{|cl|} \hline
                    313: #\multicolumn{2}{|c|}{Command-line Editing Commands} \\ \hline \hline
                    314: #Character & Function \\ \hline
                    315: # & \multicolumn{1}{|c|}{Line Editing}\\ \cline{2-2}
                    316: #\verb~^B~ & move back a single character.\\
                    317: #\verb~^F~ & move forward a single character.\\
                    318: #\verb~^A~ & move to the beginning of the line.\\
                    319: #\verb~^E~ & move to the end of the line.\\
                    320: #\verb~^H, DEL~ & delete the previous character.\\
                    321: #\verb~^D~ & delete the current character.\\
                    322: #\verb~^K~ & delete from current position to the end of line.\\
                    323: #\verb~^L, ^R~ & redraw line in case it gets trashed.\\
                    324: #\verb~^U~ & delete the entire line. \\
                    325: #\verb~^W~ & delete from the current word to the end of line. \\ \hline
                    326: # & \multicolumn{1}{|c|}{History} \\ \cline{2-2}
                    327: #\verb~^P~ & move back through history.\\
                    328: #\verb~^N~ & move forward through history.\\
                    329: %c l .
                    330: %Character@Function
                    331: %_
                    332: %@Line Editing
                    333: %^B@move back a single character.
                    334: %^F@move forward a single character.
                    335: %^A@move to the beginning of the line.
                    336: %^E@move to the end of the line.
                    337: %^H, DEL@delete the previous character.
                    338: %^D@delete the current character.
                    339: %^K@delete from current position to the end of line.
                    340: %^L, ^R@redraw line in case it gets trashed.
                    341: %^U@delete the entire line.
                    342: %^W@delete from the current word to the end of line.
                    343: %_
                    344: %@History
                    345: %^P@move back through history.
                    346: %^N@move forward through history.
                    347: @end table
                    348:
                    349:  On the IBM PC, the use of a TSR program such as DOSEDIT or CED may be desired
                    350:  for line editing.  The default makefile assumes that this is the case;  by
                    351:  default `gnuplot` will be compiled with no line-editing capability.  If you
                    352:  want to use `gnuplot`'s line editing, set READLINE in the makefile and add
                    353:  readline.obj to the link file.  The following arrow keys may be used on the
                    354:  IBM PC and Atari versions if readline is used:
                    355:
                    356: @start table - first is interactive cleartext form
                    357:        Left  Arrow      - same as ^B.
                    358:        Right Arrow      - same as ^F.
                    359:        Ctrl Left  Arrow - same as ^A.
                    360:        Ctrl Right Arrow - same as ^E.
                    361:        Up    Arrow      - same as ^P.
                    362:        Down  Arrow      - same as ^N.
                    363: #\begin{tabular}{|cl|} \hline
                    364: #Arrow key  & Function \\ \hline
                    365: #Left       & same as \verb~^B~. \\
                    366: #Right      & same as \verb~^F~. \\
                    367: #Ctrl Left  & same as \verb~^A~. \\
                    368: #Ctrl Right & same as \verb~^E~. \\
                    369: #Up         & same as \verb~^P~. \\
                    370: #Down       & same as \verb~^N~. \\
                    371: %c l .
                    372: %Arrow key@Function
                    373: %_
                    374: %Left Arrow@same as ^B.
                    375: %Right Arrow@same as ^F.
                    376: %Ctrl Left Arrow@same as ^A.
                    377: %Ctrl Right Arrow@same as ^E.
                    378: %Up Arrow@same as ^P.
                    379: %Down Arrow@same as ^N.
                    380: %_
                    381: @end table
                    382:
                    383:  The Atari version of readline defines some additional key aliases:
                    384:
                    385: @start table - first is interactive cleartext form
                    386:        Undo            - same as ^L.
                    387:        Home            - same as ^A.
                    388:        Ctrl Home       - same as ^E.
                    389:        Esc             - same as ^U.
                    390:        Help            - `help` plus return.
                    391:        Ctrl Help       - `help `.
                    392: #\begin{tabular}{|cl|} \hline
1.1.1.3 ! ohara     393: #Key       & Function \\ \hline
1.1       maekawa   394: #Undo      & same as \verb~^L~. \\
                    395: #Home      & same as \verb~^A~. \\
                    396: #Ctrl Home & same as \verb~^E~. \\
                    397: #Esc       & same as \verb~^U~. \\
                    398: #Help      & `{\bf help}' plus return. \\
                    399: #Ctrl Help & `{\bf help }'. \\
                    400: %c l .
1.1.1.3 ! ohara     401: %Key@Function
1.1       maekawa   402: %_
                    403: %Undo@same as ^L.
                    404: %Home@same as ^A.
                    405: %Ctrl Home@same as ^E.
                    406: %Esc@same as ^U.
                    407: %Help@help plus return.
                    408: %Ctrl Help@help .
                    409: %_
                    410: @end table
                    411: 2 Comments
                    412: ?comments
                    413:  Comments are supported as follows: a `#` may appear in most places in a line
                    414:  and `gnuplot` will ignore the rest of the line.  It will not have this effect
                    415:  inside quotes, inside numbers (including complex numbers), inside command
                    416:  substitutions, etc.  In short, it works anywhere it makes sense to work.
                    417: 2 Coordinates
                    418: ?coordinates
                    419:  The commands `set arrow`, `set key`, and `set label` allow you to draw
                    420:  something at an arbitrary position on the graph.  This position is specified
                    421:  by the syntax:
                    422:
                    423:        {<system>} <x>, {<system>} <y> {,{<system>} <z>}
                    424:
                    425:  Each <system> can either be `first`, `second`, `graph` or `screen`.
                    426:
                    427:  `first` places the x, y, or z coordinate in the system defined by the left
                    428:  and bottom axes; `second` places it in the system defined by the second axes
                    429:  (top and right); `graph` specifies the area within the axes---0,0 is bottom
                    430:  left and 1,1 is top right (for splot, 0,0,0 is bottom left of plotting area;
                    431:  use negative z to get to the base---see `set ticslevel`); and `screen`
                    432:  specifies the screen area (the entire area---not just the portion selected by
                    433:  `set size`), with 0,0 at bottom left and 1,1 at top right.
                    434:
                    435:  If the coordinate system for x is not specified, `first` is used.  If the
                    436:  system for y is not specified, the one used for x is adopted.
                    437:
                    438:  If one (or more) axis is timeseries, the appropriate coordinate should
                    439:  be given as a quoted time string according to the `timefmt` format string.
                    440:  See `set xdata` and `set timefmt`.  `gnuplot` will also accept an integer
                    441:  expression, which will be interpreted as seconds from 1 January 2000.
                    442: 2 Environment
                    443: ?environment
                    444:  A number of shell environment variables are understood by `gnuplot`.  None of
                    445:  these are required, but may be useful.
                    446:
                    447:  If GNUTERM is defined, it is used as the name of the terminal type to be
                    448:  used.  This overrides any terminal type sensed by `gnuplot` on start-up, but
                    449:  is itself overridden by the .gnuplot (or equivalent) start-up file (see
                    450:  `start-up`) and, of course, by later explicit changes.
                    451:
                    452:  On Unix, AmigaOS, AtariTOS, MS-DOS and OS/2, GNUHELP may be defined to be the
                    453:  pathname of the HELP file (gnuplot.gih).
                    454:
                    455:  On VMS, the logical name GNUPLOT$HELP should be defined as the name of the
                    456:  help library for `gnuplot`.  The `gnuplot` help can be put inside any system
                    457:  help library, allowing access to help from both within and outside `gnuplot`
                    458:  if desired.
                    459:
                    460:  On Unix, HOME is used as the name of a directory to search for a .gnuplot
                    461:  file if none is found in the current directory.  On AmigaOS, AtariTOS,
                    462:  MS-DOS and OS/2, gnuplot is used.  On VMS, SYS$LOGIN: is used. See `help
                    463:  start-up`.
                    464:
                    465:  On Unix, PAGER is used as an output filter for help messages.
                    466:
                    467:  On Unix, AtariTOS and AmigaOS, SHELL is used for the `shell` command.  On
                    468:  MS-DOS and OS/2, COMSPEC is used for the `shell` command.
                    469:
                    470:  On MS-DOS, if the BGI or Watcom interface is used, PCTRM is used to tell
                    471:  the maximum resolution supported by your monitor by setting it to
                    472:  S<max. horizontal resolution>. E.g. if your monitor's maximum resolution is
                    473:  800x600, then use:
                    474:        set PCTRM=S800
                    475:  If PCTRM is not set, standard VGA is used.
                    476:
                    477:  FIT_SCRIPT may be used to specify a `gnuplot` command to be executed when a
                    478:  fit is interrupted---see `fit`.  FIT_LOG specifies the filename of the
                    479:  logfile maintained by fit.
                    480: 2 Expressions
                    481: ?expressions
                    482:  In general, any mathematical expression accepted by C, FORTRAN, Pascal, or
                    483:  BASIC is valid.  The precedence of these operators is determined by the
                    484:  specifications of the C programming language.  White space (spaces and tabs)
                    485:  is ignored inside expressions.
                    486:
                    487:  Complex constants are expressed as {<real>,<imag>}, where <real> and <imag>
                    488:  must be numerical constants.  For example, {3,2} represents 3 + 2i; {0,1}
                    489:  represents 'i' itself.  The curly braces are explicitly required here.
                    490:
                    491:  Note that gnuplot uses both "real" and "integer" arithmetic, like FORTRAN and
                    492:  C.  Integers are entered as "1", "-10", etc; reals as "1.0", "-10.0", "1e1",
                    493:  3.5e-1, etc.  The most important difference between the two forms is in
                    494:  division: division of integers truncates: 5/2 = 2; division of reals does
                    495:  not: 5.0/2.0 = 2.5.  In mixed expressions, integers are "promoted" to reals
                    496:  before evaluation: 5/2e0 = 2.5.  The result of division of a negative integer
                    497:  by a positive one may vary among compilers.  Try a test like "print -5/2" to
                    498:  determine if your system chooses -2 or -3 as the answer.
                    499:
                    500:  The integer expression "1/0" may be used to generate an "undefined" flag,
                    501:  which causes a point to ignored; the `ternary` operator gives an example.
                    502:
                    503:  The real and imaginary parts of complex expressions are always real, whatever
                    504:  the form in which they are entered: in {3,2} the "3" and "2" are reals, not
                    505:  integers.
                    506: 3 Functions
                    507: ?expressions functions
                    508: ?functions
                    509:  The functions in `gnuplot` are the same as the corresponding functions in
                    510:  the Unix math library, except that all functions accept integer, real, and
                    511:  complex arguments, unless otherwise noted.
                    512:
                    513:  For those functions that accept or return angles that may be given in either
                    514:  degrees or radians (sin(x), cos(x), tan(x), asin(x), acos(x), atan(x),
                    515:  atan2(x) and arg(z)), the unit may be selected by `set angles`, which
                    516:  defaults to radians.
                    517:
                    518: @start table
                    519: #\begin{tabular}{|ccl|} \hline
                    520: #\multicolumn{3}{|c|}{Math library functions} \\ \hline \hline
                    521: #Function & Arguments & Returns \\ \hline
                    522: %c c l .
                    523: %Function@Arguments@Returns
                    524: %_
                    525: 4 abs
                    526: ?expressions functions abs
                    527: ?functions abs
                    528: ?abs
                    529: #abs(x) & any  &  absolute value of $x$, $|x|$; same type \\
                    530: #abs(x) & complex &  length of $x$, $\sqrt{{\mbox{real}(x)^{2} +
                    531: #\mbox{imag}(x)^{2}}}$ \\
                    532: %abs(x)@any@absolute value of $x$, $|x|$; same type
                    533: %abs(x)@complex@length of $x$, $sqrt{roman real (x) sup 2 + roman imag (x) sup 2}$
1.1.1.2   maekawa   534:  The `abs(x)` function returns the absolute value of its argument.  The
                    535:  returned value is of the same type as the argument.
1.1       maekawa   536:
                    537:  For complex arguments, abs(x) is defined as the length of x in the complex
                    538:  plane [i.e.,  sqrt(real(x)**2 + imag(x)**2) ].
                    539: 4 acos
                    540: ?expressions functions acos
                    541: ?functions acos
                    542: ?acos
                    543: #acos(x) & any  & $\cos^{-1} x$ (inverse cosine) \\
                    544: %acos(x)@any@$cos sup -1 x$ (inverse cosine)
1.1.1.2   maekawa   545:  The `acos(x)` function returns the arc cosine (inverse cosine) of its
                    546:  argument.  `acos` returns its argument in radians or degrees, as selected by
                    547:  `set angles`.
1.1       maekawa   548: 4 acosh
                    549: ?expressions functions acosh
                    550: ?functions acosh
                    551: ?acosh
                    552: #acosh(x) & any  & $\cosh^{-1} x$ (inverse hyperbolic cosine) in radians \\
                    553: %acosh(x)@any@$cosh sup -1 x$ (inverse hyperbolic cosine) in radians
1.1.1.2   maekawa   554:  The `acosh(x)` function returns the inverse hyperbolic cosine of its argument
                    555:  in radians.
1.1       maekawa   556: 4 arg
                    557: ?expressions functions arg
                    558: ?functions arg
                    559: ?arg
                    560: #arg(x) & complex & the phase of $x$ \\
                    561: %arg(x)@complex@the phase of $x$
1.1.1.2   maekawa   562:  The `arg(x)` function returns the phase of a complex number in radians or
1.1       maekawa   563:  degrees, as selected by `set angles`.
                    564: 4 asin
                    565: ?expressions functions asin
                    566: ?functions asin
                    567: ?asin
                    568: #asin(x) & any  & $\sin^{-1} x$ (inverse sin) \\
                    569: %asin(x)@any@$sin sup -1 x$ (inverse sin)
1.1.1.2   maekawa   570:  The `asin(x)` function returns the arc sin (inverse sin) of its argument.
1.1       maekawa   571:  `asin` returns its argument in radians or degrees, as selected by `set
                    572:  angles`.
                    573: 4 asinh
                    574: ?expressions functions asinh
                    575: ?functions asinh
                    576: ?asinh
                    577: #asinh(x) & any  & $\sinh^{-1} x$ (inverse hyperbolic sin) in radians \\
                    578: %asinh(x)@any@$sinh sup -1 x$ (inverse hyperbolic sin) in radians
1.1.1.2   maekawa   579:  The `asinh(x)` function returns the inverse hyperbolic sin of its argument in
1.1       maekawa   580:  radians.
                    581: 4 atan
                    582: ?expressions functions atan
                    583: ?functions atan
                    584: ?atan
                    585: #atan(x) & any  & $\tan^{-1} x$ (inverse tangent) \\
                    586: %atan(x)@any@$tan sup -1 x$ (inverse tangent)
1.1.1.2   maekawa   587:  The `atan(x)` function returns the arc tangent (inverse tangent) of its
1.1       maekawa   588:  argument.  `atan` returns its argument in radians or degrees, as selected by
                    589:  `set angles`.
                    590: 4 atan2
                    591: ?expressions functions atan2
                    592: ?functions atan2
                    593: ?atan2
                    594: #atan2(y,x) & int or real & $\tan^{-1} (y/x)$ (inverse tangent) \\
                    595: %atan2(y,x)@int or real@$tan sup -1 (y/x)$ (inverse tangent)
1.1.1.2   maekawa   596:  The `atan2(y,x)` function returns the arc tangent (inverse tangent) of the
                    597:  ratio of the real parts of its arguments.  `atan2` returns its argument in
                    598:  radians or degrees, as selected by `set angles`, in the correct quadrant.
1.1       maekawa   599: 4 atanh
                    600: ?expressions functions atanh
                    601: ?functions atanh
1.1.1.2   maekawa   602: ?atanh
1.1       maekawa   603: #atanh(x) & any  & $\tanh^{-1} x$ (inverse hyperbolic tangent) in radians \\
                    604: %atanh(x)@any@$tanh sup -1 x$ (inverse hyperbolic tangent) in radians
1.1.1.2   maekawa   605:  The `atanh(x)` function returns the inverse hyperbolic tangent of its
                    606:  argument in radians.
1.1       maekawa   607: 4 besj0
                    608: ?expressions functions besj0
                    609: ?functions besj0
                    610: ?besj0
                    611: #besj0(x) & int or real &  $j_{0}$ Bessel function of $x$, in radians \\
                    612: %besj0(x)@int or real@$j sub 0$ Bessel function of $x$, in radians
1.1.1.2   maekawa   613:  The `besj0(x)` function returns the j0th Bessel function of its argument.
1.1       maekawa   614:  `besj0` expects its argument to be in radians.
                    615: 4 besj1
                    616: ?expressions functions besj1
                    617: ?functions besj1
                    618: ?besj1
                    619: #besj1(x) & int or real & $j_{1}$ Bessel function of $x$, in radians \\
                    620: %besj1(x)@int or real@$j sub 1$ Bessel function of $x$, in radians
1.1.1.2   maekawa   621:  The `besj1(x)` function returns the j1st Bessel function of its argument.
1.1       maekawa   622:  `besj1` expects its argument to be in radians.
                    623: 4 besy0
                    624: ?expressions functions besy0
                    625: ?functions besy0
                    626: ?besy0
                    627: #besy0(x) & int or real & $y_{0}$ Bessel function of $x$, in radians \\
                    628: %besy0(x)@int or real@$y sub 0$ Bessel function of $x$, in radians
1.1.1.3 ! ohara     629:  The `besy0(x)` function returns the y0th Bessel function of its argument.
1.1       maekawa   630:  `besy0` expects its argument to be in radians.
                    631: 4 besy1
                    632: ?expressions functions besy1
                    633: ?functions besy1
                    634: ?besy1
                    635: #besy1(x) & int or real & $y_{1}$ Bessel function of $x$, in radians \\
                    636: %besy1(x)@int or real@$y sub 1$ Bessel function of $x$, in radians
1.1.1.2   maekawa   637:  The `besy1(x)` function returns the y1st Bessel function of its argument.
1.1       maekawa   638:  `besy1` expects its argument to be in radians.
                    639: 4 ceil
                    640: ?expressions functions ceil
                    641: ?functions ceil
                    642: ?ceil
                    643: #ceil(x) & any & $\lceil x \rceil$, smallest integer not less than $x$
                    644: #(real part) \\
                    645: %ceil(x)@any@$left ceiling x right ceiling$, smallest integer not less than $x$ (real part)
1.1.1.2   maekawa   646:  The `ceil(x)` function returns the smallest integer that is not less than its
1.1       maekawa   647:  argument.  For complex numbers, `ceil` returns the smallest integer not less
                    648:  than the real part of its argument.
                    649: 4 cos
                    650: ?expressions functions cos
                    651: ?functions cos
                    652: ?cos
                    653: #cos(x) & any & $\cos x$, cosine of $x$ \\
                    654: %cos(x)@radians@$cos~x$, cosine of $x$
1.1.1.2   maekawa   655:  The `cos(x)` function returns the cosine of its argument.  `cos` accepts its
1.1       maekawa   656:  argument in radians or degrees, as selected by `set angles`.
                    657: 4 cosh
                    658: ?expressions functions cosh
                    659: ?functions cosh
                    660: ?cosh
                    661: #cosh(x) & any & $\cosh x$, hyperbolic cosine of $x$ in radians \\
                    662: %cosh(x)@any@$cosh~x$, hyperbolic cosine of $x$ in radians
1.1.1.2   maekawa   663:  The `cosh(x)` function returns the hyperbolic cosine of its argument.  `cosh`
1.1       maekawa   664:  expects its argument to be in radians.
                    665: 4 erf
                    666: ?expressions functions erf
                    667: ?functions erf
                    668: ?erf
                    669: #erf(x) & any & $\mbox{erf}(\mbox{real}(x))$,  error function of real($x$) \\
                    670: %erf(x)@any@$erf ( roman real (x))$, error function of real ($x$)
1.1.1.2   maekawa   671:  The `erf(x)` function returns the error function of the real part of its
1.1       maekawa   672:  argument.  If the argument is a complex value, the imaginary component is
                    673:  ignored.
                    674: 4 erfc
                    675: ?expressions functions erfc
                    676: ?functions erfc
                    677: ?erfc
                    678: #erfc(x) & any & $\mbox{erfc}(\mbox{real}(x))$,  1.0 - error function of real($x$) \\
                    679: %erfc(x)@any@$erfc ( roman real (x))$, 1.0 - error function of real ($x$)
1.1.1.2   maekawa   680:  The `erfc(x)` function returns 1.0 - the error function of the real part of
                    681:  its argument.  If the argument is a complex value, the imaginary component is
1.1       maekawa   682:  ignored.
                    683: 4 exp
                    684: ?expressions functions exp
                    685: ?functions exp
                    686: ?exp
                    687: #exp(x) & any & $e^{x}$,  exponential function of $x$ \\
                    688: %exp(x)@any@$e sup x$, exponential function of $x$
1.1.1.2   maekawa   689:  The `exp(x)` function returns the exponential function of its argument (`e`
1.1       maekawa   690:  raised to the power of its argument).  On some implementations (notably
                    691:  suns), exp(-x) returns undefined for very large x.  A user-defined function
                    692:  like safe(x) = x<-100 ? 0 : exp(x) might prove useful in these cases.
                    693: 4 floor
                    694: ?expressions functions floor
                    695: ?functions floor
                    696: ?floor
                    697: #floor(x) & any & $\lfloor x \rfloor$,  largest integer not greater
                    698: #than $x$ (real part) \\
                    699: %floor(x)@any@$left floor x right floor$, largest integer not greater than $x$ (real part)
1.1.1.2   maekawa   700:  The `floor(x)` function returns the largest integer not greater than its
1.1       maekawa   701:  argument.  For complex numbers, `floor` returns the largest integer not
                    702:  greater than the real part of its argument.
                    703: 4 gamma
                    704: ?expressions functions gamma
                    705: ?functions gamma
                    706: ?gamma
                    707: #gamma(x) & any & $\mbox{gamma}(\mbox{real}(x))$,  gamma function of real($x$) \\
                    708: %gamma(x)@any@$GAMMA ( roman real (x))$, gamma function of real ($x$)
1.1.1.2   maekawa   709:  The `gamma(x)` function returns the gamma function of the real part of its
1.1       maekawa   710:  argument.  For integer n, gamma(n+1) = n!.  If the argument is a complex
                    711:  value, the imaginary component is ignored.
                    712: 4 ibeta
                    713: ?expressions functions ibeta
                    714: ?functions ibeta
                    715: ?ibeta
                    716: #ibeta(p,q,x) & any & $\mbox{ibeta}(\mbox{real}(p,q,x))$,  ibeta function of real($p$,$q$,$x$) \\
                    717: %ibeta(p,q,x)@any@$ibeta ( roman real (p,q,x))$, ibeta function of real ($p$,$q$,$x$)
1.1.1.2   maekawa   718:  The `ibeta(p,q,x)` function returns the incomplete beta function of the real
                    719:  parts of its arguments. p, q > 0 and x in [0:1].  If the arguments are
                    720:  complex, the imaginary components are ignored.
1.1       maekawa   721: 4 inverf
                    722: ?expressions functions inverf
                    723: ?functions inverf
                    724: ?inverf
                    725: #inverf(x) & any &  inverse error function of real($x$)  \\
                    726: %inverf(x)@any@inverse error function real($x$)
1.1.1.2   maekawa   727:  The `inverf(x)` function returns the inverse error function of the real part
1.1       maekawa   728:  of its argument.
                    729: 4 igamma
                    730: ?expressions functions igamma
                    731: ?functions igamma
                    732: ?igamma
                    733: #igamma(a,x) & any & $\mbox{igamma}(\mbox{real}(a,x))$,  igamma function of real($a$,$x$) \\
                    734: %igamma(a,x)@any@$igamma ( roman real (a,x))$, igamma function of real ($a$,$x$)
1.1.1.2   maekawa   735:  The `igamma(a,x)` function returns the incomplete gamma function of the real
1.1       maekawa   736:  parts of its arguments.  a > 0 and x >= 0.  If the arguments are complex,
                    737:  the imaginary components are ignored.
                    738: 4 imag
                    739: ?expressions functions imag
                    740: ?functions imag
                    741: ?imag
                    742: #imag(x) & complex &  imaginary part of $x$ as a real number \\
                    743: %imag(x)@complex@imaginary part of $x$ as a real number
1.1.1.2   maekawa   744:  The `imag(x)` function returns the imaginary part of its argument as a real
1.1       maekawa   745:  number.
                    746: 4 invnorm
                    747: ?expressions functions invnorm
                    748: ?functions invnorm
                    749: ?invnorm
                    750: #invnorm(x) & any &  inverse normal distribution function of real($x$)  \\
                    751: %invnorm(x)@any@inverse normal distribution function real($x$)
1.1.1.2   maekawa   752:  The `invnorm(x)` function returns the inverse normal distribution function of
1.1       maekawa   753:  the real part of its argument.
                    754: 4 int
                    755: ?expressions functions int
                    756: ?functions int
                    757: ?int
                    758: #int(x) & real &  integer part of $x$, truncated toward zero \\
                    759: %int(x)@real@integer part of $x$, truncated toward zero
1.1.1.2   maekawa   760:  The `int(x)` function returns the integer part of its argument, truncated
1.1       maekawa   761:  toward zero.
                    762: 4 lgamma
                    763: ?expressions functions lgamma
                    764: ?functions lgamma
                    765: ?lgamma
                    766: #lgamma(x) & any & $\mbox{lgamma}(\mbox{real}(x))$,  lgamma function of real($x$) \\
                    767: %lgamma(x)@any@$lgamma ( roman real (x))$, lgamma function of real ($x$)
1.1.1.2   maekawa   768:  The `lgamma(x)` function returns the natural logarithm of the gamma function
1.1       maekawa   769:  of the real part of its argument.  If the argument is a complex value, the
                    770:  imaginary component is ignored.
                    771: 4 log
                    772: ?expressions functions log
                    773: ?functions log
                    774: ?log
                    775: #log(x) & any & $\log_{e} x$,  natural logarithm (base $e$) of $x$ \\
                    776: %log(x)@any@$ln~x$, natural logarithm (base $e$) of $x$
1.1.1.2   maekawa   777:  The `log(x)` function returns the natural logarithm (base `e`) of its
                    778:  argument.
1.1       maekawa   779: 4 log10
                    780: ?expressions functions log10
                    781: ?functions log10
                    782: ?log10
                    783: #log10(x) & any & $\log_{10} x$,  logarithm (base $10$) of $x$ \\
                    784: %log10(x)@any@${log sub 10}~x$, logarithm (base $10$) of $x$
1.1.1.2   maekawa   785:  The `log10(x)` function returns the logarithm (base 10) of its argument.
1.1       maekawa   786: 4 norm
                    787: ?expressions functions norm
                    788: ?functions norm
                    789: ?norm
                    790: #norm(x) & any & normal distribution (Gaussian) function of real($x$) \\
                    791: %norm(x)@any@$norm(x)$, normal distribution function of real($x$)
1.1.1.2   maekawa   792:  The `norm(x)` function returns the normal distribution function (or Gaussian)
1.1       maekawa   793:  of the real part of its argument.
                    794: 4 rand
                    795: ?expressions functions rand
                    796: ?functions rand
                    797: ?rand
                    798: #rand(x) & any & $\mbox{rand}(\mbox{real}(x))$,  pseudo random number generator \\
                    799: %rand(x)@any@$rand ( roman real (x))$, pseudo random number generator
1.1.1.2   maekawa   800:  The `rand(x)` function returns a pseudo random number in the interval [0:1]
1.1       maekawa   801:  using the real part of its argument as a seed.  If seed < 0, the sequence
                    802:  is (re)initialized.  If the argument is a complex value, the imaginary
                    803:  component is ignored.
                    804: 4 real
                    805: ?expressions functions real
                    806: ?functions real
                    807: ?real
                    808: #real(x) & any &  real part of $x$ \\
                    809: %real(x)@any@real part of $x$
1.1.1.2   maekawa   810:  The `real(x)` function returns the real part of its argument.
1.1       maekawa   811: 4 sgn
                    812: ?expressions functions sgn
                    813: ?functions sgn
                    814: ?sgn
                    815: #sgn(x) & any & 1 if $x>0$, -1 if $x<0$, 0 if $x=0$. imag($x$) ignored \\
                    816: %sgn(x)@any@1 if $x > 0$, -1 if $x < 0$, 0 if $x = 0$. $roman imag (x)$ ignored
1.1.1.2   maekawa   817:  The `sgn(x)` function returns 1 if its argument is positive, -1 if its
                    818:  argument is negative, and 0 if its argument is 0.  If the argument is a
                    819:  complex value, the imaginary component is ignored.
1.1       maekawa   820: 4 sin
                    821: ?expressions functions sin
                    822: ?functions sin
                    823: ?sin
                    824: #sin(x) & any & $\sin x$, sine of $x$ \\
                    825: %sin(x)@any@$sin~x$, sine of $x$
1.1.1.2   maekawa   826:  The `sin(x)` function returns the sine of its argument.  `sin` expects its
1.1       maekawa   827:  argument to be in radians or degrees, as selected by `set angles`.
                    828: 4 sinh
                    829: ?expressions functions sinh
                    830: ?functions sinh
                    831: ?sinh
1.1.1.3 ! ohara     832: #sinh(x) & any & $\sinh x$, hyperbolic sine of $x$ in radians \\
        !           833: %sinh(x)@any@$sinh~x$, hyperbolic sine of $x$ in radians
1.1.1.2   maekawa   834:  The `sinh(x)` function returns the hyperbolic sine of its argument.  `sinh`
1.1       maekawa   835:  expects its argument to be in radians.
                    836: 4 sqrt
                    837: ?expressions functions sqrt
                    838: ?functions sqrt
                    839: ?sqrt
                    840: #sqrt(x) & any & $\sqrt{x}$,  square root of $x$ \\
                    841: %sqrt(x)@any@$sqrt x $, square root of $x$
1.1.1.2   maekawa   842:  The `sqrt(x)` function returns the square root of its argument.
1.1       maekawa   843: 4 tan
                    844: ?expressions functions tan
                    845: ?functions tan
                    846: ?tan
                    847: #tan(x) & any & $\tan x$,  tangent of $x$ \\
                    848: %tan(x)@any@$tan~x$, tangent of $x$
1.1.1.2   maekawa   849:  The `tan(x)` function returns the tangent of its argument.  `tan` expects
1.1       maekawa   850:  its argument to be in radians or degrees, as selected by `set angles`.
                    851: 4 tanh
                    852: ?expressions functions tanh
                    853: ?functions tanh
                    854: ?tanh
                    855: #tanh(x) & any & $\tanh x$, hyperbolic tangent of $x$ in radians\\
                    856: %tanh(x)@any@$tanh~x$, hyperbolic tangent of $x$ in radians
1.1.1.2   maekawa   857:  The `tanh(x)` function returns the hyperbolic tangent of its argument.  `tanh`
1.1       maekawa   858:  expects its argument to be in radians.
                    859: @end table
                    860:
                    861:  A few additional functions are also available.
                    862:
                    863: @start table
                    864: #\begin{tabular}{|ccl|} \hline
                    865: #\multicolumn{3}{|c|}{other {\bf gnuplot} functions} \\ \hline \hline
                    866: #Function & Arguments & Returns \\ \hline
                    867: %c c l .
                    868: %Function@Arguments@Returns
                    869: %_
                    870: 4 column
                    871: ?expressions functions column
                    872: ?functions column
                    873: ?column
                    874: #column(x) & int & column $x$ during datafile manipulation. \\
                    875: %column(x)@int@ column $x$ during datafile manipulation.
                    876:  `column(x)` may be used only in expressions as part of `using` manipulations
                    877:  to fits or datafile plots.  See `plot datafile using`.
                    878: 4 tm_hour
                    879: ?expressions tm_hour
                    880: ?functions tm_hour
                    881: #tm\_hour(x) & int & the hour \\
                    882: %tm_hour(x)@int@the hour
                    883:  The `tm_hour` function interprets its argument as a time, in seconds from
                    884:  1 Jan 2000.  It returns the hour (an integer in the range 0--23) as a real.
                    885: 4 tm_mday
                    886: ?expressions tm_mday
                    887: ?functions tm_mday
                    888: #tm\_mday(x) & int & the day of the month \\
                    889: %tm_mday(x)@int@the day of the month
                    890:  The `tm_mday` function interprets its argument as a time, in seconds from
                    891:  1 Jan 2000.  It returns the day of the month (an integer in the range 1--31)
                    892:  as a real.
                    893: 4 tm_min
                    894: ?expressions tm_min
                    895: ?functions tm_min
                    896: #tm\_min(x) & int & the minute \\
                    897: %tm_min(x)@int@the minute
                    898:  The `tm_min` function interprets its argument as a time, in seconds from
                    899:  1 Jan 2000.  It returns the minute (an integer in the range 0--59) as a real.
                    900: 4 tm_mon
                    901: ?expressions tm_mon
                    902: ?functions tm_mon
                    903: #tm\_mon(x) & int & the month \\
                    904: %tm_mon(x)@int@the month
                    905:  The `tm_mon` function interprets its argument as a time, in seconds from
                    906:  1 Jan 2000.  It returns the month (an integer in the range 1--12) as a real.
                    907: 4 tm_sec
                    908: ?expressions tm_sec
                    909: ?functions tm_sec
                    910: #tm\_sec(x) & int & the second \\
                    911: %tm_sec(x)@int@the second
                    912:  The `tm_sec` function interprets its argument as a time, in seconds from
                    913:  1 Jan 2000.  It returns the second (an integer in the range 0--59) as a real.
                    914: 4 tm_wday
                    915: ?expressions tm_wday
                    916: ?functions tm_wday
                    917: #tm\_wday(x) & int & the day of the week \\
                    918: %tm_wday(x)@int@the day of the week
                    919:  The `tm_wday` function interprets its argument as a time, in seconds from
                    920:  1 Jan 2000.  It returns the day of the week (an integer in the range 1--7) as
                    921:  a real.
                    922: 4 tm_yday
                    923: ?expressions tm_yday
                    924: ?functions tm_yday
                    925: #tm\_yday(x) & int & the day of the year \\
                    926: %tm_yday(x)@int@the day of the year
                    927:  The `tm_yday` function interprets its argument as a time, in seconds from
                    928:  1 Jan 2000.  It returns the day of the year (an integer in the range 1--366)
                    929:  as a real.
                    930: 4 tm_year
                    931: ?expressions tm_year
                    932: ?functions tm_year
                    933: #tm\_year(x) & int & the year \\
                    934: %tm_year(x)@int@the year
                    935:  The `tm_year` function interprets its argument as a time, in seconds from
                    936:  1 Jan 2000.  It returns the year (an integer) as a real.
                    937: 4 valid
                    938: ?expressions functions valid
                    939: ?functions valid
                    940: ?valid
                    941: #valid(x) & int & test validity of $\mbox{column}(x)$ during datafile manip.\\
                    942: %valid(x)@int@ test validity of column($x$) during datafile manip.
                    943:  `valid(x)` may be used only in expressions as part of `using` manipulations
                    944:  to fits or datafile plots.  See `plot datafile using`.
                    945: @end table
1.1.1.2   maekawa   946: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/airfoil.html">Use of functions and complex variables for airfoils </a>
1.1       maekawa   947: 3 Operators
                    948: ?expressions operators
                    949: ?operators
                    950:  The operators in `gnuplot` are the same as the corresponding operators in the
                    951:  C programming language, except that all operators accept integer, real, and
                    952:  complex arguments, unless otherwise noted.  The ** operator (exponentiation)
                    953:  is supported, as in FORTRAN.
                    954:
                    955:  Parentheses may be used to change order of evaluation.
                    956: 4 Unary
                    957: ?expressions operators unary
                    958: ?operators unary
                    959: ?unary
                    960:  The following is a list of all the unary operators and their usages:
                    961:
                    962: @start table - first is interactive cleartext form
                    963:      Symbol      Example    Explanation
                    964:        -           -a          unary minus
                    965:        +           +a          unary plus (no-operation)
                    966:        ~           ~a        * one's complement
                    967:        !           !a        * logical negation
                    968:        !           a!        * factorial
                    969:        $           $3        * call arg/column during `using` manipulation
                    970: #\begin{tabular}{|ccl|} \hline
                    971: #\multicolumn{3}{|c|}{Unary Operators}\\ \hline \hline
                    972: #Symbol & Example & Explanation \\ \hline
                    973: #\verb@-@ & \verb@-a@ & unary minus \\
                    974: #\verb@+@ & \verb@+a@ & unary plus (no-operation) \\
                    975: #\verb@~@ & \verb@~a@ & * one's complement \\
                    976: #\verb@!@ & \verb@!a@ & * logical negation \\
                    977: #\verb@!@ & \verb@a!@ & * factorial \\
                    978: #\verb@$@ & \verb@$3@ & * call arg/column during `using` manipulation \\
                    979: C ugly hack: doc2ms uses $ as delimiter for eqn's so it doesn't seem to
                    980: C be able to print them. So we have to typeset this table without using
                    981: C eqn (at least that's the only solution I found, without any real docs
                    982: C on *roff and eqn
                    983: C First, terminate the table doc2ms.c already started:
                    984: %.TE
                    985: C ... then turn off eqn delimiters:
                    986: %.EQ
                    987: %delim off
                    988: %.EN
                    989: C ... and restart the table:
                    990: %.TS
                    991: %center box tab (@) ;
                    992: %c c l .
                    993: %Symbol@Example@Explanation
                    994: %_
                    995: %-@-a@unary minus
                    996: %+@+a@unary plus (no-operation)
                    997: %~@~a@* one's complement
                    998: %!@!a@* logical negation
                    999: %!@a!@* factorial
                   1000: %$@$3@* call arg/column during `using` manipulation
                   1001: %_
                   1002: @end table
                   1003:  (*) Starred explanations indicate that the operator requires an integer
                   1004:  argument.
                   1005:
                   1006:  Operator precedence is the same as in Fortran and C.  As in those languages,
                   1007:  parentheses may be used to change the order of operation.  Thus -2**2 = -4,
                   1008:  but (-2)**2 = 4.
                   1009:
                   1010:  The factorial operator returns a real number to allow a greater range.
                   1011: 4 Binary
                   1012: ?expressions operators binary
                   1013: ?operators binary
                   1014: ?binary
                   1015:  The following is a list of all the binary operators and their usages:
                   1016:
                   1017: @start table - first is interactive cleartext form
                   1018:      Symbol       Example      Explanation
                   1019:        **          a**b          exponentiation
                   1020:        *           a*b           multiplication
                   1021:        /           a/b           division
                   1022:        %           a%b         * modulo
                   1023:        +           a+b           addition
                   1024:        -           a-b           subtraction
                   1025:        ==          a==b          equality
                   1026:        !=          a!=b          inequality
                   1027:        <           a<b           less than
                   1028:        <=          a<=b          less than or equal to
                   1029:        >           a>b           greater than
                   1030:        >=          a>=b          greater than or equal to
                   1031:        &           a&b         * bitwise AND
                   1032:        ^           a^b         * bitwise exclusive OR
                   1033:        |           a|b         * bitwise inclusive OR
                   1034:        &&          a&&b        * logical AND
                   1035:        ||          a||b        * logical OR
                   1036: #\begin{tabular}{|ccl|} \hline
                   1037: #\multicolumn{3}{|c|}{Binary Operators} \\ \hline \hline
                   1038: #Symbol & Example & Explanation \\ \hline
                   1039: #\verb~**~ & \verb~a**b~ & exponentiation\\
                   1040: #\verb~*~ & \verb~a*b~ & multiplication\\
                   1041: #\verb~/~ & \verb~a/b~ & division\\
                   1042: #\verb~%~ & \verb~a%b~ & * modulo\\
                   1043: #\verb~+~ & \verb~a+b~ & addition\\
                   1044: #\verb~-~ & \verb~a-b~ & subtraction\\
                   1045: #\verb~==~ & \verb~a==b~ & equality\\
                   1046: #\verb~!=~ & \verb~a!=b~ & inequality\\
                   1047: #\verb~<~ & \verb~a<b~ & less than\\
                   1048: #\verb~<=~ & \verb~a<=b~ & less than or equal to\\
                   1049: #\verb~>~ & \verb~a>b~ & greater than\\
                   1050: #\verb~>=~ & \verb~a>=b~ & greater than or equal to\\
                   1051: #\verb~&~ & \verb~a&b~ & * bitwise AND\\
                   1052: #\verb~^~ & \verb~a^b~ & * bitwise exclusive OR\\
                   1053: #\verb~|~ & \verb~a|b~ & * bitwise inclusive OR\\
                   1054: #\verb~&&~ & \verb~a&&b~ & * logical AND\\
                   1055: #\verb~||~ & \verb~a||b~ & * logical OR\\
                   1056: %c c l .
                   1057: %Symbol@Example@Explanation
                   1058: %_
                   1059: %**@a**b@exponentiation
                   1060: %*@a*b@multiplication
                   1061: %/@a/b@division
                   1062: %%@a%b@* modulo
                   1063: %+@a+b@addition
                   1064: %-@a-b@subtraction
                   1065: %==@a==b@equality
                   1066: %!=@a!=b@inequality
                   1067: %<@a<b@less than
                   1068: %<=@a<=b@less than or equal to
                   1069: %>@a>b@greater than
                   1070: %>=@a>=b@greater than or equal to
                   1071: %&@a&b@* bitwise AND
                   1072: %^@a^b@* bitwise exclusive OR
                   1073: %|@a|b@* bitwise inclusive OR
                   1074: %&&@a&&b@* logical AND
                   1075: %||@a||b@* logical OR
                   1076:
                   1077: @end table
                   1078:  (*) Starred explanations indicate that the operator requires integer
                   1079:  arguments.
                   1080:
                   1081:  Logical AND (&&) and OR (||) short-circuit the way they do in C.  That is,
                   1082:  the second `&&` operand is not evaluated if the first is false; the second
                   1083:  `||` operand is not evaluated if the first is true.
                   1084: 4 Ternary
                   1085: ?expressions operators ternary
                   1086: ?operators ternary
                   1087: ?ternary
                   1088:  There is a single ternary operator:
                   1089:
                   1090: @start table - first is interactive cleartext form
                   1091:      Symbol       Example      Explanation
                   1092:        ?:          a?b:c     ternary operation
                   1093: #\begin{tabular}{|ccl|} \hline
                   1094: #\multicolumn{3}{|c|}{Ternary Operator} \\ \hline \hline
                   1095: #Symbol & Example & Explanation \\ \hline
                   1096: #\verb~?:~ & \verb~a?b:c~ & ternary operation\\
                   1097: %c c l .
                   1098: %Symbol@Example@Explanation
                   1099: %_
                   1100: %?:@a?b:c@* ternary operation
                   1101:
                   1102: @end table
                   1103:  The ternary operator behaves as it does in C.  The first argument (a), which
                   1104:  must be an integer, is evaluated.  If it is true (non-zero), the second
                   1105:  argument (b) is evaluated and returned; otherwise the third argument (c) is
                   1106:  evaluated and returned.
                   1107:
                   1108:  The ternary operator is very useful both in constructing piecewise functions
                   1109:  and in plotting points only when certain conditions are met.
                   1110:
                   1111:  Examples:
                   1112:
                   1113:  Plot a function that is to equal sin(x) for 0 <= x < 1, 1/x for 1 <= x < 2,
                   1114:  and undefined elsewhere:
                   1115:        f(x) = 0<=x && x<1 ? sin(x) : 1<=x && x<2 ? 1/x : 1/0
                   1116:        plot f(x)
                   1117: ^ <img align=bottom src="http://www.nas.nasa.gov/~woo/gnuplot/doc/ternary.gif" alt="[ternary.gif]" width=640 height=480>
                   1118:  Note that `gnuplot` quietly ignores undefined values, so the final branch of
                   1119:  the function (1/0) will produce no plottable points.  Note also that f(x)
                   1120:  will be plotted as a continuous function across the discontinuity if a line
                   1121:  style is used.  To plot it discontinuously, create separate functions for the
                   1122:  two pieces.  (Parametric functions are also useful for this purpose.)
                   1123:
                   1124:  For data in a file, plot the average of the data in columns 2 and 3 against
                   1125:  the datum in column 1, but only if the datum in column 4 is non-negative:
                   1126:
                   1127:        plot 'file' using 1:( $4<0 ? 1/0 : ($2+$3)/2 )
                   1128:
                   1129:  Please see `plot data-file using` for an explanation of the `using` syntax.
                   1130: 3 User-defined
                   1131: ?expressions user-defined
                   1132: ?user-defined
                   1133: ?variables
                   1134:  New user-defined variables and functions of one through five variables may
                   1135:  be declared and used anywhere, including on the `plot` command itself.
                   1136:
                   1137:  User-defined function syntax:
                   1138:        <func-name>( <dummy1> {,<dummy2>} ... {,<dummy5>} ) = <expression>
                   1139:
                   1140:  where <expression> is defined in terms of <dummy1> through <dummy5>.
                   1141:
                   1142:  User-defined variable syntax:
                   1143:        <variable-name> = <constant-expression>
                   1144:
                   1145:  Examples:
                   1146:        w = 2
                   1147:        q = floor(tan(pi/2 - 0.1))
                   1148:        f(x) = sin(w*x)
                   1149:        sinc(x) = sin(pi*x)/(pi*x)
                   1150:        delta(t) = (t == 0)
                   1151:        ramp(t) = (t > 0) ? t : 0
                   1152:        min(a,b) = (a < b) ? a : b
                   1153:        comb(n,k) = n!/(k!*(n-k)!)
                   1154:        len3d(x,y,z) = sqrt(x*x+y*y+z*z)
                   1155:        plot f(x) = sin(x*a), a = 0.2, f(x), a = 0.4, f(x)
                   1156:
                   1157: ^ <img align=bottom src="http://www.nas.nasa.gov/~woo/gnuplot/doc/userdefined.gif" alt="[userdefined.gif]" width=640 height=480>
                   1158:  Note that the variable `pi` is already defined.  But it is in no way magic;
                   1159:  you may redefine it to be whatever you like.
                   1160:
                   1161:  Valid names are the same as in most programming languages: they must begin
                   1162:  with a letter, but subsequent characters may be letters, digits, "$", or "_".
                   1163:  Note, however, that the `fit` mechanism uses several variables with names
                   1164:  that begin "FIT_".  It is safest to avoid using such names.  "FIT_LIMIT",
                   1165:  however, is one that you may wish to redefine. See the documentation
                   1166:  on `fit` for details.
                   1167:
                   1168:
                   1169:  See `show functions`, `show variables`, and `fit`.
                   1170: 2 Glossary
                   1171: ?glossary
                   1172:  Throughout this document an attempt has been made to maintain consistency of
                   1173:  nomenclature.  This cannot be wholly successful because as `gnuplot` has
                   1174:  evolved over time, certain command and keyword names have been adopted that
                   1175:  preclude such perfection.  This section contains explanations of the way
                   1176:  some of these terms are used.
                   1177:
                   1178:  A "page" or "screen" is the entire area addressable by `gnuplot`.  On a
                   1179:  monitor, it is the full screen; on a plotter, it is a single sheet of paper.
                   1180:
                   1181:  A screen may contain one or more "plots".  A plot is defined by an abscissa
                   1182:  and an ordinate, although these need not actually appear on it, as well as
                   1183:  the margins and any text written therein.
                   1184:
                   1185:  A plot contains one "graph".  A graph is defined by an abscissa and an
                   1186:  ordinate, although these need not actually appear on it.
                   1187:
                   1188:  A graph may contain one or more "lines".  A line is a single function or
                   1189:  data set.  "Line" is also a plotting style.  The word will also be used in
                   1190:  sense "a line of text".  Presumably the context will remove any ambiguity.
                   1191:
                   1192:  The lines on a graph may have individual names.  These may be listed
                   1193:  together with a sample of the plotting style used to represent them in
                   1194:  the "key", sometimes also called the "legend".
                   1195:
                   1196:  The word "title" occurs with multiple meanings in `gnuplot`.  In this
                   1197:  document, it will always be preceded by the adjective "plot", "line", or
                   1198:  "key" to differentiate among them.
                   1199:
                   1200:  A graph may have up to four labelled axes.  Various commands have the name of
                   1201:  an axis built into their names, such as `set xlabel`.  Other commands have
                   1202:  one or more axis names as options, such as `set logscale xy`.  The names of
                   1203:  the four axes for these usages are "x" for the axis along the bottom border
                   1204:  of the plot, "y" for the left border, "x2" for the top border, and "y2" for
                   1205:  the right border.  "z" also occurs in commands used with 3-d plotting.
                   1206:
                   1207:  When discussing data files, the term "record" will be resurrected and used
                   1208:  to denote a single line of text in the file, that is, the characters between
                   1209:  newline or end-of-record characters.  A "point" is the datum extracted from
                   1210:  a single record.  A "datablock" is a set of points from consecutive records,
                   1211:  delimited by blank records.  A line, when referred to in the context of a
                   1212:  data file, is a subset of a datablock.
                   1213: 2 Plotting
                   1214: ?plotting
                   1215:  There are three `gnuplot` commands which actually create a plot: `plot`,
                   1216:  `splot` and `replot`.  `plot` generates 2-d plots, `splot` generates 3-d
                   1217:  plots (actually 2-d projections, of course), and `replot` appends its
                   1218:  arguments to the previous `plot` or `splot` and executes the modified
                   1219:  command.
                   1220:
                   1221:  Much of the general information about plotting can be found in the discussion
                   1222:  of `plot`; information specific to 3-d can be found in the `splot` section.
                   1223:
                   1224:  `plot` operates in either rectangular or polar coordinates -- see `set polar`
                   1225:  for details of the latter.  `splot` operates only in rectangular coordinates,
                   1226:  but the `set mapping` command allows for a few other coordinate systems to be
                   1227:  treated.  In addition, the `using` option allows both `plot` and `splot` to
                   1228:  treat almost any coordinate system you'd care to define.
                   1229:
                   1230:  `splot` can plot surfaces and contours in addition to points and/or lines.
                   1231:  In addition to `splot`, see `set isosamples` for information about defining
                   1232:  the grid for a 3-d function;  `splot datafile` for information about the
                   1233:  requisite file structure for 3-d data values; and `set contour` and `set
                   1234:  cntrparam` for information about contours.
                   1235: 2 Start-up
                   1236: ?startup
                   1237: ?start
                   1238: ?.gnuplot
                   1239:  When `gnuplot` is run, it looks for an initialization file to load.  This
                   1240:  file is called `.gnuplot` on Unix and AmigaOS systems, and `GNUPLOT.INI` on
                   1241:  other systems.  If this file is not found in the current directory, the
                   1242:  program will look for it in the home directory (under AmigaOS,
                   1243:  Atari(single)TOS, MS-DOS and OS/2, the environment variable `gnuplot` should
                   1244:  contain the name of this directory).  Note: if NOCWDRC is defined during the
                   1245:  installation, `gnuplot` will not read from the current directory.
                   1246:
                   1247:  If the initialization file is found, `gnuplot` executes the commands in it.
                   1248:  These may be any legal `gnuplot` commands, but typically they are limited to
                   1249:  setting the terminal and defining frequently-used functions or variables.
                   1250: 2 Substitution
                   1251: ?substitution
                   1252:  Command-line substitution is specified by a system command enclosed in
                   1253:  backquotes.  This command is spawned and the output it produces replaces
                   1254:  the name of the command (and backquotes) on the command line.  Some
                   1255:  implementations also support pipes;  see `plot data-file special-filenames`.
                   1256:
                   1257:  Newlines in the output produced by the spawned command are replaced with
                   1258:  blanks.
                   1259:
                   1260:  Command-line substitution can be used anywhere on the `gnuplot` command
1.1.1.3 ! ohara    1261:  line, except inside strings delimited by single quotes.
1.1       maekawa  1262:
                   1263:  Example:
                   1264:
                   1265:  This will run the program `leastsq` and replace `leastsq` (including
                   1266:  backquotes) on the command line with its output:
                   1267:        f(x) = `leastsq`
                   1268:
                   1269:  or, in VMS
                   1270:        f(x) = `run leastsq`
1.1.1.3 ! ohara    1271:
        !          1272:  These will generate labels with the current time and userid:
        !          1273:        set label "generated on `date +%Y-%m-%d`by `whoami`" at 1,1
        !          1274:        set timestamp "generated on %Y-%m-%d by `whoami`"
        !          1275:
1.1       maekawa  1276: 2 Syntax
                   1277: ?syntax
                   1278: ?specify
                   1279: ?punctuation
                   1280:  The general rules of syntax and punctuation in `gnuplot` are that keywords
                   1281:  and options are order-dependent.  Options and any accompanying parameters are
                   1282:  separated by spaces whereas lists and coordinates are separated by commas.
                   1283:  Ranges are separated by colons and enclosed in brackets [], text and file
                   1284:  names are enclosed in quotes, and a few miscellaneous things are enclosed
                   1285:  in parentheses.  Braces {} are used for a few special purposes.
                   1286:
                   1287:  Commas are used to separate coordinates on the `set` commands `arrow`,
                   1288:  `key`, and `label`; the list of variables being fitted (the list after the
                   1289:  `via` keyword on the `fit` command); lists of discrete contours or the loop
                   1290:  parameters which specify them on the `set cntrparam` command; the arguments
                   1291:  of the `set` commands `dgrid3d`, `dummy`, `isosamples`, `offsets`, `origin`,
                   1292:  `samples`, `size`, `time`, and `view`; lists of tics or the loop parameters
                   1293:  which specify them; the offsets for titles and axis labels; parametric
                   1294:  functions to be used to calculate the x, y, and z coordinates on the `plot`,
                   1295:  `replot` and `splot` commands; and the complete sets of keywords specifying
                   1296:  individual plots (data sets or functions) on the `plot`, `replot` and `splot`
                   1297:  commands.
                   1298:
                   1299:  Parentheses are used to delimit sets of explicit tics (as opposed to loop
                   1300:  parameters) and to indicate computations in the `using` filter of the `fit`,
                   1301:  `plot`, `replot` and `splot` commands.
                   1302:
                   1303:  (Parentheses and commas are also used as usual in function notation.)
                   1304:
                   1305:  Brackets are used to delimit ranges, whether they are given on `set`, `plot`
                   1306:  or `splot` commands.
                   1307:
                   1308:  Colons are used to separate extrema in `range` specifications (whether they
                   1309:  are given on `set`, `plot` or `splot` commands) and to separate entries in
                   1310:  the `using` filter of the `plot`, `replot`, `splot` and `fit` commands.
                   1311:
                   1312:  Semicolons are used to separate commands given on a single command line.
                   1313:
                   1314:  Braces are used in text to be specially processed by some terminals, like
                   1315:  `postscript`.  They are also used to denote complex numbers: {3,2} = 3 + 2i.
                   1316:
                   1317:  Text may be enclosed in single- or double-quotes.  Backslash processing of
                   1318:  sequences like \n (newline) and \345 (octal character code) is performed for
                   1319:  double-quoted strings, but not for single-quoted strings.
                   1320:
                   1321:  The justification is the same for each line of a multi-line string.  Thus the
                   1322:  center-justified string
                   1323:        "This is the first line of text.\nThis is the second line."
                   1324:  will produce
                   1325:                         This is the first line of text.
                   1326:                            This is the second line.
                   1327:  but
                   1328:        'This is the first line of text.\nThis is the second line.'
                   1329:  will produce
                   1330:            This is the first line of text.\nThis is the second line.
                   1331:
                   1332:  Filenames may be entered with either single- or double-quotes.  In this
                   1333:  manual the command examples generally single-quote filenames and double-quote
                   1334:  other string tokens for clarity.
                   1335:
                   1336:  At present you should not embed \n inside {} when using the enhanced option
                   1337:  of the postscript terminal.
                   1338:
                   1339:  The EEPIC, Imagen, Uniplex, LaTeX, and TPIC drivers allow a newline to be
                   1340:  specified by \\ in a single-quoted string or \\\\ in a double-quoted string.
                   1341:
                   1342:  Back-quotes are used to enclose system commands for substitution.
                   1343: 2 Time/Date data
                   1344: ?time/date
                   1345:  `gnuplot` supports the use of time and/or date information as input data.
                   1346:  This feature is activated by the commands `set xdata time`, `set ydata time`,
                   1347:  etc.
                   1348:
                   1349:  Internally all times and dates are converted to the number of seconds from
                   1350:  the year 2000.  The command `set timefmt` defines the format for all inputs:
                   1351:  data files, ranges, tics, label positions---in short, anything that accepts a
                   1352:  data value must receive it in this format.  Since only one input format can
                   1353:  be in force at a given time, all time/date quantities being input at the same
                   1354:  time must be presented in the same format.  Thus if both x and y data in a
                   1355:  file are time/date, they must be in the same format.
                   1356:
                   1357:  The conversion to and from seconds assumes Universal Time (which is the same
                   1358:  as Greenwich Standard Time).  There is no provision for changing the time
                   1359:  zone or for daylight savings.  If all your data refer to the same time zone
                   1360:  (and are all either daylight or standard) you don't need to worry about these
                   1361:  things.  But if the absolute time is crucial for your application, you'll
                   1362:  need to convert to UT yourself.
                   1363:
                   1364:  Commands like `show xrange` will re-interpret the integer according to
                   1365:  `timefmt`.  If you change `timefmt`, and then `show` the quantity again, it
                   1366:  will be displayed in the new `timefmt`.  For that matter, if you give the
                   1367:  deactivation command (like `set xdata`), the quantity will be shown in its
                   1368:  numerical form.
                   1369:
                   1370:  The command `set format` defines the format that will be used for tic labels,
                   1371:  whether or not the specified axis is time/date.
                   1372:
                   1373:  If time/date information is to be plotted from a file, the `using` option
                   1374:  _must_ be used on the `plot` or `splot` command.  These commands simply use
                   1375:  white space to separate columns, but white space may be embedded within the
                   1376:  time/date string.  If you use tabs as a separator, some trial-and-error may
                   1377:  be necessary to discover how your system treats them.
                   1378:
                   1379:  The following example demonstrates time/date plotting.
                   1380:
                   1381:  Suppose the file "data" contains records like
                   1382:
                   1383:        03/21/95 10:00  6.02e23
                   1384:
                   1385:  This file can be plotted by
                   1386:
                   1387:        set xdata time
                   1388:        set timefmt "%m/%d/%y"
                   1389:        set xrange ["03/21/95":"03/22/95"]
                   1390:        set format x "%m/%d"
                   1391:        set timefmt "%m/%d/%y %H:%M"
                   1392:        plot "data" using 1:3
                   1393:
                   1394:  which will produce xtic labels that look like "03/21".
                   1395:
                   1396:  See the descriptions of each command for more details.
                   1397: 1 Commands
                   1398: ?commands
                   1399:  This section lists the commands acceptable to `gnuplot` in alphabetical
                   1400:  order.  Printed versions of this document contain all commands; on-line
                   1401:  versions may not be complete.  Indeed, on some systems there may be no
                   1402:  commands at all listed under this heading.
                   1403:
                   1404:  Note that in most cases unambiguous abbreviations for command names and their
                   1405:  options are permissible, i.e., "`p f(x) w l`" instead of "`plot f(x) with
                   1406:  lines`".
                   1407:
                   1408:  In the syntax descriptions, braces ({}) denote optional arguments and a
                   1409:  vertical bar (|) separates mutually exclusive choices.
                   1410: 2 cd
                   1411: ?commands cd
                   1412: ?cd
                   1413:  The `cd` command changes the working directory.
                   1414:
                   1415:  Syntax:
                   1416:        cd '<directory-name>'
                   1417:
                   1418:  The directory name must be enclosed in quotes.
                   1419:
                   1420:  Examples:
                   1421:        cd 'subdir'
                   1422:        cd ".."
                   1423:
                   1424:  DOS users _must_ use single-quotes---backslash [\] has special significance
                   1425:  inside double-quotes.  For example,
                   1426:        cd "c:\newdata"
                   1427:  fails, but
                   1428:        cd 'c:\newdata'
                   1429:  works as expected.
                   1430: 2 call
                   1431: ?commands call
                   1432: ?call
                   1433:  The `call` command is identical to the load command with one exception: you
                   1434:  can have up to ten additional parameters to the command (delimited according
                   1435:  to the standard parser rules) which can be substituted into the lines read
                   1436:  from the file.  As each line is read from the `call`ed input file, it is
                   1437:  scanned for the sequence `$` (dollar-sign) followed by a digit (0--9).  If
                   1438:  found, the sequence is replaced by the corresponding parameter from the
                   1439:  `call` command line.  If the parameter was specified as a string in the
                   1440:  `call` line, it is substituted without its enclosing quotes.  `$` followed by
                   1441:  any character other than a digit will be that character.  E.g. use `$$` to
                   1442:  get a single `$`.  Providing more than ten parameters on the `call` command
                   1443:  line will cause an error.  A parameter that was not provided substitutes as
                   1444:  nothing.  Files being `call`ed may themselves contain `call` or `load`
                   1445:  commands.
                   1446:
                   1447:  The `call` command _must_ be the last command on a multi-command line.
                   1448:
                   1449:  Syntax:
                   1450:        call "<input-file>" <parameter-0> <parm-1> ... <parm-9>
                   1451:
                   1452:  The name of the input file must be enclosed in quotes, and it is recommended
                   1453:  that parameters are similarly enclosed in quotes (future versions of gnuplot
                   1454:  may treat quoted and unquoted arguments differently).
                   1455:
                   1456:  Example:
                   1457:
                   1458:  If the file 'calltest.gp' contains the line:
                   1459:        print "p0=$0 p1=$1 p2=$2 p3=$3 p4=$4 p5=$5 p6=$6 p7=x$7x"
                   1460:
                   1461:  entering the command:
                   1462:        call 'calltest.gp' "abcd" 1.2 + "'quoted'" -- "$2"
                   1463:
                   1464:  will display:
                   1465:        p0=abcd p1=1.2 p2=+ p3='quoted' p4=- p5=- p6=$2 p7=xx
                   1466:
                   1467:  NOTE: there is a clash in syntax with the datafile `using` callback
                   1468:  operator.  Use `$$n` or `column(n)` to access column n from a datafile inside
                   1469:  a `call`ed datafile plot.
                   1470: 2 clear
                   1471: ?commands clear
                   1472: ?clear
                   1473:  The `clear` command erases the current screen or output device as specified
                   1474:  by `set output`.  This usually generates a formfeed on hardcopy devices.  Use
                   1475:  `set terminal` to set the device type.
                   1476:
                   1477:  For some terminals `clear` erases only the portion of the plotting surface
                   1478:  defined by `set size`, so for these it can be used in conjunction with `set
                   1479:  multiplot` to create an inset.
                   1480:
                   1481:  Example:
                   1482:        set multiplot
                   1483:        plot sin(x)
                   1484:        set origin 0.5,0.5
                   1485:        set size 0.4,0.4
                   1486:        clear
                   1487:        plot cos(x)
                   1488:        set nomultiplot
                   1489:
                   1490:  Please see `set multiplot`, `set size`, and `set origin` for details of these
                   1491:  commands.
                   1492: 2 exit
                   1493: ?commands exit
                   1494: ?exit
                   1495:  The commands `exit` and `quit` and the END-OF-FILE character will exit the
                   1496:  current `gnuplot` command file and `load` the next one.  See "help
                   1497:  batch/interactive" for more details.
                   1498:
                   1499:  Each of these commands will clear the output device (as does the `clear`
                   1500:  command) before exiting.
                   1501: 2 fit
                   1502: ?commands fit
                   1503: ?fit
                   1504: ?least-squares
                   1505: ?Marquardt
                   1506:  The `fit` command can fit a user-defined function to a set of data points
                   1507:  (x,y) or (x,y,z), using an implementation of the nonlinear least-squares
                   1508:  (NLLS) Marquardt-Levenberg algorithm.  Any user-defined variable occurring in
                   1509:  the function body may serve as a fit parameter, but the return type of the
                   1510:  function must be real.
                   1511:
                   1512:  Syntax:
                   1513:        fit {[xrange] {[yrange]}} <function> '<datafile>'
                   1514:            {datafile-modifiers}
                   1515:            via '<parameter file>' | <var1>{,<var2>,...}
                   1516:
                   1517:  Ranges may be specified to temporarily limit the data which is to be fitted;
                   1518:  any out-of-range data points are ignored. The syntax is
                   1519:        [{dummy_variable=}{<min>}{:<max>}],
                   1520:  analogous to `plot`; see `plot ranges`.
                   1521:
                   1522:  <function> is any valid `gnuplot` expression, although it is usual to use a
                   1523:  previously user-defined function of the form f(x) or f(x,y).
                   1524:
                   1525:  <datafile> is treated as in the `plot` command.  All the `plot datafile`
                   1526:  modifiers (`using`, `every`,...) except `smooth` are applicable to `fit`.
                   1527:  See `plot datafile`.
                   1528:
                   1529:  The default data formats for fitting functions with a single independent
                   1530:  variable, y=f(x), are {x:}y or x:y:s; those formats can be changed with
                   1531:  the datafile `using` qualifier.  The third item, (a column number or an
                   1532:  expression), if present, is interpreted as the standard deviation of the
                   1533:  corresponding y value and is used to compute a weight for the datum, 1/s**2.
                   1534:  Otherwise, all data points are weighted equally, with a weight of one.
                   1535:
                   1536:  To fit a function with two independent variables, z=f(x,y), the required
                   1537:  format is `using` with four items, x:y:z:s.  The complete format must be
                   1538:  given---no default columns are assumed for a missing token.  Weights for
                   1539:  each data point are evaluated from 's' as above.  If error estimates are
                   1540:  not available, a constant value can be specified as a constant expression
                   1541:  (see `plot datafile using`), e.g., `using 1:2:3:(1)`.
                   1542:
                   1543:  Multiple datasets may be simultaneously fit with functions of one
                   1544:  independent variable by making y a 'pseudo-variable', e.g., the dataline
                   1545:  number, and fitting as two independent variables.  See `fit multibranch`.
                   1546:
                   1547:  The `via` qualifier specifies which parameters are to be adjusted, either
                   1548:  directly, or by referencing a parameter file.
                   1549:
                   1550:  Examples:
                   1551:        f(x) = a*x**2 + b*x + c
                   1552:        g(x,y) = a*x**2 + b*y**2 + c*x*y
                   1553:        FIT_LIMIT = 1e-6
                   1554:        fit f(x) 'measured.dat' via 'start.par'
                   1555:        fit f(x) 'measured.dat' using 3:($7-5) via 'start.par'
                   1556:        fit f(x) './data/trash.dat' using 1:2:3 via a, b, c
                   1557:        fit g(x,y) 'surface.dat' using 1:2:3:(1) via a, b, c
                   1558:
                   1559:  After each iteration step, detailed information about the current state
                   1560:  of the fit is written to the display.  The same information about the
                   1561:  initial and final states is written to a log file, "fit.log".  This file
                   1562:  is always appended to, so as to not lose any previous fit history;  it
                   1563:  should be deleted or renamed as desired.
                   1564:
                   1565:  The fit may be interrupted by pressing Ctrl-C (any key but Ctrl-C under
                   1566:  MSDOS and Atari Multitasking Systems).  After the current iteration
                   1567:  completes, you have the option to (1) stop the fit and accept the current
                   1568:  parameter values, (2) continue the fit, (3) execute a `gnuplot` command
                   1569:  as specified by the environment variable FIT_SCRIPT.  The default for
                   1570:  FIT_SCRIPT is `replot`, so if you had previously plotted both the data
                   1571:  and the fitting function in one graph, you can display the current state
                   1572:  of the fit.
                   1573:
                   1574:  Once `fit` has finished, the `update` command may be used to store final
                   1575:  values in a file for subsequent use as a parameter file.   See `update`
                   1576:  for details.
                   1577: 3 adjustable parameters
                   1578: ?commands fit parameters
                   1579: ?fit parameters
                   1580: ?commands fit adjustable_parameters
                   1581: ?fit adjustable_parameters
                   1582: ?fit_parameters
                   1583:  There are two ways that `via` can specify the parameters to be adjusted,
                   1584:  either directly on the command line or indirectly, by referencing a
                   1585:  parameter file.  The two use different means to set initial values.
                   1586:
                   1587:  Adjustable parameters can be specified by a comma-separated list of variable
1.1.1.3 ! ohara    1588:  names after the `via` keyword.  Any variable that is not already defined
1.1       maekawa  1589:  is created with an initial value of 1.0.  However, the fit is more likely
                   1590:  to converge rapidly if the variables have been previously declared with more
                   1591:  appropriate starting values.
                   1592:
                   1593:  In a parameter file, each parameter to be varied and a corresponding initial
                   1594:  value are specified, one per line, in the form
                   1595:        varname = value
                   1596:
                   1597:  Comments, marked by '#', and blank lines are permissible.  The
                   1598:  special form
                   1599:        varname = value       # FIXED
                   1600:
                   1601:  means that the variable is treated as a 'fixed parameter', initialized by the
                   1602:  parameter file, but not adjusted by `fit`.  For clarity, it may be useful to
                   1603:  designate variables as fixed parameters so that their values are reported by
                   1604:  `fit`.  The keyword `# FIXED` has to appear in exactly this form.
                   1605:
                   1606: 3 beginner's guide
                   1607: ?commands fit beginners_guide
                   1608: ?fit beginners_guide
                   1609: ?fit guide
                   1610: ?fitting
                   1611:  `fit` is used to find a set of parameters that 'best' fits your data to your
                   1612:  user-defined function.  The fit is judged on the basis of the the sum of the
                   1613:  squared differences or 'residuals' (SSR) between the input data points and
                   1614:  the function values, evaluated at the same places.  This quantity is often
                   1615:  called 'chisquare' (i.e., the Greek letter chi, to the power of 2).  The
                   1616:  algorithm attempts to minimize SSR, or more precisely, WSSR, as the residuals
                   1617:  are 'weighted' by the input data errors (or 1.0) before being squared; see
                   1618:  `fit error_estimates` for details.
                   1619:
                   1620:  That's why it is called 'least-squares fitting'.  Let's look at an example
                   1621:  to see what is meant by 'non-linear', but first we had better go over some
                   1622:  terms.  Here it is convenient to use z as the dependent variable for
                   1623:  user-defined functions of either one independent variable, z=f(x), or two
                   1624:  independent variables, z=f(x,y).  A parameter is a user-defined variable
                   1625:  that `fit` will adjust, i.e., an unknown quantity in the function
                   1626:  declaration.  Linearity/non-linearity refers to the relationship of the
                   1627:  dependent variable, z, to the parameters which `fit` is adjusting, not of
                   1628:  z to the independent variables, x and/or y.  (To be technical, the
                   1629:  second {and higher} derivatives of the fitting function with respect to
                   1630:  the parameters are zero for a linear least-squares problem).
                   1631:
                   1632:  For linear least-squares (LLS), the user-defined function will be a sum of
                   1633:  simple functions, not involving any parameters, each multiplied by one
                   1634:  parameter.  NLLS handles more complicated functions in which parameters can
                   1635:  be used in a large number of ways.  An example that illustrates the
                   1636:  difference between linear and nonlinear least-squares is the Fourier series.
                   1637:  One member may be written as
                   1638:       z=a*sin(c*x) + b*cos(c*x).
                   1639:  If a and b are the unknown parameters and c is constant, then estimating
                   1640:  values of the parameters is a linear least-squares problem.  However, if
                   1641:  c is an unknown parameter, the problem is nonlinear.
                   1642:
                   1643:  In the linear case, parameter values can be determined by comparatively
                   1644:  simple linear algebra, in one direct step.  However LLS is a special case
                   1645:  which is also solved along with more general NLLS problems by the iterative
                   1646:  procedure that `gnuplot` uses.  `fit` attempts to find the minimum by doing
                   1647:  a search.  Each step (iteration) calculates WSSR with a new set of parameter
                   1648:  values.  The Marquardt-Levenberg algorithm selects the parameter values for
                   1649:  the next iteration.  The process continues until a preset criterium is met,
                   1650:  either (1) the fit has "converged" (the relative change in WSSR is less than
                   1651:  FIT_LIMIT), or (2) it reaches a preset iteration count limit, FIT_MAXITER
                   1652:  (see `fit control variables`).  The fit may also be interrupted
                   1653:  and subsequently halted from the keyboard (see `fit`).
                   1654:
                   1655:  Often the function to be fitted will be based on a model (or theory) that
                   1656:  attempts to describe or predict the behaviour of the data.  Then `fit` can
                   1657:  be used to find values for the free parameters of the model, to determine
                   1658:  how well the data fits the model, and to estimate an error range for each
                   1659:  parameter.  See `fit error_estimates`.
                   1660:
                   1661:  Alternatively, in curve-fitting, functions are selected independent of
                   1662:  a model (on the basis of experience as to which are likely to describe
                   1663:  the trend of the data with the desired resolution and a minimum number
                   1664:  of parameters*functions.)  The `fit` solution then provides an analytic
                   1665:  representation of the curve.
                   1666:
                   1667:  However, if all you really want is a smooth curve through your data points,
                   1668:  the `smooth` option to `plot` may be what you've been looking for rather
                   1669:  than `fit`.
                   1670: 3 error estimates
                   1671: ?commands fit error_estimate
                   1672: ?fit error_estimate
                   1673: ?fit errors
                   1674:  In `fit`, the term "error" is used in two different contexts, data error
                   1675:  estimates and parameter error estimates.
                   1676:
                   1677:  Data error estimates are used to calculate the relative weight of each data
                   1678:  point when determining the weighted sum of squared residuals, WSSR or
                   1679:  chisquare.  They can affect the parameter estimates, since they determine
                   1680:  how much influence the deviation of each data point from the fitted function
                   1681:  has on the final values.  Some of the `fit` output information, including
                   1682:  the parameter error estimates, is more meaningful if accurate data error
                   1683:  estimates have been provided.
                   1684:
                   1685:  The 'statistical overview' describes some of the `fit` output and gives some
                   1686:  background for the 'practical guidelines'.
                   1687: 4 statistical overview
                   1688: ?commands fit error statistical_overview
                   1689: ?fit error statistical_overview
                   1690: ?statistical_overview
                   1691:  The theory of non-linear least-squares (NLLS) is generally described in terms
                   1692:  of a normal distribution of errors, that is, the input data is assumed to be
                   1693:  a sample from a population having a given mean and a Gaussian (normal)
                   1694:  distribution about the mean with a given standard deviation.  For a sample of
                   1695:  sufficiently large size, and knowing the population standard deviation, one
                   1696:  can use the statistics of the chisquare distribution to describe a "goodness
                   1697:  of fit" by looking at the variable often called "chisquare".  Here, it is
                   1698:  sufficient to say that a reduced chisquare (chisquare/degrees of freedom,
                   1699:  where degrees of freedom is the number of datapoints less the number of
                   1700:  parameters being fitted) of 1.0 is an indication that the weighted sum of
                   1701:  squared deviations between the fitted function and the data points is the
                   1702:  same as that expected for a random sample from a population characterized by
                   1703:  the function with the current value of the parameters and the given standard
                   1704:  deviations.
                   1705:
                   1706:  If the standard deviation for the population is not constant, as in counting
                   1707:  statistics where variance = counts, then each point should be individually
                   1708:  weighted when comparing the observed sum of deviations and the expected sum
                   1709:  of deviations.
                   1710:
                   1711:  At the conclusion `fit` reports 'stdfit', the standard deviation of the fit,
                   1712:  which is the rms of the residuals, and the variance of the residuals, also
                   1713:  called 'reduced chisquare' when the data points are weighted.  The number of
                   1714:  degrees of freedom (the number of data points minus the number of fitted
                   1715:  parameters) is used in these estimates because the parameters used in
                   1716:  calculating the residuals of the datapoints were obtained from the same data.
                   1717:
                   1718:  To estimate confidence levels for the parameters, one can use the minimum
                   1719:  chisquare obtained from the fit and chisquare statistics to determine the
                   1720:  value of chisquare corresponding to the desired confidence level, but
                   1721:  considerably more calculation is required to determine the combinations of
                   1722:  parameters which produce such values.
                   1723:
                   1724:  Rather than determine confidence intervals, `fit` reports parameter error
                   1725:  estimates which are readily obtained from the variance-covariance matrix
                   1726:  after the final iteration.  By convention, these estimates are called
                   1727:  "standard errors" or "asymptotic standard errors", since they are calculated
                   1728:  in the same way as the standard errors (standard deviation of each parameter)
                   1729:  of a linear least-squares problem, even though the statistical conditions for
                   1730:  designating the quantity calculated to be a standard deviation are not
                   1731:  generally valid for the NLLS problem.  The asymptotic standard errors are
                   1732:  generally over-optimistic and should not be used for determining confidence
                   1733:  levels, but are useful for qualitative purposes.
                   1734:
                   1735:  The final solution also produces a correlation matrix, which gives an
                   1736:  indication of the correlation of parameters in the region of the solution;
                   1737:  if one parameter is changed, increasing chisquare, does changing another
                   1738:  compensate?  The main diagonal elements, autocorrelation, are all 1; if
                   1739:  all parameters were independent, all other elements would be nearly 0.  Two
                   1740:  variables which completely compensate each other would have an off-diagonal
                   1741:  element of unit magnitude, with a sign depending on whether the relation is
                   1742:  proportional or inversely proportional.  The smaller the magnitudes of the
                   1743:  off-diagonal elements, the closer the estimates of the standard deviation
                   1744:  of each parameter would be to the asymptotic standard error.
                   1745: 4 practical guidelines
                   1746: ?commands fit error practical_guidelines
                   1747: ?fit error practical_guidelines
                   1748: ?practical_guidelines
                   1749: ?guidelines
                   1750:  If you have a basis for assigning weights to each data point, doing so lets
                   1751:  you make use of additional knowledge about your measurements, e.g., take into
                   1752:  account that some points may be more reliable than others.  That may affect
                   1753:  the final values of the parameters.
                   1754:
                   1755:  Weighting the data provides a basis for interpreting the additional `fit`
                   1756:  output after the last iteration.  Even if you weight each point equally,
                   1757:  estimating an average standard deviation rather than using a weight of 1
                   1758:  makes WSSR a dimensionless variable, as chisquare is by definition.
                   1759:
                   1760:  Each fit iteration will display information which can be used to evaluate
                   1761:  the progress of the fit.  (An '*' indicates that it did not find a smaller
                   1762:  WSSR and is trying again.)  The 'sum of squares of residuals', also called
                   1763:  'chisquare', is the WSSR between the data and your fitted function; `fit`
                   1764:  has minimized that.  At this stage, with weighted data, chisquare is expected
                   1765:  to approach the number of degrees of freedom (data points minus parameters).
                   1766:  The WSSR can be used to calculate the reduced chisquare (WSSR/ndf) or stdfit,
                   1767:  the standard deviation of the fit, sqrt(WSSR/ndf).  Both of these are
                   1768:  reported for the final WSSR.
                   1769:
                   1770:  If the data are unweighted, stdfit is the rms value of the deviation of the
                   1771:  data from the fitted function, in user units.
                   1772:
                   1773:  If you supplied valid data errors, the number of data points is large enough,
                   1774:  and the model is correct, the reduced chisquare should be about unity.  (For
                   1775:  details, look up the 'chi-squared distribution' in your favourite statistics
                   1776:  reference.)  If so, there are additional tests, beyond the scope of this
                   1777:  overview, for determining how well the model fits the data.
                   1778:
                   1779:  A reduced chisquare much larger than 1.0 may be due to incorrect data error
                   1780:  estimates, data errors not normally distributed, systematic measurement
                   1781:  errors, 'outliers', or an incorrect model function.  A plot of the residuals,
                   1782:  e.g., `plot 'datafile' using 1:($2-f($1))`, may help to show any systematic
                   1783:  trends.  Plotting both the data points and the function may help to suggest
                   1784:  another model.
                   1785:
                   1786:  Similarly, a reduced chisquare less than 1.0 indicates WSSR is less than that
                   1787:  expected for a random sample from the function with normally distributed
                   1788:  errors.  The data error estimates may be too large, the statistical
                   1789:  assumptions may not be justified, or the model function may be too general,
                   1790:  fitting fluctuations in a particular sample in addition to the underlying
                   1791:  trends.  In the latter case, a simpler function may be more appropriate.
                   1792:
                   1793:  You'll have to get used to both `fit` and the kind of problems you apply it
                   1794:  to before you can relate the standard errors to some more practical estimates
                   1795:  of parameter uncertainties or evaluate the significance of the correlation
                   1796:  matrix.
                   1797:
                   1798:  Note that `fit`, in common with most NLLS implementations, minimizes the
                   1799:  weighted sum of squared distances (y-f(x))**2.  It does not provide any means
                   1800:  to account for "errors" in the values of x, only in y.  Also, any "outliers"
                   1801:  (data points outside the normal distribution of the model) will have an
                   1802:  exaggerated effect on the solution.
                   1803: 3 fit controlling
                   1804: ?commands fit_control
                   1805: ?fit_control
                   1806: ?fit control
                   1807:  There are a number of `gnuplot` variables that can be defined to affect
                   1808:  `fit`.  Those which can be defined once `gnuplot` is running are listed
                   1809:  under 'control_variables' while those defined before starting `gnuplot`
                   1810:  are listed under 'environment_variables'.
                   1811: 4 control variables
                   1812: ?commands fit_control variables
                   1813: ?fit_control variables
                   1814: ?fit control variables
                   1815:  The default epsilon limit (1e-5) may be changed by declaring a value for
                   1816:        FIT_LIMIT
                   1817:  When the sum of squared residuals changes between two iteration steps by
                   1818:  a factor less than this number (epsilon), the fit is considered to have
                   1819:  'converged'.
                   1820:
                   1821:  The maximum number of iterations may be limited by declaring a value for
                   1822:        FIT_MAXITER
                   1823:  A value of 0 (or not defining it at all)  means that there is no limit.
                   1824:
                   1825:  If you need even more control about the algorithm, and know the
                   1826:  Marquardt-Levenberg algorithm well, there are some more variables to
                   1827:  influence it. The startup value of `lambda` is normally calculated
                   1828:  automatically from the ML-matrix, but if you want to, you may provide
                   1829:  your own one with
                   1830:        FIT_START_LAMBDA
                   1831:  Specifying FIT_START_LAMBDA as zero or less will re-enable the automatic
                   1832:  selection. The variable
                   1833:        FIT_LAMBDA_FACTOR
                   1834:  gives the factor by which `lambda` is increased or decreased whenever
                   1835:  the chi-squared target function increased or decreased significantly.
                   1836:  Setting FIT_LAMBDA_FACTOR to zero re-enables the default factor of
                   1837:  10.0.
                   1838:
1.1.1.3 ! ohara    1839:  Other variables with the FIT_ prefix may be added to `fit`, so it is safer
1.1       maekawa  1840:  not to use that prefix for user-defined variables.
                   1841:
                   1842:  The variables FIT_SKIP and FIT_INDEX were used by earlier releases of
                   1843:  `gnuplot` with a 'fit' patch called `gnufit` and are no longer available.
                   1844:  The datafile `every` modifier provides the functionality of FIT_SKIP.
                   1845:  FIT_INDEX was used for multi-branch fitting, but multi-branch fitting of
                   1846:  one independent variable is now done as a pseudo-3D fit in which the
                   1847:  second independent variable and `using` are used to specify the branch.
                   1848:  See `fit multi-branch`.
                   1849: 4 environment variables
                   1850: ?commands fit_control environment
                   1851: ?fit_control environment
                   1852: ?fit control environment
                   1853:  The environment variables must be defined before `gnuplot` is executed; how
                   1854:  to do so depends on your operating system.
                   1855:
                   1856:        FIT_LOG
                   1857:  changes the name (and/or path) of the file to which the fit log will be
                   1858:  written from the default of "fit.log" in the working directory.
                   1859:
                   1860:        FIT_SCRIPT
                   1861:  specifies a command that may be executed after an user interrupt. The default
                   1862:  is `replot`, but a `plot` or `load` command may be useful to display a plot
                   1863:  customized to highlight the progress of the fit.
                   1864: 3 multi-branch
                   1865: ?commands fit multi-branch
                   1866: ?fit multi-branch
                   1867: ?multi-branch
                   1868: ?branch
                   1869:  In multi-branch fitting, multiple data sets can be simultaneously fit with
                   1870:  functions of one independent variable having common parameters by minimizing
                   1871:  the total WSSR.  The function and parameters (branch) for each data set are
                   1872:  selected by using a 'pseudo-variable', e.g., either the dataline number (a
                   1873:  'column' index of -1) or the datafile index (-2), as the second independent
                   1874:  variable.
                   1875:
                   1876:  Example:  Given two exponential decays of the form, z=f(x), each describing
                   1877:  a different data set but having a common decay time, estimate the values of
                   1878:  the parameters.  If the datafile has the format x:z:s, then
                   1879:       f(x,y) = (y==0) ? a*exp(-x/tau) : b*exp(-x/tau)
                   1880:       fit f(x,y) 'datafile' using  1:-1:2:3  via a, b, tau
                   1881:
                   1882:  For a more complicated example, see the file "hexa.fnc" used by the
                   1883:  "fit.dem" demo.
                   1884:
                   1885:  Appropriate weighting may be required since unit weights may cause one
                   1886:  branch to predominate if there is a difference in the scale of the dependent
                   1887:  variable.  Fitting each branch separately, using the multi-branch solution
                   1888:  as initial values, may give an indication as to the relative effect of each
                   1889:  branch on the joint solution.
                   1890: 3 starting values
                   1891: ?commands fit starting_values
                   1892: ?fit starting_values
                   1893: ?starting_values
                   1894:  Nonlinear fitting is not guaranteed to converge to the global optimum (the
                   1895:  solution with the smallest sum of squared residuals, SSR), and can get stuck
                   1896:  at a local minimum.  The routine has no way to determine that;  it is up to
                   1897:  you to judge whether this has happened.
                   1898:
                   1899:  `fit` may, and often will get "lost" if started far from a solution, where
                   1900:  SSR is large and changing slowly as the parameters are varied, or it may
                   1901:  reach a numerically unstable region (e.g., too large a number causing a
                   1902:  floating point overflow) which results in an "undefined value" message
                   1903:  or `gnuplot` halting.
                   1904:
                   1905:  To improve the chances of finding the global optimum, you should set the
                   1906:  starting values at least roughly in the vicinity of the solution, e.g.,
                   1907:  within an order of magnitude, if possible.  The closer your starting values
                   1908:  are to the solution, the less chance of stopping at another minimum.  One way
                   1909:  to find starting values is to plot data and the fitting function on the same
                   1910:  graph and change parameter values and `replot` until reasonable similarity
                   1911:  is reached.  The same plot is also useful to check whether the fit stopped at
                   1912:  a minimum with a poor fit.
                   1913:
                   1914:  Of course, a reasonably good fit is not proof there is not a "better" fit (in
                   1915:  either a statistical sense, characterized by an improved goodness-of-fit
                   1916:  criterion, or a physical sense, with a solution more consistent with the
                   1917:  model.)  Depending on the problem, it may be desirable to `fit` with various
                   1918:  sets of starting values, covering a reasonable range for each parameter.
                   1919: 3 tips
                   1920: ?commands fit tips
                   1921: ?fit tips
                   1922: ?tips
                   1923:  Here are some tips to keep in mind to get the most out of `fit`.  They're not
                   1924:  very organized, so you'll have to read them several times until their essence
                   1925:  has sunk in.
                   1926:
                   1927:  The two forms of the `via` argument to `fit` serve two largely distinct
                   1928:  purposes.  The `via "file"` form is best used for (possibly unattended) batch
                   1929:  operation, where you just supply the startup values in a file and can later
                   1930:  use `update` to copy the results back into another (or the same) parameter
                   1931:  file.
                   1932:
                   1933:  The `via var1, var2, ...` form is best used interactively, where the command
                   1934:  history mechanism may be used to edit the list of parameters to be fitted or
                   1935:  to supply new startup values for the next try.  This is particularly useful
                   1936:  for hard problems, where a direct fit to all parameters at once won't work
                   1937:  without good starting values.  To find such, you can iterate several times,
                   1938:  fitting only some of the parameters, until the values are close enough to the
                   1939:  goal that the final fit to all parameters at once will work.
                   1940:
                   1941:  Make sure that there is no mutual dependency among parameters of the function
                   1942:  you are fitting.  For example, don't try to fit a*exp(x+b), because
                   1943:  a*exp(x+b)=a*exp(b)*exp(x).  Instead, fit either a*exp(x) or exp(x+b).
                   1944:
                   1945:  A technical issue:  the parameters must not be too different in magnitude.
                   1946:  The larger the ratio of the largest and the smallest absolute parameter
                   1947:  values, the slower the fit will converge.  If the ratio is close to or above
                   1948:  the inverse of the machine floating point precision, it may take next to
                   1949:  forever to converge, or refuse to converge at all.  You will have to adapt
                   1950:  your function to avoid this, e.g., replace 'parameter' by '1e9*parameter' in
                   1951:  the function definition, and divide the starting value by 1e9.
                   1952:
                   1953:  If you can write your function as a linear combination of simple functions
                   1954:  weighted by the parameters to be fitted, by all means do so.  That helps a
                   1955:  lot, because the problem is no longer nonlinear and should converge with only
                   1956:  a small number of iterations, perhaps just one.
                   1957:
                   1958:  Some prescriptions for analysing data, given in practical experimentation
                   1959:  courses, may have you first fit some functions to your data, perhaps in a
                   1960:  multi-step process of accounting for several aspects of the underlying
                   1961:  theory one by one, and then extract the information you really wanted from
                   1962:  the fitting parameters of those functions.  With `fit`, this may often be
                   1963:  done in one step by writing the model function directly in terms of the
                   1964:  desired parameters.  Transforming data can also quite often be avoided,
                   1965:  though sometimes at the cost of a more difficult fit problem.  If you think
                   1966:  this contradicts the previous paragraph about simplifying the fit function,
                   1967:  you are correct.
                   1968:
                   1969:  A "singular matrix" message indicates that this implementation of the
                   1970:  Marquardt-Levenberg algorithm can't calculate parameter values for the next
                   1971:  iteration.  Try different starting values, writing the function in another
                   1972:  form, or a simpler function.
                   1973:
                   1974:  Finally, a nice quote from the manual of another fitting package (fudgit),
                   1975:  that kind of summarizes all these issues:  "Nonlinear fitting is an art!"
                   1976: 2 help
                   1977: ?commands help
                   1978: ?help
                   1979:  The `help` command displays on-line help. To specify information on a
                   1980:  particular topic use the syntax:
                   1981:
                   1982:        help {<topic>}
                   1983:
                   1984:  If <topic> is not specified, a short message is printed about `gnuplot`.
                   1985:  After help for the requested topic is given, a menu of subtopics is given;
                   1986:  help for a subtopic may be requested by typing its name, extending the help
                   1987:  request.  After that subtopic has been printed, the request may be extended
                   1988:  again or you may go back one level to the previous topic.  Eventually, the
                   1989:  `gnuplot` command line will return.
                   1990:
                   1991:  If a question mark (?) is given as the topic, the list of topics currently
                   1992:  available is printed on the screen.
                   1993: 2 if
                   1994: ?commands if
                   1995: ?if
                   1996:  The `if` command allows commands to be executed conditionally.
                   1997:
                   1998:  Syntax:
                   1999:        if (<condition>) <command-line>
                   2000:
                   2001:  <condition> will be evaluated.  If it is true (non-zero), then the command(s)
                   2002:  of the <command-line> will be executed.  If <condition> is false (zero), then
                   2003:  the entire <command-line> is ignored.  Note that use of `;` to allow multiple
                   2004:  commands on the same line will _not_ end the conditionalized commands.
                   2005:
                   2006:  Examples:
                   2007:        pi=3
                   2008:        if (pi!=acos(-1)) print "?Fixing pi!"; pi=acos(-1); print pi
                   2009:  will display:
                   2010:        ?Fixing pi!
                   2011:        3.14159265358979
                   2012:  but
                   2013:        if (1==2) print "Never see this"; print "Or this either"
                   2014:  will not display anything.
                   2015:
                   2016:  See `reread` for an example of how `if` and `reread` can be used together to
                   2017:  perform a loop.
                   2018: 2 load
                   2019: ?commands load
                   2020: ?load
                   2021:  The `load` command executes each line of the specified input file as if it
                   2022:  had been typed in interactively.  Files created by the `save` command can
                   2023:  later be `load`ed.  Any text file containing valid commands can be created
                   2024:  and then executed by the `load` command.  Files being `load`ed may themselves
                   2025:  contain `load` or `call` commands.  See `comment` for information about
                   2026:  comments in commands.  To `load` with arguments, see `call`.
                   2027:
                   2028:  The `load` command _must_ be the last command on a multi-command line.
                   2029:
                   2030:  Syntax:
                   2031:        load "<input-file>"
                   2032:
                   2033:  The name of the input file must be enclosed in quotes.
                   2034:
                   2035:  The special filename "-" may be used to `load` commands from standard input.
                   2036:  This allows a `gnuplot` command file to accept some commands from standard
                   2037:  input.  Please see "help batch/interactive" for more details.
                   2038:
                   2039:  Examples:
                   2040:        load 'work.gnu'
                   2041:        load "func.dat"
                   2042:
                   2043:  The `load` command is performed implicitly on any file names given as
                   2044:  arguments to `gnuplot`.  These are loaded in the order specified, and
                   2045:  then `gnuplot` exits.
                   2046: 2 pause
                   2047: ?commands pause
                   2048: ?pause
                   2049:  The `pause` command displays any text associated with the command and then
                   2050:  waits a specified amount of time or until the carriage return is pressed.
                   2051:  `pause` is especially useful in conjunction with `load` files.
                   2052:
                   2053:  Syntax:
                   2054:        pause <time> {"<string>"}
                   2055:
                   2056:  <time> may be any integer constant or expression.  Choosing -1 will wait
                   2057:  until a carriage return is hit, zero (0) won't pause at all, and a positive
                   2058:  integer will wait the specified number of seconds.  `pause 0` is synonymous
                   2059:  with `print`.
                   2060:
                   2061:  Note: Since `pause` communicates with the operating system rather than the
                   2062:  graphics, it may behave differently with different device drivers (depending
                   2063:  upon how text and graphics are mixed).
                   2064:
                   2065:  Examples:
                   2066:        pause -1    # Wait until a carriage return is hit
                   2067:        pause 3     # Wait three seconds
                   2068:        pause -1  "Hit return to continue"
                   2069:        pause 10  "Isn't this pretty?  It's a cubic spline."
                   2070:
                   2071: 2 plot
                   2072: ?commands plot
                   2073: ?plot
                   2074:  `plot` is the primary command for drawing plots with `gnuplot`.  It creates
                   2075:  plots of functions and data in many, many ways.  `plot` is used to draw 2-d
                   2076:  functions and data; `splot` draws 2-d projections of 3-d surfaces and data.
                   2077:  `plot` and `splot` contain many common features; see `splot` for differences.
                   2078:  Note specifically that `splot`'s `binary` and `matrix` options do not exist
                   2079:  for `plot`.
                   2080:
                   2081:  Syntax:
                   2082:        plot {<ranges>}
                   2083:             {<function> | {"<datafile>" {datafile-modifiers}}}
                   2084:             {axes <axes>} {<title-spec>} {with <style>}
                   2085:             {, {definitions,} <function> ...}
                   2086:
                   2087:  where either a <function> or the name of a data file enclosed in quotes is
                   2088:  supplied.  A function is a mathematical expression or a pair of mathematical
                   2089:  expressions in parametric mode.  The expressions may be defined completely or
                   2090:  in part earlier in the stream of `gnuplot` commands (see `user-defined`).
                   2091:
                   2092:  It is also possible to define functions and parameters on the `plot` command
                   2093:  itself.  This is done merely by isolating them from other items with commas.
                   2094:
                   2095:  There are four possible sets of axes available; the keyword <axes> is used to
                   2096:  select the axes for which a particular line should be scaled.  `x1y1` refers
                   2097:  to the axes on the bottom and left; `x2y2` to those on the top and right;
                   2098:  `x1y2` to those on the bottom and right; and `x2y1` to those on the top and
                   2099:  left.  Ranges specified on the `plot` command apply only to the first set of
                   2100:  axes (bottom left).
                   2101:
                   2102:  Examples:
                   2103:        plot sin(x)
                   2104:        plot f(x) = sin(x*a), a = .2, f(x), a = .4, f(x)
                   2105:        plot [t=1:10] [-pi:pi*2] tan(t), \
                   2106:             "data.1" using (tan($2)):($3/$4) smooth csplines \
                   2107:                      axes x1y2 notitle with lines 5
                   2108:
                   2109: 3 data-file
                   2110: ?commands plot datafile
                   2111: ?plot datafile
                   2112: ?data-file
                   2113: ?datafile
                   2114: ?data
                   2115:  Discrete data contained in a file can be displayed by specifying the name of
                   2116:  the data file (enclosed in single or double quotes) on the `plot` command line.
                   2117:
                   2118:  Syntax:
                   2119:        plot '<file_name>' {index <index list>}
                   2120:                              {every <every list>}
                   2121:                              {thru <thru expression>}
                   2122:                              {using <using list>}
                   2123:                              {smooth <option>}
                   2124:
                   2125:  The modifiers `index`, `every`, `thru`, `using`, and `smooth` are discussed
                   2126:  separately.  In brief, `index` selects which data sets in a multi-data-set
                   2127:  file are to be plotted, `every` specifies which points within a single data
                   2128:  set are to be plotted, `using` determines how the columns within a single
                   2129:  record are to be interpreted (`thru` is a special case of `using`), and
                   2130:  `smooth` allows for simple interpolation and approximation.  ('splot' has a
                   2131:  similar syntax, but does not support the `smooth` and `thru` options.)
                   2132:
                   2133:  Data files should contain at least one data point per record (`using` can
                   2134:  select one data point from the record).  Records beginning with `#` (and
                   2135:  also with `!` on VMS) will be treated as comments and ignored.  Each data
                   2136:  point represents an (x,y) pair.  For `plot`s with error bars (see `set style
                   2137:  errorbars`), each data point is (x,y,ydelta), (x,y,ylow,yhigh), (x,y,xdelta),
                   2138:  (x,y,xlow,xhigh), or (x,y,xlow,xhigh,ylow,yhigh).  In all cases, the numbers
                   2139:  on each record of a data file must be separated by white space (one or more
                   2140:  blanks or tabs), unless a format specifier is provided by the `using` option.
                   2141:  This white space divides each record into columns.
                   2142:
                   2143:  Data may be written in exponential format with the exponent preceded by the
                   2144:  letter e, E, d, D, q, or Q.
                   2145:
                   2146:  Only one column (the y value) need be provided.  If x is omitted, `gnuplot`
                   2147:  provides integer values starting at 0.
                   2148:
                   2149:  In datafiles, blank records (records with no characters other than blanks and
                   2150:  a newline and/or carriage return) are significant---pairs of blank records
                   2151:  separate `index`es (see `plot datafile index`).  Data separated by double
                   2152:  blank records are treated as if they were in separate data files.
                   2153:
                   2154:  Single blank records designate discontinuities in a `plot`; no line will join
                   2155:  points separated by a blank records (if they are plotted with a line style).
                   2156:
                   2157:  If autoscaling has been enabled (`set autoscale`), the axes are automatically
                   2158:  extended to include all datapoints, with a whole number of tic marks if tics
                   2159:  are being drawn.  This has two consequences: i) For `splot`, the corner of
                   2160:  the surface may not coincide with the corner of the base.  In this case, no
                   2161:  vertical line is drawn.  ii) When plotting data with the same x range on a
                   2162:  dual-axis graph, the x coordinates may not coincide if the x2tics are not
                   2163:  being drawn.  This is because the x axis has been autoextended to a whole
                   2164:  number of tics, but the x2 axis has not.  The following example illustrates
                   2165:  the problem:
                   2166:
                   2167:        reset; plot '-', '-'
                   2168:        1 1
                   2169:        19 19
                   2170:        e
                   2171:        1 1
                   2172:        19 19
                   2173:        e
                   2174: 4 every
                   2175: ?commands plot datafile every
                   2176: ?plot datafile every
                   2177: ?plot every
                   2178: ?data-file every
                   2179: ?datafile every
                   2180: ?every
                   2181:  The `every` keyword allows a periodic sampling of a data set to be plotted.
                   2182:
                   2183:  In the discussion a "point" is a datum defined by a single record in the
                   2184:  file; "block" here will mean the same thing as "datablock" (see `glossary`).
                   2185:
                   2186:  Syntax:
                   2187:        plot 'file' every {<point_incr>}
                   2188:                            {:{<block_incr>}
                   2189:                              {:{<start_point>}
                   2190:                                {:{<start_block>}
                   2191:                                  {:{<end_point>}
                   2192:                                    {:<end_block>}}}}}
                   2193:
                   2194:  The data points to be plotted are selected according to a loop from
                   2195:  <`start_point`> to <`end_point`> with increment <`point_incr`> and the
                   2196:  blocks according to a loop from <`start_block`> to <`end_block`> with
                   2197:  increment <`block_incr`>.
                   2198:
                   2199:  The first datum in each block is numbered '0', as is the first block in the
                   2200:  file.
                   2201:
                   2202:  Note that records containing unplottable information are counted.
                   2203:
                   2204:  Any of the numbers can be omitted; the increments default to unity, the start
                   2205:  values to the first point or block, and the end values to the last point or
                   2206:  block.  If `every` is not specified, all points in all lines are plotted.
                   2207:
                   2208:  Examples:
                   2209:        every :::3::3    # selects just the fourth block ('0' is first)
                   2210:        every :::::9     # selects the first 10 blocks
                   2211:        every 2:2        # selects every other point in every other block
                   2212:        every ::5::15    # selects points 5 through 15 in each block
1.1.1.2   maekawa  2213: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/simple.html">Simple Plot Demos </a>,
1.1       maekawa  2214: ^ <a href="http://www.nas.nasa.gov/~woo/gnuplot/surfacea/surfacea.html">Non-parametric splot demos </a>, and
                   2215: ^ <a href="http://www.nas.nasa.gov/~woo/gnuplot/surfaceb/surfaceb.html">Parametric splot demos.</a>
                   2216: 4 example datafile
                   2217: ?commands plot datafile example
                   2218: ?plot datafile example
                   2219: ?plot example
                   2220: ?datafile example
                   2221: ?data-file example
                   2222: ?example
                   2223:  This example plots the data in the file "population.dat" and a theoretical
                   2224:  curve:
                   2225:
                   2226:        pop(x) = 103*exp((1965-x)/10)
                   2227:        plot [1960:1990] 'population.dat', pop(x)
                   2228:
                   2229:  The file "population.dat" might contain:
                   2230:
                   2231:        # Gnu population in Antarctica since 1965
                   2232:           1965   103
                   2233:           1970   55
                   2234:           1975   34
                   2235:           1980   24
                   2236:           1985   10
                   2237:
                   2238: ^ <img align=bottom src="http://www.nas.nasa.gov/~woo/gnuplot/doc/population.gif" alt="[population.gif]" width=640 height=480>
                   2239: 4 index
                   2240: ?commands plot datafile index
                   2241: ?plot datafile index
                   2242: ?plot index
                   2243: ?data-file index
                   2244: ?datafile index
                   2245: ?index
                   2246:  The `index` keyword allows only some of the data sets in a multi-data-set
                   2247:  file to be plotted.
                   2248:
                   2249:  Syntax:
                   2250:        plot 'file' index <m>{{:<n>}:<p>}
                   2251:
                   2252:  Data sets are separated by pairs of blank records.  `index <m>` selects only
                   2253:  set <m>; `index <m>:<n>` selects sets in the range <m> to <n>; and `index
                   2254:  <m>:<n>:<p>` selects indices <m>, <m>+<p>, <m>+2<p>, etc., but stopping at
                   2255:  <n>.  Following C indexing, the index 0 is assigned to the first data set in
                   2256:  the file.  Specifying too large an index results in an error message.  If
                   2257:  `index` is not specified, all sets are plotted as a single data set.
                   2258:
                   2259:  Example:
                   2260:        plot 'file' index 4:5
1.1.1.2   maekawa  2261: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/multimsh.html"> splot with indices demo. </a>
1.1       maekawa  2262: 4 smooth
                   2263: ?commands plot datafile smooth
                   2264: ?plot datafile smooth
                   2265: ?plot smooth
                   2266: ?data-file smooth
                   2267: ?datafile smooth
                   2268: ?smooth
                   2269:  `gnuplot` includes a few general-purpose routines for interpolation and
                   2270:  approximation of data; these are grouped under the `smooth` option.  More
                   2271:  sophisticated data processing may be performed by preprocessing the data
                   2272:  externally or by using `fit` with an appropriate model.
                   2273:
                   2274:  Syntax:
                   2275:        smooth {unique | csplines | acsplines | bezier | sbezier}
                   2276:
                   2277:  `unique` plots the data after making them monotonic.  Each of the other
                   2278:  routines uses the data to determine the coefficients of a continuous curve
                   2279:  between the endpoints of the data.  This curve is then plotted in the same
                   2280:  manner as a function, that is, by finding its value at uniform intervals
                   2281:  along the abscissa (see `set samples`) and connecting these points with
                   2282:  straight line segments (if a line style is chosen).
                   2283:
                   2284:  If `autoscale` is in effect, the ranges will be computed such that the
                   2285:  plotted curve lies within the borders of the graph.
                   2286:
                   2287:  If too few points are available to allow the selected option to be applied,
                   2288:  an error message is produced.  The minimum number is one for `unique`, four
                   2289:  for `acsplines`, and three for the others.
                   2290:
                   2291:  The `smooth` options have no effect on function plots.
                   2292: 5 acsplines
                   2293: ?commands plot datafile smooth acsplines
                   2294: ?plot datafile smooth acsplines
                   2295: ?data-file smooth acsplines
                   2296: ?datafile smooth acsplines
                   2297: ?plot smooth acsplines
                   2298: ?plot acsplines
                   2299: ?smooth acsplines
                   2300: ?acsplines
                   2301:  The `acsplines` option approximates the data with a "natural smoothing spline".
                   2302:  After the data are made monotonic in x (see `smooth unique`), a curve is
                   2303:  piecewise constructed from segments of cubic polynomials whose coefficients
                   2304:  are found by the weighting the data points; the weights are taken from the
                   2305:  third column in the data file.  That default can be modified by the third
                   2306:  entry in the `using` list, e.g.,
                   2307:        plot 'data-file' using 1:2:(1.0) smooth acsplines
                   2308:
                   2309:  Qualitatively, the absolute magnitude of the weights determines the number
                   2310:  of segments used to construct the curve.  If the weights are large, the
                   2311:  effect of each datum is large and the curve approaches that produced by
                   2312:  connecting consecutive points with natural cubic splines.  If the weights are
                   2313:  small, the curve is composed of fewer segments and thus is smoother; the
                   2314:  limiting case is the single segment produced by a weighted linear least
                   2315:  squares fit to all the data.  The smoothing weight can be expressed in terms
                   2316:  of errors as a statistical weight for a point divided by a "smoothing factor"
                   2317:  for the curve so that (standard) errors in the file can be used as smoothing
                   2318:  weights.
                   2319:
                   2320:  Example:
                   2321:        sw(x,S)=1/(x*x*S)
                   2322:        plot 'data_file' using 1:2:(sw($3,100)) smooth acsplines
                   2323: 5 bezier
                   2324: ?commands plot datafile smooth bezier
                   2325: ?plot datafile smooth bezier
                   2326: ?plot smooth bezier
                   2327: ?data-file smooth bezier
                   2328: ?datafile smooth bezier
                   2329: ?plot bezier
                   2330: ?smooth bezier
                   2331: ?bezier
                   2332:  The `bezier` option approximates the data with a Bezier curve of degree n
                   2333:  (the number of data points) that connects the endpoints.
                   2334: 5 csplines
                   2335: ?commands plot datafile smooth csplines
                   2336: ?plot datafile smooth csplines
                   2337: ?plot smooth csplines
                   2338: ?data-file smooth csplines
                   2339: ?datafile smooth csplines
                   2340: ?plot csplines
                   2341: ?smooth csplines
                   2342: ?csplines
                   2343:  The `csplines` option connects consecutive points by natural cubic splines
                   2344:  after rendering the data monotonic (see `smooth unique`).
                   2345: 5 sbezier
                   2346: ?commands plot datafile smooth sbezier
                   2347: ?plot datafile smooth sbezier
                   2348: ?plot smooth sbezier
                   2349: ?data-file smooth sbezier
                   2350: ?datafile smooth sbezier
                   2351: ?plot sbezier
                   2352: ?smooth sbezier
                   2353: ?sbezier
                   2354:  The `sbezier` option first renders the data monotonic (`unique`) and then
                   2355:  applies the `bezier` algorithm.
                   2356: 5 unique
                   2357: ?commands plot datafile smooth unique
                   2358: ?plot datafile smooth unique
                   2359: ?plot smooth unique
                   2360: ?data-file smooth unique
                   2361: ?datafile smooth unique
                   2362: ?plot unique
                   2363: ?smooth unique
                   2364: ?unique
                   2365:  The `unique` option makes the data monotonic in x; points with the same
                   2366:  x-value are replaced by a single point having the average y-value.  The
                   2367:  resulting points are then connected by straight line segments.
1.1.1.2   maekawa  2368: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/mgr.html"> See demos. </a>
1.1       maekawa  2369: 4 special-filenames
                   2370: ?commands plot datafile special-filenames
                   2371: ?plot datafile special-filenames
                   2372: ?plot special-filenames
                   2373: ?datafile special-filenames
                   2374: ?special-filenames
                   2375:  A special filename of `'-'` specifies that the data are inline; i.e., they
                   2376:  follow the command.  Only the data follow the command; `plot` options like
                   2377:  filters, titles, and line styles remain on the 'plot' command line.  This is
                   2378:  similar to << in unix shell script, and $DECK in VMS DCL.  The data are
                   2379:  entered as though they are being read from a file, one data point per record.
                   2380:  The letter "e" at the start of the first column terminates data entry.  The
                   2381:  `using` option can be applied to these data---using it to filter them through
                   2382:  a function might make sense, but selecting columns probably doesn't!
                   2383:
                   2384:  `'-'` is intended for situations where it is useful to have data and commands
                   2385:  together, e.g., when `gnuplot` is run as a sub-process of some front-end
                   2386:  application.  Some of the demos, for example, might use this feature.  While
                   2387:  `plot` options such as `index` and `every` are recognized, their use forces
                   2388:  you to enter data that won't be used.  For example, while
                   2389:
                   2390:        plot '-' index 0, '-' index 1
                   2391:        2
                   2392:        4
                   2393:        6
                   2394:
                   2395:
                   2396:        10
                   2397:        12
                   2398:        14
                   2399:        e
                   2400:        2
                   2401:        4
                   2402:        6
                   2403:
                   2404:
                   2405:        10
                   2406:        12
                   2407:        14
                   2408:        e
                   2409:
                   2410:  does indeed work,
                   2411:
                   2412:        plot '-', '-'
                   2413:        2
                   2414:        4
                   2415:        6
                   2416:        e
                   2417:        10
                   2418:        12
                   2419:        14
                   2420:        e
                   2421:
                   2422:  is a lot easier to type.
                   2423:
                   2424:  If you use `'-'` with `replot`, you may need to enter the data more than once
                   2425:  (see `replot`).
                   2426:
                   2427:  A blank filename ('') specifies that the previous filename should be reused.
                   2428:  This can be useful with things like
                   2429:
                   2430:        plot 'a/very/long/filename' using 1:2, '' using 1:3, '' using 1:4
                   2431:
                   2432:  (If you use both `'-'` and `''` on the same `plot` command, you'll need to
                   2433:  have two sets of inline data, as in the example above.)
                   2434:
                   2435:  On some computer systems with a popen function (Unix), the datafile can be
                   2436:  piped through a shell command by starting the file name with a '<'.  For
                   2437:  example,
                   2438:
                   2439:        pop(x) = 103*exp(-x/10)
                   2440:        plot "< awk '{print $1-1965, $2}' population.dat", pop(x)
                   2441:
                   2442:  would plot the same information as the first population example but with
                   2443:  years since 1965 as the x axis.  If you want to execute this example, you
                   2444:  have to delete all comments from the data file above or substitute the
                   2445:  following command for the first part of the command above (the part up to
                   2446:  the comma):
                   2447:
                   2448:        plot "< awk '$0 !~ /^#/ {print $1-1965, $2}' population.dat"
                   2449:
                   2450:  While this approach is most flexible, it is possible to achieve simple
                   2451:  filtering with the `using` or `thru` keywords.
                   2452: 4 thru
                   2453: ?commands plot datafile thru
                   2454: ?plot datafile thru
                   2455: ?plot thru
                   2456: ?data-file thru
                   2457: ?datafile thru
                   2458: ?thru
                   2459:  The `thru` function is provided for backward compatibility.
                   2460:
                   2461:  Syntax:
                   2462:        plot 'file' thru f(x)
                   2463:
                   2464:  It is equivalent to:
                   2465:
                   2466:        plot 'file' using 1:(f($2))
                   2467:
                   2468:  While the latter appears more complex, it is much more flexible.  The more
                   2469:  natural
                   2470:
                   2471:        plot 'file' thru f(y)
                   2472:
                   2473:  also works (i.e. you can use y as the dummy variable).
                   2474:
                   2475:  `thru` is parsed for `splot` and `fit` but has no effect.
                   2476: 4 using
                   2477: ?commands plot datafile using
                   2478: ?plot datafile using
                   2479: ?plot using
                   2480: ?data-file using
                   2481: ?datafile using
                   2482: ?using
                   2483:  The most common datafile modifier is `using`.
                   2484:
                   2485:  Syntax:
                   2486:        plot 'file' using {<entry> {:<entry> {:<entry> ...}}} {'format'}
                   2487:
                   2488:  If a format is specified, each datafile record is read using the C library's
                   2489:  'scanf' function, with the specified format string.  Otherwise the record is
                   2490:  read and broken into columns at spaces or tabs.  A format cannot be specified
                   2491:  if time-format data is being used (this must be done by `set data time`).
                   2492:
                   2493:  The resulting array of data is then sorted into columns according to the
                   2494:  entries.  Each <entry> may be a simple column number, which selects the
                   2495:  datum, an expression enclosed in parentheses, or empty.  The expression can
                   2496:  use $1 to access the first item read, $2 for the second item, and so on.  It
                   2497:  can also use `column(x)` and `valid(x)` where x is an arbitrary expression
                   2498:  resulting in an integer.  `column(x)` returns the x'th datum; `valid(x)`
                   2499:  tests that the datum in the x'th column is a valid number.  A column number
                   2500:  of 0 generates a number increasing (from zero) with each point, and is reset
                   2501:  upon encountering two blank records.  A column number of -1 gives the
                   2502:  dataline number, which starts at 0, increments at single blank records, and
                   2503:  is reset at double blank records.  A column number of -2 gives the index
                   2504:  number, which is incremented only when two blank records are found.  An empty
                   2505:  <entry> will default to its order in the list of entries.  For example,
                   2506:  `using ::4` is interpreted as `using 1:2:4`.
                   2507:
                   2508:  N.B.---the `call` command also uses $'s as a special character.  See `call`
                   2509:  for details about how to include a column number in a `call` argument list.
                   2510:
                   2511:  If the `using` list has but a single entry, that <entry> will be used for y
                   2512:  and the data point number is used for x; for example, "`plot 'file' using 1`"
                   2513:  is identical to "`plot 'file' using 0:1`".  If the `using` list has two
                   2514:  entries, these will be used for x and y.  Additional entries are usually
                   2515:  errors in x and/or y.  See `set style` for details about plotting styles that
                   2516:  make use of error information, and `fit` for use of error information in
                   2517:  curve fitting.
                   2518:
                   2519:  'scanf' accepts several numerical specifications but `gnuplot` requires all
                   2520:  inputs to be double-precision floating-point variables, so `lf` is the only
                   2521:  permissible specifier.  'scanf' expects to see white space---a blank, tab
                   2522:  ("\t"), newline ("\n"), or formfeed ("\f")---between numbers; anything else
                   2523:  in the input stream must be explicitly skipped.
                   2524:
                   2525:  Note that the use of "\t", "\n", or "\f" or requires use of double-quotes
                   2526:  rather than single-quotes.
                   2527:
                   2528:  Examples:
                   2529:
                   2530:  This creates a plot of the sum of the 2nd and 3rd data against the first:
                   2531:  (The format string specifies comma- rather than space-separated columns.)
                   2532:        plot 'file' using 1:($2+$3) '%lf,%lf,%lf'
                   2533:
                   2534:  In this example the data are read from the file "MyData" using a more
                   2535:  complicated format:
                   2536:        plot 'MyData' using "%*lf%lf%*20[^\n]%lf"
                   2537:
                   2538:  The meaning of this format is:
                   2539:
                   2540:        %*lf        ignore a number
                   2541:        %lf         read a double-precision number (x by default)
                   2542:        %*20[^\n]   ignore 20 non-newline characters
                   2543:        %lf         read a double-precision number (y by default)
                   2544:
                   2545:  One trick is to use the ternary `?:` operator to filter data:
                   2546:
                   2547:        plot 'file' using 1:($3>10 ? $2 : 1/0)
                   2548:
                   2549:  which plots the datum in column two against that in column one provided
                   2550:  the datum in column three exceeds ten.  `1/0` is undefined; `gnuplot`
                   2551:  quietly ignores undefined points, so unsuitable points are suppressed.
                   2552:
                   2553:  In fact, you can use a constant expression for the column number, provided it
                   2554:  doesn't start with an opening parenthesis; constructs like `using
                   2555:  0+(complicated expression)` can be used.  The crucial point is that the
                   2556:  expression is evaluated once if it doesn't start with a left parenthesis, or
                   2557:  once for each data point read if it does.
                   2558:
                   2559:  If timeseries data are being used, the time can span multiple columns.  The
                   2560:  starting column should be specified.  Note that the spaces within the time
                   2561:  must be included when calculating starting columns for other data.  E.g., if
                   2562:  the first element on a line is a time with an embedded space, the y value
                   2563:  should be specified as column three.
                   2564:
                   2565:  It should be noted that `plot 'file'`, `plot 'file' using 1:2`, and `plot
                   2566:  'file' using ($1):($2)` can be subtly different: 1) if `file` has some lines
                   2567:  with one column and some with two, the first will invent x values when they
                   2568:  are missing, the second will quietly ignore the lines with one column, and
                   2569:  the third will store an undefined value for lines with one point (so that in
                   2570:  a plot with lines, no line joins points across the bad point); 2) if a line
                   2571:  contains text at the first column, the first will abort the plot on an error,
                   2572:  but the second and third should quietly skip the garbage.
                   2573:
                   2574:  In fact, it is often possible to plot a file with lots of lines of garbage at
                   2575:  the top simply by specifying
                   2576:
                   2577:        plot 'file' using 1:2
                   2578:
                   2579:  However, if you want to leave text in your data files, it is safer to put the
                   2580:  comment character (#) in the first column of the text lines.
1.1.1.2   maekawa  2581: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/using.html"> Feeble using demos. </a>
1.1       maekawa  2582: 3 errorbars
                   2583: ?commands plot errorbars
                   2584: ?commands splot errorbars
                   2585: ?plot errorbars
                   2586: ?splot errorbars
                   2587: ?errorbars
                   2588:  Error bars are supported for 2-d data file plots by reading one to four
                   2589:  additional columns (or `using` entries); these additional values are used in
                   2590:  different ways by the various errorbar styles.
                   2591:
                   2592:  In the default situation, `gnuplot` expects to see three, four, or six
                   2593:  numbers on each line of the data file---either
                   2594:
                   2595:        (x, y, ydelta),
                   2596:        (x, y, ylow, yhigh),
                   2597:        (x, y, xdelta),
                   2598:        (x, y, xlow, xhigh),
                   2599:        (x, y, xdelta, ydelta), or
                   2600:        (x, y, xlow, xhigh, ylow, yhigh).
                   2601:
                   2602:  The x coordinate must be specified.  The order of the numbers must be
                   2603:  exactly as given above, though the `using` qualifier can manipulate the order
                   2604:  and provide values for missing columns.  For example,
                   2605:
                   2606:        plot 'file' with errorbars
                   2607:        plot 'file' using 1:2:(sqrt($1)) with xerrorbars
                   2608:        plot 'file' using 1:2:($1-$3):($1+$3):4:5 with xyerrorbars
                   2609:
                   2610:  The last example is for a file containing an unsupported combination of
                   2611:  relative x and absolute y errors.  The `using` entry generates absolute x min
                   2612:  and max from the relative error.
                   2613:
                   2614:  The y error bar is a vertical line plotted from (x, ylow) to (x, yhigh).
                   2615:  If ydelta is specified instead of ylow and yhigh, ylow = y - ydelta and
                   2616:  yhigh = y + ydelta are derived.  If there are only two numbers on the record,
                   2617:  yhigh and ylow are both set to y.  The x error bar is a horizontal line
                   2618:  computed in the same fashion.  To get lines plotted between the data points,
                   2619:  `plot` the data file twice, once with errorbars and once with lines (but
                   2620:  remember to use the `notitle` option on one to avoid two entries in the key).
                   2621:
                   2622:  The error bars have crossbars at each end unless `set bar` is used (see `set
                   2623:  bar` for details).
                   2624:
                   2625:  If autoscaling is on, the ranges will be adjusted to include the error bars.
                   2626: ^ <a href="http://www.nas.nasa.gov/~woo/gnuplot/errorbar/errorbar.html"> Errorbar demos. </a>
                   2627:
                   2628:  See `plot using`, `plot with`, and `set style` for more information.
                   2629: 3 parametric
                   2630: ?commands plot parametric
                   2631: ?commands splot parametric
                   2632: ?plot parametric
                   2633: ?splot parametric
                   2634: ?parametric
                   2635:  When in parametric mode (`set parametric`) mathematical expressions must be
                   2636:  given in pairs for `plot` and in triplets for `splot`.
                   2637:
                   2638:  Examples:
                   2639:        plot sin(t),t**2
                   2640:        splot cos(u)*cos(v),cos(u)*sin(v),sin(u)
                   2641:
                   2642:  Data files are plotted as before, except any preceding parametric function
                   2643:  must be fully specified before a data file is given as a plot.  In other
                   2644:  words, the x parametric function (`sin(t)` above) and the y parametric
                   2645:  function (`t**2` above) must not be interrupted with any modifiers or data
                   2646:  functions; doing so will generate a syntax error stating that the parametric
                   2647:  function is not fully specified.
                   2648:
                   2649:  Other modifiers, such as `with` and `title`, may be specified only after the
                   2650:  parametric function has been completed:
                   2651:
                   2652:        plot sin(t),t**2 title 'Parametric example' with linespoints
1.1.1.2   maekawa  2653: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/param.html"> Parametric Mode Demos. </a>
1.1       maekawa  2654: 3 ranges
                   2655: ?commands plot ranges
                   2656: ?commands splot ranges
                   2657: ?plot ranges
                   2658: ?splot ranges
                   2659: ?ranges
                   2660:  The optional ranges specify the region of the graph that will be displayed.
                   2661:
                   2662:  Syntax:
                   2663:        [{<dummy-var>=}{{<min>}:{<max>}}]
                   2664:        [{{<min>}:{<max>}}]
                   2665:
                   2666:  The first form applies to the independent variable (`xrange` or `trange`, if
                   2667:  in parametric mode).  The second form applies to the dependent variable
                   2668:  `yrange` (and `xrange`, too, if in parametric mode).  <dummy-var> is a new
                   2669:  name for the independent variable.  (The defaults may be changed with `set
                   2670:  dummy`.)  The optional <min> and <max> terms can be constant expressions or *.
                   2671:
                   2672:  In non-parametric mode, the order in which ranges must be given is `xrange`
                   2673:  and `yrange`.
                   2674:
                   2675:  In parametric mode, the order for the `plot` command is `trange`, `xrange`,
                   2676:  and `yrange`.  The following `plot` command shows setting the `trange` to
                   2677:  [-pi:pi], the `xrange` to [-1.3:1.3] and the `yrange` to [-1:1] for the
                   2678:  duration of the graph:
                   2679:
                   2680:        plot [-pi:pi] [-1.3:1.3] [-1:1] sin(t),t**2
                   2681:
                   2682:  Note that the x2range and y2range cannot be specified here---`set x2range`
                   2683:  and `set y2range` must be used.
                   2684:
                   2685:  Ranges are interpreted in the order listed above for the appropriate mode.
                   2686:  Once all those needed are specified, no further ones must be listed, but
                   2687:  unneeded ones cannot be skipped---use an empty range `[]` as a placeholder.
                   2688:
                   2689:  `*` can be used to allow autoscaling of either of min and max.  See also
                   2690:  `set autoscale`.
                   2691:
                   2692:  Ranges specified on the `plot` or `splot` command line affect only that
                   2693:  graph; use the `set xrange`, `set yrange`, etc., commands to change the
                   2694:  default ranges for future graphs.
                   2695:
                   2696:  With time data, you must provide the range (in the same manner as the time
                   2697:  appears in the datafile) within quotes.  `gnuplot` uses the `timefmt` string
                   2698:  to read the value---see `set timefmt`.
                   2699:
                   2700:  Examples:
                   2701:
                   2702:  This uses the current ranges:
                   2703:        plot cos(x)
                   2704:
                   2705:  This sets the x range only:
                   2706:        plot [-10:30] sin(pi*x)/(pi*x)
                   2707:
                   2708:  This is the same, but uses t as the dummy-variable:
                   2709:        plot [t = -10 :30]  sin(pi*t)/(pi*t)
                   2710:
                   2711:  This sets both the x and y ranges:
                   2712:        plot [-pi:pi] [-3:3]  tan(x), 1/x
                   2713:
                   2714:  This sets only the y range, and turns off autoscaling on both axes:
                   2715:        plot [ ] [-2:sin(5)*-8] sin(x)**besj0(x)
                   2716:
                   2717:  This sets xmax and ymin only:
                   2718:        plot [:200] [-pi:]  exp(sin(x))
                   2719:
                   2720:  This sets the x range for a timeseries:
                   2721:        set timefmt "%d/%m/%y %H:%M"
                   2722:        plot ["1/6/93 12:00":"5/6/93 12:00"] 'timedata.dat'
                   2723:
                   2724: ^<a href="http://www.nas.nasa.gov/~woo/gnuplot/ranges/ranges.html"> See Demo. </a>
                   2725: 3 title
                   2726: ?commands plot title
                   2727: ?commands splot title
                   2728: ?plot title
                   2729: ?splot title
                   2730:  A line title for each function and data set appears in the key, accompanied
                   2731:  by a sample of the line and/or symbol used to represent it.  It can be
                   2732:  changed by using the `title` option.
                   2733:
                   2734:  Syntax:
                   2735:        title "<title>" | notitle
                   2736:
                   2737:  where <title> is the new title of the line and must be enclosed in quotes.
                   2738:  The quotes will not be shown in the key.  A special character may be given as
                   2739:  a backslash followed by its octal value ("\345").  The tab character "\t" is
                   2740:  understood.  Note that backslash processing occurs only for strings enclosed
                   2741:  in double quotes---use single quotes to prevent such processing.  The newline
                   2742:  character "\n" is not processed in key entries in either type of string.
                   2743:
                   2744:  The line title and sample can be omitted from the key by using the keyword
                   2745:  `notitle`.  A null title (`title ''`) is equivalent to `notitle`.  If only
                   2746:  the sample is wanted, use one or more blanks (`title ' '`).
                   2747:
                   2748:  By default the line title is the function or file name as it appears on the
                   2749:  `plot` command.  If it is a file name, any datafile modifiers specified will
                   2750:  be included in the default title.
                   2751:
                   2752:  The layout of the key itself (position, title justification, etc.) can be
                   2753:  controlled by `set key`.  Please see `set key` for details.
                   2754:
                   2755:  Examples:
                   2756:
                   2757:  This plots y=x with the title 'x':
                   2758:        plot x
                   2759:
                   2760:  This plots x squared with title "x^2" and file "data.1" with title
                   2761:  "measured data":
                   2762:        plot x**2 title "x^2", 'data.1' t "measured data"
                   2763:
                   2764:  This puts an untitled circular border around a polar graph:
                   2765:        set polar; plot my_function(t), 1 notitle
                   2766: 3 with
                   2767: ?commands plot with
                   2768: ?commands splot with
                   2769: ?commands plot style
                   2770: ?commands splot style
                   2771: ?plot with
                   2772: ?plot style
                   2773: ?splot with
                   2774: ?splot style
                   2775: ?style
                   2776: ?with
                   2777:  Functions and data may be displayed in one of a large number of styles.
                   2778:  The `with` keyword provides the means of selection.
                   2779:
                   2780:  Syntax:
                   2781:        with <style> { {linestyle | ls <line_style>}
                   2782:                       | {{linetype | lt <line_type>}
                   2783:                          {linewidth | lw <line_width>}
                   2784:                          {pointtype | pt <point_type>}
                   2785:                          {pointsize | ps <point_size>}} }
                   2786:
                   2787:  where <style> is either `lines`, `points`, `linespoints`, `impulses`, `dots`,
                   2788:  `steps`, `fsteps`, `histeps`, `errorbars`, `xerrorbars`, `yerrorbars`,
                   2789:  `xyerrorbars`, `boxes`, `boxerrorbars`, `boxxyerrorbars`, `financebars`,
                   2790:  `candlesticks` or `vector`.  Some of these styles require additional
                   2791:  information.  See `set style <style>` for details of each style.
                   2792:
                   2793:  Default styles are chosen with the `set function style` and `set data style`
                   2794:  commands.
                   2795:
                   2796:  By default, each function and data file will use a different line type and
                   2797:  point type, up to the maximum number of available types.  All terminal
                   2798:  drivers support at least six different point types, and re-use them, in
                   2799:  order, if more are required.  The LaTeX driver supplies an additional six
                   2800:  point types (all variants of a circle), and thus will only repeat after 12
                   2801:  curves are plotted with points.  The PostScript drivers (`postscript`)
                   2802:  supplies a total of 64.
                   2803:
                   2804:  If you wish to choose the line or point type for a single plot, <line_type>
                   2805:  and <point_type> may be specified.  These are positive integer constants (or
                   2806:  expressions) that specify the line type and point type to be used for the
                   2807:  plot.  Use `test` to display the types available for your terminal.
                   2808:
                   2809:  You may also scale the line width and point size for a plot by using
                   2810:  <line_width> and <point_size>, which are specified relative to the default
                   2811:  values for each terminal.  The pointsize may also be altered globally---see
                   2812:  `set pointsize` for details.  But note that both <point_size> as set here and
                   2813:  as set by `set pointsize` multiply the default point size---their effects are
                   2814:  not cumulative.  That is, `set pointsize 2; plot x w p ps 3` will use points
                   2815:  three times default size, not six.
                   2816:
                   2817:  If you have defined specific line type/width and point type/size combinations
                   2818:  with `set linestyle`, one of these may be selected by setting <line_style> to
                   2819:  the index of the desired style.
                   2820:
                   2821:  The keywords may be abbreviated as indicated.
                   2822:
                   2823:  Note that the `linewidth` and `pointsize` options are not supported by all
                   2824:  terminals.
                   2825:
                   2826:  Examples:
                   2827:
                   2828:  This plots sin(x) with impulses:
                   2829:        plot sin(x) with impulses
                   2830:
                   2831:  This plots x with points, x**2 with the default:
1.1.1.3 ! ohara    2832:        plot x w points, x**2
1.1       maekawa  2833:
                   2834:  This plots tan(x) with the default function style, file "data.1" with lines:
                   2835:        plot [ ] [-2:5] tan(x), 'data.1' with l
                   2836:
                   2837:  This plots "leastsq.dat" with impulses:
                   2838:        plot 'leastsq.dat' w i
                   2839:
                   2840:  This plots the data file "population" with boxes:
                   2841:        plot 'population' with boxes
                   2842:
                   2843:  This plots "exper.dat" with errorbars and lines connecting the points
                   2844:  (errorbars require three or four columns):
                   2845:        plot 'exper.dat' w lines, 'exper.dat' notitle w errorbars
                   2846:
                   2847:  This plots sin(x) and cos(x) with linespoints, using the same line type but
                   2848:  different point types:
                   2849:        plot sin(x) with linesp lt 1 pt 3, cos(x) with linesp lt 1 pt 4
                   2850:
                   2851:  This plots file "data" with points of type 3 and twice usual size:
                   2852:        plot 'data' with points pointtype 3 pointsize 2
                   2853:
                   2854:  This plots two data sets with lines differing only by weight:
                   2855:        plot 'd1' t "good" w l lt 2 lw 3, 'd2' t "bad" w l lt 2 lw 1
                   2856:
                   2857:  See `set style` to change the default styles.
                   2858: ^ <a href="http://www.nas.nasa.gov/~woo/gnuplot/styles/styles.html"> Styles demos. </a>
                   2859: 2 print
                   2860: ?commands print
                   2861: ?print
                   2862:  The `print` command prints the value of <expression> to the screen.  It is
                   2863:  synonymous with `pause 0`.  <expression> may be anything that `gnuplot` can
                   2864:  evaluate that produces a number, or it can be a string.
                   2865:
                   2866:  Syntax:
                   2867:        print <expression> {, <expression>, ...}
                   2868:
                   2869:  See `expressions`.
                   2870: 2 pwd
                   2871: ?commands pwd
                   2872: ?pwd
                   2873:  The `pwd` command prints the name of the working directory to the screen.
                   2874: 2 quit
                   2875: ?commands quit
                   2876: ?quit
                   2877:  The `exit` and `quit` commands and END-OF-FILE character will exit `gnuplot`.
                   2878:  Each of these commands will clear the output device (as does the `clear`
                   2879:  command) before exiting.
                   2880: 2 replot
                   2881: ?commands replot
                   2882: ?replot
                   2883:  The `replot` command without arguments repeats the last `plot` or `splot`
                   2884:  command.  This can be useful for viewing a plot with different `set` options,
                   2885:  or when generating the same plot for several devices.
                   2886:
                   2887:  Arguments specified after a `replot` command will be added onto the last
                   2888:  `plot` or `splot` command (with an implied ',' separator) before it is
                   2889:  repeated.  `replot` accepts the same arguments as the `plot` and `splot`
                   2890:  commands except that ranges cannot be specified.  Thus you can use `replot`
                   2891:  to plot a function against the second axes if the previous command was `plot`
                   2892:  but not if it was `splot`, and similarly you can use `replot` to add a plot
                   2893:  from a binary file only if the previous command was `splot`.
                   2894:
                   2895:  N.B.---use of
                   2896:
                   2897:        plot '-' ; ... ; replot
                   2898:
                   2899:  is not recommended.  `gnuplot` does not store the inline data internally, so
                   2900:  since `replot` appends new information to the previous `plot` and then
                   2901:  executes the modified command, the `'-'` from the initial `plot` will expect
                   2902:  to read inline data again.
                   2903:
                   2904:  Note that `replot` does not work in `multiplot` mode, since it reproduces
                   2905:  only the last plot rather than the entire screen.
                   2906:
                   2907:  See also `command-line-editing` for ways to edit the last `plot` (`splot`)
                   2908:  command.
                   2909: 2 reread
                   2910: ?commands reread
                   2911: ?reread
                   2912:  The `reread` command causes the current `gnuplot` command file, as specified
                   2913:  by a `load` command or on the command line, to be reset to its starting
                   2914:  point before further commands are read from it.  This essentially implements
                   2915:  an endless loop of the commands from the beginning of the command file to
                   2916:  the `reread` command.  (But this is not necessarily a disaster---`reread` can
                   2917:  be very useful when used in conjunction with `if`.  See `if` for details.)
                   2918:  The `reread` command has no effect if input from standard input.
                   2919:
                   2920:  Examples:
                   2921:
                   2922:  Suppose the file "looper" contains the commands
                   2923:        a=a+1
                   2924:        plot sin(x*a)
                   2925:        pause -1
                   2926:        if(a<5) reread
                   2927:  and from within `gnuplot` you submit the commands
                   2928:        a=0
                   2929:        load 'looper'
                   2930:  The result will be four plots (separated by the `pause` message).
                   2931:
                   2932:  Suppose the file "data" contains six columns of numbers with a total yrange
                   2933:  from 0 to 10; the first is x and the next are five different functions of x.
                   2934:  Suppose also that the file "plotter" contains the commands
                   2935:        c_p = c_p+1
                   2936:        plot "$0" using 1:c_p with lines linetype c_p
                   2937:        if(c_p <  n_p) reread
                   2938:  and from within `gnuplot` you submit the commands
                   2939:        n_p=6
                   2940:        c_p=1
                   2941:        set nokey
                   2942:        set yrange [0:10]
                   2943:        set multiplot
                   2944:        call 'plotter' 'data'
                   2945:        set nomultiplot
                   2946:  The result is a single graph consisting of five plots.  The yrange must be
                   2947:  set explicitly to guarantee that the five separate graphs (drawn on top of
                   2948:  each other in multiplot mode) will have exactly the same axes.  The linetype
                   2949:  must be specified; otherwise all the plots would be drawn with the same type.
1.1.1.2   maekawa  2950: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/animate.html"> Reread Animation Demo</a>
1.1       maekawa  2951: 2 reset
                   2952: ?commands reset
                   2953: ?reset
                   2954:  The `reset` command causes all options that can be set with the `set`
                   2955:  command to take on their default values.  The only exceptions are that the
                   2956:  terminal set with `set term` and the output file set with `set output` are
                   2957:  left unchanged.  This command is useful, e.g., to restore the default
                   2958:  settings at the end of a command file, or to return to a defined state after
                   2959:  lots of settings have been changed within a command file.  Please refer to
                   2960:  the `set` command to see the default values that the various options take.
                   2961: 2 save
                   2962: ?commands save
                   2963: ?save
                   2964:  The `save` command saves user-defined functions, variables, `set` options,
                   2965:  or all three, plus the last `plot` (`splot`) command to the specified file.
                   2966:
                   2967:  Syntax:
                   2968:        save  {<option>} '<filename>'
                   2969:
                   2970:  where <option> is `functions`, `variables` or `set`. If no option is used,
                   2971:  `gnuplot` saves functions, variables, `set` options and the last `plot`
                   2972:  (`splot`) command.
                   2973:
                   2974:  `save`d files are written in text format and may be read by the `load`
                   2975:  command.
                   2976:
                   2977:  The filename must be enclosed in quotes.
                   2978:
                   2979:  Examples:
                   2980:        save 'work.gnu'
                   2981:        save functions 'func.dat'
                   2982:        save var 'var.dat'
                   2983:        save set 'options.dat'
                   2984: 2 set-show
                   2985: ?commands set
                   2986: ?commands show
                   2987: ?set
                   2988: ?show
                   2989: ?show all
                   2990:  The `set` command can be used to sets _lots_ of options.  No screen is
                   2991:  drawn, however, until a `plot`, `splot`, or `replot` command is given.
                   2992:
                   2993:  The `show` command shows their settings;  `show all` shows all the
                   2994:  settings.
                   2995:
                   2996:  If a variable contains time/date data, `show` will display it according to
                   2997:  the format currently defined by `set timefmt`, even if that was not in effect
                   2998:  when the variable was initially defined.
                   2999: 3 angles
                   3000: ?commands set angles
                   3001: ?commands show angles
                   3002: ?set angles
                   3003: ?show angles
                   3004: ?angles
                   3005: ?commands set angles degrees
                   3006: ?set angles degrees
                   3007: ?angles degrees
                   3008: ?degrees
                   3009:  By default, `gnuplot` assumes the independent variable in polar graphs is in
                   3010:  units of radians.  If `set angles degrees` is specified before `set polar`,
                   3011:  then the default range is [0:360] and the independent variable has units of
                   3012:  degrees.  This is particularly useful for plots of data files.  The angle
                   3013:  setting also applies to 3-d mapping as set via the `set mapping` command.
                   3014:
                   3015:  Syntax:
                   3016:        set angles {degrees | radians}
                   3017:        show angles
                   3018:
                   3019:  The angle specified in `set grid polar` is also read and displayed in the
                   3020:  units specified by `set angles`.
                   3021:
                   3022:  `set angles` also affects the arguments of the machine-defined functions
                   3023:  sin(x), cos(x) and tan(x), and the outputs of asin(x), acos(x), atan(x),
                   3024:  atan2(x), and arg(x).  It has no effect on the arguments of hyperbolic
                   3025:  functions or Bessel functions.  However, the output arguments of inverse
                   3026:  hyperbolic functions of complex arguments are affected; if these functions
                   3027:  are used, `set angles radians` must be in effect to maintain consistency
                   3028:  between input and output arguments.
                   3029:
                   3030:        x={1.0,0.1}
                   3031:        set angles radians
                   3032:        y=sinh(x)
                   3033:        print y         #prints {1.16933, 0.154051}
                   3034:        print asinh(y)  #prints {1.0, 0.1}
                   3035:  but
                   3036:        set angles degrees
                   3037:        y=sinh(x)
                   3038:        print y         #prints {1.16933, 0.154051}
                   3039:        print asinh(y)  #prints {57.29578, 5.729578}
1.1.1.2   maekawa  3040: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/poldat.html"> Polar plot using `set angles`. </a>
1.1       maekawa  3041: 3 arrow
                   3042: ?commands set arrow
                   3043: ?commands set noarrow
                   3044: ?commands show arrow
                   3045: ?set arrow
                   3046: ?set noarrow
                   3047: ?show arrow
                   3048: ?arrow
                   3049: ?noarrow
                   3050:  Arbitrary arrows can be placed on a plot using the `set arrow` command.
                   3051:
                   3052:  Syntax:
                   3053:        set arrow {<tag>} {from <position>} {to <position>} {{no}head}
                   3054:                  { {linestyle | ls <line_style>}
                   3055:                    | {linetype | lt <line_type>}
                   3056:                      {linewidth | lw <line_width} }
                   3057:        set noarrow {<tag>}
                   3058:        show arrow
                   3059:
                   3060:  <tag> is an integer that identifies the arrow.  If no tag is given, the
                   3061:  lowest unused tag value is assigned automatically.  The tag can be used to
                   3062:  delete or change a specific arrow.  To change any attribute of an existing
                   3063:  arrow, use the `set arrow` command with the appropriate tag and specify the
                   3064:  parts of the arrow to be changed.
                   3065:
                   3066:  The <position>s are specified by either x,y or x,y,z, and may be preceded by
                   3067:  `first`, `second`, `graph`, or `screen` to select the coordinate system.
                   3068:  Unspecified coordinates default to 0.  The endpoints can be specified in
                   3069:  one of four coordinate systems---`first` or `second` axes, `graph` or
                   3070:  `screen`.  See `coordinates` for details.  A coordinate system specifier
                   3071:  does not carry over from the "from" position to the "to" position.  Arrows
                   3072:  outside the screen boundaries are permitted but may cause device errors.
                   3073:
                   3074:  Specifying `nohead` produces an arrow drawn without a head---a line segment.
                   3075:  This gives you yet another way to draw a line segment on the plot.  By
                   3076:  default, arrows have heads.
                   3077:
                   3078:  The line style may be selected from a user-defined list of line styles (see
                   3079:  `set linestyle`) or may be defined here by providing values for <line_type>
                   3080:  (an index from the default list of styles) and/or <line_width> (which is a
                   3081:  multiplier for the default width).
                   3082:
                   3083:  Note, however, that if a user-defined line style has been selected, its
                   3084:  properties (type and width) cannot be altered merely by issuing another
                   3085:  `set arrow` command with the appropriate index and `lt` or `lw`.
                   3086:
                   3087:  Examples:
                   3088:
                   3089:  To set an arrow pointing from the origin to (1,2) with user-defined style 5,
                   3090:  use:
                   3091:        set arrow to 1,2 ls 5
                   3092:
                   3093:  To set an arrow from bottom left of plotting area to (-5,5,3), and tag the
                   3094:  arrow number 3, use:
                   3095:        set arrow 3 from graph 0,0 to -5,5,3
                   3096:
                   3097:  To change the preceding arrow to end at 1,1,1, without an arrow head and
                   3098:  double its width, use:
                   3099:        set arrow 3 to 1,1,1 nohead lw 2
                   3100:
                   3101:  To draw a vertical line from the bottom to the top of the graph at x=3, use:
                   3102:        set arrow from 3, graph 0 to 3, graph 1 nohead
                   3103:
                   3104:  To delete arrow number 2, use:
                   3105:        set noarrow 2
                   3106:
                   3107:  To delete all arrows, use:
                   3108:        set noarrow
                   3109:
                   3110:  To show all arrows (in tag order), use:
                   3111:        show arrow
                   3112: ^ <a href="http://www.nas.nasa.gov/~woo/gnuplot/arrows/arrows.html"> Arrows Demos. </a>
                   3113: 3 autoscale
                   3114: ?commands set autoscale
                   3115: ?commands set noautoscale
                   3116: ?commands show autoscale
                   3117: ?set autoscale
                   3118: ?set noautoscale
                   3119: ?show autoscale
                   3120: ?autoscale
                   3121: ?noautoscale
                   3122:  Autoscaling may be set individually on the x, y or z axis or globally on all
                   3123:  axes. The default is to autoscale all axes.
                   3124:
                   3125:  Syntax:
                   3126:        set autoscale {<axes>{min|max}}
                   3127:        set noautoscale {<axes>{min|max}}
                   3128:        show autoscale
                   3129:
                   3130:  where <axes> is either `x`, `y`, `z`, `x2`, `y2` or `xy`.  A keyword with
                   3131:  `min` or `max` appended (this cannot be done with `xy`) tells `gnuplot` to
                   3132:  autoscale just the minimum or maximum of that axis.  If no keyword is given,
                   3133:  all axes are autoscaled.
                   3134:
                   3135:  When autoscaling, the axis range is automatically computed and the dependent
                   3136:  axis (y for a `plot` and z for `splot`) is scaled to include the range of the
                   3137:  function or data being plotted.
                   3138:
                   3139:  If autoscaling of the dependent axis (y or z) is not set, the current y or z
                   3140:  range is used.
                   3141:
                   3142:  Autoscaling the independent variables (x for `plot` and x,y for `splot`) is a
                   3143:  request to set the domain to match any data file being plotted.  If there are
                   3144:  no data files, autoscaling an independent variable has no effect.  In other
                   3145:  words, in the absence of a data file, functions alone do not affect the x
                   3146:  range (or the y range if plotting z = f(x,y)).
                   3147:
                   3148:  Please see `set xrange` for additional information about ranges.
                   3149:
                   3150:  The behavior of autoscaling remains consistent in parametric mode, (see `set
                   3151:  parametric`).  However, there are more dependent variables and hence more
                   3152:  control over x, y, and z axis scales.  In parametric mode, the independent or
                   3153:  dummy variable is t for `plot`s and u,v for `splot`s.  `autoscale` in
                   3154:  parametric mode, then, controls all ranges (t, u, v, x, y, and z) and allows
                   3155:  x, y, and z to be fully autoscaled.
                   3156:
                   3157:  Autoscaling works the same way for polar mode as it does for parametric mode
                   3158:  for `plot`, with the extension that in polar mode `set dummy` can be used to
                   3159:  change the independent variable from t (see `set dummy`).
                   3160:
                   3161:  When tics are displayed on second axes but no plot has been specified for
                   3162:  those axes, x2range and y2range are inherited from xrange and yrange.  This
                   3163:  is done _before_ xrange and yrange are autoextended to a whole number of
                   3164:  tics, which can cause unexpected results.
                   3165:
                   3166:  Examples:
                   3167:
                   3168:  This sets autoscaling of the y axis (other axes are not affected):
                   3169:        set autoscale y
                   3170:
                   3171:  This sets autoscaling only for the minimum of the y axis (the maximum of the
                   3172:  y axis and the other axes are not affected):
                   3173:        set autoscale ymin
                   3174:
                   3175:  This sets autoscaling of the x and y axes:
                   3176:        set autoscale xy
                   3177:
                   3178:  This sets autoscaling of the x, y, z, x2 and y2 axes:
                   3179:        set autoscale
                   3180:
                   3181:  This disables autoscaling of the x, y, z, x2 and y2 axes:
                   3182:        set noautoscale
                   3183:
                   3184:  This disables autoscaling of the z axis only:
                   3185:        set noautoscale z
                   3186: 4 parametric mode
                   3187: ?commands set autoscale parametric
                   3188: ?set autoscale parametric
                   3189: ?set autoscale t
                   3190:  When in parametric mode (`set parametric`), the xrange is as fully scalable
                   3191:  as the y range.  In other words, in parametric mode the x axis can be
                   3192:  automatically scaled to fit the range of the parametric function that is
                   3193:  being plotted.  Of course, the y axis can also be automatically scaled just
                   3194:  as in the non-parametric case.  If autoscaling on the x axis is not set, the
                   3195:  current x range is used.
                   3196:
                   3197:  Data files are plotted the same in parametric and non-parametric mode.
                   3198:  However, there is a difference in mixed function and data plots: in
                   3199:  non-parametric mode with autoscaled x, the x range of the datafile controls
                   3200:  the x range of the functions; in parametric mode it has no influence.
                   3201:
                   3202:  For completeness a last command `set autoscale t` is accepted.  However, the
                   3203:  effect of this "scaling" is very minor.  When `gnuplot` determines that the
                   3204:  t range would be empty, it makes a small adjustment if autoscaling is true.
                   3205:  Otherwise, `gnuplot` gives an error.  Such behavior may, in fact, not be very
                   3206:  useful and the command `set autoscale t` is certainly questionable.
                   3207:
                   3208:  `splot` extends the above ideas as you would expect.  If autoscaling is set,
                   3209:  then x, y, and z ranges are computed and each axis scaled to fit the
                   3210:  resulting data.
                   3211: 4 polar mode
                   3212: ?commands set autoscale polar
                   3213: ?set autoscale polar
                   3214: ?set autoscale t
                   3215:  When in polar mode (`set polar`), the xrange and the yrange are both found
                   3216:  from the polar coordinates, and thus they can both be automatically scaled.
                   3217:  In other words, in polar mode both the x and y axes can be automatically
                   3218:  scaled to fit the ranges of the polar function that is being plotted.
                   3219:
                   3220:  When plotting functions in polar mode, the rrange may be autoscaled.  When
                   3221:  plotting data files in polar mode, the trange may also be autoscaled.  Note
                   3222:  that if the trange is contained within one quadrant, autoscaling will produce
                   3223:  a polar plot of only that single quadrant.
                   3224:
                   3225:  Explicitly setting one or two ranges but not others may lead to unexpected
                   3226:  results.
1.1.1.2   maekawa  3227: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/poldat.html"> See polar demos </a>
1.1       maekawa  3228: 3 bar
                   3229: ?commands set bar
                   3230: ?commands show bar
                   3231: ?set bar
                   3232: ?show bar
                   3233:  The `set bar` command controls the tics at the ends of errorbars.
                   3234:
                   3235:  Syntax:
                   3236:        set bar {small | large | <size>}
                   3237:        show bar
                   3238:
                   3239:  `small` is a synonym for 0.0, and `large` for 1.0.
                   3240:  The default is 1.0 if no size is given.
                   3241: 3 bmargin
                   3242: ?commands set bmargin
                   3243: ?set bmargin
                   3244: ?bmargin
                   3245:  The command `set bmargin` sets the size of the bottom margin.  Please see
                   3246:  `set margin` for details.
                   3247: 3 border
                   3248: ?commands set border
                   3249: ?commands set noborder
                   3250: ?commands show border
                   3251: ?set border
                   3252: ?set noborder
                   3253: ?show border
                   3254: ?border
                   3255: ?noborder
                   3256:  The `set border` and `set noborder` commands control the display of the graph
                   3257:  borders for the `plot` and `splot` commands.
                   3258:
                   3259:  Syntax:
                   3260:        set border {<integer> { {linestyle | ls <line_style>}
                   3261:                                | {linetype | lt <line_type> }
                   3262:                                  {linewidth | lw <line_width>} } }
                   3263:        set noborder
                   3264:        show border
                   3265:
                   3266:  The borders are encoded in a 12-bit integer: the bottom four bits control the
                   3267:  border for `plot` and the sides of the base for `splot`; The next four bits
                   3268:  control the verticals in `splot`; the top four bits control the edges on top
                   3269:  of the `splot`.  In detail, the `<integer>` should be the sum of the
                   3270:  appropriate entries from the following table:
                   3271:
                   3272: @start table - first is interactive cleartext form
                   3273:                          plot border     splot         splot
                   3274:            Side          splot base    verticals        top
                   3275:        bottom (south)         1            16           256
                   3276:        left   (west)          2            32           512
                   3277:        top    (north)         4            64          1024
                   3278:        right  (east)          8           128          2048
                   3279: #\begin{tabular}{|cc|ccc|} \hline
                   3280: #\multicolumn{5}{|c|}{Graph Border Encoding} \\ \hline \hline
                   3281: # & & \multicolumn{3}{|c|}{Integer value of selection bit} \\ \cline{3-5}
                   3282: # & & plot border & splot & splot \\
                   3283: #\multicolumn{2}{|c|}{Side}& splot base & verticals & top \\ \hline
                   3284: #bottom & (south) & 1 & 16 & 256 \\
                   3285: #left   & (west)  & 2 & 32 & 512 \\
                   3286: #top    & (north) & 4 & 64 & 1024 \\
                   3287: #right  & (east)  & 8 & 128 & 2048 \\
                   3288: %c c c c c .
                   3289: %@plot border@splot@splot
                   3290: %@splot base@verticals@top
                   3291: %_
                   3292: %bottom (south)@1@16@256
                   3293: %left   (west)@2@32@512
                   3294: %top    (north)@4@64@1024
                   3295: %right  (east)@8@128@2048
                   3296: @end table
                   3297:
                   3298:  The default is 31, which is all four sides for `plot`, and base and z axis
                   3299:  for `splot`.
                   3300:
                   3301:  Using the optional <line_style>, <line_type> and <line_width>
                   3302:  specifiers, the way the border lines are drawn can be influenced
1.1.1.2   maekawa  3303:  (limited by what the current terminal driver supports).  By default,
                   3304:  the border is drawn with twice the usual linewidth.  The <line_width>
                   3305:  specifier scales this default value; for example, `set border 15 lw 2`
                   3306:  will produce a border with four times the usual linewidth.
1.1       maekawa  3307:
                   3308:  Various axes or combinations of axes may be added together in the command.
                   3309:
                   3310:  To have tics on edges other than bottom and left, disable the usual tics and
                   3311:  enable the second axes.
                   3312:
                   3313:  Examples:
                   3314:
                   3315:  Draw all borders:
                   3316:        set border
                   3317:
                   3318:  Draw only the SOUTHWEST borders:
                   3319:        set border 3
                   3320:
                   3321:  Draw a complete box around a `splot`:
                   3322:        set border 4095
                   3323:
                   3324:  Draw a partial box, omitting the front vertical:
                   3325:        set border 127+256+512
                   3326:
                   3327:  Draw only the NORTHEAST borders:
                   3328:        set noxtics; set noytics; set x2tics; set y2tics; set border 12
                   3329:
                   3330: ^ <a href="http://www.nas.nasa.gov/~woo/gnuplot/borders/borders.html"> Borders Demo. </a>
                   3331: 3 boxwidth
                   3332: ?commands set boxwidth
                   3333: ?commands show boxwidth
                   3334: ?set boxwidth
                   3335: ?show boxwidth
                   3336: ?boxwidth
                   3337:  The `set boxwidth` command is used to set the default width of boxes in the
                   3338:  `boxes` and `boxerrorbars` styles.
                   3339:
                   3340:  Syntax:
                   3341:        set boxwidth {<width>}
                   3342:        show boxwidth
                   3343:
                   3344:  If a data file is plotted without the width being specified in the third,
                   3345:  fourth, or fifth column (or `using` entry), or if a function is plotted, the
                   3346:  width of each box is set by the `set boxwidth` command.  (If a width is given
                   3347:  both in the file and by the `set boxwidth` command, the one in the file is
                   3348:  used.)  If the width is not specified in one of these ways, the width of each
                   3349:  box will be calculated automatically so that it touches the adjacent boxes.
                   3350:  In a four-column data set, the fourth column will be interpreted as the box
                   3351:  width unless the width is set to -2.0, in which case the width will be
                   3352:  calculated automatically.  See `set style boxerrorbars` for more details.
                   3353:
                   3354:  To set the box width to automatic use the command
                   3355:        set boxwidth
                   3356:  or, for four-column data,
                   3357:        set boxwidth -2
                   3358:
                   3359:  The same effect can be achieved with the `using` keyword in `plot`:
                   3360:        plot 'file' using 1:2:3:4:(-2)
                   3361: 3 clabel
                   3362: ?commands set clabel
                   3363: ?commands set noclabel
                   3364: ?commands show clabel
                   3365: ?set clabel
                   3366: ?set noclabel
                   3367: ?show clabel
                   3368: ?clabel
                   3369: ?noclabel
                   3370:  `gnuplot` will vary the linetype used for each contour level when clabel is
                   3371:  set.  When this option on (the default), a legend labels each linestyle with
                   3372:  the z level it represents.  It is not possible at present to separate the
                   3373:  contour labels from the surface key.
                   3374:
                   3375:  Syntax:
                   3376:        set clabel {'<format>'}
                   3377:        set noclabel
                   3378:        show clabel
                   3379:
                   3380:  The default for the format string is %8.3g, which gives three decimal places.
                   3381:  This may produce poor label alignment if the key is altered from its default
                   3382:  configuration.
                   3383:
                   3384:  The first contour linetype, or only contour linetype when clabel is off, is
                   3385:  the surface linetype +1; contour points are the same style as surface points.
                   3386:
                   3387:  See also `set contour`.
                   3388: 3 clip
                   3389: ?commands set clip
                   3390: ?commands set noclip
                   3391: ?commands show clip
                   3392: ?set clip
                   3393: ?set noclip
                   3394: ?show clip
                   3395: ?clip
                   3396: ?noclip
                   3397:  `gnuplot` can clip data points and lines that are near the boundaries of a
                   3398:  graph.
                   3399:
                   3400:  Syntax:
                   3401:        set clip <clip-type>
                   3402:        set noclip <clip-type>
                   3403:        show clip
                   3404:
                   3405:  Three clip types are supported by `gnuplot`: `points`, `one`, and `two`.
                   3406:  One, two, or all three clip types may be active for a single graph.
                   3407:
                   3408:  The `points` clip type forces `gnuplot` to clip (actually, not plot at all)
                   3409:  data points that fall within but too close to the boundaries.  This is done
                   3410:  so that large symbols used for points will not extend outside the boundary
                   3411:  lines.  Without clipping points near the boundaries, the plot may look bad.
                   3412:  Adjusting the x and y ranges may give similar results.
                   3413:
                   3414:  Setting the `one` clip type causes `gnuplot` to draw a line segment which has
                   3415:  only one of its two endpoints within the graph.  Only the in-range portion of
                   3416:  the line is drawn.  The alternative is to not draw any portion of the line
                   3417:  segment.
                   3418:
                   3419:  Some lines may have both endpoints out of range, but pass through the graph.
                   3420:  Setting the `two` clip-type allows the visible portion of these lines to be
                   3421:  drawn.
                   3422:
                   3423:  In no case is a line drawn outside the graph.
                   3424:
                   3425:  The defaults are `noclip points`, `clip one`, and `noclip two`.
                   3426:
                   3427:  To check the state of all forms of clipping, use
                   3428:        show clip
                   3429:
                   3430:  For backward compatibility with older versions, the following forms are also
                   3431:  permitted:
                   3432:        set clip
                   3433:        set noclip
                   3434:
                   3435:  `set clip` is synonymous with `set clip points`; `set noclip` turns off all
                   3436:  three types of clipping.
                   3437: 3 cntrparam
                   3438: ?commands set cntrparam
                   3439: ?commands show cntrparam
                   3440: ?set cntrparam
                   3441: ?show cntrparam
                   3442: ?cntrparam
                   3443:  `set cntrparam` controls the generation of contours and their smoothness for
                   3444:  a contour plot. `show contour` displays current settings of `cntrparam` as
                   3445:  well as `contour`.
                   3446:
                   3447:  Syntax:
                   3448:        set cntrparam {  {linear | cubicspline | bspline}
                   3449:                        { points <n>} { order <n> }
                   3450:                        { levels   auto {<n>} | <n>
                   3451:                                 | discrete <z1> {,<z2>{,<z3>...}}
                   3452:                                 | incremental <start>, <incr> {,<end>}
                   3453:                         }
                   3454:                       }
                   3455:        show contour
                   3456:
                   3457:  This command has two functions.  First, it sets the values of z for which
                   3458:  contour points are to be determined (by linear interpolation between data
                   3459:  points or function isosamples.)  Second, it controls the way contours are
                   3460:  drawn between the points determined to be of equal z.  <n> should be an
                   3461:  integral constant expression and <z1>, <z2> ... any constant expressions.
                   3462:  The parameters are:
                   3463:
                   3464:  `linear`, `cubicspline`, `bspline`---Controls type of approximation or
                   3465:  interpolation.  If `linear`, then straight line segments connect points of
                   3466:  equal z magnitude.  If `cubicspline`, then piecewise-linear contours are
                   3467:  interpolated between the same equal z points to form somewhat smoother
                   3468:  contours, but which may undulate.  If `bspline`, a guaranteed-smoother curve
                   3469:  is drawn, which only approximates the position of the points of equal-z.
                   3470:
                   3471:  `points`---Eventually all drawings are done with piecewise-linear strokes.
                   3472:  This number controls the number of line segments used to approximate the
                   3473:  `bspline` or `cubicspline` curve.  Number of cubicspline or bspline
                   3474:  segments (strokes) = `points` * number of linear segments.
                   3475:
                   3476:  `order`---Order of the bspline approximation to be used.  The bigger this
                   3477:  order is, the smoother the resulting contour.  (Of course, higher order
                   3478:  bspline curves will move further away from the original piecewise linear
                   3479:  data.)  This option is relevant for `bspline` mode only.  Allowed values are
                   3480:  integers in the range from 2 (linear) to 10.
                   3481:
                   3482:  `levels`--- Selection of contour levels,  controlled by `auto` (default),
                   3483:  `discrete`, `incremental`, and <n>, number of contour levels, limited to
                   3484:   MAX_DISCRETE_LEVELS as defined in plot.h (30 is standard.)
                   3485:
                   3486:  For `auto`, <n> specifies a nominal number of levels; the actual number will
                   3487:  be adjusted to give simple labels. If the surface is bounded by zmin and zmax,
                   3488:  contours will be generated at integer multiples of dz between zmin and zmax,
                   3489:  where dz is 1, 2, or 5 times some power of ten (like the step between two
                   3490:  tic marks).
                   3491:
                   3492:  For `levels discrete`, contours will be generated at z = <z1>, <z2> ... as
                   3493:  specified; the number of discrete levels sets the number of contour levels.
                   3494:  In `discrete` mode, any `set cntrparms levels <n>` are ignored.
                   3495:
                   3496:  For `incremental`, contours are generated at values of z beginning at <start>
                   3497:  and increasing by <increment>, until the number of contours is reached. <end>
                   3498:  is used to determine the number of contour levels, which will be changed by
                   3499:  any subsequent `set cntrparam levels <n>`.
                   3500:
                   3501:  If the command `set cntrparam` is given without any arguments specified,  the
                   3502:  defaults are used: linear, 5 points, order 4, 5 auto levels.
                   3503:
                   3504:  Examples:
                   3505:        set cntrparam bspline
                   3506:        set cntrparam points 7
                   3507:        set cntrparam order 10
                   3508:
                   3509:  To select levels automatically, 5 if the level increment criteria are met:
                   3510:        set cntrparam levels auto 5
                   3511:
                   3512:  To specify discrete levels at .1, .37, and .9:
                   3513:        set cntrparam levels discrete .1,1/exp(1),.9
                   3514:
                   3515:  To specify levels from 0 to 4 with increment 1:
                   3516:        set cntrparam levels incremental  0,1,4
                   3517:
                   3518:  To set the number of levels to 10 (changing an incremental end or possibly
                   3519:  the number of auto levels):
                   3520:        set cntrparam levels 10
                   3521:
                   3522:  To set the start and increment while retaining the number of levels:
                   3523:        set cntrparam levels incremental 100,50
                   3524:
                   3525:  See also `set contour` for control of where the contours are drawn, and `set
                   3526:  clabel` for control of the format of the contour labels and linetypes.
1.1.1.2   maekawa  3527: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/contours.html">Contours Demo</a> and
                   3528: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/discrete.html">contours with User Defined Levels.</a>
1.1       maekawa  3529: 3 contour
                   3530: ?commands set contour
                   3531: ?commands set nocontour
                   3532: ?commands show contour
                   3533: ?set contour
                   3534: ?set nocontour
                   3535: ?show contour
                   3536: ?contour
                   3537: ?nocontour
                   3538:  `set contour` enables contour drawing for surfaces. This option is available
                   3539:  for `splot` only.
                   3540:
                   3541:  Syntax:
                   3542:        set contour {base | surface | both}
                   3543:        set nocontour
                   3544:        show contour
                   3545:
                   3546:  The three options specify where to draw the contours: `base` draws the
                   3547:  contours on the grid base where the x/ytics are placed, `surface` draws the
                   3548:  contours on the surfaces themselves, and `both` draws the contours on both
                   3549:  the base and the surface.  If no option is provided, the default is `base`.
                   3550:
                   3551:  See also `set cntrparam` for the parameters that affect the drawing of
                   3552:  contours, and `set clabel` for control of labelling of the contours.
                   3553:
                   3554:  The surface can be switched off (see `set surface`), giving a contour-only
                   3555:  graph.  Though it is possible to use `set size` to enlarge the plot to fill
                   3556:  the screen, more control over the output format can be obtained by writing
                   3557:  the contour information to a file, and rereading it as a 2-d datafile plot:
                   3558:
                   3559:        set nosurface
                   3560:        set contour
                   3561:        set cntrparam ...
                   3562:        set term table
                   3563:        set out 'filename'
                   3564:        splot ...
                   3565:        set out
                   3566:        # contour info now in filename
                   3567:        set term <whatever>
                   3568:        plot 'filename'
                   3569:
                   3570:  In order to draw contours, the data should be organized as "grid data".  In
                   3571:  such a file all the points for a single y-isoline are listed, then all the
                   3572:  points for the next y-isoline, and so on.  A single blank line (a line
                   3573:  containing no characters other than blank spaces and a carriage return and/or
                   3574:  a line feed) separates one y-isoline from the next.  See also `splot datafile`.
                   3575:
                   3576:  If contours are desired from non-grid data, `set dgrid3d` can be used to
                   3577:  create an appropriate grid.  See `set dgrid3d` for more information.
1.1.1.2   maekawa  3578: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/contours.html">Contours Demo</a> and
                   3579: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/discrete.html">contours with User Defined Levels.</a>
1.1       maekawa  3580: 3 data style
                   3581: ?commands set data style
                   3582: ?commands show data style
                   3583: ?set data style
                   3584: ?show data style
                   3585: ?data style
                   3586:  The `set data style` command changes the default plotting style for data
                   3587:  plots.
                   3588:
                   3589:  Syntax:
                   3590:        set data style <style-choice>
                   3591:        show data style
                   3592:
                   3593:  See `set style` for the choices.  If no choice is given, the choices are
                   3594:  listed.  `show data style` shows the current default data plotting style.
                   3595: 3 dgrid3d
                   3596: ?commands set dgrid3d
                   3597: ?commands set nodgrid3d
                   3598: ?commands show dgrid3d
                   3599: ?set dgrid3d
                   3600: ?set nodgrid3d
                   3601: ?show dgrid3d
                   3602: ?dgrid3d
                   3603: ?nodgrid3d
                   3604:  The `set dgrid3d` command enables, and can set parameters for, non-grid
                   3605:  to grid data mapping.
                   3606:
                   3607:  Syntax:
                   3608:        set dgrid3d {<row_size>} {,{<col_size>} {,<norm>}}
                   3609:        set nodgrid3d
                   3610:        show dgrid3d
                   3611:
                   3612:  By default `dgrid3d` is disabled.  When enabled, 3-d data read from a file
                   3613:  are always treated as a scattered data set.  A grid with dimensions derived
                   3614:  from a bounding box of the scattered data and size as specified by the
                   3615:  row/col_size parameters is created for plotting and contouring.  The grid
                   3616:  is equally spaced in x (rows) and in y (columns); the z values are computed
                   3617:  as weighted averages of the scattered points' z values.
                   3618:
                   3619:  The third parameter, norm, controls the weighting:  Each data point is
                   3620:  weighted inversely by its distance from the grid point raised to the norm
                   3621:  power.  (Actually, the weights are given by the inverse of dx^norm + dy^norm,
                   3622:  where dx and dy are the components of the separation of the grid point from
                   3623:  each data point.  For some norms that are powers of two, specifically 4, 8,
                   3624:  and 16, the computation is optimized by using the Euclidean distance in the
                   3625:  weight calculation, (dx^2+dx^2)^norm/2.  However, any non-negative integer
                   3626:  can be used.)
                   3627:
                   3628:  The closer the data point is to a grid point, the more effect it has on
                   3629:  that grid point and the larger the value of norm the less effect more
                   3630:  distant data points have on that grid point.
                   3631:
                   3632:  The `dgrid3d` option is a simple low pass filter that converts scattered
                   3633:  data to a grid data set.  More sophisticated approaches to this problem
                   3634:  exist and should be used to preprocess the data outside `gnuplot` if this
                   3635:  simple solution is found inadequate.
                   3636:
                   3637:  (The z values are found by weighting all data points, not by interpolating
                   3638:  between nearby data points;  also edge effects may produce unexpected and/or
                   3639:  undesired results.  In some cases, small norm values produce a grid point
                   3640:  reflecting the average of distant data points rather than a local average,
                   3641:  while large values of norm may produce "steps" with several grid points
                   3642:  having the same value as the closest data point, rather than making a smooth
                   3643:  transition between adjacent data points.  Some areas of a grid may be filled
                   3644:  by extrapolation, to an arbitrary boundary condition.  The variables are
                   3645:  not normalized; consequently the units used for x and y will affect the
                   3646:  relative weights of points in the x and y directions.)
                   3647:
                   3648:  Examples:
                   3649:        set dgrid3d 10,10,1     # defaults
                   3650:        set dgrid3d ,,4
                   3651:
                   3652:  The first specifies that a grid of size 10 by 10 is to be constructed using
                   3653:  a norm value of 1 in the weight computation.  The second only modifies the
                   3654:  norm, changing it to 4.
1.1.1.2   maekawa  3655: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/scatter.html"> Dgrid3d Demo.</a>
1.1       maekawa  3656:
                   3657: 3 dummy
                   3658: ?commands set dummy
                   3659: ?commands show dummy
                   3660: ?set dummy
                   3661: ?show dummy
                   3662: ?dummy
                   3663:  The `set dummy` command changes the default dummy variable names.
                   3664:
                   3665:  Syntax:
                   3666:        set dummy {<dummy-var>} {,<dummy-var>}
                   3667:        show dummy
                   3668:
                   3669:  By default, `gnuplot` assumes that the independent, or "dummy", variable for
                   3670:  the `plot` command is "t" if in parametric or polar mode, or "x" otherwise.
                   3671:  Similarly the independent variables for the `splot` command are "u" and "v"
                   3672:  in parametric mode (`splot` cannot be used in polar mode), or "x" and "y"
                   3673:  otherwise.
                   3674:
                   3675:  It may be more convenient to call a dummy variable by a more physically
                   3676:  meaningful or conventional name.  For example, when plotting time functions:
                   3677:
                   3678:        set dummy t
                   3679:        plot sin(t), cos(t)
                   3680:
                   3681:  At least one dummy variable must be set on the command; `set dummy` by itself
                   3682:  will generate an error message.
                   3683:
                   3684:  Examples:
                   3685:        set dummy u,v
                   3686:        set dummy ,s
                   3687:
                   3688:  The second example sets the second variable to s.
                   3689: 3 encoding
                   3690: ?commands set encoding
                   3691: ?commands show encoding
                   3692: ?set encoding
                   3693: ?show encoding
                   3694: ?encoding
                   3695:  The `set encoding` command selects a character encoding.  Valid values are
                   3696:  `default`, which tells a terminal to use its default; `iso_8859_1` (known in
                   3697:  the PostScript world as `ISO-Latin1`), which is used on many Unix workstations
                   3698:  and with MS-Windows; `cp850`, for OS/2; and `cp437`, for MS-DOS.
                   3699:
                   3700:  Syntax:
                   3701:        set encoding {<value>}
                   3702:        show encoding
                   3703:
                   3704:  Note that encoding is not supported by all terminal drivers and that
                   3705:  the device must be able to produce the desired non-standard characters.
                   3706: 3 format
                   3707: ?commands set format
                   3708: ?commands show format
                   3709: ?set format
                   3710: ?show format
                   3711: ?format
                   3712:  The format of the tic-mark labels can be set with the `set format` command.
                   3713:
                   3714:  Syntax:
                   3715:        set format {<axes>} {"<format-string>"}
                   3716:        set format {<axes>} {'<format-string>'}
                   3717:        show format
                   3718:
                   3719:  where <axes> is either `x`, `y`, `z`, `xy`, `x2`, `y2` or nothing (which is
                   3720:  the same as `xy`).  The length of the string representing a tic mark (after
                   3721:  formatting with 'printf') is restricted to 100 characters.  If the format
                   3722:  string is omitted, the format will be returned to the default "%g".  For
                   3723:  LaTeX users, the format "$%g$" is often desirable.  If the empty string "" is
                   3724:  used, no label will be plotted with each tic, though the tic mark will still
                   3725:  be plotted.  To eliminate all tic marks, use `set noxtics` or `set noytics`.
                   3726:
                   3727:  Newline (\n) is accepted in the format string.  Use double-quotes rather than
                   3728:  single-quotes to enable such interpretation.  See also `syntax`.
                   3729:
                   3730:  The default format for both axes is "%g", but other formats such as "%.2f" or
                   3731:  "%3.0em" are often desirable.  Anything accepted by 'printf' when given a
                   3732:  double precision number, and accepted by the terminal, will work.  Some other
                   3733:  options have been added.  If the format string looks like a floating point
                   3734:  format, then `gnuplot` tries to construct a reasonable format.
                   3735:
                   3736:  Characters not preceded by "%" are printed verbatim.  Thus you can include
                   3737:  spaces and labels in your format string, such as "%g m", which will put " m"
                   3738:  after each number.  If you want "%" itself, double it: "%g %%".
                   3739:
                   3740:  See also `set xtics` for more information about tic labels.
1.1.1.2   maekawa  3741: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/electron.html"> See demo. </a>
1.1       maekawa  3742: 4 format specifiers
                   3743: ?commands set format specifiers
                   3744: ?set format specifiers
                   3745: ?format specifiers
                   3746: ?format_specifiers
                   3747:  The acceptable formats (if not in time/date mode) are:
                   3748:
                   3749: @start table - first is interactive cleartext form
                   3750:        Format       Explanation
                   3751:        %f           floating point notation
                   3752:        %e or %E     exponential notation; an "e" or "E" before the power
                   3753:        %g or %G     the shorter of %e (or %E) and %f
                   3754:        %x or %X     hex
                   3755:        %o or %O     octal
                   3756:        %t           mantissa to base 10
                   3757:        %l           mantissa to base of current logscale
                   3758:        %s           mantissa to base of current logscale; scientific power
                   3759:        %T           power to base 10
                   3760:        %L           power to base of current logscale
                   3761:        %S           scientific power
                   3762:        %c           character replacement for scientific power
                   3763:        %P           multiple of pi
                   3764: #\begin{tabular}{|cl|} \hline
                   3765: #\multicolumn{2}{|c|}{Tic-mark label numerical format specifiers}\\
                   3766: #\hline \hline
                   3767: #Format & Explanation \\ \hline
                   3768: #\verb@%f@ & floating point notation \\
                   3769: #\verb@%e@ or \verb@%E@ & exponential notation; an "e" or "E" before the power \\
                   3770: #\verb@%g@ or \verb@%G@ & the shorter of \verb@%e@ (or \verb@%E@) and \verb@%f@ \\
                   3771: #\verb@%x@ or \verb@%X@ & hex \\
                   3772: #\verb@%o@ or \verb@%O@ & octal \\
                   3773: #\verb@%t@ & mantissa to base 10 \\
                   3774: #\verb@%l@ & mantissa to base of current logscale \\
                   3775: #\verb@%s@ & mantissa to base of current logscale; scientific power \\
                   3776: #\verb@%T@ & power to base 10 \\
                   3777: #\verb@%L@ & power to base of current logscale \\
                   3778: #\verb@%S@ & scientific power \\
                   3779: #\verb@%c@ & character replacement for scientific power \\
                   3780: #\verb@%P@ & multiple of pi \\
                   3781: %c l .
                   3782: %Format@Explanation
                   3783: %_
                   3784: %%f@floating point notation
                   3785: %%e or %E@exponential notation; an "e" or "E" before the power
                   3786: %%g or %G@the shorter of %e (or %E) and %f
                   3787: %%x or %X@hex
                   3788: %%o or %O@octal
                   3789: %%t@mantissa to base 10
                   3790: %%l@mantissa to base of current logscale
                   3791: %%s@mantissa to base of current logscale; scientific power
                   3792: %%T@power to base 10
                   3793: %%L@power to base of current logscale
                   3794: %%S@scientific power
                   3795: %%c@character replacement for scientific power
                   3796: %%P@multiple of pi
                   3797: %_
                   3798: @end table
                   3799:
                   3800:  A 'scientific' power is one such that the exponent is a multiple of three.
                   3801:  Character replacement of scientific powers (`"%c"`) has been implemented
                   3802:  for powers in the range -18 to +18.  For numbers outside of this range the
                   3803:  format reverts to exponential.
                   3804:
                   3805:  Other acceptable modifiers (which come after the "%" but before the format
                   3806:  specifier) are "-", which left-justifies the number; "+", which forces all
                   3807:  numbers to be explicitly signed; "#", which places a decimal point after
                   3808:  floats that have only zeroes following the decimal point; a positive integer,
                   3809:  which defines the field width; "0" (the digit, not the letter) immediately
                   3810:  preceding the field width, which indicates that leading zeroes are to be used
                   3811:  instead of leading blanks; and a decimal point followed by a non-negative
                   3812:  integer, which defines the precision (the minimum number of digits of an
                   3813:  integer, or the number of digits following the decimal point of a float).
                   3814:
                   3815:  Some releases of 'printf' may not support all of these modifiers but may also
                   3816:  support others; in case of doubt, check the appropriate documentation and
                   3817:  then experiment.
                   3818:
                   3819:  Examples:
                   3820:        set format y "%t"; set ytics (5,10)          # "5.0" and "1.0"
                   3821:        set format y "%s"; set ytics (500,1000)      # "500" and "1.0"
                   3822:        set format y "+-12.3f"; set ytics(12345)     # "+12345.000  "
                   3823:        set format y "%.2t*10^%+03T"; set ytic(12345)# "1.23*10^+04"
                   3824:        set format y "%s*10^{%S}"; set ytic(12345)   # "12.345*10^{3}"
                   3825:        set format y "%s %cg"; set ytic(12345)       # "12.345 kg"
                   3826:        set format y "%.0P pi"; set ytic(6.283185)   # "2 pi"
                   3827:        set format y "%.0P%%"; set ytic(50)          # "50%"
                   3828:
                   3829:        set log y 2; set format y '%l'; set ytics (1,2,3)
                   3830:        #displays "1.0", "1.0" and "1.5" (since 3 is 1.5 * 2^1)
                   3831:
                   3832:  There are some problem cases that arise when numbers like 9.999 are printed
                   3833:  with a format that requires both rounding and a power.
                   3834:
                   3835:  If the data type for the axis is time/date, the format string must contain
                   3836:  valid codes for the 'strftime' function (outside of `gnuplot`, type "man
                   3837:  strftime").  See `set timefmt` for a list of the allowed input format codes.
                   3838: 4 time/date specifiers
                   3839: ?commands set format time/date_specifiers
                   3840: ?set format time/date_specifiers
                   3841: ?set time/date_specifiers
                   3842: ?time/date_specifiers
                   3843:  In time/date mode, the acceptable formats are:
                   3844:
                   3845: @start table - first is interactive cleartext form
                   3846:        Format       Explanation
                   3847:        %a           abbreviated name of day of the week
                   3848:        %A           full name of day of the week
                   3849:        %b or %h     abbreviated name of the month
                   3850:        %B           full name of the month
                   3851:        %d           day of the month, 1--31
                   3852:        %D           shorthand for "%m/%d/%y"
                   3853:        %H or %k     hour, 0--24
                   3854:        %I or %l     hour, 0--12
                   3855:        %j           day of the year, 1--366
                   3856:        %m           month, 1--12
                   3857:        %M           minute, 0--60
                   3858:        %p           "am" or "pm"
                   3859:        %r           shorthand for "%I:%M:%S %p"
1.1.1.3 ! ohara    3860:        %R           shorthand for "%H:%M"
1.1       maekawa  3861:        %S           second, 0--60
                   3862:        %T           shorthand for "%H:%M:%S"
                   3863:        %U           week of the year (week starts on Sunday)
                   3864:        %w           day of the week, 0--6 (Sunday = 0)
                   3865:        %W           week of the year (week starts on Monday)
                   3866:        %y           year, 0-99
                   3867:        %Y           year, 4-digit
                   3868: #\begin{tabular}{|cl|} \hline
                   3869: #\multicolumn{2}{|c|}{Tic-mark label Date/Time Format Specifiers}\\
                   3870: #\hline \hline
                   3871: #Format & Explanation \\ \hline
                   3872: #\verb@%a@ & abbreviated name of day of the week \\
                   3873: #\verb@%A@ & full name of day of the week \\
                   3874: #\verb@%b@ or \verb@%h@ & abbreviated name of the month \\
                   3875: #\verb@%B@ & full name of the month \\
                   3876: #\verb@%d@ & day of the month, 1--31 \\
                   3877: #\verb@%D@ & shorthand for \verb@"%m/%d/%y"@ \\
                   3878: #\verb@%H@ or \verb@%k@ & hour, 0--24 \\
                   3879: #\verb@%I@ or \verb@%l@ & hour, 0--12 \\
                   3880: #\verb@%j@ & day of the year, 1--366 \\
                   3881: #\verb@%m@ & month, 1--12 \\
                   3882: #\verb@%M@ & minute, 0--60 \\
                   3883: #\verb@%p@ & "am" or "pm" \\
                   3884: #\verb@%r@ & shorthand for \verb@"%I:%M:%S %p"@ \\
                   3885: #\verb@%R@ & shorthand for \verb@%H:%M"@ \\
                   3886: #\verb@%S@ & second, 0--60 \\
                   3887: #\verb@%T@ & shorthand for \verb@"%H:%M:%S"@ \\
                   3888: #\verb@%U@ & week of the year (week starts on Sunday) \\
                   3889: #\verb@%w@ & day of the week, 0--6 (Sunday = 0) \\
                   3890: #\verb@%W@ & week of the year (week starts on Monday) \\
                   3891: #\verb@%y@ & year, 0-99 \\
                   3892: #\verb@%Y@ & year, 4-digit \\
                   3893: %c l .
                   3894: %Format@Explanation
                   3895: %_
                   3896: %%a@abbreviated name of day of the week
                   3897: %%A@full name of day of the week
                   3898: %%b or %h@abbreviated name of the month
                   3899: %%B@full name of the month
                   3900: %%d@day of the month, 1--31
                   3901: %%D@shorthand for "%m/%d/%y"
                   3902: %%H or %k@hour, 0--24
                   3903: %%I or %l@hour, 0--12
                   3904: %%j@day of the year, 1--366
                   3905: %%m@month, 1--12
                   3906: %%M@minute, 0--60
                   3907: %%p@"am" or "pm"
                   3908: %%r@shorthand for "%I:%M:%S %p"
                   3909: %%R@shorthand for %H:%M"
                   3910: %%S@second, 0--60
                   3911: %%T@shorthand for "%H:%M:%S"
                   3912: %%U@week of the year (week starts on Sunday)
                   3913: %%w@day of the week, 0--6 (Sunday = 0)
                   3914: %%W@week of the year (week starts on Monday)
                   3915: %%y@year, 0-99
                   3916: %%Y@year, 4-digit
                   3917: %_
                   3918: @end table
                   3919:
                   3920:  Except for the non-numerical formats, these may be preceded by a "0" ("zero",
                   3921:  not "oh") to pad the field length with leading zeroes, and a positive digit,
                   3922:  to define the minimum field width (which will be overridden if the specified
                   3923:  width is not large enough to contain the number).  There is a 24-character
                   3924:  limit to the length of the printed text; longer strings will be truncated.
                   3925:
                   3926:  Examples:
                   3927:
                   3928:  Suppose the text is "76/12/25 23:11:11".  Then
                   3929:        set format x                 # defaults to "12/25/76" \n "23:11"
                   3930:        set format x "%A, %d %b %Y"  # "Saturday, 25 Dec 1976"
                   3931:        set format x "%r %d"         # "11:11:11 pm 12/25/76"
                   3932:
                   3933:  Suppose the text is "98/07/06 05:04:03".  Then
                   3934:        set format x "%1y/%2m/%3d %01H:%02M:%03S"  # "98/ 7/  6 5:04:003"
                   3935: 3 function style
                   3936: ?commands set function style
                   3937: ?commands show function style
                   3938: ?set function style
                   3939: ?show function style
                   3940: ?function style
                   3941:  The `set function style` command changes the default plotting style for
                   3942:  function plots.
                   3943:
                   3944:  Syntax:
                   3945:        set function style <style-choice>
                   3946:        show function style
                   3947:
                   3948:  See `set style` for the choices.  If no choice is given, the choices are
                   3949:  listed.  `show function style` shows the current default function plotting
                   3950:  style.
                   3951: 3 functions
                   3952: ?commands show functions
                   3953: ?show functions
                   3954:  The `show functions` command lists all user-defined functions and their
                   3955:  definitions.
                   3956:
                   3957:  Syntax:
                   3958:        show functions
                   3959:
                   3960:  For information about the definition and usage of functions in `gnuplot`,
                   3961:  please see `expressions`.
1.1.1.2   maekawa  3962: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/spline.html"> Splines as User Defined Functions.</a>
                   3963: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/airfoil.html">Use of functions and complex variables for airfoils </a>
1.1       maekawa  3964: 3 grid
                   3965: ?commands set grid
                   3966: ?commands set nogrid
                   3967: ?commands show grid
                   3968: ?set grid
                   3969: ?set nogrid
                   3970: ?show grid
                   3971: ?grid
                   3972: ?nogrid
                   3973:  The `set grid` command allows grid lines to be drawn on the plot.
                   3974:
                   3975:  Syntax:
                   3976:        set grid {{no}{m}xtics} {{no}{m}ytics} {{no}{m}ztics}
                   3977:                 {{no}{m}x2tics} {{no}{m}y2tics}
                   3978:                 {polar {<angle>}}
                   3979:                 { {linestyle <major_linestyle>}
                   3980:                   | {linetype | lt <major_linetype>}
                   3981:                     {linewidth | lw <major_linewidth>}
                   3982:                   { , {linestyle | ls <minor_linestyle>}
                   3983:                       | {linetype | lt <minor_linetype>}
                   3984:                         {linewidth | lw <minor_linewidth>} } }
                   3985:        set nogrid
                   3986:        show grid
                   3987:
                   3988:  The grid can be enabled and disabled for the major and/or minor tic
                   3989:  marks on any axis, and the linetype and linewidth can be specified
                   3990:  for major and minor grid lines, also via a predefined linestyle, as
                   3991:  far as the active terminal driver supports this.
                   3992:
                   3993:  Additionally, a polar grid can be selected for 2-d plots---circles are drawn
                   3994:  to intersect the selected tics, and radial lines are drawn at definable
                   3995:  intervals.  (The interval is given in degrees or radians ,depending on the
                   3996:  `set angles` setting.)  Note that a polar grid is no longer automatically
                   3997:  generated in polar mode.
                   3998:
                   3999:  The pertinent tics must be enabled before `set grid` can draw them; `gnuplot`
                   4000:  will quietly ignore instructions to draw grid lines at non-existent tics, but
                   4001:  they will appear if the tics are subsequently enabled.
                   4002:
                   4003:  If no linetype is specified for the minor gridlines, the same linetype as the
                   4004:  major gridlines is used.  The default polar angle is 30 degrees.
                   4005:
1.1.1.2   maekawa  4006:  By default, grid lines are drawn with half the usual linewidth. The major and
                   4007:  minor linewidth specifiers scale this default value; for example, `set grid
                   4008:  lw .5` will draw grid lines with one quarter the usual linewidth.
                   4009:
1.1       maekawa  4010:  Z grid lines are drawn on the back of the plot.  This looks better if a
                   4011:  partial box is drawn around the plot---see `set border`.
                   4012: 3 hidden3d
                   4013: ?commands set hidden3d
                   4014: ?commands set nohidden3d
                   4015: ?commands show hidden3d
                   4016: ?set hidden3d
                   4017: ?set nohidden3d
                   4018: ?show hidden3d
                   4019: ?hidden3d
                   4020: ?nohidden3d
                   4021:  The `set hidden3d` command enables hidden line removal for surface plotting
                   4022:  (see `splot`).  Some optional features of the underlying algorithm can also
                   4023:  be controlled using this command.
                   4024:
                   4025:  Syntax:
                   4026:        set hidden3d {defaults} |
                   4027:                     { {{offset <offset>} | {nooffset}}
                   4028:                       {trianglepattern <bitpattern>}
                   4029:                       {{undefined <level>} | {noundefined}}
                   4030:                       {{no}altdiagonal}
                   4031:                       {{no}bentover} }
                   4032:        set nohidden3d
                   4033:        show hidden3d
                   4034:
                   4035:  In contrast to the usual display in gnuplot, hidden line removal actually
                   4036:  treats the given function or data grids as real surfaces that can't be seen
                   4037:  through, so parts behind the surface will be hidden by it.  For this to be
                   4038:  possible, the surface needs to have 'grid structure' (see `splot datafile`
                   4039:  about this), and it has to be drawn `with lines` or `with linespoints`.
                   4040:
                   4041:  When `hidden3d` is set, both the hidden portion of the surface and possibly
                   4042:  its contours drawn on the base (see `set contour`) as well as the grid will
                   4043:  be hidden.  Each surface has its hidden parts removed with respect to itself
                   4044:  and to other surfaces, if more than one surface is plotted.  Contours drawn
                   4045:  on the surface (`set contour surface`) don't work.  Labels and arrows are
                   4046:  always visible and are unaffected.  The key is also never hidden by the
                   4047:  surface.
                   4048:
                   4049:  Functions are evaluated at isoline intersections.  The algorithm interpolates
                   4050:  linearly between function points or data points when determining the visible
                   4051:  line segments.  This means that the appearance of a function may be different
                   4052:  when plotted with `hidden3d` than when plotted with `nohidden3d` because in
                   4053:  the latter case functions are evaluated at each sample.  Please see `set
                   4054:  samples` and `set isosamples` for discussion of the difference.
                   4055:
                   4056:  The algorithm used to remove the hidden parts of the surfaces has some
                   4057:  additional features controllable by this command.  Specifying `defaults` will
                   4058:  set them all to their default settings, as detailed below.  If `defaults` is
                   4059:  not given, only explicitly specified options will be influenced: all others
                   4060:  will keep their previous values, so you can turn on/off hidden line removal
                   4061:  via `set {no}hidden3d`, without modifying the set of options you chose.
                   4062:
                   4063:  The first option, `offset`, influences the linestyle used for lines on the
                   4064:  'back' side.  Normally, they are drawn in a linestyle one index number higher
                   4065:  than the one used for the front, to make the two sides of the surface
                   4066:  distinguishable.  You can specify a different line style offset to add
                   4067:  instead of the default 1, by `offset <offset>`.  Option `nooffset` stands for
                   4068:  `offset 0`, making the two sides of the surface use the same linestyle.
                   4069:
                   4070:  Next comes the option `trianglepattern <bitpattern>`.  <bitpattern> must be
                   4071:  a number between 0 and 7, interpreted as a bit pattern.  Each bit determines
                   4072:  the visibility of one edge of the triangles each surface is split up into.
                   4073:  Bit 0 is for the 'horizontal' edges of the grid, Bit 1 for the 'vertical'
                   4074:  ones, and Bit 2 for the diagonals that split each cell of the original grid
                   4075:  into two triangles.  The default pattern is 3, making all horizontal and
                   4076:  vertical lines visible, but not the diagonals.  You may want to choose 7 to
                   4077:  see those diagonals as well.
                   4078:
                   4079:  The `undefined <level>` option lets you decide what the algorithm is to do
                   4080:  with data points that are undefined (missing data, or undefined function
                   4081:  values), or exceed the given x-, y- or z-ranges.  Such points can either be
                   4082:  plotted nevertheless, or taken out of the input data set.  All surface
                   4083:  elements touching a point that is taken out will be taken out as well, thus
                   4084:  creating a hole in the surface.  If <level> = 3, equivalent to option
                   4085:  `noundefined`, no points will be thrown away at all.  This may produce all
                   4086:  kinds of problems elsewhere, so you should avoid this.  <level> = 2 will
                   4087:  throw away undefined points, but keep the out-of-range ones.  <level> = 1,
                   4088:  the default, will get rid of out-of-range points as well.
                   4089:
                   4090:  By specifying `noaltdiagonal`, you can override the default handling of a
                   4091:  special case can occur if `undefined` is active (i.e. <level> is not 3).
                   4092:  Each cell of the grid-structured input surface will be divided in two
                   4093:  triangles along one of its diagonals.  Normally, all these diagonals have
                   4094:  the same orientation relative to the grid.  If exactly one of the four cell
                   4095:  corners is excluded by the `undefined` handler, and this is on the usual
                   4096:  diagonal, both triangles will be excluded.  However if the default setting
                   4097:  of `altdiagonal` is active, the other diagonal will be chosen for this cell
                   4098:  instead, minimizing the size of the hole in the surface.
                   4099:
                   4100:  The `bentover` option controls what happens to another special case, this
                   4101:  time in conjunction with the `trianglepattern`.  For rather crumply surfaces,
                   4102:  it can happen that the two triangles a surface cell is divided into are seen
                   4103:  from opposite sides (i.e. the original quadrangle is 'bent over'), as
                   4104:  illustrated in the following ASCII art:
                   4105:
                   4106:                                                                C----B
                   4107:      original quadrangle:  A--B      displayed quadrangle:     |\   |
                   4108:        ("set view 0,0")    | /|    ("set view 75,75" perhaps)  | \  |
                   4109:                            |/ |                                |  \ |
                   4110:                            C--D                                |   \|
                   4111:                                                                A    D
                   4112:
                   4113:  If the diagonal edges of the surface cells aren't generally made visible by
                   4114:  bit 2 of the <bitpattern> there, the edge CB above wouldn't be drawn at all,
                   4115:  normally, making the resulting display hard to understand.  Therefore, the
                   4116:  default option of `bentover` will turn it visible in this case.  If you don't
                   4117:  want that, you may choose `nobentover` instead.
1.1.1.2   maekawa  4118: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/hidden.html"> Hidden Line Removal Demo</a> and
                   4119: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/singulr.html"> Complex Hidden Line Demo. </a>
1.1       maekawa  4120: 3 isosamples
                   4121: ?commands set isosamples
                   4122: ?commands show isosamples
                   4123: ?set isosamples
                   4124: ?show isosamples
                   4125: ?isosamples
                   4126:  The isoline density (grid) for plotting functions as surfaces may be changed
                   4127:  by the `set isosamples` command.
                   4128:
                   4129:  Syntax:
                   4130:        set isosamples <iso_1> {,<iso_2>}
                   4131:        show isosamples
                   4132:
                   4133:  Each function surface plot will have <iso_1> iso-u lines and <iso_2> iso-v
                   4134:  lines.  If you only specify <iso_1>, <iso_2> will be set to the same value
                   4135:  as <iso_1>.  By default, sampling is set to 10 isolines per u or v axis.
                   4136:  A higher sampling rate will produce more accurate plots, but will take longer.
                   4137:  These parameters have no effect on data file plotting.
                   4138:
                   4139:  An isoline is a curve parameterized by one of the surface parameters while
                   4140:  the other surface parameter is fixed.  Isolines provide a simple means to
                   4141:  display a surface.  By fixing the u parameter of surface s(u,v), the iso-u
                   4142:  lines of the form c(v) = s(u0,v) are produced, and by fixing the v parameter,
                   4143:  the iso-v lines of the form c(u) = s(u,v0) are produced.
                   4144:
                   4145:  When a function surface plot is being done without the removal of hidden
                   4146:  lines, `set samples`  controls the number of points sampled along each
                   4147:  isoline;  see `set samples` and `set hidden3d`.  The contour algorithm
                   4148:  assumes that a function sample occurs at each isoline intersection, so
                   4149:  change in `samples` as well as `isosamples` may be desired when changing
                   4150:  the resolution of a function surface/contour.
                   4151: 3 key
                   4152: ?commands set key
                   4153: ?commands set nokey
                   4154: ?commands show key
                   4155: ?set key
                   4156: ?set nokey
                   4157: ?show key
                   4158: ?key
                   4159: ?nokey
                   4160: ?legend
                   4161:  The `set key` enables a key (or legend) describing plots on a plot.
                   4162:
                   4163:  The contents of the key, i.e., the names given to each plotted data set and
                   4164:  function and samples of the lines and/or symbols used to represent them, are
                   4165:  determined by the `title` and `with` options of the {`s`}`plot` command.
                   4166:  Please see `plot title` and `plot with` for more information.
                   4167:
                   4168:  Syntax:
                   4169:        set key {  left | right | top | bottom | outside | below
                   4170:                 | <position>}
                   4171:                {Left | Right} {{no}reverse}
                   4172:                {samplen <sample_length>} {spacing <vertical_spacing>}
                   4173:                {width <width_increment>}
                   4174:                {title "<text>"}
                   4175:                {{no}box { {linestyle | ls <line_style>}
                   4176:                           | {linetype | lt <line_type>}
                   4177:                             {linewidth | lw <line_width>}}}
                   4178:        set nokey
                   4179:        show key
                   4180:
                   4181:  By default the key is placed in the upper right corner of the graph.  The
                   4182:  keywords `left`, `right`, `top`, `bottom`, `outside` and `below` may be used
                   4183:  to place the key in the other corners inside the graph or to the right
                   4184:  (outside) or below the graph.  They may be given alone or combined.
                   4185:
                   4186:  Justification of the labels within the key is controlled by `Left` or `Right`
                   4187:  (default is `Right`).  The text and sample can be reversed (`reverse`) and a
                   4188:  box can be drawn around the key (`box {...}`) in a specified `linetype`
                   4189:  and `linewidth`, or a user-defined `linestyle`. Note that not all
                   4190:  terminal drivers support linewidth selection, though.
                   4191:
                   4192:  The length of the sample line can be controlled by `samplen`.  The sample
                   4193:  length is computed as the sum of the tic length and <sample_length> times the
                   4194:  character width.  `samplen` also affects the positions of point samples in
                   4195:  the key since these are drawn at the midpoint of the sample line, even if it
                   4196:  is not drawn.  <sample_length> must be an integer.
                   4197:
                   4198:  The vertical spacing between lines is controlled by `spacing`.  The spacing
                   4199:  is set equal to the product of the pointsize, the vertical tic size, and
                   4200:  <vertical_spacing>.  The program will guarantee that the vertical spacing is
                   4201:  no smaller than the character height.
                   4202:
                   4203:  The <width_increment> is a number of character widths to be added to or
                   4204:  subtracted from the length of the string.  This is useful only when you are
                   4205:  putting a box around the key and you are using control characters in the text.
                   4206:  `gnuplot` simply counts the number of characters in the string when computing
                   4207:  the box width; this allows you to correct it.
                   4208:
                   4209:  A title can be put on the key (`title "<text>"`)---see also `syntax` for the
                   4210:  distinction between text in single- or double-quotes.  The key title uses the
                   4211:  same justification as do the plot titles.
                   4212:
                   4213:  The defaults for `set key` are `right`, `top`, `Right`, `noreverse`, `samplen
                   4214:  4`, `spacing 1.25`, `title ""`, and `nobox`.  The default <linetype> is the
                   4215:  same as that used for the plot borders.  Entering `set key` with no options
                   4216:  returns the key to its default configuration.
                   4217:
                   4218:  The <position> can be a simple x,y,z as in previous versions, but these can
                   4219:  be preceded by one of four keywords (`first`, `second`, `graph`, `screen`)
                   4220:  which selects the coordinate system in which the position is specified.  See
                   4221:  `coordinates` for more details.
                   4222:
                   4223:  The key is drawn as a sequence of lines, with one plot described on each
                   4224:  line.  On the right-hand side (or the left-hand side, if `reverse` is
                   4225:  selected) of each line is a representation that attempts to mimic the way the
                   4226:  curve is plotted.  On the other side of each line is the text description
                   4227:  (the line title), obtained from the `plot` command.  The lines are vertically
                   4228:  arranged so that an imaginary straight line divides the left- and right-hand
                   4229:  sides of the key.  It is the coordinates of the top of this line that are
                   4230:  specified with the `set key` command.  In a `plot`, only the x and y
                   4231:  coordinates are used to specify the line position.  For a `splot`, x, y and
                   4232:  z are all used as a 3-d location mapped using the same mapping as the graph
                   4233:  itself to form the required 2-d screen position of the imaginary line.
                   4234:
                   4235:  Some or all of the key may be outside of the graph boundary, although this
                   4236:  may interfere with other labels and may cause an error on some devices.  If
                   4237:  you use the keywords `outside` or `below`, `gnuplot` makes space for the keys
                   4238:  and the graph becomes smaller.  Putting keys outside to the right, they
                   4239:  occupy as few columns as possible, and putting them below, as many columns as
                   4240:  possible (depending of the length of the labels), thus stealing as little
                   4241:  space from the graph as possible.
                   4242:
                   4243:  When using the TeX or PostScript drivers, or similar drivers where formatting
                   4244:  information is embedded in the string, `gnuplot` is unable to calculate
                   4245:  correctly the width of the string for key positioning.  If the key is to be
                   4246:  positioned at the left, it may be convenient to use the combination  `set key
                   4247:  left Left reverse`.  The box and gap in the grid will be the width of the
                   4248:  literal string.
                   4249:
                   4250:  If `splot` is being used to draw contours, the contour labels will be listed
                   4251:  in the key.  If the alignment of these labels is poor or a different number
                   4252:  of decimal places is desired, the label format can be specified.  See `set
                   4253:  clabel` for details.
                   4254:
                   4255:  Examples:
                   4256:
                   4257:  This places the key at the default location:
                   4258:        set key
                   4259:
                   4260:  This disables the key:
                   4261:        set nokey
                   4262:
                   4263:  This places a key at coordinates 2,3.5,2 in the default (first) coordinate
                   4264:  system:
                   4265:        set key 2,3.5,2
                   4266:
                   4267:  This places the key below the graph:
                   4268:        set key below
                   4269:
                   4270:  This places the key in the bottom left corner, left-justifies the text,
                   4271:  gives it a title, and draws a box around it in linetype 3:
                   4272:        set key left bottom Left title 'Legend' box 3
                   4273: 3 label
                   4274: ?commands set label
                   4275: ?commands set nolabel
                   4276: ?commands show label
                   4277: ?set label
                   4278: ?set nolabel
                   4279: ?show label
                   4280: ?label
                   4281: ?nolabel
                   4282:  Arbitrary labels can be placed on the plot using the `set label` command.
                   4283:
                   4284:  Syntax:
                   4285:        set label {<tag>} {"<label_text>"} {at <position>}
                   4286:                  {<justification>} {{no}rotate} {font "<name><,size>"}
                   4287:        set nolabel {<tag>}
                   4288:        show label
                   4289:
                   4290:  The <position> is specified by either x,y or x,y,z, and may be preceded by
                   4291:  `first`, `second`, `graph`, or `screen` to select the coordinate system.
                   4292:  See `coordinates` for details.
                   4293:
                   4294:  The tag is an integer that is used to identify the label. If no <tag> is
                   4295:  given, the lowest unused tag value is assigned automatically.  The tag can be
                   4296:  used to delete or modify a specific label.  To change any attribute of an
                   4297:  existing label, use the `set label` command with the appropriate tag, and
                   4298:  specify the parts of the label to be changed.
                   4299:
                   4300:  By default, the text is placed flush left against the point x,y,z.  To adjust
                   4301:  the way the label is positioned with respect to the point x,y,z, add the
                   4302:  parameter <justification>, which may be `left`, `right` or `center`,
                   4303:  indicating that the point is to be at the left, right or center of the text.
                   4304:  Labels outside the plotted boundaries are permitted but may interfere with
                   4305:  axis labels or other text.
                   4306:
                   4307:  If `rotate` is given, the label is written vertically (if the terminal can do
                   4308:  so, of course).
                   4309:
                   4310:  If one (or more) axis is timeseries, the appropriate coordinate should be
                   4311:  given as a quoted time string according to the `timefmt` format string.  See
                   4312:  `set xdata` and `set timefmt`.
                   4313:
                   4314:  The EEPIC, Imagen, LaTeX, and TPIC drivers allow \\ in a string to specify
                   4315:  a newline.
                   4316:
                   4317:  Examples:
                   4318:
                   4319:  To set a label at (1,2) to "y=x", use:
                   4320:        set label "y=x" at 1,2
                   4321:
                   4322:  To set a Sigma of size 24, from the Symbol font set, at the center of
                   4323:  the graph, use:
                   4324:        set label "S" at graph 0.5,0.5 center font "Symbol,24"
                   4325:
                   4326:  To set a label "y=x^2" with the right of the text at (2,3,4), and tag the
                   4327:  label as number 3, use:
                   4328:        set label 3 "y=x^2" at 2,3,4 right
                   4329:
                   4330:  To change the preceding label to center justification, use:
                   4331:        set label 3 center
                   4332:
                   4333:  To delete label number 2, use:
                   4334:        set nolabel 2
                   4335:
                   4336:  To delete all labels, use:
                   4337:        set nolabel
                   4338:
                   4339:  To show all labels (in tag order), use:
                   4340:        show label
                   4341:
                   4342:  To set a label on a graph with a timeseries on the x axis, use, for example:
                   4343:        set timefmt "%d/%m/%y,%H:%M"
                   4344:        set label "Harvest" at "25/8/93",1
                   4345: 3 linestyle
                   4346: ?commands set linestyle
                   4347: ?commands set nolinestyle
                   4348: ?commands show linestyle
                   4349: ?set linestyle
                   4350: ?set nolinestyle
                   4351: ?show linestyle
                   4352: ?linestyle
                   4353:  Each terminal has a default set of line and point types, which can be seen
                   4354:  by using the command `test`.  `set linestyle` defines a set of line types
                   4355:  and widths and point types and sizes so that you can refer to them later by
                   4356:  an index instead of repeating all the information at each invocation.
                   4357:
                   4358:  Syntax:
                   4359:        set linestyle <index> {linetype | lt <line_type>}
                   4360:                              {linewidth | lw <line_width>}
                   4361:                              {pointtype | pt <point_type>}
                   4362:                              {pointsize | ps <point_size>}
                   4363:        set nolinestyle
                   4364:        show linestyle
                   4365:
                   4366:  The line and point types are taken from the default types for the terminal
                   4367:  currently in use.  The line width and point size are multipliers for the
                   4368:  default width and size (but note that <point_size> here is unaffected by
                   4369:  the multiplier given on 'set pointsize').
                   4370:
                   4371:  The defaults for the line and point types is the index.  The defaults for
                   4372:  the width and size are both unity.
                   4373:
                   4374:  Linestyles created by this mechanism do not replace the default styles;
                   4375:  both may be used.
                   4376:
                   4377:  Not all terminals support the `linewidth` and `pointsize` features; if
                   4378:  not supported, the option will be ignored.
                   4379:
                   4380:  Note that this feature is not completely implemented; linestyles defined by
                   4381:  this mechanism may be used with 'plot', 'splot', 'replot', and 'set arrow',
                   4382:  but not by other commands that allow the default index to be used, such as
                   4383:  'set grid'.
                   4384:
                   4385:  Example:
                   4386:  Suppose that the default lines for indices 1, 2, and 3 are red, green, and
                   4387:  blue, respectively, and the default point shapes for the same indices are a
                   4388:  square, a cross, and a triangle, respectively.  Then
                   4389:
                   4390:        set linestyle 1 lt 2 lw 2 pt 3 ps 0.5
                   4391:
                   4392:  defines a new linestyle that is green and twice the default width and a new
                   4393:  pointstyle that is a half-sized triangle.  The commands
                   4394:
                   4395:        set function style lines
                   4396:        plot f(x) lt 3, g(x) ls 1
                   4397:
                   4398:  will create a plot of f(x) using the default blue line and a plot of g(x)
                   4399:  using the user-defined wide green line.  Similarly the commands
                   4400:
                   4401:        set function style linespoints
                   4402:        plot p(x) lt 1 pt 3, q(x) ls 1
                   4403:
                   4404:  will create a plot of f(x) using the default triangles connected by a red
                   4405:  line and q(x) using small triangles connected by a green line.
                   4406: 3 lmargin
                   4407: ?commands set lmargin
                   4408: ?set lmargin
                   4409: ?lmargin
                   4410:  The command `set lmargin` sets the size of the left margin.  Please see
                   4411:  `set margin` for details.
                   4412: 3 locale
                   4413: ?commands set locale
                   4414: ?commands show logscale
                   4415: ?set locale
                   4416: ?show logscale
                   4417: ?locale
                   4418:  The `locale` setting determines the language with which `{x,y,z}{d,m}tics`
                   4419:  will write the days and months.
                   4420:
                   4421:  Syntax:
                   4422:        set locale {"<locale>"}
                   4423:
                   4424:  <locale> may be any language designation acceptable to your installation.
                   4425:  See your system documentation for the available options.  The default value
                   4426:  is determined from the LANG environment variable.
                   4427: 3 logscale
                   4428: ?commands set logscale
                   4429: ?commands set nologscale
                   4430: ?commands show logscale
                   4431: ?set logscale
                   4432: ?set nologscale
                   4433: ?show logscale
                   4434: ?logscale
                   4435: ?nologscale
                   4436:  Log scaling may be set on the x, y, z, x2 and/or y2 axes.
                   4437:
                   4438:  Syntax:
                   4439:        set logscale <axes> <base>
                   4440:        set nologscale <axes>
                   4441:        show logscale
                   4442:
                   4443:  where <axes> may be any combinations of `x`, `y`, and `z`, in any order, or
                   4444:  `x2` or `y2` and where <base> is the base of the log scaling.  If <base> is
                   4445:  not given, then 10 is assumed.  If <axes> is not given, then all axes are
                   4446:  assumed.  `set nologscale` turns off log scaling for the specified axes.
                   4447:
                   4448:  Examples:
                   4449:
                   4450:  To enable log scaling in both x and z axes:
                   4451:        set logscale xz
                   4452:
                   4453:  To enable scaling log base 2 of the y axis:
                   4454:        set logscale y 2
                   4455:
                   4456:  To disable z axis log scaling:
                   4457:        set nologscale z
                   4458: 3 mapping
                   4459: ?commands set mapping
                   4460: ?commands show mapping
                   4461: ?set mapping
                   4462: ?show mapping
                   4463: ?mapping
                   4464:  If data are provided to `splot` in spherical or cylindrical coordinates,
                   4465:  the `set mapping` command should be used to instruct `gnuplot` how to
                   4466:  interpret them.
                   4467:
                   4468:  Syntax:
                   4469:        set mapping {cartesian | spherical | cylindrical}
                   4470:
                   4471:  A cartesian coordinate system is used by default.
                   4472:
                   4473:  For a spherical coordinate system, the data occupy two or three columns (or
1.1.1.3 ! ohara    4474:  `using` entries).  The first two are interpreted as the azimuthal and polar
1.1       maekawa  4475:  angles theta and phi (in the units specified by `set angles`).  The radius r
                   4476:  is taken from the third column if there is one, or is set to unity if there
                   4477:  is no third column.  The mapping is:
                   4478:
                   4479:        x = r * cos(theta) * cos(phi)
                   4480:        y = r * sin(theta) * cos(phi)
                   4481:        z = r * sin(phi)
                   4482:
                   4483:  Note that this is a "geographic" spherical system, rather than a "polar" one.
                   4484:
                   4485:  For a cylindrical coordinate system, the data again occupy two or three
                   4486:  columns.  The first two are interpreted as theta (in the units specified by
                   4487:  `set angles`) and z.  The radius is either taken from the third column or set
                   4488:  to unity, as in the spherical case.  The mapping is:
                   4489:
                   4490:        x = r * cos(theta)
                   4491:        y = r * sin(theta)
                   4492:        z = z
                   4493:
                   4494:  The effects of `mapping` can be duplicated with the `using` filter on the
                   4495:  `splot` command, but `mapping` may be more convenient if many data files are
                   4496:  to be processed.  However even if `mapping` is used, `using` may still be
                   4497:  necessary if the data in the file are not in the required order.
                   4498:
                   4499:  `mapping` has no effect on `plot`.
1.1.1.2   maekawa  4500: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/world.html">Mapping Demos.</a>
1.1       maekawa  4501: 3 margin
                   4502: ?commands set margin
                   4503: ?commands show margin
                   4504: ?set margin
                   4505: ?show margin
                   4506: ?margin
1.1.1.2   maekawa  4507:  The computed margins can be overridden by the `set margin` commands.  `show
                   4508:  margin` shows the current settings.
1.1       maekawa  4509:
                   4510:  Syntax:
                   4511:        set bmargin {<margin>}
                   4512:        set lmargin {<margin>}
                   4513:        set rmargin {<margin>}
                   4514:        set tmargin {<margin>}
                   4515:        show margin
                   4516:
                   4517:  The units of <margin> are character heights or widths, as appropriate.  A
                   4518:  positive value defines the absolute size of the margin.  A negative value
                   4519:  (or none) causes `gnuplot` to revert to the computed value.
1.1.1.2   maekawa  4520:
                   4521:  Normally the margins of a plot are automatically calculated based on tics,
                   4522:  tic labels, axis labels, the plot title, the timestamp and the size of the
                   4523:  key if it is outside the borders.  If, however, tics are attached to the
                   4524:  axes (`set xtics axis`, for example), neither the tics themselves nor their
                   4525:  labels will be included in either the margin calculation or the calculation
                   4526:  of the positions of other text to be written in the margin.  This can lead
                   4527:  to tic labels overwriting other text if the axis is very close to the border.
1.1       maekawa  4528: 3 missing
                   4529: ?commands set missing
                   4530: ?set missing
                   4531: ?missing
                   4532:  The `set missing` command allows you to tell `gnuplot` what character is
                   4533:  used in a data file to denote missing data.
                   4534:
                   4535:  Syntax:
                   4536:        set missing {"<character>"}
                   4537:        show missing
                   4538:
                   4539:  Example:
                   4540:        set missing "?"
                   4541:
                   4542:  would mean that, when plotting a file containing
                   4543:
                   4544:           1 1
                   4545:           2 ?
                   4546:           3 2
                   4547:
                   4548:  the middle line would be ignored.
                   4549:
                   4550:  There is no default character for `missing`.
                   4551: 3 multiplot
                   4552: ?commands set multiplot
                   4553: ?commands set nomultiplot
                   4554: ?set multiplot
                   4555: ?set nomultiplot
                   4556: ?multiplot
                   4557: ?nomultiplot
                   4558:  The command `set multiplot` places `gnuplot` in the multiplot mode, in which
                   4559:  several plots are placed on the same page, window, or screen.
                   4560:
                   4561:  Syntax:
                   4562:        set multiplot
                   4563:        set nomultiplot
                   4564:
                   4565:  For some terminals, no plot is displayed until the command `set nomultiplot`
                   4566:  is given, which causes the entire page to be drawn and then returns `gnuplot`
                   4567:  to its normal single-plot mode.  For other terminals, each separate `plot`
                   4568:  command produces a plot, but the screen may not be cleared between plots.
                   4569:
                   4570:  Any labels or arrows that have been defined will be drawn for each plot
                   4571:  according to the current size and origin (unless their coordinates are
                   4572:  defined in the `screen` system).  Just about everything else that can be
                   4573:  `set` is applied to each plot, too.  If you want something to appear only
                   4574:  once on the page, for instance a single time stamp, you'll need to put a `set
                   4575:  time`/`set notime` pair around one of the `plot`, `splot` or `replot`
                   4576:  commands within the `set multiplot`/`set nomultiplot` block.
                   4577:
                   4578:  The commands `set origin` and `set size` must be used to correctly position
                   4579:  each plot; see `set origin` and `set size` for details of their usage.
                   4580:
                   4581:  Example:
                   4582:        set size 0.7,0.7
                   4583:        set origin 0.1,0.1
                   4584:        set multiplot
                   4585:        set size 0.4,0.4
                   4586:        set origin 0.1,0.1
                   4587:        plot sin(x)
                   4588:        set size 0.2,0.2
                   4589:        set origin 0.5,0.5
                   4590:        plot cos(x)
                   4591:        set nomultiplot
                   4592:
                   4593:  displays a plot of cos(x) stacked above a plot of sin(x).  Note the initial
                   4594:  `set size` and `set origin`.  While these are not always required, their
                   4595:  inclusion is recommended.  Some terminal drivers require that bounding box
                   4596:  information be available before any plots can be made, and the form given
                   4597:  above guarantees that the bounding box will include the entire plot array
                   4598:  rather than just the bounding box of the first plot.
                   4599:
                   4600:  `set size` and `set origin` refer to the entire plotting area used for each
                   4601:  plot.  If you want to have the axes themselves line up, you can guarantee
                   4602:  that the margins are the same size with the `set margin` commands.  See
                   4603:  `set margin` for their use.  Note that the margin settings are absolute,
                   4604:  in character units, so the appearance of the graph in the remaining space
                   4605:  will depend on the screen size of the display device, e.g., perhaps quite
                   4606:  different on a video display and a printer.
1.1.1.2   maekawa  4607: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/multiplt.html"> See demo. </a>
1.1       maekawa  4608: 3 mx2tics
                   4609: ?commands set mx2tics
                   4610: ?commands set nomx2tics
                   4611: ?commands show mx2tics
                   4612: ?set mx2tics
                   4613: ?set nomx2tics
                   4614: ?show mx2tics
                   4615: ?mx2tics
                   4616: ?nomx2tics
                   4617:  Minor tic marks along the x2 (top) axis are controlled by `set mx2tics`.
                   4618:  Please see `set mxtics`.
                   4619: 3 mxtics
                   4620: ?commands set mxtics
                   4621: ?commands set nomxtics
                   4622: ?commands show mxtics
                   4623: ?set mxtics
                   4624: ?set nomxtics
                   4625: ?show mxtics
                   4626: ?mxtics
                   4627: ?nomxtics
                   4628:  Minor tic marks along the x axis are controlled by `set mxtics`.  They can be
                   4629:  turned off with `set nomxtics`.  Similar commands control minor tics along
                   4630:  the other axes.
                   4631:
                   4632:  Syntax:
                   4633:        set mxtics {<freq> | default}
                   4634:        set nomxtics
                   4635:        show mxtics
                   4636:
                   4637:  The same syntax applies to `mytics`, `mztics`, `mx2tics` and `my2tics`.
                   4638:
                   4639:  <freq> is the number of sub-intervals (NOT the number of minor tics) between
                   4640:  major tics (ten is the default for a linear axis, so there are nine minor
                   4641:  tics between major tics). Selecting `default` will return the number of minor
                   4642:  ticks to its default value.
                   4643:
                   4644:  If the axis is logarithmic, the number of sub-intervals will be set to a
                   4645:  reasonable number by default (based upon the length of a decade).  This will
                   4646:  be overridden if <freq> is given.  However the usual minor tics (2, 3, ...,
                   4647:  8, 9 between 1 and 10, for example) are obtained by setting <freq> to 10,
                   4648:  even though there are but nine sub-intervals.
                   4649:
                   4650:  Minor tics can be used only with uniformly spaced major tics.  Since major
                   4651:  tics can be placed arbitrarily by `set {x|x2|y|y2|z}tics`, minor tics cannot
                   4652:  be used if major tics are explicitly `set`.
                   4653:
                   4654:  By default, minor tics are off for linear axes and on for logarithmic axes.
                   4655:  They inherit the settings for `axis|border` and `{no}mirror` specified for
                   4656:  the major tics.  Please see `set xtics` for information about these.
                   4657: 3 my2tics
                   4658: ?commands set my2tics
                   4659: ?commands set nomy2tics
                   4660: ?commands show my2tics
                   4661: ?set my2tics
                   4662: ?set nomy2tics
                   4663: ?show my2tics
                   4664: ?my2tics
                   4665: ?nomy2tics
                   4666:  Minor tic marks along the y2 (right-hand) axis are controlled by `set
                   4667:  my2tics`.  Please see `set mxtics`.
                   4668: 3 mytics
                   4669: ?commands set mytics
                   4670: ?commands set nomytics
                   4671: ?commands show mytics
                   4672: ?set mytics
                   4673: ?set nomytics
                   4674: ?show mytics
                   4675: ?mytics
                   4676: ?nomytics
                   4677:  Minor tic marks along the y axis are controlled by `set mytics`.  Please
                   4678:  see `set mxtics`.
                   4679: 3 mztics
                   4680: ?commands set mztics
                   4681: ?commands set nomztics
                   4682: ?commands show mztics
                   4683: ?set mztics
                   4684: ?set nomztics
                   4685: ?show mztics
                   4686: ?mztics
                   4687: ?nomztics
                   4688:  Minor tic marks along the z axis are controlled by `set mztics`.  Please
                   4689:  see `set mxtics`.
                   4690: 3 offsets
                   4691: ?commands set offsets
                   4692: ?commands set nooffsets
                   4693: ?commands show offsets
                   4694: ?set offsets
                   4695: ?set nooffsets
                   4696: ?show offsets
                   4697: ?offsets
                   4698: ?nooffsets
                   4699:  Offsets provide a mechanism to put a boundary around the data inside of an
                   4700:  autoscaled graph.
                   4701:
                   4702:  Syntax:
                   4703:        set offsets <left>, <right>, <top>, <bottom>
                   4704:        set nooffsets
                   4705:        show offsets
                   4706:
                   4707:  Each offset may be a constant or an expression.  Each defaults to 0.  Left
                   4708:  and right offsets are given in units of the x axis, top and bottom offsets in
                   4709:  units of the y axis.  A positive offset expands the graph in the specified
                   4710:  direction, e.g., a positive bottom offset makes ymin more negative.  Negative
                   4711:  offsets, while permitted, can have unexpected interactions with autoscaling
                   4712:  and clipping.
                   4713:
                   4714:  Offsets are ignored in `splot`s.
                   4715:
                   4716:  Example:
                   4717:        set offsets 0, 0, 2, 2
                   4718:        plot sin(x)
                   4719:
                   4720:  This graph of sin(x) will have a y range [-3:3] because the function
                   4721:  will be autoscaled to [-1:1] and the vertical offsets are each two.
                   4722: 3 origin
                   4723: ?commands set origin
                   4724: ?commands show origin
                   4725: ?set origin
                   4726: ?show origin
                   4727: ?origin
                   4728:  The `set origin` command is used to specify the origin of a plotting surface
                   4729:  (i.e., the graph and its margins) on the screen.  The coordinates are given
                   4730:  in the `screen` coordinate system (see `coordinates` for information about
                   4731:  this system).
                   4732:
                   4733:  Syntax:
                   4734:        set origin <x-origin>,<y-origin>
                   4735: 3 output
                   4736: ?commands set output
                   4737: ?commands show output
                   4738: ?set output
                   4739: ?show output
                   4740: ?output
                   4741:  By default, screens are displayed to the standard output. The `set output`
                   4742:  command redirects the display to the specified file or device.
                   4743:
                   4744:  Syntax:
                   4745:        set output {"<filename>"}
                   4746:        show output
                   4747:
                   4748:  The filename must be enclosed in quotes.  If the filename is omitted, any
                   4749:  output file opened by a previous invocation of `set output` will be closed
                   4750:  and new output will be sent to STDOUT.  (If you give the command `set output
                   4751:  "STDOUT"`, your output may be sent to a file named "STDOUT"!  ["May be", not
                   4752:  "will be", because some terminals, like `x11`, ignore `set output`.])
                   4753:
                   4754:  MSDOS users should note that the \ character has special significance in
                   4755:  double-quoted strings, so single-quotes should be used for filenames in
                   4756:  different directories.
                   4757:
                   4758:  When both `set terminal` and `set output` are used together, it is safest to
                   4759:  give `set terminal` first, because some terminals set a flag which is needed
                   4760:  in some operating systems.  This would be the case, for example, if the
                   4761:  operating system needs to know whether or not a file is to be formatted in
                   4762:  order to open it properly.
                   4763:
                   4764:  On machines with popen functions (Unix), output can be piped through a shell
                   4765:  command if the first non-whitespace character of the filename is '|'.
                   4766:  For instance,
                   4767:
                   4768:        set output "|lpr -Plaser filename"
                   4769:        set output "|lp -dlaser filename"
                   4770:
                   4771:  On MSDOS machines, `set output "PRN"` will direct the output to the default
                   4772:  printer.  On VMS, output can be sent directly to any spooled device.  It is
                   4773:  also possible to send the output to DECnet transparent tasks, which allows
                   4774:  some flexibility.
                   4775: 3 parametric
                   4776: ?commands set parametric
                   4777: ?commands set noparametric
                   4778: ?commands show parametric
                   4779: ?set parametric
                   4780: ?set noparametric
                   4781: ?show parametric
                   4782: ?parametric
                   4783: ?noparametric
                   4784:  The `set parametric` command changes the meaning of `plot` (`splot`) from
                   4785:  normal functions to parametric functions.  The command `set noparametric`
                   4786:  restores the plotting style to normal, single-valued expression plotting.
                   4787:
                   4788:  Syntax:
                   4789:        set parametric
                   4790:        set noparametric
                   4791:        show parametric
                   4792:
                   4793:  For 2-d plotting, a parametric function is determined by a pair of parametric
                   4794:  functions operating on a parameter.  An example of a 2-d parametric function
                   4795:  would be `plot sin(t),cos(t)`, which draws a circle (if the aspect ratio is
                   4796:  set correctly---see `set size`).  `gnuplot` will display an error message if
                   4797:  both functions are not provided for a parametric `plot`.
                   4798:
                   4799:  For 3-d plotting, the surface is described as x=f(u,v), y=g(u,v), z=h(u,v).
                   4800:  Therefore a triplet of functions is required.  An example of a 3-d parametric
                   4801:  function would be `cos(u)*cos(v),cos(u)*sin(v),sin(u)`, which draws a sphere.
                   4802:  `gnuplot` will display an error message if all three functions are not
                   4803:  provided for a parametric `splot`.
                   4804:
                   4805:  The total set of possible plots is a superset of the simple f(x) style plots,
                   4806:  since the two functions can describe the x and y values to be computed
                   4807:  separately.  In fact, plots of the type t,f(t) are equivalent to those
                   4808:  produced with f(x) because the x values are computed using the identity
                   4809:  function.  Similarly, 3-d plots of the type u,v,f(u,v) are equivalent to
                   4810:  f(x,y).
                   4811:
                   4812:  Note that the order the parametric functions are specified is xfunction,
                   4813:  yfunction (and zfunction) and that each operates over the common parametric
                   4814:  domain.
                   4815:
                   4816:  Also, the `set parametric` function implies a new range of values.  Whereas
                   4817:  the normal f(x) and f(x,y) style plotting assume an xrange and yrange (and
                   4818:  zrange), the parametric mode additionally specifies a trange, urange, and
                   4819:  vrange.  These ranges may be set directly with `set trange`, `set urange`,
                   4820:  and `set vrange`, or by specifying the range on the `plot` or `splot`
                   4821:  commands.  Currently the default range for these parametric variables is
                   4822:  [-5:5].  Setting the ranges to something more meaningful is expected.
                   4823: 3 pointsize
                   4824: ?commands set pointsize
                   4825: ?commands show pointsize
                   4826: ?set pointsize
                   4827: ?show pointsize
                   4828: ?pointsize
                   4829:  The `set pointsize` command scales the size of the points used in plots.
                   4830:
                   4831:  Syntax:
                   4832:        set pointsize <multiplier>
                   4833:        show pointsize
                   4834:
                   4835:  The default is a multiplier of 1.0.  Larger pointsizes may be useful to
                   4836:  make points more visible in bitmapped graphics.
                   4837:
                   4838:  The pointsize of a single plot may be changed on the `plot` command.  See
                   4839:  `plot with` for details.
                   4840:
                   4841:  Please note that the pointsize setting is not supported by all terminal
                   4842:  types.
                   4843: 3 polar
                   4844: ?commands set polar
                   4845: ?commands set nopolar
                   4846: ?commands show polar
                   4847: ?set polar
                   4848: ?set nopolar
                   4849: ?show polar
                   4850: ?polar
                   4851: ?nopolar
                   4852:  The `set polar` command changes the meaning of the plot from rectangular
                   4853:  coordinates to polar coordinates.
                   4854:
                   4855:  Syntax:
                   4856:        set polar
                   4857:        set nopolar
                   4858:        show polar
                   4859:
                   4860:  There have been changes made to polar mode in version 3.7, so that scripts
                   4861:  for `gnuplot` versions 3.5 and earlier will require modification.  The main
                   4862:  change is that the dummy variable t is used for the angle so that the x and
                   4863:  y ranges can be controlled independently.  Other changes are:
                   4864:  1) tics are no longer put along the zero axes automatically
                   4865:  ---use `set xtics axis nomirror`; `set ytics axis nomirror`;
                   4866:  2) the grid, if selected, is not automatically polar
                   4867:  ---use `set grid polar`;
                   4868:  3) the grid is not labelled with angles
                   4869:  ---use `set label` as necessary.
                   4870:
                   4871:  In polar coordinates, the dummy variable (t) is an angle.  The default range
                   4872:  of t is [0:2*pi], or, if degree units have been selected, to [0:360] (see
                   4873:  `set angles`).
                   4874:
                   4875:  The command `set nopolar` changes the meaning of the plot back to the default
                   4876:  rectangular coordinate system.
                   4877:
                   4878:  The `set polar` command is not supported for `splot`s.  See the `set mapping`
                   4879:  command for similar functionality for `splot`s.
                   4880:
                   4881:  While in polar coordinates the meaning of an expression in t is really
                   4882:  r = f(t), where t is an angle of rotation.  The trange controls the domain
                   4883:  (the angle) of the function, and the x and y ranges control the range of the
                   4884:  graph in the x and y directions.  Each of these ranges, as well as the
                   4885:  rrange, may be autoscaled or set explicitly.  See `set xrange` for details
                   4886:  of all the `set range` commands.
                   4887:
                   4888:  Example:
                   4889:        set polar
                   4890:        plot t*sin(t)
                   4891:        plot [-2*pi:2*pi] [-3:3] [-3:3] t*sin(t)
                   4892:
                   4893:  The first `plot` uses the default polar angular domain of 0 to 2*pi.  The
                   4894:  radius and the size of the graph are scaled automatically.  The second `plot`
                   4895:  expands the domain, and restricts the size of the graph to [-3:3] in both
                   4896:  directions.
                   4897:
                   4898:  You may want to `set size square` to have `gnuplot` try to make the aspect
                   4899:  ratio equal to unity, so that circles look circular.
1.1.1.2   maekawa  4900: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/polar.html">Polar demos </a>
                   4901: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/poldat.html">Polar Data Plot. </a>
1.1       maekawa  4902: 3 rmargin
                   4903: ?commands set rmargin
                   4904: ?set rmargin
                   4905: ?rmargin
                   4906:  The command `set rmargin` sets the size of the right margin.  Please see
                   4907:  `set margin` for details.
                   4908: 3 rrange
                   4909: ?commands set rrange
                   4910: ?commands show rrange
                   4911: ?set rrange
                   4912: ?show rrange
                   4913: ?rrange
                   4914:  The `set rrange` command sets the range of the radial coordinate for a
                   4915:  graph in polar mode.  Please see `set xrange` for details.
                   4916: 3 samples
                   4917: ?commands set samples
                   4918: ?commands show samples
                   4919: ?set samples
                   4920: ?show samples
                   4921: ?samples
                   4922:  The sampling rate of functions, or for interpolating data, may be changed
                   4923:  by the `set samples` command.
                   4924:
                   4925:  Syntax:
                   4926:        set samples <samples_1> {,<samples_2>}
                   4927:        show samples
                   4928:
                   4929:  By default, sampling is set to 100 points.  A higher sampling rate will
                   4930:  produce more accurate plots, but will take longer.  This parameter has no
                   4931:  effect on data file plotting unless one of the interpolation/approximation
                   4932:  options is used.  See `plot smooth` re 2-d data and `set cntrparam` and
                   4933:  `set dgrid3d` re 3-d data.
                   4934:
                   4935:  When a 2-d graph is being done, only the value of <samples_1> is relevant.
                   4936:
                   4937:  When a surface plot is being done without the removal of hidden lines, the
                   4938:  value of samples specifies the number of samples that are to be evaluated for
                   4939:  the isolines.  Each iso-v line will have <sample_1> samples and each iso-u
                   4940:  line will have <sample_2> samples.  If you only specify <samples_1>,
                   4941:  <samples_2> will be set to the same value as <samples_1>.  See also `set
                   4942:  isosamples`.
                   4943: 3 size
                   4944: ?commands set size
                   4945: ?commands show size
                   4946: ?set size
                   4947: ?show size
                   4948: ?size
                   4949:  The `set size` command scales the displayed size of the plot.
                   4950:
                   4951:  Syntax:
                   4952:        set size {{no}square | ratio <r> | noratio} {<xscale>,<yscale>}
                   4953:        show size
                   4954:
                   4955:  The <xscale> and <yscale> values are the scaling factors for the size of the
                   4956:  plot, which includes the graph and the margins.
                   4957:
                   4958:  `ratio` causes `gnuplot` to try to create a graph with an aspect ratio of <r>
                   4959:  (the ratio of the y-axis length to the x-axis length) within the portion of
                   4960:  the plot specified by <xscale> and <yscale>.
                   4961:
                   4962:  The meaning of a negative value for <r> is different.  If <r>=-1, gnuplot
                   4963:  tries to set the scales so that the unit has the same length on both the x
                   4964:  and y axes (suitable for geographical data, for instance).  If <r>=-2, the
                   4965:  unit on y has twice the length of the unit on x, and so on.
                   4966:
                   4967:  The success of `gnuplot` in producing the requested aspect ratio depends on
                   4968:  the terminal selected.  The graph area will be the largest rectangle of
                   4969:  aspect ratio <r> that will fit into the specified portion of the output
                   4970:  (leaving adequate margins, of course).
                   4971:
                   4972:  `square` is a synonym for `ratio 1`.
                   4973:
                   4974:  Both `noratio` and `nosquare` return the graph to the default aspect ratio
                   4975:  of the terminal, but do not return <xscale> or <yscale> to their default
                   4976:  values (1.0).
                   4977:
                   4978:  `ratio` and `square` have no effect on 3-d plots.
                   4979:
                   4980:  `set size` is relative to the default size, which differs from terminal to
                   4981:  terminal.  Since `gnuplot` fills as much of the available plotting area as
                   4982:  possible by default, it is safer to use `set size` to decrease the size of
                   4983:  a plot than to increase it.  See `set terminal` for the default sizes.
                   4984:
                   4985:  On some terminals, changing the size of the plot will result in text being
                   4986:  misplaced.
                   4987:
                   4988:  Examples:
                   4989:
                   4990:  To set the size to normal size use:
                   4991:        set size 1,1
                   4992:
                   4993:  To make the graph half size and square use:
                   4994:        set size square 0.5,0.5
                   4995:
                   4996:  To make the graph twice as high as wide use:
                   4997:        set size ratio 2
                   4998:
1.1.1.2   maekawa  4999: ^<a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/airfoil.html"> See demo. </a>
1.1       maekawa  5000: 3 style
                   5001: ?commands set function style
                   5002: ?commands show function style
                   5003: ?commands set data style
                   5004: ?commands show data style
                   5005: ?set function style
                   5006: ?show function style
                   5007: ?set data style
                   5008: ?show data style
                   5009: ?set style
                   5010: ?show style
                   5011:  Default styles are chosen with the `set function style` and `set data style`
                   5012:  commands.  See `plot with` for information about how to override the default
                   5013:  plotting style for individual functions and data sets.
                   5014:
                   5015:  Syntax:
                   5016:        set function style <style>
                   5017:        set data style <style>
                   5018:        show function style
                   5019:        show data style
                   5020:
                   5021:  The types used for all line and point styles (i.e., solid, dash-dot, color,
                   5022:  etc. for lines; circles, squares, crosses, etc. for points) will be either
                   5023:  those specified on the `plot` or `splot` command or will be chosen
                   5024:  sequentially from the types available to the terminal in use.  Use the
                   5025:  command `test` to see what is available.
                   5026:
                   5027:  None of the styles requiring more than two columns of information (e.g.,
                   5028:  `errorbars`) can be used with `splot`s or function `plot`s.  Neither `boxes`
                   5029:  nor any of the `steps` styles can be used with `splot`s.  If an inappropriate
                   5030:  style is specified, it will be changed to `points`.
                   5031:
                   5032:  For 2-d data with more than two columns, `gnuplot` is picky about the allowed
                   5033:  `errorbar` styles.  The `using` option on the `plot` command can be used to
                   5034:  set up the correct columns for the style you want.  (In this discussion,
                   5035:  "column" will be used to refer both to a column in the data file and an entry
                   5036:  in the `using` list.)
                   5037:
                   5038:  For three columns, only `xerrorbars`, `yerrorbars` (or `errorbars`), `boxes`,
                   5039:  and `boxerrorbars` are allowed.  If another plot style is used, the style
                   5040:  will be changed to `yerrorbars`.  The `boxerrorbars` style will calculate the
                   5041:  boxwidth automatically.
                   5042:
                   5043:  For four columns, only `xerrorbars`, `yerrorbars` (or `errorbars`),
                   5044:  `xyerrorbars`, `boxxyerrorbars`, and `boxerrorbars` are allowed.  An illegal
                   5045:  style will be changed to `yerrorbars`.
                   5046:
                   5047:  Five-column data allow only the `boxerrorbars`, `financebars`, and
                   5048:  `candlesticks` styles.  (The last two of these are primarily used for plots
                   5049:  of financial prices.)  An illegal style will be changed to `boxerrorbars`
                   5050:  before plotting.
                   5051:
                   5052:  Six- and seven-column data only allow the `xyerrorbars` and `boxxyerrorbars`
                   5053:  styles.  Illegal styles will be changed to `xyerrorbars` before plotting.
                   5054:
                   5055:  For more information about error bars, please see `plot errorbars`.
                   5056: 4 boxerrorbars
                   5057: ?commands set style boxerrorbars
                   5058: ?set style boxerrorbars
                   5059: ?style boxerrorbars
                   5060: ?boxerrorbars
                   5061:  The `boxerrorbars` style is only relevant to 2-d data plotting.  It is a
                   5062:  combination of the `boxes` and `yerrorbars` styles.  The boxwidth will come
                   5063:  from the fourth column if the y errors are in the form of "ydelta" and the
                   5064:  boxwidth was not previously set equal to -2.0 (`set boxwidth -2.0`) or from
                   5065:  the fifth column if the y errors are in the form of "ylow yhigh".  The
                   5066:  special case  `boxwidth = -2.0` is for four-column data with y errors in the
                   5067:  form "ylow yhigh".  In this case the boxwidth will be calculated so that each
                   5068:  box touches the adjacent boxes.  The width will also be calculated in cases
                   5069:  where three-column data are used.
                   5070:
                   5071:  The box height is determined from the y error in the same way as it is for
                   5072:  the `yerrorbars` style---either from y-ydelta to y+ydelta or from ylow to
                   5073:  yhigh, depending on how many data columns are provided.
                   5074: ^<a href="http://www.nas.nasa.gov/~woo/gnuplot/errorbar/errorbar.html"> See Demo. </a>
                   5075: 4 boxes
                   5076: ?commands set style boxes
                   5077: ?commands set style bargraph
                   5078: ?set style boxes
                   5079: ?set style bargraph
                   5080: ?style boxes
                   5081: ?style bargraph
                   5082: ?boxes
                   5083: ?bargraph
                   5084:  The `boxes` style is only relevant to 2-d plotting.  It draws a box centered
                   5085:  about the given x coordinate from the x axis (not the graph border) to the
                   5086:  given y coordinate.  The width of the box is obtained in one of three ways.
                   5087:  If it is a data plot and the data file has a third column, this will be used
                   5088:  to set the width of the box.  If not, if a width has been set using the `set
                   5089:  boxwidth` command, this will be used.  If neither of these is available, the
                   5090:  width of each box will be calculated automatically so that it touches the
                   5091:  adjacent boxes.
                   5092: 4 boxxyerrorbars
                   5093: ?commands set style boxxyerrorbars
                   5094: ?set style boxxyerrorbars
                   5095: ?style boxxyerrorbars
                   5096: ?boxxyerrorbars
                   5097:  The `boxxyerrorbars` style is only relevant to 2-d data plotting.  It is a
                   5098:  combination of the `boxes` and `xyerrorbars` styles.
                   5099:
                   5100:  The box width and height are determined from the x and y errors in the same
                   5101:  way as they are for the `xyerrorbars` style---either from xlow to xhigh and
                   5102:  from ylow to yhigh, or from x-xdelta to x+xdelta and from y-ydelta to
                   5103:  y+ydelta , depending on how many data columns are provided.
                   5104: 4 candlesticks
                   5105: ?commands set style candlesticks
                   5106: ?set style candlesticks
                   5107: ?style candlesticks
                   5108: ?candlesticks
                   5109:  The `candlesticks` style is only relevant for 2-d data plotting of financial
                   5110:  data.  Five columns of data are required; in order, these should be the x
                   5111:  coordinate (most likely a date) and the opening, low, high, and closing
                   5112:  prices.  The symbol is an open rectangle, centered horizontally at the x
                   5113:  coordinate and limited vertically by the opening and closing prices.  A
                   5114:  vertical line segment at the x coordinate extends up from the top of the
                   5115:  rectangle to the high price and another down to the low.  The width of the
                   5116:  rectangle may be changed by `set bar`.  The symbol will be unchanged if the
                   5117:  low and high prices are interchanged or if the opening and closing prices
                   5118:  are interchanged.  See `set bar` and `financebars`.
                   5119: ^<a href="http://www.nas.nasa.gov/~woo/gnuplot/finance/finance.html"> See demos.</a>
                   5120: 4 dots
                   5121: ?commands set style dots
                   5122: ?set style dots
                   5123: ?style dots
                   5124: ?dots
                   5125:  The `dots` style plots a tiny dot at each point; this is useful for scatter
                   5126:  plots with many points.
                   5127: 4 financebars
                   5128: ?commands set style financebars
                   5129: ?set style financebars
                   5130: ?style financebars
                   5131: ?financebars
                   5132:  The `financebars` style is only relevant for 2-d data plotting of financial
                   5133:  data.  Five columns of data are required; in order, these should be the x
                   5134:  coordinate (most likely a date) and the opening, low, high, and closing
                   5135:  prices.  The symbol is a vertical line segment, located horizontally at the x
                   5136:  coordinate and limited vertically by the high and low prices.  A horizontal
                   5137:  tic on the left marks the opening price and one on the right marks the
                   5138:  closing price.  The length of these tics may be changed by `set bar`.  The
                   5139:  symbol will be unchanged if the high and low prices are interchanged.  See
                   5140:  `set bar` and `candlesticks`.
                   5141: ^<a href="http://www.nas.nasa.gov/~woo/gnuplot/finance/finance.html"> See demos.</a>
                   5142: 4 fsteps
                   5143: ?commands set style fsteps
                   5144: ?set style fsteps
                   5145: ?style fsteps
                   5146: ?fsteps
                   5147:  The `fsteps` style is only relevant to 2-d plotting.  It connects consecutive
                   5148:  points with two line segments: the first from (x1,y1) to (x1,y2) and the
                   5149:  second from (x1,y2) to (x2,y2).
1.1.1.2   maekawa  5150: ^<a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/steps.html"> See demo. </a>
1.1       maekawa  5151: 4 histeps
                   5152: ?commands set style histeps
                   5153: ?set style histeps
                   5154: ?style histeps
                   5155: ?histeps
                   5156:  The `histeps` style is only relevant to 2-d plotting.  It is intended for
                   5157:  plotting histograms.  Y-values are assumed to be centered at the x-values;
                   5158:  the point at x1 is represented as a horizontal line from ((x0+x1)/2,y1) to
                   5159:  ((x1+x2)/2,y1).  The lines representing the end points are extended so that
                   5160:  the step is centered on at x.  Adjacent points are connected by a vertical
                   5161:  line at their average x, that is, from ((x1+x2)/2,y1) to ((x1+x2)/2,y2).
                   5162:
                   5163:  If `autoscale` is in effect, it selects the xrange from the data rather than
                   5164:  the steps, so the end points will appear only half as wide as the others.
1.1.1.2   maekawa  5165: ^<a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/steps.html"> See demo. </a>
1.1       maekawa  5166:
                   5167:  `histeps` is only a plotting style; `gnuplot` does not have the ability to
                   5168:  create bins and determine their population from some data set.
                   5169: 4 impulses
                   5170: ?commands set style impulses
                   5171: ?set style impulses
                   5172: ?style impulses
                   5173: ?impulses
                   5174:  The `impulses` style displays a vertical line from the x axis (not the graph
                   5175:  border), or from the grid base for `splot`, to each point.
                   5176: 4 lines
                   5177: ?commands set style lines
                   5178: ?set style lines
                   5179: ?style lines
                   5180: ?lines
                   5181:  The `lines` style connects adjacent points with straight line segments.
                   5182: 4 linespoints
                   5183: ?commands set style linespoints
                   5184: ?commands set style lp
                   5185: ?set style linespoints
                   5186: ?set style lp
                   5187: ?style linespoints
                   5188: ?style lp
                   5189: ?linespoints
                   5190: ?lp
                   5191:  The `linespoints` style does both `lines` and `points`, that is, it draws a
                   5192:  small symbol at each point and then connects adjacent points with straight
                   5193:  line segments.  The command `set pointsize` may be used to change the size of
                   5194:  the points.  See `set pointsize` for its usage.
                   5195:
                   5196:  `linespoints` may be abbreviated `lp`.
                   5197: 4 points
                   5198: ?commands set style points
                   5199: ?set style points
                   5200: ?style points
                   5201: ?points
                   5202:  The `points` style displays a small symbol at each point.  The command `set
                   5203:  pointsize` may be used to change the size of the points.  See `set pointsize`
                   5204:  for its usage.
                   5205: 4 steps
                   5206: ?commands set style steps
                   5207: ?set style steps
                   5208: ?style steps
                   5209: ?steps
                   5210:  The `steps` style is only relevant to 2-d plotting.  It connects consecutive
                   5211:  points with two line segments: the first from (x1,y1) to (x2,y1) and the
                   5212:  second from (x2,y1) to (x2,y2).
1.1.1.2   maekawa  5213: ^<a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/steps.html"> See demo. </a>
1.1       maekawa  5214: 4 vector
                   5215: ?commands set style vector
                   5216: ?set style vector
                   5217: ?style vector
                   5218: ?vector
                   5219:  The `vector` style draws a vector from (x,y) to (x+xdelta,y+ydelta).  Thus
                   5220:  it requires four columns of data.  It also draws a small arrowhead at the
                   5221:  end of the vector.
                   5222:
1.1.1.3 ! ohara    5223:  `set clip one` and `set clip two` affect drawing vectors.
        !          5224:  Please see `set clip`.
1.1       maekawa  5225: 4 xerrorbars
                   5226: ?commands set style xerrorbars
                   5227: ?set style xerrorbars
                   5228: ?style xerrorbars
                   5229: ?xerrorbars
                   5230:  The `xerrorbars` style is only relevant to 2-d data plots.  `xerrorbars` is
                   5231:  like `dots`, except that a horizontal error bar is also drawn.  At each point
                   5232:  (x,y), a line is drawn from (xlow,y) to (xhigh,y) or from (x-xdelta,y) to
                   5233:  (x+xdelta,y), depending on how many data columns are provided.  A tic mark
                   5234:  is placed at the ends of the error bar (unless `set bar` is used---see `set
                   5235:  bar` for details).
                   5236: 4 xyerrorbars
                   5237: ?commands set style xyerrorbars
                   5238: ?set style xyerrorbars
                   5239: ?style xyerrorbars
                   5240: ?xyerrorbars
                   5241:  The `xyerrorbars` style is only relevant to 2-d data plots.  `xyerrorbars` is
                   5242:  like `dots`, except that horizontal and vertical error bars are also drawn.
                   5243:  At each point (x,y), lines are drawn from (x,y-ydelta) to (x,y+ydelta) and
                   5244:  from (x-xdelta,y) to (x+xdelta,y) or from (x,ylow) to (x,yhigh) and from
                   5245:  (xlow,y) to (xhigh,y), depending upon the number of data columns provided.  A
                   5246:  tic mark is placed at the ends of the error bar (unless `set bar` is
                   5247:  used---see `set bar` for details).
                   5248:
                   5249:  If data are provided in an unsupported mixed form, the `using` filter on the
                   5250:  `plot` command should be used to set up the appropriate form.  For example,
                   5251:  if the data are of the form (x,y,xdelta,ylow,yhigh), then you can use
                   5252:
1.1.1.3 ! ohara    5253:        plot 'data' using 1:2:($1-$3):($1+$3):4:5 with xyerrorbars
1.1       maekawa  5254: 4 yerrorbars
                   5255: ?commands set style yerrorbars
                   5256: ?commands set style errorbars
                   5257: ?set style yerrorbars
                   5258: ?set style errorbars
                   5259: ?style yerrorbars
                   5260: ?style errorbars
                   5261: ?yerrorbars
                   5262: ?errorbars
                   5263:  The `yerrorbars` (or `errorbars`) style is only relevant to 2-d data plots.
                   5264:  `yerrorbars` is like `dots`, except that a vertical error bar is also drawn.
                   5265:  At each point (x,y), a line is drawn from (x,y-ydelta) to (x,y+ydelta) or
                   5266:  from (x,ylow) to (x,yhigh), depending on how many data columns are provided.
                   5267:  A tic mark is placed at the ends of the error bar (unless `set bar` is
                   5268:  used---see `set bar` for details).
                   5269: ^<a href="http://www.nas.nasa.gov/~woo/gnuplot/errorbar/errorbar.html"> See demo. </a>
                   5270: 3 surface
                   5271: ?commands set surface
                   5272: ?commands set nosurface
                   5273: ?commands show surface
                   5274: ?set surface
                   5275: ?set nosurface
                   5276: ?show surface
                   5277: ?surface
                   5278: ?nosurface
                   5279:  The command `set surface` controls the display of surfaces by `splot`.
                   5280:
                   5281:  Syntax:
                   5282:        set surface
                   5283:        set nosurface
                   5284:        show surface
                   5285:
                   5286:  The surface is drawn with the style specifed by `with`, or else the
                   5287:  appropriate style, data or function.
                   5288:
                   5289:  Whenever `set nosurface` is issued, `splot` will not draw points or lines
1.1.1.3 ! ohara    5290:  corresponding to the function or data file points.  Contours may still be
1.1       maekawa  5291:  drawn on the surface, depending on the `set contour` option. `set nosurface;
                   5292:  set contour base` is useful for displaying contours on the grid base.  See
                   5293:  also `set contour`.
                   5294: ^ <h2> Terminal Types </h2>
                   5295: 3 terminal
                   5296: ?commands set terminal
                   5297: ?commands show terminal
                   5298: ?set terminal
                   5299: ?set term
                   5300: ?show terminal
                   5301: ?terminal
                   5302: ?term
                   5303:  `gnuplot` supports many different graphics devices.  Use `set terminal` to
                   5304:  tell `gnuplot` what kind of output to generate. Use `set output` to redirect
                   5305:  that output to a file or device.
                   5306:
                   5307:  Syntax:
                   5308:        set terminal {<terminal-type>}
                   5309:        show terminal
                   5310:
                   5311:  If <terminal-type> is omitted, `gnuplot` will list the available terminal
                   5312:  types.  <terminal-type> may be abbreviated.
                   5313:
                   5314:  If both `set terminal` and `set output` are used together, it is safest to
                   5315:  give `set terminal` first, because some terminals set a flag which is needed
                   5316:  in some operating systems.
                   5317:
                   5318:  Several terminals have additional options.  For example, see `dumb`,
                   5319:  `iris4d`, `hpljii` or `postscript`.
                   5320:
                   5321:  This document may describe drivers that are not available to you because they
                   5322:  were not installed, or it may not describe all the drivers that are available
                   5323:  to you, depending on its output format.
                   5324: <4 -- all terminal stuff is pulled from the .trm files
                   5325: 3 tics
                   5326: ?commands set tics
                   5327: ?commands show tics
                   5328: ?set tics
                   5329: ?show tics
                   5330: ?tics
                   5331:  The `set tics` command can be used to change the tics to be drawn outwards.
                   5332:
                   5333:  Syntax:
                   5334:        set tics {<direction>}
                   5335:        show tics
                   5336:
                   5337:  where <direction> may be `in` (the default) or `out`.
                   5338:
                   5339:  See also `set xtics` for more control of major (labelled) tic marks and `set
                   5340:  mxtics` for control of minor tic marks.
                   5341: 3 ticslevel
                   5342: ?commands set ticslevel
                   5343: ?commands show ticslevel
                   5344: ?set ticslevel
                   5345: ?show ticslevel
                   5346: ?ticslevel
                   5347:  Using `splot`, one can adjust the relative height of the vertical (Z) axis
                   5348:  using `set ticslevel`.  The numeric argument provided specifies the location
                   5349:  of the bottom of the scale (as a fraction of the z-range) above the xy-plane.
                   5350:  The default value is 0.5.  Negative values are permitted, but tic labels on
                   5351:  the three axes may overlap.
                   5352:
                   5353:  To place the xy-plane at a position 'pos' on the z-axis, `ticslevel` should
                   5354:  be set equal to  (pos - zmin) / (zmin - zmax).
                   5355:
                   5356:  Syntax:
                   5357:        set ticslevel {<level>}
                   5358:        show tics
                   5359:
                   5360:  See also `set view`.
                   5361: 3 ticscale
                   5362: ?commands set ticscale
                   5363: ?commands show ticscale
                   5364: ?set ticscale
                   5365: ?show ticscale
                   5366: ?ticscale
                   5367:  The size of the tic marks can be adjusted with `set ticscale`.
                   5368:
                   5369:  Syntax:
                   5370:        set ticscale {<major> {<minor>}}
                   5371:        show tics
                   5372:
                   5373:  If <minor> is not specified, it is 0.5*<major>.  The default size is 1.0 for
                   5374:  major tics and 0.5 for minor tics.  Note that it is possible to have the tic
                   5375:  marks pointing outward by specifying a negative size.
                   5376: 3 timestamp
                   5377: ?commands set timestamp
                   5378: ?commands set time
                   5379: ?commands set notimestamp
                   5380: ?commands show timestamp
                   5381: ?set timestamp
                   5382: ?set time
                   5383: ?set notimestamp
                   5384: ?show timestamp
                   5385: ?timestamp
                   5386: ?notimestamp
                   5387:  The command `set timestamp` places the time and date of the plot in the left
                   5388:  margin.
                   5389:
                   5390:  Syntax:
                   5391:        set timestamp {"<format>"} {top|bottom} {{no}rotate}
                   5392:                      {<xoff>}{,<yoff>} {"<font>"}
                   5393:        set notimestamp
                   5394:        show timestamp
                   5395:
                   5396:  The format string allows you to choose the format used to write the date and
                   5397:  time.  Its default value is what asctime() uses: "%a %b %d %H:%M:%S %Y"
                   5398:  (weekday, month name, day of the month, hours, minutes, seconds, four-digit
                   5399:  year).  With `top` or `bottom` you can place the timestamp at the top or
                   5400:  bottom of the left margin (default: bottom).  `rotate` lets you write the
                   5401:  timestamp vertically, if your terminal supports vertical text.  The constants
1.1.1.3 ! ohara    5402:  <xoff> and <yoff> are offsets from the default position given in character
1.1       maekawa  5403:  screen coordinates.  <font> is used to specify the font with which the time
                   5404:  is to be written.
                   5405:
                   5406:  The abbreviation `time` may be used in place of `timestamp`.
                   5407:
                   5408:  Example:
                   5409:        set timestamp "%d/%m/%y %H:%M" 80,-2 "Helvetica"
                   5410:
                   5411:  See `set timefmt` for more information about time format strings.
                   5412: 3 timefmt
                   5413: ?commands set timefmt
                   5414: ?commands show timefmt
                   5415: ?set timefmt
                   5416: ?show timefmt
                   5417: ?timefmt
                   5418:  This command applies to timeseries where data are composed of dates/times.
                   5419:  It has no meaning unless the command `set xdata time` is given also.
                   5420:
                   5421:  Syntax:
                   5422:        set timefmt "<format string>"
                   5423:        show timefmt
                   5424:
                   5425:  The string argument tells `gnuplot` how to read timedata from the datafile.
                   5426:  The valid formats are:
                   5427:
                   5428: @start table - first is interactive cleartext form
                   5429:        Format       Explanation
                   5430:        %d           day of the month, 1--31
                   5431:        %m           month of the year, 1--12
                   5432:        %y           year, 0--99
                   5433:        %Y           year, 4-digit
                   5434:        %j           day of the year, 1--365
                   5435:        %H           hour, 0--24
                   5436:        %M           minute, 0--60
1.1.1.3 ! ohara    5437:        %s           seconds since the Unix epoch (1970-01-01, 00:00 UTC)
1.1       maekawa  5438:        %S           second, 0--60
                   5439:        %b           three-character abbreviation of the name of the month
                   5440:        %B           name of the month
                   5441: #\begin{tabular}{|cl|} \hline
                   5442: #\multicolumn{2}{|c|}{Time Series timedata Format Specifiers}\\
                   5443: #\hline \hline
                   5444: #Format & Explanation \\ \hline
                   5445: #\verb@%d@ & day of the month, 1--31 \\
                   5446: #\verb@%m@ & month of the year, 1--12 \\
                   5447: #\verb@%y@ & year, 0--99 \\
                   5448: #\verb@%Y@ & year, 4-digit \\
                   5449: #\verb@%j@ & day of the year, 1--365 \\
                   5450: #\verb@%H@ & hour, 0--24 \\
                   5451: #\verb@%M@ & minute, 0--60 \\
1.1.1.3 ! ohara    5452: #\verb@%s@ & seconds since the Unix epoch (1970-01-01 00:00 UTC) \\
1.1       maekawa  5453: #\verb@%S@ & second, 0--60 \\
                   5454: #\verb@%b@ & three-character abbreviation of the name of the month \\
                   5455: #\verb@%B@ & name of the month \\
                   5456: %c l .
                   5457: %Format@Explanation
                   5458: %_
                   5459: %%d@day of the month, 1--31
                   5460: %%m@month of the year, 1--12
                   5461: %%y@year, 0--99
                   5462: %%Y@year, 4-digit
                   5463: %%j@day of the year, 1--365
                   5464: %%H@hour, 0--24
                   5465: %%M@minute, 0--60
1.1.1.3 ! ohara    5466: %%s@seconds since the Unix epoch (1970-01-01 00:00 UTC)
1.1       maekawa  5467: %%S@second, 0--60
                   5468: %%b@three-character abbreviation of the name of the month
                   5469: %%B@name of the month
                   5470: %_
                   5471: @end table
                   5472:  Any character is allowed in the string, but must match exactly.  \t (tab) is
                   5473:  recognized.  Backslash-octals (\nnn) are converted to char.  If there is no
                   5474:  separating character between the time/date elements, then %d, %m, %y, %H, %M
                   5475:  and %S read two digits each, %Y reads four digits and %j reads three digits.
                   5476:  %b requires three characters, and %B requires as many as it needs.
                   5477:
                   5478:  Spaces are treated slightly differently.  A space in the string stands for
                   5479:  zero or more whitespace characters in the file.  That is, "%H %M" can be used
                   5480:  to read "1220" and "12     20" as well as "12 20".
                   5481:
                   5482:  Each set of non-blank characters in the timedata counts as one column in the
                   5483:  `using n:n` specification.  Thus `11:11  25/12/76  21.0` consists of three
                   5484:  columns.  To avoid confusion, `gnuplot` requires that you provide a complete
                   5485:  `using` specification if your file contains timedata.
                   5486:
                   5487:  Since `gnuplot` cannot read non-numerical text, if the date format includes
                   5488:  the day or month in words, the format string must exclude this text.  But
                   5489:  it can still be printed with the "%a", "%A", "%b", or "%B" specifier: see
                   5490:  `set format` for more details about these and other options for printing
                   5491:  timedata.  (`gnuplot` will determine the proper month and weekday from the
                   5492:  numerical values.)
                   5493:
                   5494:  See also `set xdata` and `Time/date` for more information.
                   5495:
                   5496:  Example:
                   5497:        set timefmt "%d/%m/%Y\t%H:%M"
                   5498:  tells `gnuplot` to read date and time separated by tab.  (But look closely at
                   5499:  your data---what began as a tab may have been converted to spaces somewhere
                   5500:  along the line; the format string must match what is actually in the file.)
1.1.1.2   maekawa  5501: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/timedat.html"> Time Data Demo </a>
1.1       maekawa  5502: 3 title
                   5503: ?commands set title
                   5504: ?commands show title
                   5505: ?set title
                   5506: ?show title
                   5507: ?title
                   5508:  The `set title` command produces a plot title that is centered at the top of
                   5509:  the plot.  `set title` is a special case of `set label`.
                   5510:
                   5511:  Syntax:
                   5512:        set title {"<title-text>"} {<xoff>}{,<yoff>} {"<font>,{<size>}"}
                   5513:        show title
                   5514:
                   5515:  Specifying constants <xoff> or <yoff> as optional offsets for the title will
                   5516:  move the title <xoff> or <yoff> character screen coordinates (not graph
                   5517:  coordinates).  For example, "`set title ,-1`" will change only the y offset
                   5518:  of the title, moving the title down by roughly the height of one character.
                   5519:
                   5520:  <font> is used to specify the font with which the title is to be written;
                   5521:  the units of the font <size> depend upon which terminal is used.
                   5522:
                   5523:  `set title` with no parameters clears the title.
                   5524:
                   5525:  See `syntax` for details about the processing of backslash sequences and
                   5526:  the distinction between single- and double-quotes.
                   5527: 3 tmargin
                   5528: ?commands set tmargin
                   5529: ?set tmargin
                   5530: ?tmargin
                   5531:  The command `set tmargin` sets the size of the top margin.  Please see
                   5532:  `set margin` for details.
                   5533: 3 trange
                   5534: ?commands set trange
                   5535: ?commands show trange
                   5536: ?set trange
                   5537: ?show trange
                   5538: ?trange
                   5539:  The `set trange` command sets the parametric range used to compute x and y
                   5540:  values when in parametric or polar modes.  Please see `set xrange` for
                   5541:  details.
                   5542: 3 urange
                   5543: ?commands set urange
                   5544: ?commands show urange
                   5545: ?set urange
                   5546: ?show urange
                   5547: ?urange
                   5548:  The `set urange` and `set vrange` commands set the parametric ranges used
                   5549:  to compute x, y, and z values when in `splot` parametric mode.  Please see
                   5550:  `set xrange` for details.
                   5551: 3 variables
                   5552: ?commands show variables
                   5553: ?show variables
                   5554:  The `show variables` command lists all user-defined variables and their
                   5555:  values.
                   5556:
                   5557:  Syntax:
                   5558:        show variables
                   5559: 3 version
                   5560: ?show version
                   5561:  The `show version` command lists the version of gnuplot being run, its last
                   5562:  modification date, the copyright holders, and email addresses for the FAQ,
                   5563:  the info-gnuplot mailing list, and reporting bugs--in short, the information
                   5564:  listed on the screen when the program is invoked interactively.
                   5565:
                   5566:  Syntax:
                   5567:        show version {long}
                   5568:
                   5569:  When the `long` option is given, it also lists the operating system, the
                   5570:  compilation options used when `gnuplot` was installed, the location of the
                   5571:  help file, and (again) the useful email addresses.
                   5572: 3 view
                   5573: ?commands set view
                   5574: ?commands show view
                   5575: ?set view
                   5576: ?show view
                   5577: ?view
                   5578:  The `set view` command sets the viewing angle for `splot`s.  It controls how
                   5579:  the 3-d coordinates of the plot are mapped into the 2-d screen space.  It
                   5580:  provides controls for both rotation and scaling of the plotted data, but
                   5581:  supports orthographic projections only.
                   5582:
                   5583:  Syntax:
                   5584:        set view <rot_x> {,{<rot_z>}{,{<scale>}{,<scale_z>}}}
                   5585:        show view
                   5586:
                   5587:  where <rot_x> and <rot_z> control the rotation angles (in degrees) in a
                   5588:  virtual 3-d coordinate system aligned with the screen such that initially
                   5589:  (that is, before the rotations are performed) the screen horizontal axis is
                   5590:  x, screen vertical axis is y, and the axis perpendicular to the screen is z.
                   5591:  The first rotation applied is <rot_x> around the x axis.  The second rotation
                   5592:  applied is <rot_z> around the new z axis.
                   5593:
                   5594:  <rot_x> is bounded to the [0:180] range with a default of 60 degrees, while
                   5595:  <rot_z> is bounded to the [0:360] range with a default of 30 degrees.
                   5596:  <scale> controls the scaling of the entire `splot`, while <scale_z> scales
                   5597:  the z axis only.  Both scales default to 1.0.
                   5598:
                   5599:  Examples:
                   5600:        set view 60, 30, 1, 1
                   5601:        set view ,,0.5
                   5602:
                   5603:  The first sets all the four default values.  The second changes only scale,
                   5604:  to 0.5.
                   5605:
                   5606:  See also `set ticslevel`.
                   5607: 3 vrange
                   5608: ?commands set vrange
                   5609: ?commands show vrange
                   5610: ?set vrange
                   5611: ?show vrange
                   5612: ?vrange
                   5613:  The `set urange` and `set vrange` commands set the parametric ranges used
                   5614:  to compute x, y, and z values when in `splot` parametric mode.  Please see
                   5615:  `set xrange` for details.
                   5616: 3 x2data
                   5617: ?commands set x2data
                   5618: ?commands show x2data
                   5619: ?set x2data
                   5620: ?show x2data
                   5621: ?x2data
                   5622:  The `set x2data` command sets data on the x2 (top) axis to timeseries
                   5623:  (dates/times).  Please see `set xdata`.
                   5624: 3 x2dtics
                   5625: ?commands set x2dtics
                   5626: ?commands set nox2dtics
                   5627: ?commands show x2dtics
                   5628: ?set x2dtics
                   5629: ?set nox2dtics
                   5630: ?show x2dtics
                   5631: ?x2dtics
                   5632: ?nox2dtics
                   5633:  The `set x2dtics` command changes tics on the x2 (top) axis to days of the
                   5634:  week.  Please see `set xdtics` for details.
                   5635: 3 x2label
                   5636: ?commands set x2label
                   5637: ?commands show x2label
                   5638: ?set x2label
                   5639: ?show x2label
                   5640: ?x2label
                   5641:  The `set x2label` command sets the label for the x2 (top) axis.  Please see
                   5642:  `set xlabel`.
                   5643: 3 x2mtics
                   5644: ?commands set x2mtics
                   5645: ?commands set nox2mtics
                   5646: ?commands show x2mtics
                   5647: ?set x2mtics
                   5648: ?set nox2mtics
                   5649: ?show x2mtics
                   5650: ?x2mtics
                   5651: ?nox2mtics
                   5652:  The `set x2mtics` command changes tics on the x2 (top) axis to months of the
                   5653:  year.  Please see `set xmtics` for details.
                   5654: 3 x2range
                   5655: ?commands set x2range
                   5656: ?commands show x2range
                   5657: ?set x2range
                   5658: ?show x2range
                   5659: ?x2range
                   5660:  The `set x2range` command sets the horizontal range that will be displayed on
                   5661:  the x2 (top) axis.  Please see `set xrange` for details.
                   5662: 3 x2tics
                   5663: ?commands set x2tics
                   5664: ?commands set nox2tics
                   5665: ?commands show x2tics
                   5666: ?set x2tics
                   5667: ?set nox2tics
                   5668: ?show x2tics
                   5669: ?x2tics
                   5670: ?nox2tics
                   5671:  The `set x2tics` command controls major (labelled) tics on the x2 (top) axis.
                   5672:  Please see `set xtics` for details.
                   5673: 3 x2zeroaxis
                   5674: ?commands set x2zeroaxis
                   5675: ?commands set nox2zeroaxis
                   5676: ?commands show x2zeroaxis
                   5677: ?set x2zeroaxis
                   5678: ?set nox2zeroaxis
                   5679: ?show x2zeroaxis
                   5680: ?x2zeroaxis
                   5681: ?nox2zeroaxis
                   5682:  The `set x2zeroaxis` command draws a line at the origin of the x2 (top) axis
                   5683:  (y2 = 0).  For details, please see
                   5684:  `set zeroaxis`.
                   5685: 3 xdata
                   5686: ?commands set xdata
                   5687: ?commands show xdata
                   5688: ?set xdata
                   5689: ?show xdata
                   5690: ?xdata
                   5691:  This command sets the datatype on the x axis to time/date.  A similar command
                   5692:  does the same thing for each of the other axes.
                   5693:
                   5694:  Syntax:
                   5695:        set xdata {time}
                   5696:        show xdata
                   5697:
                   5698:  The same syntax applies to `ydata`, `zdata`, `x2data` and `y2data`.
                   5699:
                   5700:  The `time` option signals that the datatype is indeed time/date.  If the
                   5701:  option is not specified, the datatype reverts to normal.
                   5702:
                   5703:  See `set timefmt` to tell `gnuplot` how to read date or time data.  The
                   5704:  time/date is converted to seconds from start of the century.  There is
                   5705:  currently only one timefmt, which implies that all the time/date columns must
1.1.1.3 ! ohara    5706:  conform to this format.  Specification of ranges should be supplied as quoted
1.1       maekawa  5707:  strings according to this format to avoid interpretation of the time/date as
                   5708:  an expression.
                   5709:
                   5710:  The function 'strftime' (type "man strftime" on unix to look it up) is used
                   5711:  to print tic-mark labels.  `gnuplot` tries to figure out a reasonable format
                   5712:  for this  unless the `set format x "string"` has supplied something that does
                   5713:  not look like a decimal format (more than one '%' or neither %f nor %g).
                   5714:
                   5715:  See also `Time/date` for more information.
                   5716: 3 xdtics
                   5717: ?commands set xdtics
                   5718: ?commands set noxdtics
                   5719: ?commands show xdtics
                   5720: ?set xdtics
                   5721: ?set noxdtics
                   5722: ?show xdtics
                   5723: ?xdtics
                   5724: ?noxdtics
                   5725:  The `set xdtics` commands converts the x-axis tic marks to days of the week
                   5726:  where 0=Sun and 6=Sat.  Overflows are converted modulo 7 to dates.  `set
                   5727:  noxdtics` returns the labels to their default values.  Similar commands do
                   5728:  the same things for the other axes.
                   5729:
                   5730:  Syntax:
                   5731:        set xdtics
                   5732:        set noxdtics
                   5733:        show xdtics
                   5734:
                   5735:  The same syntax applies to `ydtics`, `zdtics`, `x2dtics` and `y2dtics`.
                   5736:
                   5737:  See also the `set format` command.
                   5738: 3 xlabel
                   5739: ?commands set xlabel
                   5740: ?commands show xlabel
                   5741: ?set xlabel
                   5742: ?show xlabel
                   5743: ?xlabel
                   5744:  The `set xlabel` command sets the x axis label.  Similar commands set labels
                   5745:  on the other axes.
                   5746:
                   5747:  Syntax:
                   5748:        set xlabel {"<label>"} {<xoff>}{,<yoff>} {"<font>{,<size>}"}
                   5749:        show xlabel
                   5750:
                   5751:  The same syntax applies to `x2label`, `ylabel`, `y2label` and `zlabel`.
                   5752:
                   5753:  Specifying the constants <xoff> or <yoff> as optional offsets for a label
                   5754:  will move it <xoff> or <yoff> character widths or heights.  For example,
                   5755:  "` set xlabel -1`" will change only the x offset of the xlabel, moving the
                   5756:  label roughly one character width to the left.   The size of a character
                   5757:  depends on both the font and the terminal.
                   5758:
                   5759:  <font> is used to specify the font in which the label is written; the units
                   5760:  of the font <size> depend upon which terminal is used.
                   5761:
                   5762:  To clear a label, put no options on the command line, e.g., "`set y2label`".
                   5763:
                   5764:  The default positions of the axis labels are as follows:
                   5765:
                   5766:  xlabel:  The x-axis label is centered below the bottom axis.
                   5767:
                   5768:  ylabel:  The position of the y-axis label depends on the terminal, and can be
                   5769:  one of the following three positions:
                   5770:
                   5771:  1. Horizontal text flushed left at the top left of the plot.  Terminals that
                   5772:  cannot rotate text will probably use this method.  If `set x2tics` is also
                   5773:  in use, the ylabel may overwrite the left-most x2tic label.  This may be
                   5774:  remedied by adjusting the ylabel position or the left margin.
                   5775:
                   5776:  2. Vertical text centered vertically at the left of the plot.  Terminals
                   5777:  that can rotate text will probably use this method.
                   5778:
                   5779:  3. Horizontal text centered vertically at the left of the plot.  The EEPIC,
                   5780:  LaTeX and TPIC drivers use this method.  The user must insert line breaks
                   5781:  using \\ to prevent the ylabel from overwriting the plot.  To produce a
                   5782:  vertical row of characters, add \\ between every printing character (but this
                   5783:  is ugly).
                   5784:
                   5785:  zlabel: The z-axis label is centered along the z axis and placed in the space
                   5786:  above the grid level.
                   5787:
                   5788:  y2label: The y2-axis label is placed to the right of the y2 axis.  The
                   5789:  position is terminal-dependent in the same manner as is the y-axis label.
                   5790:
                   5791:  x2label: The x2-axis label is placed above the top axis but below the plot
                   5792:  title.  It is also possible to create an x2-axis label by using new-line
                   5793:  characters to make a multi-line plot title, e.g.,
                   5794:
                   5795:        set title "This is the title\n\nThis is the x2label"
                   5796:
                   5797:  Note that double quotes must be used.  The same font will be used for both
                   5798:  lines, of course.
                   5799:
                   5800:  If you are not satisfied with the default position of an axis label, use `set
                   5801:  label` instead--that command gives you much more control over where text is
                   5802:  placed.
                   5803:
1.1.1.3 ! ohara    5804:  Please see `syntax` for further information about backslash processing
1.1       maekawa  5805:  and the difference between single- and double-quoted strings.
                   5806: 3 xmtics
                   5807: ?commands set xmtics
                   5808: ?commands set noxmtics
                   5809: ?commands show xmtics
                   5810: ?set xmtics
                   5811: ?set noxmtics
                   5812: ?show xmtics
                   5813: ?xmtics
                   5814: ?noxmtics
1.1.1.3 ! ohara    5815:  The `set xmtics` command converts the x-axis tic marks to months of the
1.1       maekawa  5816:  year where 1=Jan and 12=Dec.  Overflows are converted modulo 12 to months.
                   5817:  The tics are returned to their default labels by `set noxmtics`.  Similar
                   5818:  commands perform the same duties for the other axes.
                   5819:
                   5820:  Syntax:
                   5821:        set xmtics
                   5822:        set noxmtics
                   5823:        show xmtics
                   5824:
                   5825:  The same syntax applies to `x2mtics`, `ymtics`, `y2mtics`, and `zmtics`.
                   5826:
                   5827:  See also the `set format` command.
                   5828: 3 xrange
                   5829: ?commands set xrange
                   5830: ?commands show xrange
                   5831: ?set xrange
                   5832: ?show xrange
1.1.1.3 ! ohara    5833: ?writeback
        !          5834: ?restore
1.1       maekawa  5835: ?xrange
                   5836:  The `set xrange` command sets the horizontal range that will be displayed.
                   5837:  A similar command exists for each of the other axes, as well as for the
                   5838:  polar radius r and the parametric variables t, u, and v.
                   5839:
                   5840:  Syntax:
1.1.1.3 ! ohara    5841:        set xrange { [{{<min>}:{<max>}}] {{no}reverse} {{no}writeback} }
        !          5842:                   | restore
1.1       maekawa  5843:        show xrange
                   5844:
                   5845:  where <min> and <max> terms are constants, expressions or an asterisk to set
                   5846:  autoscaling.  If the data are time/date, you must give the range as a quoted
                   5847:  string according to the `set timefmt` format.  Any value omitted will not be
                   5848:  changed.
                   5849:
                   5850:  The same syntax applies to `yrange`, `zrange`, `x2range`, `y2range`,
                   5851:  `rrange`, `trange`, `urange` and `vrange`.
                   5852:
                   5853:  The `reverse` option reverses the direction of the axis, e.g., `set xrange
                   5854:  [0:1] reverse` will produce an axis with 1 on the left and 0 on the right.
                   5855:  This is identical to the axis produced by `set xrange [1:0]`, of course.
                   5856:  `reverse` is intended primarily for use with `autoscale`.
                   5857:
                   5858:  The `writeback` option essentially saves the range found by `autoscale` in
                   5859:  the buffers that would be filled by `set xrange`.  This is useful if you wish
                   5860:  to plot several functions together but have the range determined by only
                   5861:  some of them.  The `writeback` operation is performed during the `plot`
1.1.1.3 ! ohara    5862:  execution, so it must be specified before that command.  To restore
        !          5863:  the last saved horizontal range use `set xrange restore`. For example,
1.1       maekawa  5864:
                   5865:        set xrange [-10:10]
                   5866:        set yrange [] writeback
                   5867:        plot sin(x)
1.1.1.3 ! ohara    5868:        set yrange restore
1.1       maekawa  5869:        replot x/2
                   5870:
                   5871:  results in a yrange of [-1:1] as found only from the range of sin(x); the
                   5872:  [-5:5] range of x/2 is ignored.  Executing `show yrange` after each command
                   5873:  in the above example should help you understand what is going on.
                   5874:
                   5875:  In 2-d, `xrange` and `yrange` determine the extent of the axes, `trange`
                   5876:  determines the range of the parametric variable in parametric mode or the
                   5877:  range of the angle in polar mode.  Similarly in parametric 3-d, `xrange`,
                   5878:  `yrange`, and `zrange` govern the axes and `urange` and `vrange` govern the
                   5879:  parametric variables.
                   5880:
                   5881:  In polar mode, `rrange` determines the radial range plotted.  <rmin> acts as
                   5882:  an additive constant to the radius, whereas <rmax> acts as a clip to the
                   5883:  radius---no point with radius greater than <rmax> will be plotted.  `xrange`
                   5884:  and `yrange` are affected---the ranges can be set as if the graph was of
                   5885:  r(t)-rmin, with rmin added to all the labels.
                   5886:
                   5887:  Any range may be partially or totally autoscaled, although it may not make
                   5888:  sense to autoscale a parametric variable unless it is plotted with data.
                   5889:
                   5890:  Ranges may also be specified on the `plot` command line.  A range given on
                   5891:  the plot line will be used for that single `plot` command; a range given by
                   5892:  a `set` command will be used for all subsequent plots that do not specify
                   5893:  their own ranges.  The same holds true for `splot`.
                   5894:
                   5895:  Examples:
                   5896:
                   5897:  To set the xrange to the default:
                   5898:        set xrange [-10:10]
                   5899:
                   5900:  To set the yrange to increase downwards:
                   5901:        set yrange [10:-10]
                   5902:
                   5903:  To change zmax to 10 without affecting zmin (which may still be autoscaled):
                   5904:        set zrange [:10]
                   5905:
                   5906:  To autoscale xmin while leaving xmax unchanged:
                   5907:        set xrange [*:]
                   5908: 3 xtics
                   5909: ?commands set xtics
                   5910: ?commands set noxtics
                   5911: ?commands show xtics
                   5912: ?set xtics
                   5913: ?set noxtics
                   5914: ?show xtics
                   5915: ?xtics
                   5916: ?noxtics
                   5917:  Fine control of the major (labelled) tics on the x axis is possible with the
                   5918:  `set xtics` command.  The tics may be turned off with the `set noxtics`
                   5919:  command, and may be turned on (the default state) with `set xtics`.  Similar
                   5920:  commands control the major tics on the y, z, x2 and y2 axes.
                   5921:
                   5922:  Syntax:
                   5923:        set xtics {axis | border} {{no}mirror} {{no}rotate}
                   5924:                  {  autofreq
                   5925:                   | <incr>
                   5926:                   | <start>, <incr> {,<end>}
                   5927:                   | ({"<label>"} <pos> {,{"<label>"} <pos>}...) }
                   5928:        set noxtics
                   5929:        show xtics
                   5930:
                   5931:  The same syntax applies to `ytics`, `ztics`, `x2tics` and `y2tics`.
                   5932:
                   5933:  `axis` or `border` tells `gnuplot` to put the tics (both the tics themselves
1.1.1.2   maekawa  5934:  and the accompanying labels) along the axis or the border, respectively.  If
                   5935:  the axis is very close to the border, the `axis` option can result in tic
                   5936:  labels overwriting other text written in the margin.
                   5937:
                   5938:  `mirror` tells `gnuplot` to put unlabelled tics at the same positions on the
                   5939:  opposite border.  `nomirror` does what you think it does.
                   5940:
                   5941:  `rotate` asks `gnuplot` to rotate the text through 90 degrees, which will be
                   5942:  done if the terminal driver in use supports text rotation.  `norotate`
                   5943:  cancels this.
                   5944:
                   5945:  The defaults are `border mirror norotate` for tics on the x and y axes, and
                   5946:  `border nomirror norotate` for tics on the x2 and y2 axes.  For the z axis,
1.1.1.3 ! ohara    5947:  the `{axis | border}` option is not available and the default is
1.1.1.2   maekawa  5948:  `nomirror`.  If you do want to mirror the z-axis tics, you might want to
                   5949:  create a bit more room for them with `set border`.
                   5950:
                   5951:  `set xtics` with no options restores the default border or axis if xtics are
                   5952:  being displayed;  otherwise it has no effect.  Any previously specified tic
                   5953:  frequency or position {and labels} are retained.
1.1       maekawa  5954:
                   5955:  Positions of the tics are calculated automatically by default or if the
                   5956:  `autofreq` option is given; otherwise they may be specified in either of
                   5957:  two forms:
                   5958:
                   5959:  The implicit <start>, <incr>, <end> form specifies that a series of tics will
                   5960:  be plotted on the axis between the values <start> and <end> with an increment
                   5961:  of <incr>.  If <end> is not given, it is assumed to be infinity.  The
                   5962:  increment may be negative.  If neither <start> nor <end> is given, <start> is
                   5963:  assumed to be negative infinity, <end> is assumed to be positive infinity,
1.1.1.3 ! ohara    5964:  and the tics will be drawn at integral multiples of <incr>.  If the axis is
1.1       maekawa  5965:  logarithmic, the increment will be used as a multiplicative factor.
                   5966:
                   5967:  Examples:
                   5968:
                   5969:  Make tics at 0, 0.5, 1, 1.5, ..., 9.5, 10.
                   5970:        set xtics 0,.5,10
                   5971:
                   5972:  Make tics at ..., -10, -5, 0, 5, 10, ...
                   5973:        set xtics 5
                   5974:
                   5975:  Make tics at 1, 100, 1e4, 1e6, 1e8.
1.1.1.3 ! ohara    5976:        set logscale x; set xtics 1,100,1e8
1.1       maekawa  5977:
                   5978:  The explicit ("<label>" <pos>, ...) form allows arbitrary tic positions or
                   5979:  non-numeric tic labels.  A set of tics is a set of positions, each with its
                   5980:  own optional label.  Note that the label is a string enclosed by quotes.  It
                   5981:  may be a constant string, such as "hello", may contain formatting information
                   5982:  for converting the position into its label, such as "%3f clients", or may be
                   5983:  empty, "".  See `set format` for more information.  If no string is given,
                   5984:  the default label (numerical) is used.  In this form, the tics do not need to
                   5985:  be listed in numerical order.
                   5986:
                   5987:  Examples:
                   5988:        set xtics ("low" 0, "medium" 50, "high" 100)
                   5989:        set xtics (1,2,4,8,16,32,64,128,256,512,1024)
                   5990:        set ytics ("bottom" 0, "" 10, "top" 20)
                   5991:
                   5992:  In the second example, all tics are labelled.  In the third, only the end
                   5993:  tics are labelled.
                   5994:
                   5995:  However they are specified, tics will only be plotted when in range.
                   5996:
                   5997:  Format (or omission) of the tic labels is controlled by `set format`, unless
1.1.1.3 ! ohara    5998:  the explicit text of a labels is included in the `set xtics (`<label>`)` form.
1.1       maekawa  5999:
                   6000:  Minor (unlabelled) tics can be added by the `set mxtics` command.
                   6001:
                   6002:  In case of timeseries data, position values must be given as quoted dates
                   6003:  or times according to the format `timefmt`.  If the <start>, <incr>, <end>
                   6004:  form is used, <start> and <end> must be given according to `timefmt`, but
                   6005:  <incr> must be in seconds.  Times will be written out according to the format
                   6006:  given on `set format`, however.
                   6007:
                   6008:  Examples:
                   6009:        set xdata time
                   6010:        set timefmt "%d/%m"
                   6011:        set format x "%b %d"
                   6012:        set xrange ["01/12":"06/12"]
                   6013:        set xtics "01/12", 172800, "05/12"
                   6014:
                   6015:        set xdata time
                   6016:        set timefmt "%d/%m"
                   6017:        set format x "%b %d"
                   6018:        set xrange ["01/12":"06/12"]
                   6019:        set xtics ("01/12", "" "03/12", "05/12")
                   6020:  Both of these will produce tics "Dec 1", "Dec 3", and "Dec 5", but in the
                   6021:  second example the tic at "Dec 3" will be unlabelled.
                   6022:
                   6023: 3 xzeroaxis
                   6024: ?commands set xzeroaxis
                   6025: ?commands set noxzeroaxis
                   6026: ?commands show xzeroaxis
                   6027: ?set xzeroaxis
                   6028: ?set noxzeroaxis
                   6029: ?show xzeroaxis
                   6030: ?xzeroaxis
                   6031: ?noxzeroaxis
                   6032:  The `set xzeroaxis` command draws a line at y = 0.  For details, please see
                   6033:  `set zeroaxis`.
                   6034: 3 y2data
                   6035: ?commands set y2data
                   6036: ?commands show y2data
                   6037: ?set y2data
                   6038: ?show y2data
                   6039: ?y2data
                   6040:  The `set y2data` command sets y2 (right-hand) axis data to timeseries
                   6041:  (dates/times).  Please see `set xdata`.
                   6042: 3 y2dtics
                   6043: ?commands set y2dtics
                   6044: ?commands set noy2dtics
                   6045: ?set y2dtics
                   6046: ?set noy2dtics
                   6047: ?show y2dtics
                   6048: ?y2dtics
                   6049: ?noy2dtics
                   6050:  The `set y2dtics` command changes tics on the y2 (right-hand) axis to days of
                   6051:  the week.  Please see `set xdtics` for details.
                   6052: 3 y2label
                   6053: ?commands set y2label
                   6054: ?commands show y2label
                   6055: ?set y2label
                   6056: ?show y2label
                   6057: ?y2label
1.1.1.3 ! ohara    6058:  The `set y2label` command sets the label for the y2 (right-hand) axis.
1.1       maekawa  6059:  Please see `set xlabel`.
                   6060: 3 y2mtics
                   6061: ?commands set y2mtics
                   6062: ?commands set noy2mtics
                   6063: ?commands show y2mtics
                   6064: ?set y2mtics
                   6065: ?set noy2mtics
                   6066: ?show y2mtics
                   6067: ?y2mtics
                   6068: ?noy2mtics
                   6069:  The `set y2mtics` command changes tics on the y2 (right-hand) axis to months
                   6070:  of the year.  Please see `set xmtics` for details.
                   6071: 3 y2range
                   6072: ?commands set y2range
                   6073: ?commands show y2range
                   6074: ?set y2range
                   6075: ?show y2range
                   6076: ?y2range
                   6077:  The `set y2range` command sets the vertical range that will be displayed on
                   6078:  the y2 (right-hand) axis.  Please see `set xrange` for details.
                   6079: 3 y2tics
                   6080: ?commands set y2tics
                   6081: ?commands set noy2tics
                   6082: ?commands show y2tics
                   6083: ?set y2tics
                   6084: ?set noy2tics
                   6085: ?show y2tics
                   6086: ?y2tics
                   6087: ?noy2tics
                   6088:  The `set y2tics` command controls major (labelled) tics on the y2 (right-hand)
                   6089:  axis.  Please see `set xtics` for details.
                   6090: 3 y2zeroaxis
                   6091: ?commands set y2zeroaxis
                   6092: ?commands set noy2zeroaxis
                   6093: ?commands show y2zeroaxis
                   6094: ?set y2zeroaxis
                   6095: ?set noy2zeroaxis
                   6096: ?show y2zeroaxis
                   6097: ?y2zeroaxis
                   6098: ?noy2zeroaxis
                   6099:  The `set y2zeroaxis` command draws a line at the origin of the y2 (right-hand)
                   6100:  axis (x2 = 0).  For details, please see `set zeroaxis`.
                   6101: 3 ydata
                   6102: ?commands set ydata
                   6103: ?commands show ydata
                   6104: ?set ydata
                   6105: ?show ydata
                   6106: ?ydata
1.1.1.3 ! ohara    6107:  The `set ydata` command sets y-axis data to timeseries (dates/times).
        !          6108:  Please see `set xdata`.
1.1       maekawa  6109: 3 ydtics
                   6110: ?commands set ydtics
                   6111: ?commands set noydtics
                   6112: ?commands show ydtics
                   6113: ?set ydtics
                   6114: ?set noydtics
                   6115: ?show ydtics
                   6116: ?ydtics
                   6117: ?noydtics
                   6118:  The `set ydtics` command changes tics on the y axis to days of the week.
                   6119:  Please see `set xdtics` for details.
                   6120: 3 ylabel
                   6121: ?commands set ylabel
                   6122: ?commands show ylabel
                   6123: ?set ylabel
                   6124: ?show ylabel
                   6125: ?ylabel
                   6126:  This command sets the label for the y axis.  Please see `set xlabel`.
                   6127: 3 ymtics
                   6128: ?commands set ymtics
                   6129: ?commands set noymtics
                   6130: ?commands show ymtics
                   6131: ?set ymtics
                   6132: ?set noymtics
                   6133: ?show ymtics
                   6134: ?ymtics
                   6135: ?noymtics
                   6136:  The `set ymtics` command changes tics on the y axis to months of the year.
                   6137:  Please see `set xmtics` for details.
                   6138: 3 yrange
                   6139: ?commands set yrange
                   6140: ?commands show yrange
                   6141: ?set yrange
                   6142: ?show yrange
                   6143: ?yrange
                   6144:  The `set yrange` command sets the vertical range that will be displayed on
                   6145:  the y axis.  Please see `set xrange` for details.
                   6146: 3 ytics
                   6147: ?commands set ytics
                   6148: ?commands set noytics
                   6149: ?commands show ytics
                   6150: ?set ytics
                   6151: ?set noytics
                   6152: ?show ytics
                   6153: ?ytics
                   6154: ?noytics
                   6155:  The `set ytics` command controls major (labelled) tics on the y axis.
                   6156:  Please see `set xtics` for details.
                   6157: 3 yzeroaxis
                   6158: ?commands set yzeroaxis
                   6159: ?commands set noyzeroaxis
                   6160: ?commands show yzeroaxis
                   6161: ?set yzeroaxis
                   6162: ?set noyzeroaxis
                   6163: ?show yzeroaxis
                   6164: ?yzeroaxis
                   6165: ?noyzeroaxis
                   6166:  The `set yzeroaxis` command draws a line at x = 0.  For details, please see
                   6167:  `set zeroaxis`.
                   6168: 3 zdata
                   6169: ?commands set zdata
                   6170: ?commands show zdata
                   6171: ?set zdata
                   6172: ?show zdata
                   6173: ?zdata
1.1.1.3 ! ohara    6174:  The `set zdata` command sets z-axis data to timeseries (dates/times).
        !          6175:  Please see `set xdata`.
1.1       maekawa  6176: 3 zdtics
                   6177: ?commands set zdtics
                   6178: ?commands set nozdtics
                   6179: ?commands show zdtics
                   6180: ?set zdtics
                   6181: ?set nozdtics
                   6182: ?show zdtics
                   6183: ?zdtics
                   6184: ?nozdtics
                   6185:  The `set zdtics` command changes tics on the z axis to days of the week.
                   6186:  Please see `set xdtics` for details.
                   6187: 3 zero
                   6188: ?commands set zero
                   6189: ?commands show zero
                   6190: ?set zero
                   6191: ?show zero
                   6192: ?zero
                   6193:  The `zero` value is the default threshold for values approaching 0.0.
                   6194:
                   6195:  Syntax:
                   6196:        set zero <expression>
                   6197:        show zero
                   6198:
                   6199:  `gnuplot` will not plot a point if its imaginary part is greater in magnitude
                   6200:  than the `zero` threshold.  This threshold is also used in various other
                   6201:  parts of `gnuplot` as a (crude) numerical-error threshold.  The default
                   6202:  `zero` value is 1e-8.  `zero` values larger than 1e-3 (the reciprocal of the
                   6203:  number of pixels in a typical bitmap display) should probably be avoided, but
                   6204:  it is not unreasonable to set `zero` to 0.0.
                   6205: 3 zeroaxis
                   6206: ?commands set zeroaxis
                   6207: ?commands set nozeroaxis
                   6208: ?commands show zeroaxis
                   6209: ?set zeroaxis
                   6210: ?set nozeroaxis
                   6211: ?show zeroaxis
                   6212: ?zeroaxis
                   6213: ?nozeroaxis
                   6214:  The x axis may be drawn by `set xzeroaxis` and removed by `set noxzeroaxis`.
                   6215:  Similar commands behave similarly for the y, x2, and y2 axes.
                   6216:
                   6217:  Syntax:
                   6218:        set {x|x2|y|y2|}zeroaxis { {linestyle | ls <line_style>}
                   6219:                                   | { linetype | lt <line_type>}
                   6220:                                     { linewidth | lw <line_width>}}
                   6221:        set no{x|x2|y|y2|}zeroaxis
                   6222:        show {x|y|}zeroaxis
                   6223:
                   6224:
                   6225:  By default, these options are off.  The selected zero axis is drawn
                   6226:  with a line of type <line_type> and width <line_width> (if supported
                   6227:  by the terminal driver currently in use), or a user-defined style
                   6228:  <line_style>.
                   6229:
                   6230:  If no linetype is specified, any zero axes selected will be drawn
                   6231:  using the axis linetype (linetype 0).
                   6232:
                   6233:  `set zeroaxis l` is equivalent to `set xzeroaxis l; set yzeroaxis l`. `set
                   6234:  nozeroaxis` is equivalent to `set noxzeroaxis; set noyzeroaxis`.
                   6235: 3 zlabel
                   6236: ?commands set zlabel
                   6237: ?commands show zlabel
                   6238: ?set zlabel
                   6239: ?show zlabel
                   6240: ?zlabel
                   6241:  This command sets the label for the z axis.  Please see `set xlabel`.
                   6242: 3 zmtics
                   6243: ?commands set zmtics
                   6244: ?commands set nozmtics
                   6245: ?commands show zmtics
                   6246: ?set zmtics
                   6247: ?set nozmtics
                   6248: ?show zmtics
                   6249: ?zmtics
                   6250: ?nozmtics
                   6251:  The `set zmtics` command changes tics on the z axis to months of the year.
                   6252:  Please see `set xmtics` for details.
                   6253: 3 zrange
                   6254: ?commands set zrange
                   6255: ?commands show zrange
                   6256: ?set zrange
                   6257: ?show zrange
                   6258: ?zrange
                   6259:  The `set zrange` command sets the range that will be displayed on the z axis.
                   6260:  The zrange is used only by `splot` and is ignored by `plot`.  Please see `set
                   6261:  xrange` for details.
                   6262: 3 ztics
                   6263: ?commands set ztics
                   6264: ?commands set noztics
                   6265: ?commands show ztics
                   6266: ?set ztics
                   6267: ?set noztics
                   6268: ?show ztics
                   6269: ?ztics
                   6270: ?noztics
                   6271:  The `set ztics` command controls major (labelled) tics on the z axis.
                   6272:  Please see `set xtics` for details.
                   6273: 2 shell
                   6274: ?commands shell
                   6275: ?shell
                   6276:  The `shell` command spawns an interactive shell.  To return to `gnuplot`,
                   6277:  type `logout` if using VMS, `exit` or the END-OF-FILE character if using
                   6278:  Unix, `endcli` if using AmigaOS, or `exit` if using MS-DOS or OS/2.
                   6279:
                   6280:  A single shell command may be spawned by preceding it with the ! character
                   6281:  ($ if using VMS) at the beginning of a command line.  Control will return
                   6282:  immediately to `gnuplot` after this command is executed.  For example, in
                   6283:  Unix, AmigaOS, MS-DOS or OS/2,
                   6284:
                   6285:        ! dir
                   6286:
                   6287:  prints a directory listing and then returns to `gnuplot`.
                   6288:
                   6289:  On an Atari, the `!` command first checks whether a shell is already loaded
                   6290:  and uses it, if available.  This is practical if `gnuplot` is run from
                   6291:  `gulam`, for example.
                   6292: 2 splot
                   6293: ?commands splot
                   6294: ?splot
                   6295:  `splot` is the command for drawing 3-d plots (well, actually projections on
                   6296:  a 2-d surface, but you knew that).  It can create a plot from functions or
                   6297:  a data file in a manner very similar to the `plot` command.
                   6298:
                   6299:  See `plot` for features common to the `plot` command; only differences are
                   6300:  discussed in detail here.  Note specifically that the `binary` and `matrix`
                   6301:  options (discussed under "datafile-modifiers") are not available for `plot`.
                   6302:
                   6303:  Syntax:
                   6304:        splot {<ranges>}
                   6305:              <function> | "<datafile>" {datafile-modifiers}}
                   6306:              {<title-spec>} {with <style>}
                   6307:              {, {definitions,} <function> ...}
                   6308:
                   6309:  where either a <function> or the name of a data file enclosed in quotes is
                   6310:  supplied.  The function can be a mathematical expression, or a triple of
                   6311:  mathematical expressions in parametric mode.
                   6312:
                   6313:  By default `splot` draws the xy plane completely below the plotted data.
                   6314:  The offset between the lowest ztic and the xy plane can be changed by `set
                   6315:  ticslevel`.  The orientation of a `splot` projection is controlled by
                   6316:  `set view`.  See `set view` and `set ticslevel` for more information.
                   6317:
                   6318:  The syntax for setting ranges on the `splot` command is the same as for
                   6319:  `plot`.  In non-parametric mode, the order in which ranges must be given is
                   6320:  `xrange`, `yrange`, and `zrange`.  In parametric mode, the order is `urange`,
                   6321:  `vrange`, `xrange`, `yrange`, and `zrange`.
                   6322:
                   6323:  The `title` option is the same as in `plot`.  The operation of `with` is also
                   6324:  the same as in `plot`, except that the plotting styles available to `splot`
                   6325:  are limited to `lines`, `points`, `linespoints`, `dots`, and `impulses`;  the
                   6326:  error-bar capabilities of `plot` are not available for `splot`.
                   6327:
                   6328:  The datafile options have more differences.
                   6329: 3 data-file
                   6330: ?commands splot datafile
                   6331: ?splot datafile
                   6332: ?splot data-file
                   6333:  As for `plot`, discrete data contained in a file can be displayed by
                   6334:  specifying the name of the data file, enclosed in quotes,  on the `splot`
                   6335:  command line.
                   6336:
                   6337:  Syntax:
                   6338:        splot '<file_name>' {binary | matrix}
                   6339:                            {index <index list>}
                   6340:                            {every <every list>}
                   6341:                            {using <using list>}
                   6342:
                   6343:  The special filenames `""` and `"-"` are permitted, as in `plot`.
                   6344:
                   6345:  In brief, `binary` and `matrix` indicate that the the data are in a special
                   6346:  form, `index` selects which data sets in a multi-data-set file are to be
                   6347:  plotted, `every` specifies which datalines (subsets) within a single data
                   6348:  set are to be plotted, and `using` determines how the columns within a single
                   6349:  record are to be interpreted.
                   6350:
                   6351:  The options `index` and `every` behave the same way as with `plot`;  `using`
                   6352:  does so also, except that the `using` list must provide three entries
                   6353:  instead of two.
                   6354:
                   6355:  The `plot` options `thru` and `smooth` are not available for `splot`, but
                   6356:  `cntrparams` and `dgrid3d` provide limited smoothing cabilities.
                   6357:
                   6358:  Data file organization is essentially the same as for `plot`, except that
                   6359:  each point is an (x,y,z) triple.  If only a single value is provided, it
                   6360:  will be used for z, the datablock number will be used for y, and the index
                   6361:  of the data point in the datablock will be used for x.  If two values are
                   6362:  provided, `gnuplot` gives you an error message.  Three values are interpreted
                   6363:  as an (x,y,z) triple.  Additional values are generally used as errors, which
                   6364:  can be used by `fit`.
                   6365:
                   6366:  Single blank records separate datablocks in a `splot` datafile; `splot`
                   6367:  treats datablocks as the equivalent of function y-isolines.  No line will
                   6368:  join points separated by a blank record.  If all datablocks contain the same
                   6369:  number of points, `gnuplot` will draw cross-isolines between datablocks,
                   6370:  connecting corresponding points.  This is termed "grid data", and is required
                   6371:  for drawing a surface, for contouring (`set contour`) and hidden-line removal
                   6372:  (`set hidden3d`). See also `splot grid data`
                   6373:
                   6374:  It is no longer necessary to specify `parametric` mode for three-column
                   6375:  `splot`s.
                   6376: 4 binary
                   6377: ?commands splot datafile binary
                   6378: ?splot datafile binary
                   6379: ?splot binary
                   6380: ?data-file binary
                   6381: ?datafile binary
                   6382: ?binary
                   6383: ?binary data
                   6384: ?binary files
                   6385:  `splot` can read binary files written with a specific format (and on a
                   6386:  system with a compatible binary file representation.)
                   6387:
                   6388:  In previous versions, `gnuplot` dynamically detected binary data files.  It
                   6389:  is now necessary to specify the keyword `binary` directly after the filename.
                   6390:
                   6391:  Single precision floats are stored in a binary file as follows:
                   6392:
                   6393:        <N+1>  <y0>   <y1>   <y2>  ...  <yN>
                   6394:         <x0> <z0,0> <z0,1> <z0,2> ... <z0,N>
                   6395:         <x1> <z1,0> <z1,1> <z1,2> ... <z1,N>
                   6396:          :      :      :      :   ...    :
                   6397:
                   6398:  which are converted into triplets:
                   6399:        <x0> <y0> <z0,0>
                   6400:        <x0> <y1> <z0,1>
                   6401:        <x0> <y2> <z0,2>
                   6402:         :    :     :
                   6403:        <x0> <yN> <z0,N>
                   6404:
                   6405:        <x1> <y0> <z1,0>
                   6406:        <x1> <y1> <z1,1>
                   6407:         :    :     :
                   6408:
                   6409:  These triplets are then converted into `gnuplot` iso-curves and then
                   6410:  `gnuplot` proceeds in the usual manner to do the rest of the plotting.
                   6411:
                   6412:  A collection of matrix and vector manipulation routines (in C) is provided
                   6413:  in `binary.c`.  The routine to write binary data is
                   6414:
                   6415:        int fwrite_matrix(file,m,nrl,nrl,ncl,nch,row_title,column_title)
                   6416:
                   6417:  An example of using these routines is provided in the file `bf_test.c`, which
                   6418:  generates binary files for the demo file `demo/binary.dem`.
                   6419:
                   6420:  The `index` keyword is not supported, since the file format allows only one
                   6421:  surface per file.  The `every` and `using` filters are supported.  `using`
                   6422:  operates as if the data were read in the above triplet form.
1.1.1.2   maekawa  6423: ^ <a href="http://www.gnuplot.vt.edu/gnuplot/gpdocs/binary.html">Binary File Splot Demo.</a>
1.1       maekawa  6424: 4 example datafile
                   6425: ?commands splot datafile example
                   6426: ?splot datafile example
                   6427: ?splot example
                   6428:  A simple example of plotting a 3-d data file is
                   6429:
                   6430:        splot 'datafile.dat'
                   6431:
                   6432:  where the file "datafile.dat" might contain:
                   6433:
                   6434:        # The valley of the Gnu.
                   6435:           0 0 10
                   6436:           0 1 10
                   6437:           0 2 10
                   6438:
                   6439:           1 0 10
                   6440:           1 1 5
                   6441:           1 2 10
                   6442:
                   6443:           2 0 10
                   6444:           2 1 1
                   6445:           2 2 10
                   6446:
                   6447:           3 0 10
                   6448:           3 1 0
                   6449:           3 2 10
                   6450:
                   6451:  Note that "datafile.dat" defines a 4 by 3 grid ( 4 rows of 3 points each ).
                   6452:  Rows (datablocks) are separated by blank records.
                   6453:
                   6454: ^ <img align=bottom src="http://www.nas.nasa.gov/~woo/gnuplot/doc/splot.gif" alt="[splot.gif]" width=640 height=480>
                   6455:  Note also that the x value is held constant within each dataline.  If you
                   6456:  instead keep y constant, and plot with hidden-line removal enabled, you will
                   6457:  find that the surface is drawn 'inside-out'.
                   6458:
                   6459:  Actually for grid data it is not necessary to keep the x values constant
                   6460:  within a datablock, nor is it necessary to keep the same sequence of y
                   6461:  values.  `gnuplot` requires only that the number of points be the same for
                   6462:  each datablock.  However since the surface mesh, from which contours are
                   6463:  derived, connects sequentially corresponding points, the effect of an
                   6464:  irregular grid on a surface plot is unpredictable and should be examined
                   6465:  on a case-by-case basis.
                   6466: 4 matrix
                   6467: ?commands splot datafile matrix
                   6468: ?splot datafile matrix
                   6469: ?splot matrix
                   6470: ?data-file matrix
                   6471: ?datafile matrix
                   6472: ?matrix
                   6473:  The `matrix` flag indicates that the ASCII data are stored in matrix format.
                   6474:  The z-values are read in a row at a time, i. e.,
                   6475:        z11 z12 z13 z14 ...
                   6476:        z21 z22 z23 z24 ...
                   6477:        z31 z32 z33 z34 ...
                   6478:  and so forth.  The row and column indices are used for the x- and y-values.
                   6479: 3 grid_data
                   6480: ?commands splot grid_data
                   6481: ?splot grid_data
                   6482: ?grid_data
                   6483:  The 3D routines are designed for points in a grid format, with one sample,
                   6484:  datapoint, at each mesh intersection; the datapoints may originate from
                   6485:  either evaluating a function, see `set isosamples`, or reading a datafile,
                   6486:  see `splot datafile`.  The term "isoline" is applied to the mesh lines for
                   6487:  both functions and data.  Note that the mesh need not be rectangular in x
                   6488:  and y, as it may be parameterized in u and v, see `set isosamples`.
                   6489:
                   6490:  However, `gnuplot` does not require that format.  In the case of functions,
                   6491:  'samples' need not be equal to 'isosamples', i.e., not every x-isoline
                   6492:  sample need intersect a y-isoline. In the case of data files, if there
                   6493:  are an equal number of scattered data points in each datablock, then
                   6494:  "isolines" will connect the points in a datablock, and "cross-isolines"
                   6495:  will connect the corresponding points in each datablock to generate a
                   6496:  "surface".  In either case, contour and hidden3d modes may give different
                   6497:  plots than if the points were in the intended format.  Scattered data can be
                   6498:  converted to a {different} grid format with `set dgrid3d`.
                   6499:
                   6500:  The contour code tests for z intensity along a line between a point on a
                   6501:  y-isoline and the corresponding point in the next y-isoline.  Thus a `splot`
                   6502:  contour of a surface with samples on the x-isolines that do not coincide with
                   6503:  a y-isoline intersection will ignore such samples. Try:
                   6504:         set xrange [-pi/2:pi/2]; set yrange [-pi/2:pi/2]
                   6505:         set function style lp
                   6506:         set contour
                   6507:         set isosamples 10,10; set samples 10,10;
                   6508:         splot cos(x)*cos(y)
                   6509:         set samples 4,10; replot
                   6510:         set samples 10,4; replot
                   6511:
                   6512: 3 splot_overview
                   6513: ?commands splot_overview
                   6514: ? splot_overview
                   6515:  `splot` can display a surface as a collection of points, or by connecting
                   6516:  those points.  As with `plot`, the points may be read from a data file or
                   6517:  result from evaluation of a function at specified intervals, see `set
                   6518:  isosamples`.  The surface may be approximated by connecting the points
                   6519:  with straight line segments, see `set surface`, in which case the surface
                   6520:  can be made opaque with `set hidden3d.`  The orientation from which the 3d
                   6521:  surface is viewed can be changed with `set view`.
                   6522:
                   6523:  Additionally, for points in a grid format, `splot` can interpolate points
                   6524:  having a common amplitude (see `set contour`) and can then connect those
                   6525:  new points to display contour lines, either directly with straight-line
                   6526:  segments or smoothed lines (see `set cntrparams`).  Functions are already
                   6527:  evaluated in a grid format, determined by `set isosamples` and `set samples`,
                   6528:  while file data must either be in a grid format, as described in `data-file`,
                   6529:  or be used to generate a grid (see `set dgrid3d`).
                   6530:
                   6531:  Contour lines may be displayed either on the surface or projected onto the
                   6532:  base.  The base projections of the contour lines may be written to a
                   6533:  file, and then read with `plot`, to take advantage of `plot`'s additional
                   6534:  formatting capabilities.
                   6535: 2 test
                   6536: ?commands test
                   6537: ?test
                   6538:  `test` creates a display of line and point styles and other useful things
                   6539:  appropriate for the terminal you are using.
                   6540:
                   6541:  Syntax:
                   6542:        test
                   6543: 2 update
                   6544: ?commands update
                   6545: ?update
                   6546:  This command writes the current values of the fit parameters into the given
                   6547:  file, formatted as an initial-value file (as described in the `fit`section).
                   6548:  This is useful for saving the current values for later use or for restarting
                   6549:  a converged or stopped fit.
                   6550:
                   6551:  Syntax:
                   6552:        update <filename> {<filename>}
                   6553:
                   6554:  If a second filename is supplied, the updated values are written to this
                   6555:  file, and the original parameter file is left unmodified.
                   6556:
                   6557:  Otherwise, if the file already exists, `gnuplot` first renames it by
                   6558:  appending `.old` and then opens a new file.  That is, "`update 'fred'`"
                   6559:  behaves the same as "`!rename fred fred.old; update 'fred.old' 'fred'`".
                   6560:  [On DOS and other systems that use the twelve-character "filename.ext"
                   6561:  naming convention, "ext" will be "`old`" and "filename" will be related
                   6562:  (hopefully recognizably) to the initial name.  Renaming is not done at all
                   6563:  on VMS systems, since they use file-versioning.]
                   6564:
                   6565:  Please see `fit` for more information.
                   6566: 1 Graphical User Interfaces
                   6567: ?graphical user interfaces
                   6568: ?gui's
                   6569:  Several graphical user interfaces have been written for `gnuplot` and one for
                   6570:  win32 is included in this distribution.  In addition, there is a Macintosh
                   6571:  interface at
                   6572: ^<a href="ftp://ftp.ee.gatech.edu/pub/mac/gnuplot">
                   6573:         ftp://ftp.ee.gatech.edu/pub/mac/gnuplot
                   6574: ^</a>
                   6575:  and several X11 interfaces include three Tcl/Tk located at the usual Tcl/Tk
                   6576:  repositories.
                   6577: 1 Bugs
                   6578: ?bugs
                   6579:  Floating point exceptions (floating point number too large/small, divide by
                   6580:  zero, etc.) may occasionally be generated by user defined functions.  Some of
                   6581:  the demos in particular may cause numbers to exceed the floating point range.
                   6582:  Whether the system ignores such exceptions (in which case `gnuplot` labels
                   6583:  the corresponding point as undefined) or aborts `gnuplot` depends on the
                   6584:  compiler/runtime environment.
                   6585:
                   6586:  The bessel functions do not work for complex arguments.
                   6587:
                   6588:  The gamma function does not work for complex arguments.
                   6589:
                   6590:  As of `gnuplot` version 3.7, all development has been done using ANSI C.
                   6591:  With current operating system, compiler, and library releases, the OS
                   6592:  specific bugs documented in release 3.5, now relegated to `old_bugs`, may
                   6593:  no longer be relevant.
                   6594:
                   6595:  Bugs reported since the current release may be located via the official
                   6596:  distribution site:
                   6597:         ftp://ftp.dartmouth.edu/pub/gnuplot
                   6598:        http://www.cs.dartmouth.edu/gnuplot_info.html
                   6599:
                   6600:  Please e-mail any bugs to bug-gnuplot@dartmouth.edu.
                   6601: 2 Old_bugs
                   6602: ?old_bugs
                   6603: ?os_bugs
                   6604:  There is a bug in the stdio library for old Sun operating systems (SunOS
                   6605:  Sys4-3.2).  The "%g" format for 'printf' sometimes incorrectly prints numbers
                   6606:  (e.g., 200000.0 as "2").  Thus, tic mark labels may be incorrect on a Sun4
                   6607:  version of `gnuplot`.  A work-around is to rescale the data or use the `set
                   6608:  format` command to change the tic mark format to "%7.0f" or some other
                   6609:  appropriate format.  This appears to have been fixed in SunOS 4.0.
                   6610:
                   6611:  Another bug: On a Sun3 under SunOS 4.0, and on Sun4's under Sys4-3.2 and
                   6612:  SunOS 4.0, the 'sscanf' routine incorrectly parses "00 12" with the format
                   6613:  "%f %f" and reads 0 and 0 instead of 0 and 12.  This affects data input.  If
                   6614:  the data file contains x coordinates that are zero but are specified like
                   6615:  '00', '000', etc, then you will read the wrong y values.  Check any data
                   6616:  files or upgrade the SunOS.  It appears to have been fixed in SunOS 4.1.1.
                   6617:
                   6618:  Suns appear to overflow when calculating exp(-x) for large x, so `gnuplot`
                   6619:  gets an undefined result.  One work-around is to make a user-defined function
                   6620:  like e(x) = x<-500 ? 0 : exp(x).  This affects plots of Gaussians (exp(-x*x))
                   6621:  in particular, since x*x grows quite rapidly.
                   6622:
                   6623:  Microsoft C 5.1 has a nasty bug associated with the %g format for 'printf'.
                   6624:  When any of the formats "%.2g", "%.1g", "%.0g", "%.g" are used, 'printf' will
                   6625:  incorrectly print numbers in the range 1e-4 to 1e-1.  Numbers that should be
                   6626:  printed in the %e format are incorrectly printed in the %f format, with the
                   6627:  wrong number of zeros after the decimal point.  To work around this problem,
                   6628:  use the %e or %f formats explicitly.
                   6629:
                   6630:  `gnuplot`, when compiled with Microsoft C, did not work correctly on two VGA
                   6631:  displays that were tested.  The CGA, EGA and VGA drivers should probably be
                   6632:  rewritten to use the Microsoft C graphics library.  `gnuplot` compiled with
                   6633:  Borland C++ uses the Turbo C graphics drivers and does work correctly with
                   6634:  VGA displays.
                   6635:
                   6636:  VAX/VMS 4.7 C compiler release 2.4 also has a poorly implemented %g format
                   6637:  for 'printf'.  The numbers are printed numerically correct, but may not be in
                   6638:  the requested format.  The K&R second edition says that for the %g format, %e
                   6639:  is used if the exponent is less than -4 or greater than or equal to the
                   6640:  precision.  The VAX uses %e format if the exponent is less than -1.  The VAX
                   6641:  appears to take no notice of the precision when deciding whether to use %e or
                   6642:  %f for numbers less than 1.  To work around this problem, use the %e or %f
                   6643:  formats explicitly.  From the VAX C 2.4 release notes: e,E,f,F,g,G  Result
                   6644:  will always contain a decimal  point.  For g and G, trailing zeros will not
                   6645:  be removed from the result.
                   6646:
                   6647:  VAX/VMS 5.2 C compiler release 3.0 has a slightly better implemented %g
                   6648:  format than release 2.4, but not much.  Trailing decimal points are now
                   6649:  removed, but trailing zeros are still not removed from %g numbers in
                   6650:  exponential format.
                   6651:
                   6652:  The two preceding problems are actually in the libraries rather than in the
                   6653:  compilers.  Thus the problems will occur whether `gnuplot` is built using
                   6654:  either the DEC compiler or some other one (e.g. the latest gcc).
                   6655:
                   6656:  ULTRIX X11R3 has a bug that causes the X11 driver to display "every other"
                   6657:  graph.  The bug seems to be fixed in DEC's release of X11R4 so newer releases
                   6658:  of ULTRIX don't seem to have the problem.  Solutions for older sites include
                   6659:  upgrading the X11 libraries (from DEC or direct from MIT) or defining
                   6660:  ULTRIX_KLUDGE when compiling the x11.trm file.  Note that the kludge is not
                   6661:  an ideal fix, however.
                   6662:
                   6663:  The constant HUGE was incorrectly defined in the NeXT OS 2.0 operating
                   6664:  system.  HUGE should be set to 1e38 in plot.h. This error has been corrected
                   6665:  in the 2.1 version of NeXT OS.
                   6666:
                   6667:  Some older models of HP plotters do not have a page eject command 'PG'.  The
                   6668:  current HPGL driver uses this command in HPGL_reset.  This may need to be
                   6669:  removed for these plotters.  The current PCL5 driver uses HPGL/2 for text as
                   6670:  well as graphics.  This should be modified to use scalable PCL fonts.
                   6671:
                   6672:  On the Atari version, it is not possible to send output directly to the
                   6673:  printer (using `/dev/lp` as output file), since CRs are added to LFs in
                   6674:  binary output.  As a work-around, write the output to a file and copy it to
                   6675:  the printer afterwards using a shell command.
                   6676:
                   6677:  On AIX 4, the literal 'NaNq' in a datafile causes the special internal value
                   6678:  'not-a-number' to be stored, rather than setting an internal 'undefined'
                   6679:  flag.  A workaround is to use `set missing 'NaNq'`.
                   6680:
                   6681:  There may be an up-to-date list of bugs since the release on the WWW page:
                   6682:        http://www.cs.dartmouth.edu/gnuplot_info.html
                   6683:
                   6684:  Please report any bugs to bug-gnuplot@dartmouth.edu.

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>