branch: elpa-admin
commit 3afe3ac6df40e934cb818c887f3f3dce625ace6f
Author: Teemu Likonen <tliko...@iki.fi>
Commit: Teemu Likonen <tliko...@iki.fi>
Use org-mode markup in README and rename it to README.org
---
README | 347 -----------------------------------------------------------------
1 file changed, 347 deletions(-)
diff --git a/README b/README
deleted file mode 100644
index 9ca3484..0000000
--- a/README
+++ /dev/null
@@ -1,347 +0,0 @@
-Wcheck mode - a general interface for text checkers
-===================================================
-
-
-Contents
---------
-
- 1 Introduction
- 2 Features
- 3 How does it compare to other spell-checkers?
- 4 Install
- 5 Configuration and basic usage
- 6 Examples
- 7 The source code repository
- 8 Copyright and license
-
-
-1 Introduction
----------------
-
-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 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 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.
-
-
-2 Features
------------
-
-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. 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.
-
-
-3 How does it compare to other spell-checkers?
------------------------------------------------
-
-The open design makes Wcheck mode (internally) quite different from
-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
-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.
-
-
-4 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):
-
- (autoload 'wcheck-mode "wcheck-mode"
- "Toggle wcheck-mode." t)
- (autoload 'wcheck-change-language "wcheck-mode"
- "Switch wcheck-mode languages." 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)
-
-
-5 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-actions)
- (global-set-key (kbd "C-c n") 'wcheck-jump-forward)
- (global-set-key (kbd "C-c p") 'wcheck-jump-backward)
-
-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.
-
-A note for Emacs Lisp programmers: Emacs Lisp function
-`wcheck-marked-text-at' returns information about marked text at a
-buffer position. Programmers can use it to perform any kind of actions
-for marked text. Function `wcheck-query-language-data' can be used for
-querying effective configuration data for any language.
-
-
-6 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 work 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 ((case-fold-search t)
- 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.
-
-
-7 The source code repository
------------------------------
-
-<https://github.com/tlikonen/wcheck-mode>
-
-The branch named "master" is the release branch and it should always be
-safe to use. New features and experimental code are developed in other
-branches and possibly merged to "master" when they are ready.
-
-
-8 Copyright and license
--------------------------
-
-Copyright (C) 2009-2011 Teemu Likonen <tliko...@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:
