README.org

#+TITLE: Gnuplot for Emacs

#+html: <a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a>
#+html: <a href="https://elpa.nongnu.org/nongnu/gnuplot.html"><img alt="NonGNU ELPA" src="https://elpa.nongnu.org/nongnu/gnuplot.svg"/></a>
#+html: <a href="https://elpa.nongnu.org/nongnu-devel/gnuplot.html"><img alt="NonGNU-devel ELPA" src="https://elpa.nongnu.org/nongnu-devel/gnuplot.svg"/></a>
#+html: <a href="https://releases.melpa.org/#/gnuplot"><img alt="MELPA Releases" src="https://releases.melpa.org/packages/gnuplot-badge.svg"/></a>
#+html: <a href="https://snapshots.melpa.org/#/gnuplot"><img alt="MELPA Snapshots" src="https://snapshots.melpa.org/packages/gnuplot-badge.svg"/></a>

This package allows running [[http://www.gnuplot.info/][Gnuplot]] files from within the [[https://www.gnu.org/software/emacs/][GNU Emacs]] editor. It
features:

- Syntax highlighting and indentation for Gnuplot scripts.
- Pull-down menus for common Gnuplot-related tasks.
- Interactive Gnuplot sessions using =comint=.
- Context-sensitive completion.
- Inline display of Gnuplot plots.

It is recommended to use GNU Emacs 28 or above, and Gnuplot version 5.0 or
above.

* Installation

The easiest way to install =gnuplot= is to directly get it from [[https://elpa.nongnu.org/nongnu/gnuplot.html][ELPA]] or [[https://releases.melpa.org/#/gnuplot][MELPA]]. You
should be able to install =gnuplot= by typing

: M-x install-package RET gnuplot RET

or do =M-x list-packages= and search for =gnuplot= in the list. Note that there is a
different [[https://github.com/mkmcc/gnuplot-mode][gnuplot-mode]] package on MELPA which is less featureful.

* Configuration

In order to customize Gnuplot, use =M-x gnuplot-customize= or set the respective
customizable variables in your user configuration.

It is recommended to configure =read-extended-command-predicate= in your Emacs
configuration, such that =M-x= only completes commands relevant for the current
mode. For example =gnuplot-*= commands are only shown in Gnuplot buffers.
Alternatively press the key =M-X= instead of =M-x= if you want relevant commands
only.

#+begin_src emacs-lisp
(setq read-extended-command-predicate #'command-completion-default-include-p)
#+end_src

* Usage

=gnuplot-mode= is enabled automatically for =*.gp= files. These functions are useful
as entry points:

- =M-x run-gnuplot= - start =gnuplot-comint-mode= REPL.
- =M-x gnuplot-mode= - switch to =gnuplot-mode= in the current buffer
- =M-x gnuplot-make-buffer= - open a new buffer, which is not visiting a file, and
  start =gnuplot-mode= in that buffer.

** Bindings

When =gnuplot-mode= is on, the following keybindings are available:

| =C-c C-l=     | send current line to gnuplot                         |
| =C-c C-v=     | send current line to gnuplot and move forward 1 line |
| =C-c C-r=     | send current region to gnuplot                       |
| =C-c C-b=     | send entire buffer to gnuplot                        |
| =C-c C-f=     | send a file to gnuplot                               |
| =C-c C-i=     | insert filename at point                             |
| =C-c C-n=     | negate set option on current line                    |
| =C-c C-c=     | comment region                                       |
| =C-c C-o=     | set arguments for command at point                   |
| =S-<mouse-2>= | set arguments for command under mouse cursor         |
| =C-c C-d=     | read the gnuplot info manual                         |
| =C-c C-e=     | show gnuplot buffer                                  |
| =C-c C-k=     | kill gnuplot process                                 |
| =C-c C-z=     | customize gnuplot-mode                               |
| =M-TAB=       | complete keyword before point                        |
| =TAB=         | indent current line                                  |

With the exception of the commands for sending commands to Gnuplot, most of the
above commands also work in the Gnuplot comint buffer, in addition to the
following:

| =M-C-p=   | plot the most recent script buffer line-by-line   |
| =M-C-f=   | save the current script buffer and load that file |
| =C-c C-e= | pop back to most recent script buffer             |

** 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 manual.

If the context-sensitivity annoys you, you can get simple non-context-sensitive
completion back by toggling =gnuplot-context-sensitive-mode=.

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 outdated version of gnuplot it will
make mistakes. Most of gnuplot 4.6's command language is parsed correctly except
for the =set terminal= commands.

** Eldoc mode

~gnuplot-mode~ shows syntax hints in the modeline when ~eldoc-mode~ is turned on and
context sensitivity is enabled. Both are enabled by default.

** Inline Images

Plots are 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. It requires Gnuplot and Emacs to have =png= support. Call
=gnuplot-external-display-mode= in a gnuplot-mode buffer to disable the feature.

* Common issues

** Usage on Windows

Multiple users have reported issues when trying to work with =gnuplot.el= on
Windows. Most notably, the Gnuplot process hangs after sending a first line of
input (this is a common Emacs issue on Windows, see [[https://www.gnu.org/software/emacs/manual/html_mono/efaq-w32.html#Sub_002dprocesses][here]]). More information on
=gnuplot.el= and Windows can be found on these threads [[https://github.com/emacs-gnuplot/gnuplot/issues/15][1]] and [[https://github.com/emacs-gnuplot/gnuplot/pull/33][2]]. You currently have
two solutions:

1. Experiment using the =gnuplot-program= and =gnuplot-program-args= variables. For
   instance the following setting has been reported to work (see [[https://github.com/emacs-gnuplot/gnuplot/pull/33/files][here]]).

   #+begin_src emacs-lisp
(setq gnuplot-program "/path/to/cmdproxy.exe"
      gnuplot-program-args "/C /path/to/gnuplot.exe")
   #+end_src

2. Try the simpler [[https://github.com/mkmcc/gnuplot-mode][gnuplot-mode]] package that sends the entire buffer to Gnuplot.
   Since no =comint= is involved, it should function correctly, but you lose most
   features of this package.

** Pause Command

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.

** Issue with Unicode Character Display

Some users have reported [[https://github.com/emacs-gnuplot/gnuplot/issues/39][issues when trying to display unicode characters]]. This
issue is likely due to your distribution bundling Gnuplot with [[https://unix.stackexchange.com/questions/496206/unicode-in-gnuplot-terminal/496245#496245][editline instead
of readline]]. Recompiling the source with support for Unicode fixes the issue
until this issue is fixed upstream.

* Maintenance of generated files

The files ~gnuplot.texi~ and ~gnuplot-eldoc.el~ are generated from the Gnuplot
source, which can be obtained from https://packages.debian.org/unstable/gnuplot.
Run ~make~ inside the ~admin~ directory to download the source and regenerate the
files.