dictionary | James Cherti

License

The quick-sdcv.el package provides a lightweight interface for the sdcv command-line tool, enabling Emacs to function as an offline dictionary.

This package allows for immediate word definitions and translations without requiring an internet connection.

Key interactive functions include:

quick-sdcv-search-at-point: Searches the word under the cursor and displays the result in a dedicated buffer.
quick-sdcv-search-input: Prompts for a custom input string and presents the corresponding dictionary entry in a buffer.

If this package enhances your workflow, please show your support by ⭐ starring quick-sdcv on GitHub to help more Emacs users discover its benefits.

Prerequisite

The sdcv command. (It can usually be installed by installing the sdcv package.)
Download dictionaries from: http://download.huzheng.org/ . Once the dictionaries are downloaded, extract them into /usr/share/stardict/dic/, or configure the variable quick-sdcv-dictionary-data-dir in the Emacs configuration to specify an alternative dictionary path.

Installation

To install quick-sdcv on Emacs from MELPA:

If you haven’t already done so, add MELPA repository to your Emacs configuration.
Add the following code at the very beginning of your init.el file, before all other packages:

(use-package quick-sdcv
  :init
  ;; When non-nil, a distinct buffer is created for each word searched.
  (setq quick-sdcv-unique-buffers t)

  ;; Change the prefix character used before dictionary names, replacing the
  ;; default `-->`:
  (setq quick-sdcv-dictionary-prefix-symbol "►")

  ;; Change the quick-sdcv dictionaries ellipsis from … to " ▼"
  ;; (In quick-sdcv buffers, `outline-minor-mode' is enabled by default, which
  ;; allows sections corresponding to individual dictionaries to be folded. The
  ;; ellipsis … indicates a folded section, making it easy to collapse all
  ;; dictionaries and expand only those of interest.)
  (setq quick-sdcv-ellipsis " ▼")

  ;; Automatically fold all dictionary entries when performing a search.
  ;; You can then unfold the dictionaries you want to read.
  (setq quick-sdcv-fold-on-search t))

Usage

To retrieve the word under the cursor and display its definition in a buffer:

(quick-sdcv-search-at-point)

To prompt the user for a word and display its definition in a buffer:

(quick-sdcv-search-input)

Customizations

To create a unique buffer for each word lookup, set the following:

;; Controls whether each word lookup creates a separate buffer.
;; Its default value is nil, but it can be set to t to enable unique buffers.
;;
;; When non-nil, a distinct buffer is created for each word searched. For
;; example, searching for the word "computer" produces a buffer named
;; "*sdcv:computer*". When nil, all lookups share the same buffer, typically
;; named "*sdcv*".
;;
;; The naming of unique buffers can be further customized using the variables:
;; - 'quick-sdcv-buffer-name-prefix'
;; - 'quick-sdcv-buffer-name-separator'
;; - 'quick-sdcv-buffer-name-suffix'
(setq quick-sdcv-unique-buffers t)

To perform exact word searches (as opposed to fuzzy searches), use:

;; To perform exact word searches (as opposed to fuzzy searches), use:
(setq quick-sdcv-exact-search t)

To change the prefix character used before dictionary names, replacing the default -->, set:

;; To change the prefix character used before dictionary names, replacing the
;; default `-->`, set:
(setq quick-sdcv-dictionary-prefix-symbol "►")

Customize the quick-sdcv dictionaries ellipsis display:

;; Customize the *quick-sdcv* dictionaries ellipsis display. In quick-sdcv
;; buffers, `outline-minor-mode' is enabled by default, which allows sections
;; corresponding to individual dictionaries to be folded. The ellipsis (…)
;; indicates a folded section, making it easy to collapse all dictionaries and
;; expand only those of interest
(setq quick-sdcv-ellipsis " ▼")

To automatically fold all dictionary entries when a search is performed:

;; Automatically fold all dictionary entries when a search is performed.
;; This is useful if you use many dictionaries and want to see a clean list
;; of dictionary names first.
(setq quick-sdcv-fold-on-search t)

To customize the sdcv history size:

;; Customize the sdcv history size
(setq quick-sdcv-hist-size 100)

To specify the path to the sdcv executable:

;; Specify the path to the sdcv executable:
(setq quick-sdcv-program "/path/to/sdcv")

To customize the naming convention of the SDCV buffer:

;; Customize the naming convention of the SDCV buffer:
(setq quick-sdcv-buffer-name-prefix "*sdcv"
      quick-sdcv-buffer-name-separator ":"
      quick-sdcv-buffer-name-suffix "*")

To specify a list of dictionaries (NOT RECOMMENDED. It is better to let sdcv show all dictionaries):

;; To specify a list of dictionaries (NOT RECOMMENDED. It is better to let sdcv
;; show all dictionaries):
(setq quick-sdcv-dictionary-complete-list '("stardict-WordNet"
                                            "stardict-Webster"
                                            "stardict-eng_eng_main"))

Frequently asked question

Why not dictd?

The primary advantage of sdcv is its direct compatibility with the StarDict format. Over the years, the StarDict ecosystem has accumulated a massive, easily accessible repository of freely distributed dictionaries (e.g, huzheng), including highly specialized, technical, and bilingual databases. Using StarDict dictionaries is easier and offers a richer selection of reference materials compared to finding or manually converting formats to support a native dictd setup.

How can dictionary entries be folded and unfolded?

The quick-sdcv mode enables outline-minor-mode by default, allowing sections corresponding to individual dictionaries to be folded.

To automatically collapse all dictionary entries upon search initialization, enable the following variable:

(setq quick-sdcv-fold-on-search t)

Since quick-sdcv inherits the standard outline keybindings, you should be able to toggle the visibility of a single dictionary section by placing your cursor on the header line and pressing TAB (which calls outline-toggle-children). If TAB is not working as expected, it is possible that another package in your configuration is shadowing that binding in the sdcv-mode buffer.

While the built-in outline-minor-mode functions can be used to open and close these folds, installing kirigami.el is highly recommended. It enhances the folding experience by providing a more robust and unified interface for folding text.

How to customize the buffer display?

By default, Emacs typically opens the *sdcv* results in a standard split window, occupying half of the frame. The placement and behavior of this buffer can be precisely controlled by customizing the display-buffer-alist variable.

Below are two common configurations to add to the Emacs initialization file:

Option 1: Display at the bottom with a fixed height

To create a less intrusive interface, Emacs can be configured to display the dictionary buffer at the bottom of the frame while maintaining the current window arrangement:

(add-to-list 'display-buffer-alist
             '("\\*sdcv"
               (display-buffer-reuse-window display-buffer-at-bottom)
               (window-height . 0.33)))

Option 2: Replace the current window entirely

Alternatively, to have the dictionary results fully replace the active window rather than creating a split, the following configuration applies:

(add-to-list 'display-buffer-alist '("\\*sdcv"
                                     (display-buffer-same-window)))

How to make links appear as links in an sdcv buffer?

To ensure that links appear as clickable links in the SDCV buffer while using quick-sdcv, add the following hook:

(add-hook 'quick-sdcv-mode-hook #'goto-address-mode)

Evil mode: How to configure the default K key to search for words using quick-sdcv?

In Evil-mode, the K key in normal mode typically triggers a help function. While viewing a word’s definition in a quick-sdcv buffer, pressing K in normal mode jumps to the definition of the word at point.

This behavior can be configured in other modes, allowing, for instance, the definition of a word to be displayed by pressing K while editing a Markdown or Org file.

For example, to configure K to search for a word using quick-sdcv when editing Markdown or Org files, use the following customization:

(dolist (mode-hook '(markdown-mode-hook org-mode-hook))
  (add-hook mode-hook
            (lambda ()
              (setq-local evil-lookup-func #'quick-sdcv-search-at-point))))

What is the difference between sdcv and quick-sdcv Emacs packages?

The quick-sdcv Emacs package is a fork of sdcv.el version 3.4, which is available on MELPA. The primary differences between the two packages are as follows:

Less dependencies: Quick-sdcv does not require any external dependencies; sdcv, on the other hand, installs popup, pos-tip, and showtip.
Customize the buffer name:: New variables to customize whether the word is included in the buffer name, as well as the prefix, separator, and suffix of the buffer name (quick-sdcv-unique-buffers, quick-sdcv-buffer-name-prefix, quick-sdcv-buffer-name-separator, and quick-sdcv-buffer-name-suffix). When the buffer is dedicated to a specific word, refresh it only when the buffer is created.
Improved Outline Minor Mode: The quick-sdcv package fixes the outline minor mode for dictionary folding, enabling users to collapse all definitions for quicker navigation through dictionaries.
Default Language Settings: Various issues have been addressed, including changing the default language setting from Chinese (zh) to nil, providing a more neutral starting point.
Buffer Customization: The quick-sdcv package employs display-buffer, allowing users to customize the display of the sdcv buffer and control its placement through display-buffer-alist.
Removal of bugs and Warnings: All Emacs warnings have been eliminated and bugs fixed. (e.g., when sdcv-search-at-point cannot locate the word under the cursor)
Code Simplification: The code has been simplified by removing unused variables and omitting features like posframe, text-to-speech using the ‘say’ command, the quick-sdcv-env-lang variable, and functions such as (quick-sdcv-scroll-up-one-line, quick-sdcv-scroll-down-one-line, quick-sdcv-next-line and quick-sdcv-prev-line) which are similar Emacs features. This simplification makes quick-sdcv easier to understand, maintain, and use by focusing solely on dictionary lookup functionality. Features like posframe and text-to-speech, which are not essential to core usage, are better suited as separate packages.
Keybindings removal: The default keybindings have been removed from quick-sdcv-mode to prevent conflicts with other modes and keeps the mode lightweight and adaptable for users’ preferences.
New options: quick-sdcv-fold-on-search, quick-sdcv-ellipsis, quick-sdcv-hist-size, quick-sdcv-exact-search, quick-sdcv-buffer-name-prefix, quick-sdcv-buffer-name-separator, quick-sdcv-buffer-name-suffix, quick-sdcv-verbose.
Various improvements: Unset the SDCV_PAGER environment variable, Ensure the buffer and the SDCV output are in UTF-8, Enhance dictionary representation with UTF-8 characters, Implement error handling for cases when the sdcv program is not found.

Community contribution: How I use quick-sdcv to get the Oxford English Dictionary entirely offline

Mingey, a quick-sdcv user, shared a workflow demonstrating how to integrate the massive Oxford English Dictionary (OED) directly into Emacs:

How I use quick-sdcv to get the Oxford English Dictionary (OED) in my Emacs

His workflow stack:

quick-sdcv: For instantaneous, offline dictionary queries. Mingey configured it to act like a native Emacs help buffer, allowing for ‘Do What I Mean’ (DWIM) searches that automatically look up the word under the cursor, display results in a collapsible outline, and cleanly restore the previous window layout when dismissed.
nov.el: For a in-editor EPUB reading experience. Binding a custom shortcut (K) directly to the dictionary tool within the reader creates an ergonomic workflow where the user can look up obscure words without ever breaking focus or leaving the book.
olivetti-mode: For distraction-free visual centering of the dense dictionary output.

Comments from users

ecraven on GitHub: Thank you very much for this mode, it is proving very helpful!
mingey on GitHub: “I don’t know if this is the appropriate place, but I wanted to thank you for writing this mode — I’ve been using Emacs about a year now, and it’s still constantly surprising me with its depth, and the richness of the added value the community brings. This package is a perfect example; I do a lot of reading in Emacs now, and with minimal configuration, I can be reading an epub and, with a keystroke, instantly get the OED article for a word I’m curious about…it’s one of those Emacs things that feels miraculous. I’m so grateful to you for taking the time to write the mode and for sharing it so generously; I hope (and expect) I’ll be using it with pleasure for years to come.”

Links

You can download sdcv dictionaries from http://download.huzheng.org/dict.org/
quick-sdcv.el @GitHub
quick-sdcv.el @MELPA
The sdcv command-line interface (prerequisite).

James Cherti

Software Development and Linux Infrastructure

Tag Archives: dictionary

quick-sdcv.el, a package that enables Emacs to function as an offline dictionary using sdcv