branch: externals/comint-mime
commit d9cdad5e8851c1f6d85babca6233e7d39ea5cd04
Author: Augusto Stoffel <arstof...@gmail.com>
Commit: Augusto Stoffel <arstof...@gmail.com>
Convert README to org format
---
README.md | 93 --------------------------------------------------------------
README.org | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 90 insertions(+), 93 deletions(-)
diff --git a/README.md b/README.md
deleted file mode 100644
index 650c2a7..0000000
--- a/README.md
+++ /dev/null
@@ -1,93 +0,0 @@
-comint-mime.el
-==============
-
-This Emacs package provides a mechanism for REPLs (or comint buffers,
-in Emacs parlance) to display graphics and other types of special
-content.
-
-![comint-mime in Python][python]
-
-The main motivation behind this package is to display plots in the
-Python shell. However, it does more that that.
-
-First, it is not constrained to graphics, and can display other “MIME
-attachments” such as HTML and LaTeX content. In fact, the Python
-backend of the package implements IPython's [rich display
-interface][ipython_repr]. A use-case beyond the displaying of
-graphics would be to render dataframes as HTML tables; this opens up
-the possibility of typographical improvements over the usual pure-text
-representation. You can also easily define rich representations for
-your own classes.
-
-Second, the package defines a flexible communication protocol between
-Emacs and the inferior process, and, consequently, can be extended to
-other comint types. Currently, besides Python, there is support for
-the regular (Unix) shell. In this case, a special command, `mimecat`,
-is provided to display content. Again, this works for images, HTML,
-LaTeX snippets, etc.
-
-![comint-mime in Bash][bash]
-
-Usage
------
-
-To start enjoying comint-mime, simply call `M-x comint-mime-setup`
-from a supported buffer (which, at the moment, are the `M-x shell` and
-`M-x run-python` buffers). To apply this permanently, add that same
-function to the appropriate mode hook:
-
-``` elisp
-(add-hook 'shell-mode-hook 'comint-mime-setup)
-(add-hook 'inferior-python-mode-hook 'comint-mime-setup)
-```
-
-Note that for Python it is important to use the IPython interpreter.
-It can be configured to have the same look-and-feel as the classic
-`python` program as follows.
-
-``` elisp
-(when (executable-find "ipython3")
- (setq python-shell-interpreter "ipython3"
- python-shell-interpreter-args "--simple-prompt --classic"))
-```
-
-Extending
----------
-
-To add support for new MIME types, see `comint-mime-renderer-alist`.
-
-To add support for new comints, an entry should be added to
-`comint-mime-setup-function-alist`. This function should arrange for
-the inferior process to emit an escape sequence whenever some MIME
-content is to be displayed.
-
-The escape sequence has the following shape:
-
-```
-ESC ] 5 1 5 1 ; header LF payload ESC \
-```
-
-Here, `header` is a JSON object containing, at least, the entry
-`type`, which should be the name of a MIME type. Other header entries
-can be passed; the interpretation is up to the rendering function.
-
-The `payload` can be either the content of the attachment, encoded in
-base64 (which is decoded before being passed to the selected
-renderer), or a `file://` URL (whose content is read and passed to the
-renderer), or yet a `tmpfile://` URL, which indicates that the file
-should be deleted after it is read.
-
-Note that it can take considerable time to insert large amounts of
-data in a comint buffer, specially if it contains long lines.
-Consider using a temporary file for large data transfers.
-
-Todos
------
-
-- [ ] It should be possible to support at least Matplotlib in the
- classic `python` interpreter.
-- [ ] Improve the HTML rendering for numeric tables
-
-[python]:
https://user-images.githubusercontent.com/6500902/133823411-ca75122d-4a39-4e3c-ac55-b2a1f974ff5e.png
-[bash]:
https://user-images.githubusercontent.com/6500902/133823494-696ee5a7-f0b0-47a3-9ccb-29ab9f36c3a9.png
-[ipython_repr]:
https://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..0eaf525
--- /dev/null
+++ b/README.org
@@ -0,0 +1,90 @@
+#+title: comint-mime.el
+#+author: Augusto Stoffel
+
+#+html: <a href="http://elpa.gnu.org/devel/comint-mime.html";><img
alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/comint-mime.svg"/></a>
+
+This Emacs package provides a mechanism for REPLs (or comint buffers,
+in Emacs parlance) to display graphics and other types of special
+content.
+
+#+caption: comint-mime in Python
+[[https://user-images.githubusercontent.com/6500902/133823411-ca75122d-4a39-4e3c-ac55-b2a1f974ff5e.png]]
+
+The main motivation behind this package is to display plots in the
+Python shell. However, it does more that that.
+
+First, it is not constrained to graphics, and can display other "MIME
+attachments" such as HTML and LaTeX content. In fact, the Python
+backend of the package implements IPython's
[[https://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display][rich
display interface]]. A
+use-case beyond the displaying of graphics would be to render
+dataframes as HTML tables; this opens up the possibility of
+typographical improvements over the usual pure-text
+representation. You can also easily define rich representations for
+your own classes.
+
+Second, the package defines a flexible communication protocol between
+Emacs and the inferior process, and, consequently, can be extended to
+other comint types. Currently, besides Python, there is support for
+the regular (Unix) shell. In this case, a special command, =mimecat=,
+is provided to display content. Again, this works for images, HTML,
+LaTeX snippets, etc.
+
+#+caption: comint-mime in Bash
+[[https://user-images.githubusercontent.com/6500902/133823494-696ee5a7-f0b0-47a3-9ccb-29ab9f36c3a9.png]]
+
+** Usage
+
+To start enjoying comint-mime, simply call =M-x comint-mime-setup=
+from a supported buffer (which, at the moment, are the =M-x shell= and
+=M-x run-python= buffers). To apply this permanently, add that same
+function to the appropriate mode hook:
+
+#+begin_src elisp
+ (add-hook 'shell-mode-hook 'comint-mime-setup)
+ (add-hook 'inferior-python-mode-hook 'comint-mime-setup)
+#+end_src
+
+Note that for Python it is important to use the IPython
+interpreter. It can be configured to have the same look-and-feel as
+the classic =python= program as follows.
+
+#+begin_src elisp
+ (when (executable-find "ipython3")
+ (setq python-shell-interpreter "ipython3"
+ python-shell-interpreter-args "--simple-prompt --classic"))
+#+end_src
+
+** Extending
+
+To add support for new MIME types, see =comint-mime-renderer-alist=.
+
+To add support for new comints, an entry should be added to
+=comint-mime-setup-function-alist=. This function should arrange for
+the inferior process to emit an escape sequence whenever some MIME
+content is to be displayed.
+
+The escape sequence has the following shape:
+
+#+begin_example
+ ESC ] 5 1 5 1 ; header LF payload ESC \
+#+end_example
+
+Here, =header= is a JSON object containing, at least, the entry
+=type=, which should be the name of a MIME type. Other header entries
+can be passed; the interpretation is up to the rendering function.
+
+The =payload= can be either the content of the attachment, encoded in
+base64 (which is decoded before being passed to the selected
+renderer), or a =file://= URL (whose content is read and passed to the
+renderer), or yet a =tmpfile://= URL, which indicates that the file
+should be deleted after it is read.
+
+Note that it can take considerable time to insert large amounts of
+data in a comint buffer, specially if it contains long lines. Consider
+using a temporary file for large data transfers.
+
+** Todos
+
+- [ ] It should be possible to support at least Matplotlib in the
+ standard Python interpreter.
+- [ ] Improve the HTML rendering for numeric tables
![https://elpa.gnu.org/devel/comint-mime.svg"/](https://elpa.gnu.org/devel/comint-mime.svg"/){kind=link}