From 9e61ef925bb1f4c7ab88ab1dd69383a6907dc046 Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Tue, 9 May 2023 19:48:53 +0300 Subject: [PATCH] Documentation updates --- README.org | 65 +++++++++++++++++++++++++++++++++++++++++++++++------- dict.el | 9 ++++---- 2 files changed, 61 insertions(+), 13 deletions(-) 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: