[elpa] externals/devdocs ccadf08 5/7: Add a README

[ELPA Syncer]

branch: externals/devdocs
commit ccadf0882aac81182dd1bc4b78b0af2ec6cc1dd3
Author: Augusto Stoffel <arstoffel@gmail.com>
Commit: Augusto Stoffel <arstoffel@gmail.com>

    Add a README
---
 README.md | 34 ++++++++++++++++++++++++++++++++++
 evdocs.el | 18 ++++++++++++++----
 2 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..675babd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,34 @@
+evdocs — Emacs viewer for DevDocs
+=================================
+
+evdocs is a documentation viewer similar to the built-in Info browser,
+but geared towards documentation obtained from the [DevDocs] website.
+
+To get started, download some documentation with `M-x evdocs-install`.
+This will first query https://devdocs.io for the available documents,
+and save to disk the selected document.
+
+Once you have the desired documents at hand, call `M-x evdocs-lookup`
+to search for entries.
+
+In any given buffer, the first call to `evdocs-lookup` will query for
+a list of documents to search (you can select more than one option by
+entering a comma-separated list).  This selection will be remembered
+in subsequent calls to `evdocs-lookup`, unless a prefix argument is
+given; in this case you can select a new list of documents.
+Alternatively, you can set the `evdocs-current-docs` variable
+directly, say via [dir-local variables] or a mode hook:
+
+```elisp
+(with-eval-after-load 'evdocs
+  (add-hook 'python-mode-hook
+            (lambda () (add-to-list 'evdocs-current-docs "python~3.9"))))
+```
+
+In the `*devdocs*` buffer, navigation keys similar to Info and
+`*Help*` buffers are available; press `C-h m` for details.  Internal
+hyperlinks are opened in the same viewing buffer, and external links
+are opened as `browse-url` normally would.
+
+[DevDocs]: https://devdocs.io
+[dir-local variables]: 
https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html
diff --git a/evdocs.el b/evdocs.el
index d022a33..bd01a39 100644
--- a/evdocs.el
+++ b/evdocs.el
@@ -23,6 +23,15 @@
 
 ;;; Commentary:
 
+;; evdocs is a documentation viewer similar to Emacs's built-in Info
+;; browser, but geared towards documentation obtained from
+;; https://devdocs.io.
+
+;; To get started, download some documentation with `evdocs-install`.
+;; This will show the available documents and save the selected one to
+;; disk.  Once you have the desired documents at hand, use
+;; `evdocs-lookup` to search for entries.
+
 ;;; Code:
 
 (require 'seq)
@@ -247,9 +256,9 @@ This is an alist containing `entries' and `types'."
 (defun evdocs--render (entry)
   "Render a DevDocs documentation entry, returning a buffer.
 
-ENTRY is an alist like those in `evdocs--index', possibly with an
-additional ENTRY.fragment which overrides the fragment part of
-ENTRY.path."
+ENTRY is an alist like those in the variable `evdocs--index',
+possibly with an additional ENTRY.fragment which overrides the
+fragment part of ENTRY.path."
   (or (libxml-available-p)
       (error "This function requires Emacs to be compiled with libxml2"))
   (with-current-buffer (get-buffer-create "*devdocs*")
@@ -274,7 +283,8 @@ ENTRY.path."
       (current-buffer))))
 
 (defun evdocs--browse-url (url &rest _)
-  "A suitable `browse-url-browser-function' for `devdocs-mode'."
+  "A suitable `browse-url-browser-function' for `devdocs-mode'.
+URL can be an internal link in a DevDocs document."
   (let-alist (car evdocs--stack)
     (let* ((dest (evdocs--path-expand url .path))
            (file (evdocs--path-file dest))