[elpa] externals/luwak 8373015f75 21/28: Prepare for ELPA submission

[ELPA Syncer]

branch: externals/luwak
commit 8373015f753497f08c3c7158a4bd2323ea007974
Author: Yuchen Pei <hi@ypei.me>
Commit: Yuchen Pei <hi@ypei.me>

    Prepare for ELPA submission
---
 README.org | 31 ++++++++++++++++++++++++++-----
 luwak.el   | 46 +++++++++++++++++++++++++++++++++-------------
 2 files changed, 59 insertions(+), 18 deletions(-)

diff --git a/README.org b/README.org
index 77ff1eda7b..4057715efd 100644
--- a/README.org
+++ b/README.org
@@ -1,30 +1,51 @@
 #+title: luwak: a text-only Emacs web browser based on lynx -dump
 
-* Install and use
+* Overview
 
 Luwak mode is a simple Emacs GET-only and text-only web browser, based
 on ~lynx -dump~.
 
+Features:
+
+- Some usual browser features: open, reload, search with a search
+  engine, follow links, go forward / backward in history, copy url of
+  the current page or link at point
+- Completion from persistent history in prompt to open a url
+- Write the dump of the current page to a file
+- Render a lynx dump in the luwak mode
+- imenu support, from all unindented strings (which look like
+  headings)
+- Support of storing and capturing for org mode, guessing the title
+  (first imenu item)
+- Multiple ways of rendering links: numbered, forward-sexp, hide
+  altogether
+- Quickly open a link on the page with completion for url / link id
+- Browse with or without torsocks
+
+* Install and use
+
 To use, clone this repo, add to ~load-path~ and ~require~.  Make sure
 you have lynx installed in your system (~apt install lynx~, ~pacman -S
 lynx~ etc.).  By default the browser uses torsocks, which can be
-disabled with a prefix arg.
+disabled with a prefix arg or switching ~luwak-tor-switch~ to ~t~.
 
 #+begin_src elisp
 (add-to-list 'load-path "~/.emacs.d/luwak")
 (require 'luwak)
 #+end_src
 
-There are two entry points:
+There are three entry points:
 
 - ~luwak-open~: open a url
-- ~luwak-search~: search a query (default to ddg html)
+- ~luwak-search~: search a query using a customisable default search
+  engine
+- ~luwak-render-buffer~: render a lynx dump file in luwak mode
 
 * Naming
 
 lynx dump -> feline excretion -> Kopi Luwak
 
-* Contact and Copyright
+* Contact and license
 
 luwak is maintained by Yuchen Pei (id@ypei.org).  It is covered by 
[[https://www.gnu.org/licenses/agpl-3.0.en.html][GNU
 AGPLv3+]].  You may find the license text in a file named COPYING.agpl3
diff --git a/luwak.el b/luwak.el
index 62ea223c9a..dcb09fa03e 100644
--- a/luwak.el
+++ b/luwak.el
@@ -1,5 +1,15 @@
-;; -*- lexical-binding: t; -*-
-;; Copyright (C) 2022 Yuchen Pei.
+;;; luwak.el --- Web browser based on lynx -dump. -*- lexical-binding: t; -*-
+
+;; Author: Yuchen Pei <id@ypei.org>
+;; Maintainer: Yuchen Pei <id@ypei.org>
+;; Created: 2022
+;; Version: 0
+;; Keywords: web-browser, lynx, html, tor
+;; Package-Requires: ((emacs "28"))
+;; Package-Type: 
+;; Homepage: https://g.ypei.me/luwak.git
+
+;; Copyright (C) 2022  Free Software Foundation, Inc.
 ;; 
 ;; This file is part of luwak.
 ;; 
@@ -16,7 +26,9 @@
 ;; You should have received a copy of the GNU Affero General Public
 ;; License along with luwak.  If not, see <https://www.gnu.org/licenses/>.
 
-(require 'org)
+;;; Commentary:
+
+;;; Code:
 
 (defvar luwak-buffer "*luwak*")
 
@@ -107,17 +119,19 @@ When non-nill, swap the tor-switch in prefix-arg effect."
     (buffer-substring-no-properties (1- (point))
                                     (progn (end-of-line 1) (point)))))
 
-(defun luwak-org-store-link ()
-  (when (derived-mode-p 'luwak-mode)
-    (org-link-store-props
-     :type "luwak"
-     :link (plist-get luwak-data :url)
-     :description (luwak-guess-title))))
+(when (require 'org nil t)
+  (defun luwak-org-store-link ()
+    (when (derived-mode-p 'luwak-mode)
+      (org-link-store-props
+       :type "luwak"
+       :link (plist-get luwak-data :url)
+       :description (luwak-guess-title))))
 
-(org-link-set-parameters "luwak"
-                         :follow #'luwak-open
-                         :store #'luwak-org-store-link)
+  (org-link-set-parameters "luwak"
+                           :follow #'luwak-open
+                           :store #'luwak-org-store-link))
 
+;;;###autoload
 (defun luwak-open (url)
   "Open URL in luwak."
   (interactive
@@ -145,6 +159,7 @@ When non-nill, swap the tor-switch in prefix-arg effect."
     (kill-new url)
     (message "Copied: %s" url)))
 
+;;;###autoload
 (defun luwak-search (query)
   "Search QUERY using 'luwak-search-engine'."
   (interactive "sLuwak search query: ")
@@ -211,7 +226,8 @@ When non-nill, swap the tor-switch in prefix-arg effect."
 
 (defun luwak-add-to-history-file ()
   (let ((url (plist-get luwak-data :url))
-        (title (luwak-guess-title)))
+        (title (luwak-guess-title))
+        (inhibit-message t))
     (append-to-file (concat url " " title "\n") nil luwak-history-file)))
 
 (defun luwak-history-backward ()
@@ -259,6 +275,7 @@ When non-nill, swap the tor-switch in prefix-arg effect."
           (funcall luwak-render-link-function i url)
           (setq i (1+ i)))))))
 
+;;;###autoload
 (defun luwak-render-buffer ()
   "Render the current buffer in luwak mode."
   (interactive)
@@ -336,6 +353,7 @@ When non-nill, swap the tor-switch in prefix-arg effect."
            (append (list name buffer "torsocks" program) program-args))))
 
 (defun luwak-save-dump (file-name)
+  "Write dump of the current luwak buffer to FILE-NAME."
   (interactive
    (list
     (read-file-name (format "Write dump of %s to: " (plist-get luwak-data 
:url))
@@ -347,3 +365,5 @@ When non-nill, swap the tor-switch in prefix-arg effect."
   (message "Wrote %s." file-name))
 
 (provide 'luwak)
+
+;;; luwak.el ends here