[elpa] elpa-admin ae7a3df 034/357: Copy Emacs wiki page's content to new README file

[Stefan Monnier]

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

    Copy Emacs wiki page's content to new README file
---
 README | 168 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 168 insertions(+)

diff --git a/README b/README
new file mode 100644
index 0000000..e8c5267
--- /dev/null
+++ b/README
@@ -0,0 +1,168 @@
+= Wcheck mode =
+
+
+== 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 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
+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
+output, decides if some parts of text should be marked in the buffer.
+
+
+== 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.
+
+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? ==
+
+The open design makes Wcheck mode (internally) quite different from
+spell-checkers like [[FlySpell]] and [[SpeckMode]]. 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
+compatible program for spell-checking natural languages. However, not
+all human languages can be supported through Ispell and there can also
+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
+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
+the on-the-fly checker performs very well. It's a true real-time
+checker.
+
+
+== Install and configure ==
+
+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):
+
+    (autoload 'wcheck-mode "wcheck-mode"
+      "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-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
+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 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))))