[elpa] elpa-admin 3c6d0e1 037/357: Copy examples from wcheck-language-data doc to README

[Stefan Monnier]

branch: elpa-admin
commit 3c6d0e13502ec77efd8c4c81ba7df45a337fdf45
Author: Teemu Likonen <tlikonen@iki.fi>
Commit: Teemu Likonen <tlikonen@iki.fi>

    Copy examples from wcheck-language-data doc to README
---
 README | 163 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 163 insertions(+)

diff --git a/README b/README
index a0e9345..1c050e3 100644
--- a/README
+++ b/README
@@ -146,6 +146,169 @@ an actions menu for marked text. Commands 
`wcheck-jump-forward' and
 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.
+
 
 
 # Local Variables: