branch: externals/eev
commit 340be0a621841b4e7e46778c7f8e52772013ad39
Author: Eduardo Ochs <eduardoo...@gmail.com>
Commit: Eduardo Ochs <eduardoo...@gmail.com>
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 <eduardoo...@gmail.com>
- * 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 <eduardoo...@gmail.com>
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 <eduardoo...@gmail.com>
;; Maintainer: Eduardo Ochs <eduardoo...@gmail.com>
-;; 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*
- #em...@irc.freenode.net
- #e...@irc.freenode.net
- (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.
