[elpa] elpa-admin 14ac0ef 040/357: Merge branch 'action'

[Stefan Monnier]

branch: elpa-admin
commit 14ac0efc7384817f77e2b6ef609f39cca66046f5
Merge: ae7a3df b25e1bf
Author: Teemu Likonen <tlikonen@iki.fi>
Commit: Teemu Likonen <tlikonen@iki.fi>

    Merge branch 'action'
    
    * action:
      The "args" option can no longer be a string
      Rephrase documentation and comments
      README: Move copyright and license text to the end
      Use plural "actions" with the install instruction's autoload
      Copy examples from wcheck-language-data doc to README
      Rephrase some parts of README
      Add \< and \> to regexps in "email" language example
      Rephrase grouping construct \(\) description in doc string
      Clarify the use of regexp-start, -body and -end
      Improve wcheck-language-data doc
      Fix a typo in wcheck-language-data doc string
      Clearer reference to the license text
      Escape \\< with \\=\\< in wcheck-language-data doc string
      Fix type in doc: "wcheck-parse-" "wcheck-parser-"
      Correction in wcheck-language-data doc: "variable" -> "value"
      Add README file
      New feature: call custom functions from suggestion menu
    
    Conflicts:
        README
---
 README | 379 +++++++++++++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 264 insertions(+), 115 deletions(-)

diff --git a/README b/README
index e8c5267..7f5d13d 100644
--- a/README
+++ b/README
@@ -1,55 +1,70 @@
-= Wcheck mode =
+Wcheck mode
+===========
 
 
-== Introduction ==
+Introduction
+------------
 
-Wcheck mode is a general-purpose text-checker interface for Emacs. It's
-a minor mode for on-the-fly (spell-)checking and marking words or other
-text elements in Emacs buffers.
+Wcheck mode is a general-purpose text-checker interface for Emacs text
+editor. Wcheck mode a minor mode which provides an on-the-fly text
+checker. It checks the visible text area, as you type, and possibly
+highlights some parts of it. What is checked and how are all
+configurable.
 
 Wcheck mode can use external programs or Emacs Lisp functions for
 checking text. For example, Wcheck mode can be used with spell-checker
-programs such as Enchant, Ispell and Hunspell, but actually any tool
+programs such as Ispell, Enchant and Hunspell, but actually any tool
 that can receive text from standard input stream and send text to
-standard output can be used. Wcheck sends parts of buffer's content to
-an external program or an Emacs Lisp function and, based on their
+standard output can be used. Wcheck mode sends parts of buffer's content
+to an external program or an Emacs Lisp function and, based on their
 output, decides if some parts of text should be marked in the buffer.
 
 
-== Features ==
+Features
+--------
 
-In terms of spelling checker and user interface Wcheck mode is an
-on-the-fly checker which can also offer spelling suggestions
-(corrections) when asked. In Wcheck mode different configuration units
-are called languages. They don't have to be human languages, though.
-Language is just a configuration unit for certain kind of text checking
-purpose.
+In Wcheck mode's configuration different configuration units are called
+"languages". In terms of a spelling checker it is natural to think of
+them as different human languages. Wcheck mode is not limited to that,
+though. Language is just a configuration unit for certain kind of text
+checking purpose.
 
 Each language can use its own checker engine (external program or a
 function), command-line arguments and other settings, such as the
 regular expressions and syntax table that are used to match words (or
-other text elements) in Emacs buffer. The on-the-fly checker can use
-different program than the spelling correction feature. User can choose
-which "face" is used to mark text elements in buffer. All the settings
-are language-specific and user is free to interpret the semantics of
-text analyzing: it's left open what marked text elements in the buffer
-actually mean. When using Wcheck mode as a spelling checker we usually
-think of marked words as misspellings.
-
-User can create language and major mode specific settings defining which
-"faces" to read or skip in buffers. A typical use for this feature is to
-spell-check only those areas in buffer which are written in human
-language. For example, in email messages usually the message body and
-Subject header are important enough to spell-check. In programming modes
-user could spell-check only documentation strings and comments (or the
-opposite if you want to use Wcheck mode to check keywords and syntax of
-the programming language itself).
-
-
-== How does it compare to other spell-checkers? ==
+other text elements) in Emacs buffer. User can choose which "face" is
+used to mark text elements in buffer.
+
+User can create language-specific and major mode specific settings
+defining which "faces" to read or skip in buffers. A typical use for
+this feature is to spell-check only those areas in buffer which are
+written in the target language. For example, in email messages usually
+the message body and Subject header are important enough to spell-check.
+In programming modes user could spell-check only documentation strings
+and comments (or the opposite if you want to use Wcheck mode to check
+keywords and syntax of the programming language itself).
+
+Wcheck mode can also be configured to offer any kind of actions for
+marked text. Actions are presented to user through a menu which is
+activated either by (1) clicking the right mouse button on a marked text
+or (2) executing interactive command `wcheck-actions' while the cursor
+(the point) is on a marked text.
+
+If you use Wcheck mode as a spelling checker then it's natural to
+configure an action menu that offers spelling suggestions for the
+misspelled word. The action menu could also have an option to add the
+marked word to spell-checker's dictionary, so that the word is
+recognized in the future. That's only one application for Wcheck mode,
+though. Wcheck mode can be configured to find almost any kind of text
+elements from buffer, mark them, and offer any kind of actions for
+marked text.
+
+
+How does it compare to other spell-checkers?
+--------------------------------------------
 
 The open design makes Wcheck mode (internally) quite different from
-spell-checkers like [[FlySpell]] and [[SpeckMode]]. They are specific
+spell-checkers like Flyspell mode and Speck mode. They are specific
 tools for spell-checking through Ispell or compatible program and are
 therefore very much tied to Ispell's features and command-line
 interface. This can be useful if you want to use Ispell or fully
@@ -59,7 +74,7 @@ be other kind of text-checking needs.
 
 The motivation behind Wcheck mode is to offer more general-purpose and
 configurable interface for text checking. It can be configured to work
-with almost anything: user's custom shell, awk or perl scripts, Lisp
+with almost anything: user's custom shell, Awk or Perl scripts, Lisp
 functions or other checkers and text filters. Even if you only need a
 spelling checker for human languages Wcheck mode can be a good choice.
 It has more configuration possibilities than other spell-checkers and
@@ -67,7 +82,8 @@ the on-the-fly checker performs very well. It's a true 
real-time
 checker.
 
 
-== Install and configure ==
+Install
+-------
 
 Put wcheck-mode.el file to some directory in your Emacs's `load-path'
 and add the following lines to Emacs's initialization file (~/.emacs):
@@ -76,93 +92,226 @@ and add the following lines to Emacs's initialization file 
(~/.emacs):
       "Toggle wcheck-mode." t)
     (autoload 'wcheck-change-language "wcheck-mode"
       "Switch wcheck-mode languages." t)
-    (autoload 'wcheck-spelling-suggestions "wcheck-mode"
-      "Spelling suggestions." t)
+    (autoload 'wcheck-actions "wcheck-mode"
+      "Open actions menu." t)
     (autoload 'wcheck-jump-forward "wcheck-mode"
       "Move point forward to next marked text area." t)
     (autoload 'wcheck-jump-backward "wcheck-mode"
       "Move point backward to previous marked text area." t)
 
-See the documentation of variable `wcheck-language-data' for information
-on how to configure Wcheck mode. For easy configuration you can use the
-options in customize group named "wcheck" (##M-x customize-group RET
-wcheck RET##). Interactive command `wcheck-mode' toggles the
-text-checker in the current buffer. Command `wcheck-change-language' is
-used to switch languages and command `wcheck-spelling-suggestions' (or
-right mouse button) gives spelling suggestion for marked text (if the
-suggestion program is properly configured). Commands
-`wcheck-jump-forward' and `wcheck-jump-backward' jump to next or
-previous marked text area.
-
-It might be convenient if Wcheck commands are bound to some easily
+
+Configuration and basic usage
+-----------------------------
+
+The internal documentation of variable `wcheck-language-data' has a
+complete description on how to configure Wcheck mode language data. For
+easy configuration you can use the options in the customize group named
+"wcheck" (M-x customize-group RET wcheck RET).
+
+It might be convenient to bind Wcheck mode commands to some easily
 accessible keys, for example:
 
     (global-set-key (kbd "C-c s") 'wcheck-mode)
     (global-set-key (kbd "C-c l") 'wcheck-change-language)
-    (global-set-key (kbd "C-c c") 'wcheck-spelling-suggestions)
+    (global-set-key (kbd "C-c c") 'wcheck-actions)
     (global-set-key (kbd "C-c n") 'wcheck-jump-forward)
     (global-set-key (kbd "C-c p") 'wcheck-jump-backward)
 
-Below is an example configuration for spell-checking languages Finnish
-(using Enchant) and British English (using Ispell). The default language
-will be "Finnish". There are also two non-human languages: "Trailing
-whitespace" is a checker which highlights trailing whitespace characters
-in lines and "Highlight FIXMEs" highlights FIXME words if they appear in
-comments in `emacs-lisp-mode' or `c-mode' (or anywhere in other modes).
-The example also configures some global defaults for all languages. For
-example, text-checkers will read only certain buffer areas (faces) in
-`emacs-lisp-mode', `c-mode' and `message-mode'.
-
-    (setq-default
-
-     wcheck-language "Finnish"
-
-     wcheck-language-data
-     '(("Finnish"
-        (program . "/usr/bin/enchant")
-        (args  "-l" "-d" "fi")
-        (syntax . my-finnish-syntax-table)
-        (suggestion-program . "/usr/bin/enchant")
-        (suggestion-args "-a" "-d" "fi")
-        (suggestion-parser . wcheck-parser-ispell-suggestions))
-       ("British English"
-        (program . "/usr/bin/ispell")
-        (args "-l" "-d" "british")
-        (suggestion-program . "/usr/bin/ispell")
-        (suggestion-args "-a" "-d" "british")
-        (suggestion-parser . wcheck-parser-ispell-suggestions))
-       ("Trailing whitespace"
-        (program . identity)
-        (suggestion-program . (lambda (string) (list "")))
-        (face . highlight)
-        (regexp-start . "")
-        (regexp-body . "[ \t]+")
-        (regexp-end . "$")
-        (regexp-discard . "")
-        (read-or-skip-faces
-         (nil)))
-       ("Highlight FIXMEs"
-        (program . (lambda (strings)
-                     (when (member "FIXME" strings)
-                       (list "FIXME"))))
-        (face . highlight)
-        (read-or-skip-faces
-         ((emacs-lisp-mode c-mode) read font-lock-comment-face)
-         (nil))))
-
-     wcheck-language-data-defaults
-     '((parser . wcheck-parser-lines)
-       (suggestion-parser . wcheck-parser-ispell-suggestions)
-       (connection . nil)
-       (face . wcheck-default-face)
-       (syntax . text-mode-syntax-table)
-       (regexp-start . "\\<'*")
-       (regexp-body . "\\w+?")
-       (regexp-end . "'*\\>")
-       (regexp-discard . "\\`'+\\'")
-       (case-fold . nil)
-       (read-or-skip-faces
-        ((emacs-lisp-mode c-mode) read
-         font-lock-comment-face font-lock-doc-face)
-        (message-mode read
-         nil message-header-subject message-cited-text))))
+Interactive command `wcheck-mode' toggles the text-checker for the
+current buffer. Command `wcheck-change-language' is used to switch
+languages and command `wcheck-actions' (or the right mouse button) opens
+an actions menu for marked text. Commands `wcheck-jump-forward' and
+`wcheck-jump-backward' jump to next or previous marked text area.
+
+
+Examples
+--------
+
+Here are some examples on how you can fill the `wcheck-language-data'
+variable. The value is a list of language configurations:
+
+    (setq wcheck-language-data
+          '(("language"
+             ...)
+            ("another language"
+             ...)))
+
+Perhaps the most common use for `wcheck-mode' is to spell-check human
+languages with Ispell (or compatible) spelling checker. Let's start with
+examples on how to configure that.
+
+The following settings configure two languages which are named "British
+English" and "Finnish". The former language uses Ispell program as the
+spell-checker engine. The latter uses Enchant which has an
+Ispell-compatible command-line interface. Both languages use
+`wcheck-mode's actions feature to offer spelling suggestions for
+misspelled words. Since both spelling checkers print spelling
+suggestions in the Ispell format we use built-in function
+`wcheck-parser-ispell-suggestions' to parse the output and populate the
+actions (spelling suggestions) menu for user.
+
+    ("British English"
+     (program . "/usr/bin/ispell")
+     (args "-l" "-d" "british")
+     (action-program . "/usr/bin/ispell")
+     (action-args "-a" "-d" "british")
+     (action-parser . wcheck-parser-ispell-suggestions))
+
+    ("Finnish"
+     (program . "/usr/bin/enchant")
+     (args  "-l" "-d" "fi")
+     (syntax . my-finnish-syntax-table)
+     (action-program . "/usr/bin/enchant")
+     (action-args "-a" "-d" "fi")
+     (action-parser . wcheck-parser-ispell-suggestions))
+
+The "Finnish" language above used a special syntax table called
+my-finnish-syntax-table. It could be defined like this:
+
+    (defvar my-finnish-syntax-table
+      (copy-syntax-table text-mode-syntax-table))
+
+    (modify-syntax-entry ?- "w" my-finnish-syntax-table)
+
+It copies `text-mode-syntax-table' (which `wcheck-mode' uses by default)
+and sets the syntactic meaning of the ASCII hyphen character (-) to a
+word character ("w"). `wcheck-mode' and its regular expression search
+will use that syntax table when scanning buffers' content in that
+language.
+
+Below is an example on how to add an "Add to dictionary" feature to the
+actions menu, among spelling suggestions. First, there's the language
+configuration. The example is similar to the "British English"
+configuration above except that `action-parser' function is a bit more
+complicated. It's a lambda expression which calls
+`wcheck-parser-ispell-suggestions' and then adds "Add to dictionary"
+option in the front of the spelling suggestions list. Choosing that
+option from the actions menu will call function add-word-to-dictionary
+(which doesn't exist yet).
+
+    ("British English"
+     (program . "/usr/bin/ispell")
+     (args "-l" "-d" "british")
+     (action-program . "/usr/bin/ispell")
+     (action-args "-a" "-d" "british")
+     (action-parser . (lambda (marked-text)
+                        (cons (cons "[Add to dictionary]"
+                                    'add-word-to-dictionary)
+                              (wcheck-parser-ispell-suggestions)))))
+
+Now we need to define the function add-word-to-dictionary. Below is an
+incomplete example. To make it complete you'll have to find out how and
+where your spelling checker stores user dictionaries. Then write code
+that adds a new string to the dictionary.
+
+    (defun add-word-to-dictionary (marked-text)
+      ;; MARKED-TEXT is a vector returned by
+      ;; `wcheck-marked-text-at' function.
+
+      (let ((word (aref marked-text 0))
+            (language (aref marked-text 4)))
+
+        ;; Do the actual job here. That is, write code that adds
+        ;; the string stored in variable "word" to the
+        ;; appropriate dictionary.
+
+        (message "Added word \"%s\" to the %s dictionary"
+                 word language)))
+
+Spell-checking human languages is not the only application for
+`wcheck-mode'. The following configuration adds language called
+"Trailing whitespace" which finds and marks all trailing whitespace
+characters (spaces and tabs) on buffer's lines. It uses regular
+expressions to match the whitespace. The checker program is the Emacs
+Lisp function `identity' which just returns its argument unchanged. The
+`action-program' feature is used to build an action menu with just one
+option: remove the whitespace. It replaces the original whitespace
+string with empty string.
+
+    ("Trailing whitespace"
+     (program . identity)
+     (action-program . (lambda (marked-text)
+                         (list (cons "Remove whitespace" ""))))
+     (face . highlight)
+     (regexp-start . "")
+     (regexp-body . "[ \t]+")
+     (regexp-end . "$")
+     (regexp-discard . "")
+     (read-or-skip-faces
+      (nil)))
+
+Sometimes it's useful to highlight only a small number of keywords in
+buffer. The following example adds a language called "Highlight FIXMEs"
+to mark "FIXME" words. FIXME is some programmers' convention to put
+reminders in source code that some parts are not complete yet and will
+be fixed or completed later. In source code files such keywords are
+written in program's comments only, not in the actual code, so we use
+`read-or-skip-faces' feature to scan only the comments. This example
+configures it for `emacs-lisp-mode' and `c-mode'. In all other major
+modes FIXMEs are marked everywhere.
+
+     ("Highlight FIXMEs"
+      (program . (lambda (strings)
+                   (when (member "FIXME" strings)
+                     (list "FIXME"))))
+      (face . highlight)
+      (read-or-skip-faces
+       ((emacs-lisp-mode c-mode) read font-lock-comment-face)
+       (nil)))
+
+The following example adds a language "email" for highlighting email
+addresses from buffer and creating an action menu which has option to
+start composing mail to that address. Here's the language configuration:
+
+    ("email"
+     (program . email-address-detect)
+     (face . highlight)
+     (regexp-start . "\\<")
+     (regexp-body . "\\S-+@\\S-+")
+     (regexp-end . "\\>")
+     (action-program . email-action-menu)
+     (read-or-skip-faces
+      (nil)))
+
+Then the needed functions:
+
+    (defun email-address-detect (strings)
+      (let (addresses)
+        (dolist (string strings addresses)
+          (when (string-match "\\<[a-z.-]+\\>@\\<[a-z.-]+\\>" string)
+            (push (match-string-no-properties 0 string) addresses)))))
+
+    (defun email-action-menu (marked-text)
+      (list (cons (concat "Mail to <" (aref marked-text 0) ">")
+                  (lambda (marked-text)
+                    (compose-mail (aref marked-text 0))))))
+
+Note that detecting all valid email addresses is difficult and a much
+more advanced parser is needed for that. Feel free to replace the
+detection function with a better one.
+
+
+Copyright and license
+---------------------
+
+Copyright (C) 2009-2011 Teemu Likonen <tlikonen@iki.fi>
+
+This program is free software: you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation, either version 3 of the License, or (at your
+option) any later version.
+
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+Public License for more details.
+
+The license text: <http://www.gnu.org/licenses/gpl-3.0.html>
+
+
+
+# Local Variables:
+# mode: text
+# mode: auto-fill
+# fill-column: 72
+# End: