Documentation and license.

1 files changed, 54 insertions, 7 deletions

diff --git a/url-rewrite.el b/url-rewrite.el
index 119e669..0736494 100644
--- a/url-rewrite.el
+++ b/url-rewrite.el
@@ -1,4 +1,51 @@
-;;; Utility functions.
+;;; url-rewrite.el -- A library for rewriting URLs -*- lexical-binding: t -*-
+
+;; Copyright (C) 2023  Free Software Foundation, Inc.
+
+;; Author: Yuchen Pei <id@ypei.org>
+;; Package-Requires: ((emacs "28.2"))
+
+;; This file is part of url-rewrite.
+
+;; url-rewrite is free software: you can redistribute it and/or modify it under
+;; the terms of the GNU Affero General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; url-rewrite is distributed in the hope that it will be useful, but WITHOUT
+;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+;; or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General
+;; Public License for more details.
+
+;; You should have received a copy of the GNU Affero General Public
+;; License along with url-rewrite.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; A library for rewriting URLs. Usecases include redirecting to an
+;; alternative client, removing tracking queries etc.
+
+;; Includes a collection of building block functions for url
+;; rewriting.
+
+;; Another usage would be:
+
+;; 1. Declare rewriting rules in `url-rw-rules' (see
+;; `url-rw-example-rules' for example)
+
+;; 2. Then declare some ad-hoc rewriting functions and add them to
+;; `url-rw-extra-rewriters'. An example is
+;; `url-rw-example-zoom-to-dial'.
+
+;; 3. Eval `(url-rw-refresh)' to populate the rewrite function list
+;; `url-rw-rewriters'.
+
+;; 4. The function `url-rw' can now be used on any url you wish to
+;; rewrite.
+
+;;; Code:
+
+;;; Utility functions
 (defun url-rw-format-filename (path queries)
   "Format a filename from PATH and QUERIES alist."
   (let ((formatted-queries
@@ -221,12 +268,12 @@ has exceeded `url-rw-max-rewrites', stop."
 
 For a longer list, see <https://redirect.invidious.io/>.")
 
-;; Uncomment the following to add the example rules and the zoom to
-;; dial function
-;; (dolist (rule url-rw-example-rules url-rw-rewriters)
-;;   (eval `(url-rw-define-rewrite ,rule)))
-;;
-;; (add-to-list 'url-rw-rewriters 'url-rw-example-zoom-to-dial)
+;; Uncomment the following to use the example rules and the zoom to
+;; dial functions
+
+;; (setq url-rw-rules url-rw-example-rules
+;;       url-rw-extra-rewriters '(url-rw-example-zoom-to-dial))
+;; (url-rw-refresh)
 
 (provide 'url-rewrite)
 ;;; url-rewrite.el ends here