[elpa] externals/eev 340be0a 8/9: Rewrote `find-rcirc-intro' and all comments in eev-rcirc.el.

[Stefan Monnier]

branch: externals/eev
commit 340be0a621841b4e7e46778c7f8e52772013ad39
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>

    Rewrote `find-rcirc-intro' and all comments in eev-rcirc.el.
---
 ChangeLog    |   6 +-
 VERSION      |   4 +-
 eev-intro.el | 193 ++++++++++++++++++++++++++++++++++-------------------------
 eev-rcirc.el |   4 +-
 4 files changed, 117 insertions(+), 90 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 3066b1e..f549a0e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,9 +1,11 @@
 2019-04-14  Eduardo Ochs  <address@hidden>
 
-       * eev-rcirc.el: rewrote all comments and some docstrings.
+       * eev-intro.el (find-rcirc-intro): rewrote completely.
 
-       * eev-rcirc.el (ee-irc-channel-around-point): commented out.
+       * eev-rcirc.el: rewrote all comments and some docstrings.
+       (ee-irc-channel-around-point): commented out.
        (ee-buffer-freenode-channel-name): commented out.
+       (find-freenode-links): small changes.
 
 2019-04-13  Eduardo Ochs  <address@hidden>
 
diff --git a/VERSION b/VERSION
index 212629a..63f9b9a 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Sun Apr 14 07:15:50 GMT 2019
-Sun Apr 14 04:15:50 -03 2019
+Sun Apr 14 17:08:11 GMT 2019
+Sun Apr 14 14:08:11 -03 2019
diff --git a/eev-intro.el b/eev-intro.el
index f3e183a..007601b 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019apr13
+;; Version:    2019apr14
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -6388,17 +6388,22 @@ Is is meant as both a tutorial and a sandbox.
 
 Recent versions with Emacs come with two IRC clients built-in:
 Rcirc and ERC. I never understood ERC well enough, and I found
-Rcirc quite easy to understand and to hack, so eev has some
-support for Rcirc (and no support for ERC).
+rcirc quite easy to understand and to hack, so eev has some
+support for rcirc (and no support for ERC).
 
   (find-node \"(rcirc)Top\")
   (find-node \"(erc)Top\")
 
+The eev support for rcirc consists mainly of three high-level
+functions that connect to Freenode (the IRC server where most
+discussion of free software projects happen), called
+`find-freenode', `find-freenode-2a' and `find-freenode-3a'.
 
 
 
-1. The server buffer and the channel buffers
-============================================
+
+1. The example the I use in workshops
+=====================================
 Let's start with an example. In
 
   (setq rcirc-default-nick \"hakuryo\")
@@ -6406,114 +6411,136 @@ Let's start with an example. In
   (find-freenode-3a \"#eev\")
 
 the first sexp tells rcirc to use the nickname \"hakuryo\" when
-connecting to an irc server; the second 
+connecting to an IRC server; the second sets the set of \"initial
+channels\" on Freenode to just one channel, #eev - a channel that
+is usually empty, but that doesn't require authentication; the
+third sexp is a \"sexp hyperlink to the Freenode channel #eev\".
+The third sexp:
+
+  1) creates a window setting like this,
+
+       _________________________
+      |           |             |
+      |           |   Freenode  |
+      |           |    server   |
+      |           |   messages  |
+      |  current  |_____________|    
+      |  buffer   |             |
+      |           |    #eev     |
+      |           |   channel   |
+      |           |             |
+      |___________|_____________|
+
+  2) tells rcirc to connect to Freenode and to the channel #eev
+     in it,
+
+  3) makes the window at the left - window \"A\" in the
+     terminology of eev-multiwindow.el - the active window. See:
+
+       (find-multiwindow-intro \"3. High-level words\")
+       (find-multiwindow-intro \"3. High-level words\" \"find-3a\")
+
+The connection process takes time - about 20 seconds at my
+machine - but you will be able to see in window \"B\" the server
+messages as they appear, and in window \"C\" the messages of the
+#eev channel. You can then use the window \"C\" to interact with
+the other users in #eev, and to experiment with commands. See:
+
+  (find-rcircnode \"Internet Relay Chat\" \"Once you have joined a channel\")
+  (find-rcircnode \"Getting started with rcirc\" \"To talk in a channel\")
+  (find-rcircnode \"rcirc commands\" \"/join #emacs\")
 
-then the second sexp will tell rcirc to connect to the server
-irc.freenode.net
 
 
-which tells Emacs to connect to Freenode and to the channel #eev,
-using this window setting:
 
-   _________________________
-  |           |             |
-  |           |   Freenode  |
-  |           |    server   |
-  |           |   messages  |
-  |  current  |_____________|    
-  |  buffer   |             |
-  |           |    #eev     |
-  |           |   channel   |
-  |           |             |
-  |___________|_____________|
+2. The two-window setting
+=========================
+Try this:
 
-You will then be able to watch the process of connecting to
-Freenode, which takes about 20s on my machine, by the messages
-that will appear at the Freenode server buffer; at some point
-rcirc will be allowed by the server to connect to channels, it
-will request to connect to the channel #eev, and some login
-messages, plus at list of all users connected to #eev and a
-prompt, will appear at the #eev channel buffer.
+  (find-freenode-2a \"#eev\")
 
-`M-66j' is mostly for establishing a connection to an IRC server
-and watching if any errors occur; once we know that we are
-connected we can use `M-6j' - with just one `M-6' - which just
-takes us to the #eev channel without changing the current window
-configuration. A mnemonic: `M-66j', which is one keypress longer,
-is to be used less often - essentially only once per session, or
-when we want to check the status of our connection to Freenode.
+It creates a window setting like
 
+   _________ ________
+  |         |        |
+  |         |        |
+  | current |  irc   |
+  | buffer  | buffer |
+  |         |        |
+  |_________|________|
 
+which is nice for when you don't want to follow the irc server
+messages.
 
 
-2. Messages and commands
-========================
-IRC is a command-line-ish protocol, in which lines starting with
-\"/\" are treated as commands and other lines as messages. A
-message typed at the #eev channel buffer is broadcast to all
-other users also connected to #eev; some commands, like
 
-  /join #emacs
 
-work in the same way no matter where they are typed, while
-others, like for example \"/part\", work differently when typed
-in #eev than when in #emacs. See:
+3. Tracking activity
+====================
+TODO: explain this:
 
-  (find-rcircnode \"rcirc commands\" \"/join #emacs\")
-  (find-rcircnode \"rcirc commands\" \"/part\")
+  (find-rcircnode \"Channels\" \"M-x rcirc-track-minor-mode\")
 
+and how to use it as a one-window setting. Also:
 
+  (find-efunctiondescr 'rcirc-track-minor-mode)
+  (find-efunction      'rcirc-track-minor-mode)
+  (find-evariable      'rcirc-track-minor-mode-map)
+  (find-ekeymapdescr    rcirc-track-minor-mode-map)
 
-3. Other channels
-=================
+  (find-efunctiondescr 'rcirc-next-active-buffer)
+  (find-efunction      'rcirc-next-active-buffer)
 
-where `find-freenode-3a' is based on `find-3a', described here:
+  (global-set-key [f2] 'rcirc-next-active-buffer)
 
-  (find-multiwindow-intro \"High-level words\")
 
-  (find-eev \"eev-rcirc.el\")
 
 
+4. Commands with very short names
+=================================
+We can apply this idea
 
-4. If you are new to IRC
-========================
-Most of the discussions between Free Software developers still
-happen in IRC channels, and mostly at Freenode. The best way to
-understand what IRC is - for modern people, I mean - is probably
-to try this first:
+  (find-eev-quick-intro \"7.4. Commands with very short names\")
+  (find-eev-quick-intro \"7.4. Commands with very short names\" \"(defun c 
()\")
 
-  http://webchat.freenode.net/
+to rcirc. If you connect occasionaly to the channels #eev,
+#emacs, #git and #ruby, you can run this, or put these lines in
+your .emacs:
 
-IRC is a command-line-ish protocol, in which lines starting with
-\"/\" are treated as commands and other lines are messages to be
-broadcast. Try to \"/join\" the channels \"#emacs\" and \"#eev\",
-with \"/join #emacs\" and \"/join #eev\"; in that webchat, try to
-switch between the channels you're connected to by clicking on
-the tabs at the top - and note that there is also a tab for a
-channel-ish thing that has only messages from the server. Try
-also to leave these channels with \"/part\", \"/part #emacs\",
-\"/part #eev\".
+  (setq rcirc-default-nick \"hakuryo\")
+  (defun e2 () (interactive) (find-freenode-2a \"#eev\"))
+  (defun e3 () (interactive) (find-freenode-3a \"#eev\"))
+  (defun m2 () (interactive) (find-freenode-2a \"#emacs\"))
+  (defun m3 () (interactive) (find-freenode-3a \"#emacs\"))
+  (defun g2 () (interactive) (find-freenode-2a \"#git\"))
+  (defun g3 () (interactive) (find-freenode-3a \"#git\"))
+  (defun r2 () (interactive) (find-freenode-2a \"#ruby\"))
+  (defun r3 () (interactive) (find-freenode-3a \"#ruby\"))
 
-In Rcirc each one of these channels, including the server
-channel, becomes an Emacs buffer. The names of these buffers will
-be:
 
-  *irc.freenode.net*
-  address@hidden
-  address@hidden
 
-  (defun eejump-66 () (find-freenode-3a \"#eev\"))
 
-For more information see:
+5. `find-freenode-links'
+========================
+You can generate lines like the ones above by running
+`find-freenode-links'. For example:
 
-  (find-node \"(rcirc)Top\")
-  (find-node \"(rcirc)Internet Relay Chat\")
-  (find-node \"(rcirc)rcirc commands\")
-  httpa://www.emacswiki.org/emacs/RcIrc
-  http://www.irchelp.org/
+  (find-freenode-links \"e\" \"#eev\")
+  (find-freenode-links \"r\" \"#ruby\")
 
-  (find-node \"(erc)Top\")
-  http://www.emacswiki.org/emacs/ErC
+
+
+6. Other servers
+================
+TODO: explain how to use find-rcirc-buffer and how to adapt
+find-freenode-* to other servers. Example:
+
+  (find-rcirc-buffer-2a \"irc.debian.org\" \"#debian-live\" nil 
\"#debian-live\")
+  (find-rcirc-buffer-3a \"irc.debian.org\" \"#debian-live\" nil 
\"#debian-live\")
+
+See:
+
+  (find-eev \"eev-rcirc.el\" \"find-freenode\")
 
 " pos-spec-list)))
 
diff --git a/eev-rcirc.el b/eev-rcirc.el
index daf77fe..f104b38 100644
--- a/eev-rcirc.el
+++ b/eev-rcirc.el
@@ -37,8 +37,6 @@
 
 ;;; Commentary:
 
-;; (New comments, 2019apr14):
-;;
 ;; This file - eev-rcirc.el - implements elisp hyperlinks for rcirc in
 ;; a way that lets several important actions be expressed as
 ;; one-liners.
@@ -297,7 +295,7 @@ window - \"#foo\" means channel \"#foo\", \"nick\" means 
query
 
 (defvar ee-freenode-achannels nil
   "The list of channels that `find-freenode' always reconnects to.
-When this is nil behave as if this was a copy of `ee-freenode-ichannels'.")
+When this is nil act as if this was a copy of `ee-freenode-ichannels'.")
 
 (defun find-freenode (&optional channel &rest pos-spec-list)
   "Connect to freenode and switch to the buffer for channel CHANNEL.