aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.org31
-rw-r--r--luwak.el46
2 files changed, 59 insertions, 18 deletions
diff --git a/README.org b/README.org
index 77ff1ed..4057715 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 62ea223..dcb09fa 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