[elpa] externals/code-cells ea7799c447 35/36: Release on ELPA

[ELPA Syncer]

branch: externals/code-cells
commit ea7799c447066fee78c4efbafbdaf09520c7109d
Author: Augusto Stoffel <arstoffel@gmail.com>
Commit: Augusto Stoffel <arstoffel@gmail.com>

    Release on ELPA
---
 README.md     | 194 ----------------------------------------------------------
 README.org    | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 code-cells.el |  20 +++---
 3 files changed, 184 insertions(+), 204 deletions(-)

diff --git a/README.md b/README.md
deleted file mode 100644
index a491979140..0000000000
--- a/README.md
+++ /dev/null
@@ -1,194 +0,0 @@
-code-cells.el – Lightweight notebooks in Emacs
-==============================================
-
-[![MELPA](https://melpa.org/packages/code-cells-badge.svg)](https://melpa.org/#/code-cells)
-
-This package lets you efficiently navigate, edit and execute code
-split into cells according to certain magic comments.  If you have
-[Jupytext] or [Pandoc] installed, you can also open ipynb notebook
-files directly in Emacs.  They will be automatically converted to a
-script for editing, and converted back to notebook format when saving.
-
-![Screenshot](https://user-images.githubusercontent.com/6500902/148531077-052c7811-9083-41ce-b575-d43003e63363.png)
-
-By default, three styles of comments are recognized as cell boundaries:
-
-```
-# In[<number>]:
-
-# %% Optional title
-
-# * Optional title
-```
-
-The first is what you get by exporting a notebook to a script on
-Jupyter's web interface or with the command `jupyter nbconvert`.  The
-second style is compatible with Jupytext, among several other tools.
-The third is in the spirit of Emacs's outline mode.  Further percent
-signs or asterisks signify nested cells.
-
-Minor mode
-----------
-
-The `code-cells-mode` minor mode provides the following things:
-
-- Fontification of cell boundaries.
-- Keybindings for the cell navigation and evaluation commands, under
-  the `C-c %` prefix.
-- Outline mode integration: cell headers have outline level determined
-  by the number of percent signs or asterisks; within a cell, outline
-  headings are as determined by the major mode, but they are demoted
-  by an amount corresponding to the level of the containing cell.
-  This provides code folding and hierarchical navigation, among other
-  things, when `outline-minor-mode` is active.
-
-`code-cells-mode` is automatically activated when opening an ipynb
-file, but of course you can activate it in any other buffer, either
-manually or through some hook.  There is also the
-`code-cells-mode-maybe` function, which activates the minor mode if
-the current buffer seems to contain cell boundaries.  It can be used
-like this, for instance:
-
-``` elisp
-(add-hook 'python-mode-hook 'code-cells-mode-maybe)
-```
-
-Editing commands
-----------------
-
-The following editing and navigation commands are provided.  Their
-keybindings in `code-cells-mode-map` are also shown.  Note, however,
-that these commands do not require the minor mode to be active.
-
-- <kbd>C-c % e</kbd>: `code-cells-eval`
-- <kbd>C-c % b</kbd>: `code-cells-backward-cell`
-- <kbd>C-c % f</kbd>: `code-cells-forward-cell`
-- <kbd>C-c % ;</kbd>: `code-cells-comment-or-uncomment`
-- <kbd>C-c % @</kbd>: `code-cells-mark-cell`
-
-The `code-cells-eval` command sends the current cell to a suitable
-REPL, chosen according to the current major and minor modes.  The
-exact behavior is controlled by the `code-cells-eval-region-commands`
-variable, which can be customized to suit your needs.
-
-You may prefer shorter keybindings for some of these commands.  One
-sensible possibility is to use `C-c C-c` to evaluate and `M-p`/`M-n`
-to navigate cells.  This can be achieved with the following
-configuration:
-
-``` elisp
-(with-eval-after-load 'code-cells
-  (let ((map code-cells-mode-map))
-    (define-key map (kbd "M-p") 'code-cells-backward-cell)
-    (define-key map (kbd "M-n") 'code-cells-forward-cell)
-    (define-key map (kbd "C-c C-c") 'code-cells-eval)
-    ;; Overriding other minor mode bindings requires some insistence...
-    (define-key map [remap jupyter-eval-line-or-region] 'code-cells-eval)))
-```
-
-Speed keys
-----------
-
-Similarly to org-mode's [speed keys], the `code-cells-speed-key`
-function returns a key definition that only acts when the point is at
-the beginning of a cell boundary.  Since this is usually not an
-interesting place to insert text, you can assign short keybindings
-there.
-
-No speed keys are set up by default.  A sample configuration is as
-follows:
-
-``` elisp
-(with-eval-after-load 'code-cells
-  (let ((map code-cells-mode-map))
-    (define-key map "n" (code-cells-speed-key 'code-cells-forward-cell))
-    (define-key map "p" (code-cells-speed-key 'code-cells-backward-cell))
-    (define-key map "e" (code-cells-speed-key 'code-cells-eval))
-    (define-key map (kbd "TAB") (code-cells-speed-key 'outline-cycle))))
-```
-
-Handling Jupyter notebook files
--------------------------------
-
-With this package, you can edit Jupyter notebook (`*.ipynb`) files as
-if they were normal plain-text scripts.  Converting to and from the
-JSON-based ipynb format is done by an external tool, [Jupytext] by
-default, which needs to be installed separately.
-
-Note that the result cells of ipynb files are not retained in the
-conversion to script format.  This means that opening and then saving
-an ipynb file clears all cell outputs.
-
-While editing a converted ipynb buffer, you can use the regular
-`write-file` command (`C-x C-w`) to save a copy in script format, as
-displayed on the screen.  Moreover, from any script file with cell
-separators understood by Jupytext, you can call
-`code-cells-write-ipynb` to save a copy in notebook format.
-
-### Tweaking the ipynb conversion
-
-If relegating markdown cells to comment blocks offends your literate
-programmer sensibilities, try including the following in the YAML
-header of a converted notebook (and then save and revert it).  It will
-cause text cells to be displayed as multiline comments.
-
-``` yaml
-jupyter:
-  jupytext:
-    cell_markers: '"""'
-```
-
-It is also possible to convert notebooks to markdown or org format.
-For markdown, use the following:
-
-``` elisp
-(setq code-cells-convert-ipynb-style '(("jupytext" "--to" "ipynb" "--from" 
"markdown")
-                                       ("jupytext" "--to" "markdown" "--from" 
"ipynb")
-                                       markdown-mode))
-```
-
-To edit ipynb files as org documents, try using [Pandoc] with the
-configuration below.  In combination with org-babel, this can provide
-a more notebook-like experience, with interspersed code and results.
-
-```elisp
-(setq code-cells-convert-ipynb-style '(("pandoc" "--to" "ipynb" "--from" "org")
-                                       ("pandoc" "--to" "org" "--from" "ipynb")
-                                       org-mode))
-```
-
-A good reason to stick with Jupytext, though, is that it offers
-round-trip consistency: if you save a script and then revert the
-buffer, the buffer shouldn't change.  With other tools, you may get
-some surprises.
-
-Alternatives
-------------
-
-[python-cell.el] provides similar cell editing commands.  It seems to
-be limited to Python code.
-
-With Jupytext's [paired notebook 
mode](https://jupytext.readthedocs.io/en/latest/paired-notebooks.html)
-it is possible to keep a notebook open in JupyterLab and simultaneously
-edit a script version in an external text editor.
-
-The [EIN] package allows to open ipynb files directly in Emacs with an
-UI similar to Jupyter notebooks.  Note that EIN also registers major
-modes for ipynb files; when installing both packages at the same time,
-you may need to adjust your `auto-mode-alist` manually.
-
-
-Contributing
-------------
-
-Discussions, suggestions and code contributions are welcome!  I'm
-considering submitting this package to GNU ELPA in the future,
-therefore I would request a FSF copyright assignment for nontrivial
-contributions (above 15 lines of code).
-
-[ein]: https://github.com/dickmao/emacs-ipython-notebook
-[emacs-jupyter]: https://github.com/dzop/emacs-jupyter
-[jupytext]: https://github.com/mwouts/jupytext
-[pandoc]: https://pandoc.org/
-[python-cell.el]: https://github.com/thisch/python-cell.el
-[speed keys]: https://orgmode.org/manual/Speed-Keys.html
diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..33b75dc932
--- /dev/null
+++ b/README.org
@@ -0,0 +1,174 @@
+#+title: code-cells.el --- Lightweight notebooks in Emacs
+
+#+html: <a href="http://elpa.gnu.org/packages/code-cells.html";><img alt="GNU 
ELPA" src="https://elpa.gnu.org/packages/code-cells.svg"/></a>
+#+html: <a href="https://melpa.org/#/code-cells";><img alt="MELPA" 
src="https://melpa.org/packages/code-cells-badge.svg"/></a>
+
+This package lets you efficiently navigate, edit and execute code
+split into cells according to certain magic comments.  If you have
+[[https://github.com/mwouts/jupytext][Jupytext]] or 
[[https://pandoc.org/][Pandoc]] installed, you can also open ipynb notebook 
files
+directly in Emacs.  They will be automatically converted to a script
+for editing, and converted back to notebook format when saving.
+
+#+caption: Working on a Jupyter notebook as a plain Python script
+https://raw.githubusercontent.com/astoff/code-cells.el/images/screenshot.png
+
+By default, three styles of comments are recognized as cell
+boundaries:
+
+#+begin_example
+  # In[<number>]:
+
+  # %% Optional title
+
+  # * Optional title
+#+end_example
+
+The first is what you get by exporting a notebook to a script on
+Jupyter's web interface or with the command =jupyter nbconvert=.  The
+second style is compatible with Jupytext, among several other tools.
+The third is in the spirit of Emacs's outline mode.  Further percent
+signs or asterisks signify nested cells.
+
+** Minor mode
+The =code-cells-mode= minor mode provides the following things:
+
+- Fontification of cell boundaries.
+- Keybindings for the cell navigation and evaluation commands, under the
+  =C-c %= prefix.
+- Outline mode integration: cell headers have outline level determined
+  by the number of percent signs or asterisks; within a cell, outline
+  headings are as determined by the major mode, but they are demoted
+  by an amount corresponding to the level of the containing cell.
+  This provides code folding and hierarchical navigation, among other
+  things, when =outline-minor-mode= is active.
+
+=code-cells-mode= is automatically activated when opening an ipynb
+file, but of course you can activate it in any other buffer, either
+manually or through some hook.  There is also the
+=code-cells-mode-maybe= function, which activates the minor mode if
+the current buffer seems to contain cell boundaries.  It can be used
+like this, for instance:
+
+#+begin_src emacs-lisp
+  (add-hook 'python-mode-hook 'code-cells-mode-maybe)
+#+end_src
+
+** Editing commands
+The following editing and navigation commands are provided.  Their
+keybindings in =code-cells-mode-map= are also shown.  Note, however,
+that these commands do not require the minor mode to be active.
+
+- =C-c % e=: =code-cells-eval=
+- =C-c % b=: =code-cells-backward-cell=
+- =C-c % f=: =code-cells-forward-cell=
+- =C-c % ;=: =code-cells-comment-or-uncomment=
+- =C-c % @=: =code-cells-mark-cell=
+
+The =code-cells-eval= command sends the current cell to a suitable
+REPL, chosen according to the current major and minor modes.  The
+exact behavior is controlled by the =code-cells-eval-region-commands=
+variable, which can be customized to suit your needs.
+
+You may prefer shorter keybindings for some of these commands.  One
+sensible possibility is to use =C-c C-c= to evaluate and =M-p=
+resp. =M-n= to navigate cells.  This can be achieved with the
+following configuration:
+
+#+begin_src emacs-lisp
+  (with-eval-after-load 'code-cells
+    (let ((map code-cells-mode-map))
+      (define-key map (kbd "M-p") 'code-cells-backward-cell)
+      (define-key map (kbd "M-n") 'code-cells-forward-cell)
+      (define-key map (kbd "C-c C-c") 'code-cells-eval)
+      ;; Overriding other minor mode bindings requires some insistence...
+      (define-key map [remap jupyter-eval-line-or-region] 'code-cells-eval)))
+#+end_src
+
+** Speed keys
+Similarly to org-mode's [[https://orgmode.org/manual/Speed-Keys.html][speed 
keys]], the =code-cells-speed-key=
+function returns a key definition that only acts when the point is at
+the beginning of a cell boundary.  Since this is usually not an
+interesting place to insert text, you can assign short keybindings
+there.
+
+No speed keys are set up by default.  A sample configuration is as
+follows:
+
+#+begin_src emacs-lisp
+  (with-eval-after-load 'code-cells
+    (let ((map code-cells-mode-map))
+      (define-key map "n" (code-cells-speed-key 'code-cells-forward-cell))
+      (define-key map "p" (code-cells-speed-key 'code-cells-backward-cell))
+      (define-key map "e" (code-cells-speed-key 'code-cells-eval))
+      (define-key map (kbd "TAB") (code-cells-speed-key 'outline-cycle))))
+#+end_src
+
+** Handling Jupyter notebook files
+With this package, you can edit Jupyter notebook (=*.ipynb=) files as
+if they were normal plain-text scripts.  Converting to and from the
+JSON-based ipynb format is done by an external tool, 
[[https://github.com/mwouts/jupytext][Jupytext]] by
+default, which needs to be installed separately.
+
+Note that the result cells of ipynb files are not retained in the
+conversion to script format.  This means that opening and then saving
+an ipynb file clears all cell outputs.
+
+While editing a converted ipynb buffer, you can use the regular
+=write-file= command (=C-x C-w=) to save a copy in script format, as
+displayed on the screen.  Moreover, from any script file with cell
+separators understood by Jupytext, you can call
+=code-cells-write-ipynb= to save a copy in notebook format.
+
+*** Tweaking the ipynb conversion
+If relegating markdown cells to comment blocks offends your literate
+programmer sensibilities, try including the following in the YAML
+header of a converted notebook (and then save and revert it).  It will
+cause text cells to be displayed as multiline comments.
+
+#+begin_example
+  jupyter:
+    jupytext:
+      cell_markers: '"""'
+#+end_example
+
+It is also possible to convert notebooks to markdown or org format.
+For markdown, use the following:
+
+#+begin_src emacs-lisp
+  (setq code-cells-convert-ipynb-style '(("jupytext" "--to" "ipynb" "--from" 
"markdown")
+                                         ("jupytext" "--to" "markdown" 
"--from" "ipynb")
+                                         markdown-mode))
+#+end_src
+
+To edit ipynb files as org documents, try using 
[[https://pandoc.org/][Pandoc]] with the
+configuration below.  In combination with org-babel, this can provide
+a more notebook-like experience, with interspersed code and results.
+
+#+begin_src emacs-lisp
+  (setq code-cells-convert-ipynb-style '(("pandoc" "--to" "ipynb" "--from" 
"org")
+                                         ("pandoc" "--to" "org" "--from" 
"ipynb")
+                                         org-mode))
+#+end_src
+
+A good reason to stick with Jupytext, though, is that it offers
+round-trip consistency: if you save a script and then revert the
+buffer, the buffer shouldn't change.  With other tools, you may get
+some surprises.
+
+** Alternatives
+[[https://github.com/thisch/python-cell.el][python-cell.el]] provides similar 
cell editing commands.  It seems to be
+limited to Python code.
+
+With Jupytext's 
[[https://jupytext.readthedocs.io/en/latest/paired-notebooks.html][paired 
notebook mode]] it is possible to keep a notebook
+open in JupyterLab and simultaneously edit a script version in an
+external text editor.
+
+The [[https://github.com/dickmao/emacs-ipython-notebook][EIN]] package allows 
to open ipynb files directly in Emacs with an
+UI similar to Jupyter notebooks.  Note that EIN also registers major
+modes for ipynb files; when installing both packages at the same time,
+you may need to adjust your =auto-mode-alist= manually.
+
+** Contributing
+Discussions, suggestions and code contributions are welcome! Since
+this package is part of GNU ELPA, nontrivial contributions (above 15
+lines of code) require a copyright assignment to the FSF.
diff --git a/code-cells.el b/code-cells.el
index d65cdf5080..f2feb1a09f 100644
--- a/code-cells.el
+++ b/code-cells.el
@@ -1,12 +1,12 @@
-;;; code-cells.el --- Work with code split into cells, including Jupyter 
notebooks -*- lexical-binding: t; -*-
+;;; code-cells.el --- Lightweight notebooks with support for ipynb files -*- 
lexical-binding: t; -*-
 
-;; Copyright (C) 2021 Augusto Stoffel
+;; Copyright (C) 2022  Free Software Foundation, Inc.
 
 ;; Author: Augusto Stoffel <arstoffel@gmail.com>
 ;; Keywords: convenience, outlines
 ;; URL: https://github.com/astoff/code-cells.el
 ;; Package-Requires: ((emacs "27.1"))
-;; Version: 0.1
+;; Version: 0.2
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
@@ -25,12 +25,12 @@
 
 ;; With this package, you can efficiently navigate, edit and execute
 ;; code split into cells according to certain magic comments.  It also
-;; allows to open ipynb notebook files directly in Emacs.  They will
-;; be automatically converted to a script for editing, and converted
-;; back to notebook format when saving.  An external tool, Jupytext by
-;; default, is required for this.
+;; allows you to open ipynb notebook files directly in Emacs.  They
+;; will be automatically converted to a script for editing, and
+;; converted back to notebook format when saving.  An external tool,
+;; Jupytext by default, is required for this.
 ;;
-;; A minor mode, `code-cells-mode`, provides the following features:
+;; A minor mode, `code-cells-mode', provides the following features:
 ;;
 ;; - Fontification of cell boundaries.
 ;;
@@ -42,12 +42,12 @@
 ;;   cell, outline headings are as determined by the major mode, but
 ;;   they are demoted by an amount corresponding to the level of the
 ;;   containing cell.  This provides code folding and hierarchical
-;;   navigation, among other things, when `outline-minor-mode` is
+;;   navigation, among other things, when `outline-minor-mode' is
 ;;   active.
 ;;
 ;; This minor mode is automatically activated when opening an ipynb
 ;; file, but you can also activate it in any other buffer, either
-;; manually or through some hook.
+;; manually or through a hook.
 
 ;;; Code: