branch: elpa/gnuplot
commit 47861d31d284b862e83cbf4844af5ee1577acb74
Author: Daniel Mendler <m...@daniel-mendler.de>
Commit: Daniel Mendler <m...@daniel-mendler.de>
Update README
---
README.org | 78 ++++++++++++++++++++++++++------------------------------------
1 file changed, 32 insertions(+), 46 deletions(-)
diff --git a/README.org b/README.org
index eca5f93250..38eb02d288 100644
--- a/README.org
+++ b/README.org
@@ -6,17 +6,17 @@
#+html: <a href="https://melpa.org/#/gnuplot";><img alt="MELPA"
src="https://melpa.org/packages/gnuplot-badge.svg"/></a>
#+html: <a href="https://stable.melpa.org/#/gnuplot";><img alt="MELPA Stable"
src="https://stable.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
+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=.
+- 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.
+- Inline display of Gnuplot plots.
-It is recommended to run =gnuplot-mode= on GNU Emacs 25 or above,
-using gnuplot version 5.0 or above.
+It is recommended to use GNU Emacs 25 or above, and Gnuplot version 5.0 or
+above.
* Installation
@@ -26,23 +26,18 @@ The easiest way to install =gnuplot= is to directly get it
from [[https://elpa.n
: M-x install-package RET gnuplot RET
-or do =M-x list-packages= and search for =gnuplot= in the list. Note that
there is
-an alternative =gnuplot-mode= package on MELPA which is less featureful.
-
-* Configuration
-
-=gnuplot-mode= is enabled automatically for =*.gp= files. The function
-=gnuplot-info-lookup-symbol= looks at the Gnuplot info file.
+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.
* Usage
-Apart from enabling =gnuplot-mode= automatically for =*.gp= files, these
functions
-are useful for starting up gnuplot-mode:
+=gnuplot-mode= is enabled automatically for =*.gp= files. These functions are
useful
+as entry points:
-- =M-x run-gnuplot= : start gnuplot repl
-- =M-x gnuplot-mode= : start 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
+- =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
@@ -58,7 +53,7 @@ When =gnuplot-mode= is on, the following keybindings are
available:
| 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 file |
+| 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 |
@@ -75,11 +70,11 @@ following:
** Context-sensitive keyword completion
-By default gnuplot-mode will try to parse your commands as you type and suggest
+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.
+Gnuplot info manual.
If the context-sensitivity annoys you, you can get simple non-context-sensitive
completion back by toggling =gnuplot-context-sensitive-mode=.
@@ -96,46 +91,37 @@ context sensitivity is enabled. Both are enabled by default.
** Inline Images
-You can have plots displayed inline in the Gnuplot comint process buffer. This
+You can 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. It requires Gnuplot to have =png= support and a GNU Emacs with
-image support. Call =gnuplot-external-display-mode= in a gnuplot-mode buffer to
-disable the feature.
+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]]).
-
-A partial workaround was to use =pgnuplot.exe= as the =gnuplot-program=.
However,
-=pgnuplot.exe= is not included with gnuplot since version 5.0.
-
-You currently have two solutions:
+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, setting
+ 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")
(setq gnuplot-program-args "/C /path/to/gnuplot.exe")
#+end_src
- has been reported to work (see
[[https://github.com/emacs-gnuplot/gnuplot/pull/33/files][here]] for a
reference).
-
-2. Use the simpler [[https://github.com/mkmcc/gnuplot-mode][gnuplot-mode]]
package that sends the entire buffer to gnuplot.
+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 the =gnuplot.el= package. We would like to implement a
send-buffer
- without comint as well eventually.
-
-More information on =gnuplot.el= and Windows can be found on these threads:
[[https://github.com/emacs-gnuplot/gnuplot/issues/15][1]],
[[https://github.com/emacs-gnuplot/gnuplot/pull/33][2]]
+ 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
+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.
@@ -143,8 +129,8 @@ 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 should fix the
+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 should fix the
issue until this issue is fixed upstream. Thanks to
[[https://github.com/rolandog][rolandog]] for discovering
this fix.
@@ -155,4 +141,4 @@ Regenerate ~gnuplot.texi~ and ~gnuplot-eldoc.el~ from the
Gnuplot source.
1. Run ~emacs -batch -l doc2texi.el -f d2t-doc-to-texi~ inside the
~gnuplot-*/docs/~
source directory.
2. Run ~makeinfo --no-split gnuplot.texi~ and ensure that it compiles cleanly.
-3. Copy ~gnuplot-eldoc.el~ and ~gnuplot.texi~ to the package source.
+3. Copy ~gnuplot-eldoc.el~ and ~gnuplot.texi~ to the package source directory.
![https://melpa.org/packages/gnuplot-badge.svg"/](https://melpa.org/packages/gnuplot-badge.svg"/){kind=link}
![https://stable.melpa.org/packages/gnuplot-badge.svg"/](https://stable.melpa.org/packages/gnuplot-badge.svg"/){kind=link}