branch: elpa-admin
commit 3c6d0e13502ec77efd8c4c81ba7df45a337fdf45
Author: Teemu Likonen <tliko...@iki.fi>
Commit: Teemu Likonen <tliko...@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:
