From: Eshel Yaron <me@eshelyaron.com>
Date: Tue, 9 May 2023 16:48:53 +0000 (+0300)
Subject: Documentation updates
X-Git-Tag: v0.1.5~2
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=9e61ef925bb1f4c7ab88ab1dd69383a6907dc046;p=dict.git

Documentation updates
---

diff --git a/README.org b/README.org
index a9f23f9..8cfe5a3 100644
--- a/README.org
+++ b/README.org
@@ -20,7 +20,22 @@ definitions.
 
 #+toc: headlines 8 insert TOC here, with eight headline levels
 
-* TODO Installation
+* Installation
+:PROPERTIES:
+:CUSTOM_ID: installation
+:DESCRIPTION: Installing Dict
+:ALT_TITLE: Installation
+:END:
+
+Dict is currently available from its Git repository.  To clone the
+latest version, run:
+
+#+begin_src sh
+  git clone git://git.eshelyaron.com/dict.git
+#+end_src
+
+Then use ~M-x package-install-file~ to install ~dict.el~ from the
+cloned repository as a package.
 
 * Displaying Word Definitions
 :PROPERTIES:
@@ -97,6 +112,29 @@ The following user options affect the behavior of ~dict-describe-word~:
   the function ~dict-display-definition-in-help-buffer~, which displays the
   definition in a =*Help*= buffer.
 
+* Programmatic Interface
+:PROPERTIES:
+:CUSTOM_ID: api
+:DESCRIPTION: Querying dictionary servers from Elisp
+:ALT_TITLE: API
+:END:
+
+Dict provides the following functions for querying dictionary servers
+from Elisp:
+
+- Function: dict-match-word word :: Return a list of dictionary matches
+  for WORD.
+- Function: dict-define-word word :: Return the dictionary definition of
+  WORD, or nil if not defined.
+
+The function ~dict-match-word~ queries the dictionary server for words
+that match a given input in the dictionary specified by the user option
+~dict-dictionary~, based on the matching strategy specified by the
+~dict-strategy~.  Similarly, ~dict-define-word~ retrieves and returns
+the definition of a given word in the dictionary specified by
+~dict-dictionary~ as a string, or it returns ~nil~ if the dictionary
+server doesn't find a definition for that word.
+
 * Extending Dict
 :PROPERTIES:
 :CUSTOM_ID: extending-dict
@@ -136,19 +174,30 @@ completion, using the word at point as the minibuffer's default
 argument.  This is also what ~dict-describe-word~ uses to prompt for a
 word when you call it interactively.
 
-* TODO How Dict Compares to Other RFC2229 Client Packages
+* Motivation Behind Dict
 :PROPERTIES:
-:CUSTOM_ID: alternatives
-:DESCRIPTION: Comparison of Dict with other RFC2229 client packages
-:ALT_TITLE: Alternatives
+:CUSTOM_ID: motivation
+:DESCRIPTION: Why develop Dict?
+:ALT_TITLE: Motivation
 :END:
 
-** dictionary
+The main motivation behind the development of Dict was to resolve some
+issues that the author came across with the =dictionary.el= package that
+ships with Emacs.  This package, initially written by Torsten Hilbrich
+to support both GNU Emacs and XEmacs, was added as a library to Emacs
+core in version 28.
 
-** define-word
+In their essence, Dict and =dictionary.el= have similar goals and they
+both operate in a similar manner - getting word definitions from RFC2229
+servers, and displaying them in an Emacs buffer.
 
-** DictEm
+Dict's differentiation comes from its simplicity and
+extensibility--while =dictionary.el= defines a bespoke major mode and
+interface for browsing word definitions, Dict leverages Emacs's Help
+mode by default, and let's you extend and control every aspect of its
+behavior via customization options.
 
+=dict.el= is also shorter than =dictionary.el=--just under 300 lines of code!
 
 #+html: <!--
 
diff --git a/dict.el b/dict.el
index 696c28d..ef3925b 100644
--- a/dict.el
+++ b/dict.el
@@ -258,7 +258,7 @@ option to it first."
          (default (car (dict-match-word word-at-point))))
     (completing-read (format-prompt "Word" default)
                      (completion-table-dynamic #'dict-match-word)
-                     nil  t nil 'dict-read-word-history default t)))
+                     nil t nil 'dict-read-word-history default t)))
 
 (define-button-type 'help-word
   :supertype 'help-xref
@@ -283,10 +283,9 @@ option to it first."
 (defun dict-describe-word (word)
   "Display the definition of WORD.
 
-This command obtains the definition of WORD from the RFC2229
-dictionary server specified by `dict-server-host' and
-`dict-server-port'.  When successful, it calls the function
-specified by `dict-display-definition-function' to display the
+This command retrieves the definition of WORD from a dictionary
+server.  When successful, it calls the function specified by
+`dict-display-definition-function' to display the
 definition.  (By default, this uses a *Help* buffer.)"
   (interactive (list (dict-read-word)))
   (let ((definition (dict-define-word word)))