
* gnuplot-mode, version 0.7

  This directory contains files for running Gnuplot from within emacs.
  This package was assembled by Bruce Ravel <bruceravel1@gmail.com>.
  See the homepage at [[http://xafs.org/BruceRavel/GnuplotMode]]

** Contents

   | File               | Description                                          |
   |--------------------+------------------------------------------------------|
   | README.org         | this file                                            |
   | INSTALL.org        | thorough installation instructions                   |
   | gnuplot.el         | gnuplot mode for emacs                               |
   | gnuplot-gui.el     | a GUI for setting command arguments interactively    |
   | gnuplot-context.el | context-sensitive completion and help lookup         |
   | gnuplot.info       | info version of gnuplot 4.6 help                     |
   | gpelcard.tex       | quick reference card for gnuplot mode (latex)        |

** Installation
*** Installing from MELPA
    In recent versions of Emacs, gnuplot-mode can be installed directly
    from the [[http://melpa.milkbox.net][MELPA]] package repository as the ~gnuplot~ package (note:
    not ~gnuplot-mode~, which is an alternative gnuplot package).

    After [[http://melpa.milkbox.net/#installing][configuring Emacs to use MELPA]], you should be able to
    install gnuplot-mode by typing
    : M-x install-package RET gnuplot RET

    Or do ~M-x list-packages~ and search for "gnuplot" in the list.

*** Installing using el-get
    [[https://github.com/dimitri/el-get.git][El-get]] includes a gnuplot-mode recipe. So to install simply call,

    : M-x el-get-install RET gnuplot-mode

    Alternatively, you can place the following in your init file so that
    ~el-get~ can install and load gnuplot-mode at Emacs start up.

    : (el-get 'sync 'gnuplot-mode)

*** Installing from cloned repository or .tar.gz
    See the file INSTALL.org for details.

** New features for gnuplot-mode 0.7
   Version 0.7 of gnuplot-mode is designed for use with gnuplot
   version 4.4 and up. It will also mostly work fine with older
   versions. If it doesn't work with newer versions, report a bug.

   This version has mostly been tested under GNU Emacs 23 and 24.
   It should also work on GNU Emacs 22 and XEmacs 21. It may work
   with earlier versions, but it has not been tested.

*** New syntax for gnuplot version 4
    This version of gnuplot-mode supports the new curly-brace-block
    ~do~ and ~if~ statements introduced in recent versions of gnuplot.
    The indentation code to handle these is pretty simple, but should
    work. Please report any bugs. The number of columns to offset
    inner blocks is controlled by the ~gnuplot-basic-offset~ variable.

*** Context-sensitive keyword completion
    By default gnuplot-mode will try to parse your commands as you
    type and suggest only relevant completion candidates on typing
    M-TAB or TAB. For example, with point after the ~with~ of a ~plot~
    command, tab completion will suggest only plotting styles. This
    also enables more specific help topic lookup in the gnuplot info
    file, provided you have the right version of ~gnuplot.info~
    installed.

    If the context-sensitivity annoys you, you can get simple
    non-context-sensitive completion back by toggling
    ~gnuplot-context-sensitive-mode~. See also the variable
    ~gnuplot-tab-completion~.

    By its nature, the completion code has to know a fair bit about
    the structure of the gnuplot language. If you use it with an old
    version of gnuplot (pre version 4) it will make mistakes. Most of
    gnuplot 4.6's command language is parsed correctly except for the
    =set terminal= commands.

*** Eldoc mode
    If you install the file ~gnuplot-eldoc.el~ from a recent Gnuplot
    distribution, gnuplot-mode can show syntax hints in the modeline
    when ~eldoc-mode~ is turned on and context sensitivity is enabled.

*** Inline images
    You can optionally have plots displayed inline in the Gnuplot
    comint process buffer. This is handy for trying things out without
    having to switch between Emacs and the Gnuplot display. Call
    ~gnuplot-inline-imge-mode~ or type ~C-c M-i~ in a gnuplot-mode
    buffer to try it out. This feature is implemented using temporary
    ~.png~ files, and is also somewhat experimental. It requires
    Gnuplot to have ~png~ support and a GNU Emacs with image support.
    Please report bugs.

** NOTES
   1. The gnuplot-mode distribution comes with the version of the gnuplot
      info file that gets made by gnuplot 4.6.  Use it rather than the
      old one.  If you really must use the older info file, see the
      document string for the variable `gnuplot-info-hook'.  If you
      already have the info file installed on your computer, you will not
      need the one that comes with gnuplot-mode.

   2. The interactive graphical graphical interface to setting command
      arguments contained in gnuplot-gui.el is experimental. It is
      incomplete and may make mistakes. Hopefully, you will find it
      useful. It *requires* that you are using a version of emacs with
      the widget library installed or that you have installed it
      yourself. Version numbers in the 20's of Emacs and XEmacs ship
      with the widget library.

   3. Gnuplot's ~pause -1~ command, which waits for the user to press a
      key, is problematic when running under Emacs.  Sending =pause -1=
      to the running gnuplot process will make Emacs appear to freeze.
      (It isn't really crashed: typing =C-g= will unlock it and let you
      continue).  The workaround for now is to make Gnuplot output a
      string before pausing, by doing
      : pause -1 "Hit return"
      or similar.  Thanks to Jim Mehl for reporting this issue.

** The todo list
   1. Use [[http://tromey.com/elpa/][ELPA]]

      Gnuplot-mode is already on http://melpa.milkbox.net, but it would
      be good to get it into the other repositories too.

   2. Using gnuplot-mode on windows is problematic.  John Handy says:

      You probably get nagged quite a bit about this. Some have been running into
      issues with gnuplot-mode and Windows and I'm wondering if you have any
      comments. I use it just fine on Linux, but it seems that Windows users are
      not able to send data to gnuplot successfully.

      Org-mode also uses gnuplot-mode and this org-plot and org-mode babel+gnuplot
      are not working correctly on Windows.

      Any thoughts? I'm hoping to include any results in the Org-mode wiki for
      gnuplot use:
      [[http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-gnuplot.php]]

      If you're interested, here are some of the threads I'm referring to:
      [[http://newsgroups.derkeiler.com/Archive/Comp/comp.emacs/2007-07/msg00159.html]]
      [[http://www.mail-archive.com/emacs-orgmode@gnu.org/msg14544.html  ]]
      [[http://groups.google.com/group/gnu.emacs.help/browse_thread/thread/53489131c79f62b3]]

      If you'd like to see my summary of the issues to the org-mode mailing list,
      it's here: [[http://thread.gmane.org/gmane.emacs.orgmode/30235]]
