code.delx.au - gnu-emacs-elpa/blob - packages/wcheck-mode/README.md

   1 Wcheck Mode
   2 ===========
   3
   4 **General-purpose text-checker interface for Emacs text editor**
   5
   6
   7 Introduction
   8 ------------
   9
  10 Wcheck mode is a general-purpose text-checker interface for [Emacs][]
  11 text editor. Wcheck mode is a minor mode which provides an on-the-fly
  12 text checker. It checks the visible text area, as you type, and possibly
  13 highlights some parts of it. What is checked and how are all
  14 configurable.
  15
  16 Wcheck mode can use external programs or Emacs Lisp functions for
  17 checking text. For example, Wcheck mode can be used with spell-checker
  18 programs such as Ispell, Enchant and Hunspell, but actually any tool
  19 that can receive text from standard input stream and send text to
  20 standard output can be used. Wcheck mode sends parts of buffer's content
  21 to an external program or an Emacs Lisp function and, relying on their
  22 output, decides if some parts of text should be marked in the buffer.
  23
  24 [Emacs]: http://www.gnu.org/software/emacs/
  25
  26
  27 Features
  28 --------
  29
  30 In Wcheck mode's configuration different configuration units are called
  31 _languages_. In terms of a spelling checker it is natural to think of
  32 them as different human languages. Wcheck mode is not limited to that,
  33 though. Language is just a configuration unit for a specific text
  34 checking purpose.
  35
  36 Each language can use its own checker engine (external program or a
  37 function), command-line arguments and other settings, such as the
  38 regular expressions and syntax table that are used to match words (or
  39 other text elements) in Emacs buffer. User can choose which _face_ is
  40 used to mark text elements in buffer.
  41
  42 User can create language-specific and major mode specific settings
  43 defining which _faces_ to read or skip in buffers. A typical use for
  44 this feature is to spell-check only those areas in buffer which are
  45 written in the target language. For example, in email messages usually
  46 the message body and Subject header are important enough to spell-check.
  47 In programming modes user could spell-check only documentation strings
  48 and comments (or the opposite if you want to use Wcheck mode to check
  49 keywords and syntax of the programming language itself).
  50
  51 Wcheck mode can also be configured to offer any kind of actions for
  52 marked text. Actions are presented to user through a menu which is
  53 activated either by (1) clicking the right mouse button on a marked text
  54 or (2) executing interactive command `wcheck-actions` while the cursor
  55 (the point) is on a marked text.
  56
  57 If you use Wcheck mode as a spelling checker then it's natural to
  58 configure an action menu that offers spelling suggestions for misspelled
  59 words. The action menu could also have an option to add marked word to
  60 spell-checker's dictionary, so that the word is recognized in the
  61 future. That's only one application for Wcheck mode, though. Wcheck mode
  62 can be configured to find almost any kind of text elements from buffer,
  63 mark them, and offer any kind of actions for marked text.
  64
  65
  66 How does it compare to other spell-checkers?
  67 --------------------------------------------
  68
  69 The open design makes Wcheck mode (internally) quite different from
  70 spell-checkers like [Flyspell][] mode and [Speck][] mode. They are
  71 specific tools for spell-checking through Ispell or compatible program
  72 and are therefore very much tied to Ispell's features and command-line
  73 interface. This can be useful if you want to use Ispell or fully
  74 compatible program for spell-checking natural languages. However, not
  75 all human languages can be supported through Ispell and there can also
  76 be other kind of text-checking needs.
  77
  78 The motivation behind Wcheck mode is to offer more general-purpose and
  79 configurable interface for text checking. It can be configured to work
  80 with almost anything: user's custom shell, Awk or Perl scripts, Lisp
  81 functions or other checkers and text filters. Even if you only need a
  82 spelling checker for human languages Wcheck mode can be a good choice.
  83 It has more configuration possibilities than other spell-checkers and
  84 the on-the-fly checker performs very well. It's a true real-time
  85 checker.
  86
  87 [Flyspell]: http://www.emacswiki.org/emacs/FlySpell
  88 [Speck]:    http://www.emacswiki.org/SpeckMode
  89
  90
  91 Install
  92 -------
  93
  94 You can install Wcheck mode through [Melpa][] package archive.
  95 Alternatively you can put `wcheck-mode.el` file to some directory in
  96 your Emacs's `load-path` and add the following lines to Emacs's
  97 initialization file (`~/.emacs` or `~/.emacs.d/init.el`):
  98
  99     (autoload 'wcheck-mode "wcheck-mode"
 100       "Toggle wcheck-mode." t)
 101     (autoload 'wcheck-change-language "wcheck-mode"
 102       "Switch wcheck-mode languages." t)
 103     (autoload 'wcheck-actions "wcheck-mode"
 104       "Open actions menu." t)
 105     (autoload 'wcheck-jump-forward "wcheck-mode"
 106       "Move point forward to next marked text area." t)
 107     (autoload 'wcheck-jump-backward "wcheck-mode"
 108       "Move point backward to previous marked text area." t)
 109
 110 [Melpa]: https://melpa.org/
 111
 112
 113 Configuration and basic usage
 114 -----------------------------
 115
 116 The internal documentation of variable `wcheck-language-data` has a
 117 complete description on how to configure Wcheck mode language data. For
 118 easy configuration you can use the options in the customize group named
 119 _wcheck_ (`M-x customize-group RET wcheck RET`).
 120
 121 It might be convenient to bind Wcheck mode commands to some easily
 122 accessible keys, for example:
 123
 124     (global-set-key (kbd "C-c s") 'wcheck-mode)
 125     (global-set-key (kbd "C-c l") 'wcheck-change-language)
 126     (global-set-key (kbd "C-c c") 'wcheck-actions)
 127     (global-set-key (kbd "C-c n") 'wcheck-jump-forward)
 128     (global-set-key (kbd "C-c p") 'wcheck-jump-backward)
 129
 130 Interactive command `wcheck-mode` toggles the text-checker minor mode
 131 for the current buffer. Command `wcheck-change-language` is used to
 132 switch languages and command `wcheck-actions` (or the right mouse
 133 button) opens an actions menu for marked text. Commands
 134 `wcheck-jump-forward` and `wcheck-jump-backward` jump to next or
 135 previous marked text area.
 136
 137 A note for Emacs Lisp programmers: Emacs Lisp function
 138 `wcheck-marked-text-at` returns information about marked text at a
 139 buffer position. Programmers can use it to perform any kind of actions
 140 for marked text. Function `wcheck-query-language-data` can be used for
 141 querying effective configuration data for any language.
 142
 143
 144 Examples
 145 --------
 146
 147 Here are some examples on how you can fill the `wcheck-language-data`
 148 variable. The value is a list of language configurations:
 149
 150     (setq wcheck-language-data
 151           '(("language"
 152              ...)
 153             ("another language"
 154              ...)))
 155
 156 Perhaps the most common use for Wcheck mode is to spell-check human
 157 languages with Ispell (or compatible) spelling checker. Let's start with
 158 examples on how to configure that.
 159
 160 The following settings configure two languages which are named "British
 161 English" and "Finnish". The former language uses Ispell program as the
 162 spell-checker engine. The latter uses Enchant which has an
 163 Ispell-compatible command-line interface. Both languages use Wcheck
 164 mode's actions feature to offer spelling suggestions for misspelled
 165 words. Since both spelling checkers print spelling suggestions in the
 166 Ispell format we use built-in function
 167 `wcheck-parser-ispell-suggestions` to parse the output and populate the
 168 actions (spelling suggestions) menu for user.
 169
 170     ("British English"
 171      (program . "/usr/bin/ispell")
 172      (args "-l" "-d" "british")
 173      (action-program . "/usr/bin/ispell")
 174      (action-args "-a" "-d" "british")
 175      (action-parser . wcheck-parser-ispell-suggestions))
 176
 177     ("Finnish"
 178      (program . "/usr/bin/enchant")
 179      (args "-l" "-d" "fi")
 180      (syntax . my-finnish-syntax-table)
 181      (action-program . "/usr/bin/enchant")
 182      (action-args "-a" "-d" "fi")
 183      (action-parser . wcheck-parser-ispell-suggestions))
 184
 185 The "Finnish" language above used a special syntax table called
 186 `my-finnish-syntax-table`. It could be defined like this:
 187
 188     (defvar my-finnish-syntax-table
 189       (copy-syntax-table text-mode-syntax-table))
 190
 191     (modify-syntax-entry ?- "w" my-finnish-syntax-table)
 192
 193 It copies `text-mode-syntax-table` (which Wcheck mode uses by default)
 194 and sets the syntactic meaning of the ASCII hyphen character (-) to a
 195 word character ("w"). Wcheck mode and its regular expression search will
 196 use that syntax table when scanning buffers' content in that language.
 197
 198 Below is an example on how to add an "Add to dictionary" feature to the
 199 actions menu, among spelling suggestions. First, there's the language
 200 configuration. The example below is similar to the "British English"
 201 configuration above except that Enchant spell-checker is used and
 202 `action-parser` is a custom function (which will be defined later).
 203
 204     ("British English"
 205      (program . "/usr/bin/enchant")
 206      (args "-l" "-d" "en_GB")
 207      (action-program . "/usr/bin/enchant")
 208      (action-args "-a" "-d" "en_GB")
 209      (action-parser . enchant-suggestions-menu))
 210
 211 The action parser is custom function `enchant-suggestions-menu`. It will
 212 call `wcheck-parser-ispell-suggestions` and then add "Add to dictionary"
 213 option in the front of the spelling suggestions list. Choosing that
 214 option from the actions menu will call function
 215 `enchant-add-to-dictionary` (will be defined later).
 216
 217     (defun enchant-suggestions-menu (marked-text)
 218       (cons (cons "[Add to dictionary]" 'enchant-add-to-dictionary)
 219             (wcheck-parser-ispell-suggestions)))
 220
 221 Now we need to define the function `enchant-add-to-dictionary`. Below is
 222 an example that works in GNU/Linux systems with Enchant spell-checker.
 223 With small modifications it should work with other spelling checkers and
 224 operating systems.
 225
 226 For British English language the user dictionary file is
 227 `~/.config/enchant/en_GB.dic`. The language code is extracted
 228 automatically from `wcheck-language-data` variable, so the function
 229 works with any Enchant language. Note that adding a word to a dictionary
 230 file doesn't have effect on the current spell-checking session. The
 231 Enchant program must be restarted.
 232
 233     (defvar enchant-dictionaries-dir "~/.config/enchant")
 234
 235     (defun enchant-add-to-dictionary (marked-text)
 236       (let* ((word (aref marked-text 0))
 237              (language (aref marked-text 4))
 238              (file (let ((code (nth 1 (member "-d" (wcheck-query-language-data
 239                                                     language 'action-args)))))
 240                      (when (stringp code)
 241                        (concat (file-name-as-directory enchant-dictionaries-dir)
 242                                code ".dic")))))
 243
 244         (when (and file (file-writable-p file))
 245           (with-temp-buffer
 246             (insert word) (newline)
 247             (append-to-file (point-min) (point-max) file)
 248             (message "Added word \"%s\" to the %s dictionary"
 249                      word language)))))
 250
 251 Spell-checking human languages is not the only application for Wcheck
 252 mode. The following configuration adds language called "Trailing
 253 whitespace" which finds and marks all trailing whitespace characters
 254 (spaces and tabs) on buffer's lines. It uses regular expressions to
 255 match the whitespace. The checker program is the Emacs Lisp function
 256 `identity` which just returns its argument unchanged. The
 257 `action-program` option and feature is used to build an action menu with
 258 just one option: remove the whitespace. It replaces the original
 259 whitespace string with empty string.
 260
 261     ("Trailing whitespace"
 262      (program . identity)
 263      (action-program . (lambda (marked-text)
 264                          (list (cons "Remove whitespace" ""))))
 265      (face . highlight)
 266      (regexp-start . "")
 267      (regexp-body . "[ \t]+")
 268      (regexp-end . "$")
 269      (regexp-discard . "")
 270      (read-or-skip-faces
 271       (nil)))
 272
 273 Sometimes it's useful to highlight only a small number of keywords in
 274 buffer. The following example adds a language called "Highlight FIXMEs"
 275 which marks only "FIXME" words. FIXME is some programmers' convention to
 276 put reminders in source code that some parts are not complete yet and
 277 will be fixed or completed later. In source code files such keywords are
 278 written in program's comments only, not in the actual code, so we use
 279 `read-or-skip-faces` feature to scan only the comments. This example
 280 configures it for `emacs-lisp-mode` and `c-mode`. In all other major
 281 modes FIXMEs are marked everywhere.
 282
 283     ("Highlight FIXMEs"
 284      (program . (lambda (strings)
 285                   (when (member "FIXME" strings)
 286                     (list "FIXME"))))
 287      (face . highlight)
 288      (read-or-skip-faces
 289       ((emacs-lisp-mode c-mode) read font-lock-comment-face)
 290       (nil)))
 291
 292 The following example adds a language "email" for highlighting email
 293 addresses in buffer and creating an action menu which has option to
 294 start composing mail to that address. Here's the language configuration:
 295
 296     ("email"
 297      (program . email-address-detect)
 298      (face . highlight)
 299      (case-fold . t)
 300      (regexp-start . "\\<")
 301      (regexp-body . "\\S-+@\\S-+")
 302      (regexp-end . "\\>")
 303      (regexp-discard . "")
 304      (action-program . email-action-menu)
 305      (read-or-skip-faces
 306       (nil)))
 307
 308 Then the needed functions:
 309
 310     (defun email-address-detect (strings)
 311       (let (addresses)
 312         (dolist (string strings addresses)
 313           (when (string-match "\\<[a-z.-]+\\>@\\<[a-z.-]+\\>" string)
 314             (push (match-string-no-properties 0 string) addresses)))))
 315
 316     (defun email-action-menu (marked-text)
 317       (list (cons (concat "Mail to <" (aref marked-text 0) ">")
 318                   (lambda (marked-text)
 319                     (compose-mail (aref marked-text 0))))))
 320
 321 Note that detecting all valid email addresses is difficult and a much
 322 more advanced parser is needed for that. Feel free to replace the
 323 detection function with a better one.
 324
 325
 326 The source code repository
 327 --------------------------
 328
 329 GitHub repository URL: <https://github.com/tlikonen/wcheck-mode>
 330
 331 The branch named _master_ is the release branch and it should always be
 332 safe to use. New features and experimental code are developed in other
 333 branches and possibly merged to _master_ when they are ready.
 334
 335
 336 Copyright and license
 337 ---------------------
 338
 339 Copyright (C) 2009-2016 Free Software Foundation, Inc.
 340
 341 This program is free software: you can redistribute it and/or modify it
 342 under the terms of the GNU General Public License as published by the
 343 Free Software Foundation, either version 3 of the License, or (at your
 344 option) any later version.
 345
 346 This program is distributed in the hope that it will be useful, but
 347 WITHOUT ANY WARRANTY; without even the implied warranty of
 348 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 349 Public License for more details.
 350
 351 The license text: <http://www.gnu.org/licenses/gpl-3.0.html>