Fleshed out commentry.

[elpher.git] / elpher.el

diff --git a/elpher.el b/elpher.el
index b97d19e..b6c4b56 100644 (file)
--- a/elpher.el
+++ b/elpher.el
@@ -26,7 +26,22 @@
 
 ;;; Commentary:
 
-;; Elpher is a tool for exploring "gopherspace" using GNU Emacs.
+;; Elpher aims to provide a full-featured gopher client for GNU Emacs.
+;; It supports:
+
+;; - intuitive keyboard and mouse-driven browsing,
+;; - caching of visited sites (both content and cursor position),
+;; - pleasant and configurable colouring of Gopher directories,
+;; - direct visualisation of image files,
+;; - clickable web and gopher links in plain text.
+
+;; The caching mechanism works by maintaining a hierarchy of visited
+;; pages rather than a linear history, meaning that it is quick and
+;; easy to navigate this history.
+
+;; To launch Elpher, simply use 'M-x elpher'.  This will open a start
+;; page containing information on key bindings and suggested starting
+;; points for your gopher exploration.
 
 ;;; Code:
 
@@ -73,6 +88,18 @@
    "\r\n")
   "Source for elpher start page.")
 
+(defconst elpher-type-map
+  '((?0 elpher-get-text-node "T" elpher-text)
+    (?1 elpher-get-index-node "/" elpher-index)
+    (?g elpher-get-image-node "im" elpher-image)
+    (?p elpher-get-image-node "im" elpher-image)
+    (?I elpher-get-image-node "im" elpher-image)
+    (?4 elpher-get-node-download "B" elpher-binary)
+    (?5 elpher-get-node-download "B" elpher-binary)
+    (?9 elpher-get-node-download "B" elpher-binary)
+    (?7 elpher-get-search-node "?" elpher-search))
+  "Association list from types to getters, margin codes and index faces.")
+
 
 ;;; Customization group
 ;;
@@ -130,6 +157,10 @@
 Otherwise, use the system browser via the BROWSE-URL function."
   :type '(boolean))
 
+(defcustom elpher-cache-images nil
+  "If non-nil, cache images in memory in the same way as other content."
+  :type '(boolean))
+
 ;;; Model
 ;;
 
@@ -261,18 +292,6 @@ content and cursor position fields of the node."
         (insert " "))
     (insert (make-string elpher-margin-width ?\s))))
 
-(defvar elpher-type-map
-  '((?0 elpher-get-text-node "T" elpher-text)
-    (?1 elpher-get-index-node "/" elpher-index)
-    (?g elpher-get-image-node "im" elpher-image)
-    (?p elpher-get-image-node "im" elpher-image)
-    (?I elpher-get-image-node "im" elpher-image)
-    (?4 elpher-get-node-download "B" elpher-binary)
-    (?5 elpher-get-node-download "B" elpher-binary)
-    (?9 elpher-get-node-download "B" elpher-binary)
-    (?7 elpher-get-search-node "?" elpher-search))
-  "Association list from types to getters, margin codes and index faces.")
-
 (defun elpher-insert-index-record (line)
   "Insert the index record corresponding to LINE into the current buffer."
   (let* ((type (elt line 0))
@@ -328,7 +347,7 @@ content and cursor position fields of the node."
 
 (defun elpher-get-selector (address after)
   "Retrieve selector specified by ADDRESS, then execute AFTER.
-The result is stored as a string in the variable elpher-selector-string."
+The result is stored as a string in the variable ‘elpher-selector-string’."
   (setq elpher-selector-string "")
   (make-network-process
    :name "elpher-process"
@@ -452,22 +471,25 @@ The result is stored as a string in the variable elpher-selector-string."
            (insert-image content))
           (setq cursor-type nil)
           (elpher-restore-pos))
-      (progn
-        (elpher-with-clean-buffer
-         (insert "LOADING IMAGE..."))
-        (elpher-get-selector address
-                              (lambda (proc event)
-                                (unless (string-prefix-p "deleted" event)
-                                  (let ((image (create-image
-                                                (encode-coding-string elpher-selector-string
-                                                                      'no-conversion)
-                                                nil t)))
-                                    (elpher-with-clean-buffer
-                                     (insert-image image))
-                                    (setq cursor-type nil)
-                                    (elpher-restore-pos)
-                                    (elpher-set-node-content elpher-current-node
-                                                              image)))))))))
+      (if (display-images-p)
+          (progn
+            (elpher-with-clean-buffer
+             (insert "LOADING IMAGE..."))
+            (elpher-get-selector address
+                                 (lambda (proc event)
+                                   (unless (string-prefix-p "deleted" event)
+                                     (let ((image (create-image
+                                                   (encode-coding-string elpher-selector-string
+                                                                         'no-conversion)
+                                                   nil t)))
+                                       (elpher-with-clean-buffer
+                                        (insert-image image))
+                                       (setq cursor-type nil)
+                                       (elpher-restore-pos)
+                                       (if elpher-cache-images
+                                           (elpher-set-node-content elpher-current-node
+                                                                    image)))))))
+        (elpher-get-node-download)))))
 
 ;; Search retrieval
 
@@ -623,7 +645,7 @@ The result is stored as a string in the variable elpher-selector-string."
         (let ((node (button-get button 'elpher-node)))
           (if node
               (elpher-visit-node (button-get button 'elpher-node)
-                                  #'elpher-get-node-download)
+                                 #'elpher-get-node-download)
             (message "Can only download gopher links, not general URLs.")))
       (message "No link selected."))))