[elpa] externals/eev 19bfd61 7/9: Added sections about functions and byte-compilation to `find-eval-intro'.

[Stefan Monnier]

branch: externals/eev
commit 19bfd616d769652db62b25823c9b54b3703e3824
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>

    Added sections about functions and byte-compilation to `find-eval-intro'.
---
 ChangeLog     |  16 ++++
 VERSION       |   4 +-
 eev-blinks.el |  31 +++++++-
 eev-intro.el  | 195 +++++++++++++++++++++++++++++++++++++++++++--
 eev-rcirc.el  | 251 ++++++++++++++++++++++++++++++++++++++++++----------------
 5 files changed, 420 insertions(+), 77 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4dcb419..3066b1e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2019-04-14  Eduardo Ochs  <address@hidden>
+
+       * eev-rcirc.el: rewrote all comments and some docstrings.
+
+       * eev-rcirc.el (ee-irc-channel-around-point): commented out.
+       (ee-buffer-freenode-channel-name): commented out.
+
+2019-04-13  Eduardo Ochs  <address@hidden>
+
+       * eev-intro.el (find-eval-intro): new sections: "10.1.
+       Byte-compiled functions", "10.2. How `find-efunction' works", and
+       "10.3. Why eev avoids byte-compilation".
+
+       * eev-blinks.el (find-eloadhistory0, find-eloadhistory): new
+       functions.
+
 2019-04-09  Eduardo Ochs  <address@hidden>
 
        * eejump.el, eev-anchors.el, eev-audiovideo.el, eev-beginner.el,
diff --git a/VERSION b/VERSION
index b60c8c1..212629a 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Wed Apr 10 03:45:34 GMT 2019
-Wed Apr 10 00:45:34 -03 2019
+Sun Apr 14 07:15:50 GMT 2019
+Sun Apr 14 04:15:50 -03 2019
diff --git a/eev-blinks.el b/eev-blinks.el
index ea92f0c..06c6f5c 100644
--- a/eev-blinks.el
+++ b/eev-blinks.el
@@ -21,7 +21,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019apr06
+;; Version:    2019apr13
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-blinks.el>
@@ -56,6 +56,7 @@
 ;; «.find-w3m»                 (to "find-w3m")
 ;; «.find-Package»             (to "find-Package")
 ;; «.find-epp»                 (to "find-epp")
+;; «.find-eloadhistory»                (to "find-eloadhistory")
 ;; «.find-einternals»          (to "find-einternals")
 ;; «.find-einsert»             (to "find-einsert")
 ;; «.find-eunicode»            (to "find-eunicode")
@@ -775,6 +776,34 @@ explicitly. Try this: (progn (message \"foo\") \"bar\")"
 
 
 
+;;;  _                 _       _     _     _                   
+;;; | | ___   __ _  __| |     | |__ (_)___| |_ ___  _ __ _   _ 
+;;; | |/ _ \ / _` |/ _` |_____| '_ \| / __| __/ _ \| '__| | | |
+;;; | | (_) | (_| | (_| |_____| | | | \__ \ || (_) | |  | |_| |
+;;; |_|\___/ \__,_|\__,_|     |_| |_|_|___/\__\___/|_|   \__, |
+;;;                                                      |___/ 
+;; «find-eloadhistory» (to ".find-eloadhistory")
+;; Display entries in the `load-history' alist.
+;; See: (find-eval-intro "10.2. How `find-efunction' works")
+;;      (find-elnode "Where Defined" "load-history")
+
+;; Tests: (find-eloadhistory0 (locate-library "eepitch"))
+;;        (find-eloadhistory0 (symbol-file 'eepitch-kill))
+(defun find-eloadhistory0 (fname &rest pos-spec-list)
+  "Hyperlink to the load-history entry for FNAME.
+FNAME must be an absolute file name."
+  (apply 'find-epp (assoc fname load-history)
+        pos-spec-list))
+
+;; Tests: (find-eloadhistory "eepitch")
+;;        (find-eloadhistory "eepitch" "eepitch-dash")
+(defun find-eloadhistory (library &rest pos-spec-list)
+  "Hyperlink to the load-history entry for LIBRARY.
+LIBRARY is converted to an absolute file name using `locate-library'."
+  (apply 'find-epp (assoc (locate-library library) load-history)
+        pos-spec-list))
+
+
 
 
 ;;;                                   _       _                        _     
diff --git a/eev-intro.el b/eev-intro.el
index 8c59acd..f3e183a 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019apr06
+;; Version:    2019apr13
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -2633,8 +2633,181 @@ keep the instructions visible.
 
 
 
-What else?
-==========
+10. More on functions
+=====================
+A symbol - for example `f' - can be both a varible and a
+function; its \"value as a variable\" and its \"value as a
+function\" are stored in different places. Try:
+
+  (setq f 2)
+  (setq f 5)
+  (defun f (x) (* x x))
+  (defun f (x) (* 10 x))
+  (symbol-value    'f)
+  (symbol-function 'f)
+
+This is explained here:
+
+  (find-elnode \"Symbol Components\")
+  (find-elnode \"Symbol Components\" \"value cell\")
+  (find-elnode \"Symbol Components\" \"function cell\")
+
+The content of a \"function cell\" is _usually_ a lambda
+expression. See:
+
+  (find-elnode \"Lambda Expressions\")
+  (find-elnode \"What Is a Function\")
+  (find-elnode \"What Is a Function\" \"lambda expression\")
+  (find-elnode \"What Is a Function\" \"byte-code function\")
+
+Try:
+
+  (setq f 2)
+  (setq f 5)
+  (set 'f 2)
+  (set 'f 5)
+  (fset 'f (lambda (x) (* x x)))
+  (fset 'f (lambda (x) (* 10 x)))
+  (defun f (x) (* 10 x))
+  (defun f (x) (* x x))
+  (symbol-value    'f)
+  (symbol-function 'f)
+  (f 4)
+  (f f)
+
+  ((lambda (x) (* x x))
+   4)
+  ((lambda (x) (* 10 x))
+   4)
+
+
+
+10.1. Byte-compiled functions
+-----------------------------
+Most functions in Emacs are byte-compiled - which means that
+their function cells contain a \"byte-code\" instead of a lambda
+expression. These byte-codes are very hard for humans to read.
+See:
+
+  (find-elnode \"What Is a Function\" \"byte-code function\")
+  (find-elnode \"Byte-Code Type\")
+  (find-elnode \"Byte Compilation\")
+  (find-elnode \"Disassembly\")
+
+Here is an example:
+
+  (find-efunctiondescr 'find-file)
+  (find-efunction      'find-file)
+  (symbol-function     'find-file)
+  (find-efunctionpp    'find-file)
+  (find-efunctiond     'find-file)
+
+The `find-efunctionpp' link above takes the content of the
+function cell of `find-file' and \"pretty-prints\" it, i.e.,
+indents it in a nice way, but the result in this case is
+unreadable... and the `find-efunctiond' link shows a decompiled
+version of that byte-code, which is only slightly better. Both
+the `find-efunctionpp' and the `find-efunctiond' links show
+internal representations that are very different from the source
+code. Compare that with a case in which the function is not
+byte-compiled:
+
+  (find-efunctiondescr 'find-fline)
+  (find-efunction      'find-fline)
+  (symbol-function     'find-fline)
+  (find-efunctionpp    'find-fline)
+
+The `(find-efunctionpp 'find-fline)' shows a lambda expression
+that is very similar to the defun that defined `find-fline'.
+
+
+
+
+10.2. How `find-efunction' works
+--------------------------------
+Eev defines hyperlink functions called `find-efunction',
+`find-evariable' and `find-eface' that are wrappers around the
+standard functions `find-function', `find-variable' and
+`find-face-definition'; the eev variants support pos-spec-lists.
+Try:
+
+  (find-efunction 'find-fline)
+  (find-function  'find-fline)
+  (find-evariable 'ee-hyperlink-prefix)
+  (find-variable  'ee-hyperlink-prefix)
+  (find-eface           'eepitch-star-face)
+  (find-face-definition 'eepitch-star-face)
+
+The Emacs functions are defined here:
+
+  (find-efile \"emacs-lisp/find-func.el\")
+
+Their inner workings are quite complex. They use `symbol-file',
+that works on the variable `load-history'. Here are some links to
+documentation and tests:
+
+  (find-efunctiondescr 'symbol-file)
+  (find-elnode \"Where Defined\")
+  (symbol-file 'find-fline          'defun)
+  (symbol-file 'ee-hyperlink-prefix 'defvar)
+  (symbol-file 'eepitch-star-face   'defface)
+  (find-epp (assoc (locate-library \"eepitch\") load-history))
+
+The functions in \"find-func.el\" use `symbol-file' to find the
+file where a given symbol was defined, and then search a defun,
+defvar of defface in it that _may be_ the definition that we are
+looking for. The eev variants use the functions
+`find-function-noselect', `find-variable-noselect' and
+`find-definition-noselect' from \"find-func.el\", that return a
+pair (BUFFER . POS). Try:
+
+  (find-efunctiondescr 'find-function-noselect)
+  (find-efunctiondescr 'find-variable-noselect)
+  (find-efunctiondescr 'find-definition-noselect)
+
+  (find-ebufferandpos (find-function-noselect 'find-fline)
+   )
+  (find-ebufferandpos (find-variable-noselect 'ee-hyperlink-prefix)
+   )
+  (find-ebufferandpos (find-definition-noselect 'eepitch-star-face 'defface)
+   )
+
+These `find-*-select' functions work quite well but are not 100%
+reliable - for example, if an elisp file has several definitions
+for the same function, variable, or face, the `find-*-select's
+don't know which ones were executed, neither which one was
+executed last, overriding the other ones... and it may return the
+position of a defun, defvar, or defface that is not the
+\"active\" one.
+
+
+
+
+10.3. Why eev avoids byte-compilation
+-------------------------------------
+All the source files of eev have a \"no-byte-compile: t\" in
+them. See:
+
+  (find-eevgrep \"grep --color -nH -e no-byte-compile: *.el\")
+  (find-elnode \"Byte Compilation\" \"no-byte-compile: t\")
+
+This is non-standard, but it is a deliberate design choice.
+
+(TODO: explain the three main reasons: it is easier to teach
+emacs to beginners if they see lots of lambda expressions and few
+byte-codes; `code-c-d' and friends define functions dynamically
+and `find-efunction' don't work on them; in a distribution with
+only the \".elc\"s of eev users wouldn't have access to the
+documentation and examples in the comments of the source files.)
+
+
+
+
+
+
+
+11. What else?
+==============
 Eev-mode defines several other key sequences similar to `M-h
 M-i'. You can get the full list here:
 
@@ -6218,15 +6391,27 @@ 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).
 
+  (find-node \"(rcirc)Top\")
+  (find-node \"(erc)Top\")
+
+
 
 
 1. The server buffer and the channel buffers
 ============================================
-If you type `M-6 M-6 M-j' - or `M-e' on the line below - then eev
-runs this,
+Let's start with an example. In
 
+  (setq rcirc-default-nick \"hakuryo\")
+  (setq ee-freenode-ichannels \"#eev\")
   (find-freenode-3a \"#eev\")
 
+the first sexp tells rcirc to use the nickname \"hakuryo\" when
+connecting to an irc server; the second 
+
+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:
 
diff --git a/eev-rcirc.el b/eev-rcirc.el
index 7df7fde..daf77fe 100644
--- a/eev-rcirc.el
+++ b/eev-rcirc.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019mar13
+;; Version:    2019apr14
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-rcirc.el>
@@ -28,8 +28,83 @@
 ;;                 <http://angg.twu.net/eev-intros/find-rcirc-intro.html>
 ;;                                                (find-rcirc-intro)
 
+;; «.low-level»                        (to "low-level")
+;; «.find-rcirc-buffer»                (to "find-rcirc-buffer")
+;; «.find-rcirc-buffer-2a»     (to "find-rcirc-buffer-2a")
+;; «.find-rcirc-buffer-3a»     (to "find-rcirc-buffer-3a")
+;; «.find-freenode»            (to "find-freenode")
+;; «.find-freenode-links»      (to "find-freenode-links")
+
 ;;; 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.
+;; 
+;; 
+;; 1. Convention on channels
+;; =========================
+;; The rcirc convention for naming buffers is that if we are
+;; connected to the server irc.foobar.net then:
+;; 
+;;         *irc.foobar.net*     is the "server buffer" (with server messages),
+;;   address@hidden      is the buffer for the channel #emacs,
+;;    address@hidden      is the buffer for chatting with the user fsbot.
+;; 
+;; Note that in IRC we "/join" channels but we "/query" users. See:
+;; 
+;;   (find-node "(rcirc)rcirc commands" "/join #emacs")
+;;   (find-node "(rcirc)rcirc commands" "/query fsbot")
+;; 
+;; The eev-rcirc convention treats the "server" and the "channel" as
+;; separate parameters. The main conversion function is
+;; `ee-rcirc-buffer':
+;; 
+;;   (ee-rcirc-buffer "irc.foobar.net" nil)
+;;         -->       "*irc.foobar.net*"
+;;   (ee-rcirc-buffer "irc.foobar.net" "#emacs")
+;;         --> "address@hidden"
+;;   (ee-rcirc-buffer "irc.foobar.net" "fsbot")
+;;         -->  "address@hidden"
+;; 
+;; In IRC channel names can't have spaces, and neither can user names.
+;; Some programming languages use the term "word" for a non-empty
+;; string without spaces. The function `ee-split' accepts both strings
+;; and lists:
+;; 
+;;   (ee-split   "#emacs   fsbot   #git   gitinfo")
+;;       -->    ("#emacs" "fsbot" "#git" "gitinfo")
+;;   (ee-split '("#emacs" "fsbot" "#git" "gitinfo"))
+;;       -->    ("#emacs" "fsbot" "#git" "gitinfo")
+;; 
+;; If it receives a string it splits it into a list of words, and if
+;; it receives a list it return it unchanged.
+;; 
+;; Eev-rcirc treats channels and users in a uniform way, as words, and
+;; it accepts lists of channels and users to be given either as
+;; strings or as lists. More precisely,
+;; 
+;;   1) all the functions defined here that have an argument called
+;;      "channel" accept both a channel name and a user name,
+;; 
+;;   2) all the functions defined here that accept an argument called
+;;      "channels" accept both a string and a list; they use
+;;      `ee-split' internally to convert it to a list.
+;;
+;; and also:
+;;
+;;   3) some functions have arguments called "ichannels" and
+;;      "achannels". "Ichannels" means "initial channels": the
+;;      channels that we connect to when we connect to the server.
+;;      "Achannels" means "always channels": the channels that we
+;;      always reconnect. TODO: define precisely this "always".
+
+
+
+
+
 ;; Most of the _comments_ below are obsolete. The recommended way to
 ;; use this is now by running, for example,
 ;;
@@ -51,35 +126,6 @@
 ;; create a two-window setup with just the current buffer and the
 ;; #emacs buffer.
 
-;; OBSOLETE COMMENTS:
-;;
-;; Here we implement a very thin eev-ish layer on top of rcirc. The
-;; main goal is:
-;;
-;;   instant gratification and irc-ing for late-night zombie-mode
-;;   half-brain-dead hackers
-;;
-;; which, in practical terms, means the following. Suppose that we
-;; want to ask something on the channel #foobar of Freenode; we run
-;; `M-x find-freenode-links', adjust the intended channel name to
-;; #foobar, and set `M-99j' and `M-9j' to the right hyperlinks. Then,
-;; if we are in a buffer called "stuff", `M-99j' would create this
-;; window setting:
-;;
-;;     _____________________
-;;    |          |          |
-;;    |          | freenode |
-;;    |          |  server  |
-;;    |  stuff   |  buffer  |
-;;    |          |__________|
-;;    |          |          |
-;;    |          | #foobar  |
-;;    |__________|__________|
-;;
-;; which is great for following in real-time the connection being
-;; established - I find this essential for when it is very late at
-;; night and I am half-brain-dead -, and `M-9j' just switches to the
-;; buffer of the channel #foobar.
 
 ;; Conventions on arguments:
 ;; CHANNELS can be a list ("#foo" "#bar") or a string like "#foo #bar";
@@ -88,22 +134,36 @@
 ;; if CHANNEL is nil, that means to use the server buffer.
 
 
-;; Building blocks:
-;;
+
+
+;;;                           _                    
+;;;   ___  ___       _ __ ___(_)_ __ ___     __/\__
+;;;  / _ \/ _ \_____| '__/ __| | '__/ __|____\    /
+;;; |  __/  __/_____| | | (__| | | | (_|_____/_  _\
+;;;  \___|\___|     |_|  \___|_|_|  \___|      \/  
+;;;                                                
+;; «low-level» (to ".low-level")
+;; Low-level functions. These functions have very bad names and they
+;; WILL BE TOTALLY REWRITTEN AT SOME POINT IN THE FUTURE.
+
 (defun ee-rcirc-buffer (server &optional channel)
-  "Return the name of an rcirc server (or channel, or chat) buffer."
+  "Return the name of an rcirc server buffer, or channel, or chat buffer."
   (if channel (format "address@hidden" channel server) (format "*%s*" server)))
 
 (defun ee-rcirc-process (server)
+  "If we are connected to SERVER then return its network connection process.
+SERVER must be the name of an irc server, like \"irc.freenode.net\"."
   (get-buffer-process (ee-rcirc-buffer server)))
 
 (defun ee-rcirc-connected (server)
-  "Return non-nil if we are already connected to SERVER."
+  "Return non-nil if we are already connected to irc server SERVER.
+SERVER must be the name of an irc server, like \"irc.freenode.net\"."
   (and (get-buffer           (ee-rcirc-buffer server))
        (rcirc-buffer-process (ee-rcirc-buffer server))))
 
 (defun ee-rcirc-connect (server channels)
-"Connect to the irc server SERVER, if not already connected, and join 
CHANNELS."
+"If we are not already connected to the irc server SERVER then connect to it
+and join the channels CHANNELS."
   (if (not (ee-rcirc-connected server))
       (rcirc-connect server nil nil nil nil (ee-split channels))))
 
@@ -121,25 +181,29 @@ CHANNEL can also be nil, meaning the server buffer, or a 
nick to /query."
        (rcirc-cmd-query channel))))
 
 
-;; Medium-level words without window setup.
-;; Tests:
-;; (find-rcirc-buffer "irc.freenode.net" "#eev #emacs")
-;; (find-rcirc-buffer "irc.freenode.net" "#eev #emacs" nil           "#eev")
-;; (find-rcirc-buffer "irc.freenode.net" "#eev #emacs" "#eev #emacs")
-;; (find-rcirc-buffer "irc.freenode.net" "#eev #emacs" "#eev #emacs" "#eev")
-;;
+
+;;;   __ _           _                _                    
+;;;  / _(_)_ __   __| |      _ __ ___(_)_ __ ___     __/\__
+;;; | |_| | '_ \ / _` |_____| '__/ __| | '__/ __|____\    /
+;;; |  _| | | | | (_| |_____| | | (__| | | | (_|_____/_  _\
+;;; |_| |_|_| |_|\__,_|     |_|  \___|_|_|  \___|      \/  
+;;;                                                        
+;; «find-rcirc-buffer» (to ".find-rcirc-buffer")
+;; Medium-level functions - two that only change the current buffer,
+;; then two that create window setups.
+
 (defun find-rcirc-buffer0
   (server &optional channel &rest pos-spec-list)
   "Switch to the buffer for CHANNEL on SERVER. Make no attempt to (re)connect."
   (apply 'find-ebuffer (ee-rcirc-buffer server channel) pos-spec-list))
 
+;; Test: (find-rcirc-buffer "irc.freenode.net" "#eev #emacs" nil "#eev")
 (defun find-rcirc-buffer
   (server ichannels &optional achannels channel &rest pos-spec-list)
   "Switch to the buffer for CHANNEL on SERVER.
-When not connected connect to SERVER, taking the initial list of
-channels from ICHANNELS; always make sure that we are connected
-to ACHANNELS and to CHANNEL, and switch to the buffer for
-CHANNEL.
+When not connected to SERVER connect to it, taking the initial
+list of channels from ICHANNELS; always make sure that we are
+connected to ACHANNELS and to CHANNEL.
 
 If ACHANNELS is nil (not \"\") then use the list in ICHANNELS.
 If CHANNEL is nil then switch to the server buffer."
@@ -150,12 +214,8 @@ If CHANNEL is nil then switch to the server buffer."
 
 
 
-
-;; Medium-level words with window setup
-;; Tests:
-;; (find-rcirc-buffer-2a "irc.freenode.net" "#eev" nil "#libreboot")
-;; (find-rcirc-buffer-3a "irc.freenode.net" "#eev" nil "#libreboot")
-;;
+;; «find-rcirc-buffer-2a» (to ".find-rcirc-buffer-2a")
+;; Test: (find-rcirc-buffer-2a "irc.freenode.net" "#eev" nil "#libreboot")
 (defun find-rcirc-buffer-2a
   (server ichannels &optional achannels channel &rest pos-spec-list)
   "Connect to the irc server SERVER and create this window setup:
@@ -168,13 +228,15 @@ If CHANNEL is nil then switch to the server buffer."
 ICHANNELS is the list of initial channels (used when connecting
 to the server for the first time). ACHANNELS is the list of
 channels to always (re)connect to; if nil it defaults to
-ICHANNELS. CHANNEL selects what to display in the irc buffer at
+ICHANNELS. CHANNEL selects what to display in the window at
 the right - nil means the server buffer, \"#foo\" means channel
 \"#foo\", \"nick\" means query \"nick\"."
   (find-2a
    nil
    `(find-rcirc-buffer server ichannels achannels channel ,@pos-spec-list)))
 
+;; «find-rcirc-buffer-3a» (to ".find-rcirc-buffer-3a")
+;; Test: (find-rcirc-buffer-3a "irc.freenode.net" "#eev" nil "#libreboot")
 (defun find-rcirc-buffer-3a
   (server ichannels achannels channel &rest pos-spec-list)
   "Connect to the irc server SERVER and create this window setup:
@@ -191,8 +253,8 @@ the right - nil means the server buffer, \"#foo\" means 
channel
 ICHANNELS is the list of initial channels (used when connecting
 to the server for the first time). ACHANNELS is the list of
 channels to always (re)connect to; if nil it defaults to
-ICHANNELS. CHANNEL selects what to display in the irc channel at
-the right - \"#foo\" means channel \"#foo\", \"nick\" means query
+ICHANNELS. CHANNEL selects what to display in the lower right
+window - \"#foo\" means channel \"#foo\", \"nick\" means query
 \"nick\"."
   (find-3a
    nil
@@ -208,32 +270,83 @@ the right - \"#foo\" means channel \"#foo\", \"nick\" 
means query
 
 ;; (find-find-links-links "{k}" "freenode" "channel")
 ;;
-(defun ee-irc-channel-around-point ()
-  (ee-stuff-around-point "#A-Za-z0-9_"))
+;; (defun ee-irc-channel-around-point ()
+;;   (ee-stuff-around-point "#A-Za-z0-9_"))
+;; 
+;; (defun ee-buffer-freenode-channel-name ()
+;;   (replace-regexp-in-string
+;;    "^\\(.*\\).irc\\.freenode\\.net" "\\1"
+;;    (buffer-name)))
 
-(defun ee-buffer-freenode-channel-name ()
-  (replace-regexp-in-string
-   "^\\(.*\\).irc\\.freenode\\.net" "\\1"
-   (buffer-name)))
 
-;; High-level
-;;
+
+
+
+;;;  _____                              _      
+;;; |  ___| __ ___  ___ _ __   ___   __| | ___ 
+;;; | |_ | '__/ _ \/ _ \ '_ \ / _ \ / _` |/ _ \
+;;; |  _|| | |  __/  __/ | | | (_) | (_| |  __/
+;;; |_|  |_|  \___|\___|_| |_|\___/ \__,_|\___|
+;;;                                            
+;; «find-freenode» (to ".find-freenode")
+
 (defvar ee-freenode-server "irc.freenode.net")
-(defvar ee-freenode-ichannels "#eev #rcirc")
-(defvar ee-freenode-achannels "#eev #rcirc")
+
+(defvar ee-freenode-ichannels "#eev #rcirc"
+  "The list of initial channels to connect to at freenode.")
+
+(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'.")
 
 (defun find-freenode (&optional channel &rest pos-spec-list)
+  "Connect to freenode and switch to the buffer for channel CHANNEL.
+This is like `find-rcirc-buffer', but uses the variables
+`ee-freenode-ichannels' and `ee-freenode-achannels'."
   (apply 'find-rcirc-buffer
          ee-freenode-server
-         ee-freenode-ichannels 
+         ee-freenode-ichannels
          ee-freenode-achannels channel pos-spec-list))
 
 (defun find-freenode-2a (channel)
+  "Connect to freenode and create this window setup:
+   _________ ________
+  |         |        |
+  | current |  irc   |
+  | buffer  | buffer |
+  |_________|________|
+
+This is like `find-rcirc-buffer-2a' but uses
+`ee-freenode-ichannels' and `ee-freenode-achannels'."
   (find-2a nil '(find-freenode channel)))
 
 (defun find-freenode-3a (channel)
+  "Connect to freenode and create this window setup:
+   _________ _________
+  |         |         |
+  |         |   irc   |
+  |         |  server |
+  | current |_________|
+  | buffer  |         |
+  |         |   irc   |
+  |         | channel |
+  |_________|_________|
+
+This is like `find-rcirc-buffer-3a' but uses
+`ee-freenode-ichannels' and `ee-freenode-achannels'."
   (find-3a nil '(find-freenode) '(find-freenode channel)))
 
+
+
+
+;;;   __                               _            _ _       _        
+;;;  / _|_ __ ___  ___ _ __   ___   __| | ___      | (_)_ __ | | _____ 
+;;; | |_| '__/ _ \/ _ \ '_ \ / _ \ / _` |/ _ \_____| | | '_ \| |/ / __|
+;;; |  _| | |  __/  __/ | | | (_) | (_| |  __/_____| | | | | |   <\__ \
+;;; |_| |_|  \___|\___|_| |_|\___/ \__,_|\___|     |_|_|_| |_|_|\_\___/
+;;;                                                                    
+;; «find-freenode-links» (to ".find-freenode-links")
+
 (defun find-freenode-links (&optional c channel &rest pos-spec-list)
 "Visit a temporary buffer containing code for connecting to a freenode 
channel."
   (interactive)
@@ -241,15 +354,16 @@ the right - \"#foo\" means channel \"#foo\", \"nick\" 
means query
   (setq channel (or channel "{channel}"))
   (apply 'find-elinks
    `((find-freenode-links ,c ,channel)
-     (find-freenode-links "{e}" "{#eev}")
      (find-freenode-links "e" "#eev")
+     (find-freenode-links)
      ;; Convention: the first sexp always regenerates the buffer.
      (find-efunction 'find-freenode-links)
      (find-efunction 'find-freenode-2a)
      ""
      ,(ee-template0 "\
+(setq rcirc-default-nick \"hakuryo\")
+(setq rcirc-default-nick \"{(user-login-name)}\")
 (setq ee-freenode-ichannels {(ee-pp0 ee-freenode-ichannels)})
-(setq ee-freenode-achannels {(ee-pp0 ee-freenode-achannels)})
 (setq ee-freenode-achannels nil)
 (defun {c}2 () (interactive) (find-freenode-2a \"{channel}\"))
 (defun {c}3 () (interactive) (find-freenode-3a \"{channel}\"))
@@ -267,6 +381,5 @@ the right - \"#foo\" means channel \"#foo\", \"nick\" means 
query
 
 ;; Local Variables:
 ;; coding:            utf-8-unix
-;; ee-anchor-format:  "defun %s "
 ;; no-byte-compile:   t
 ;; End: