[elpa] 327/352: Convert README to Markdown markup (and rename: .org -> .md)

[Stefan Monnier]

monnier pushed a commit to branch master
in repository elpa.

commit f75ef7bc67721a25988e61b328cb050989bdf06f
Author: Teemu Likonen <address@hidden>
Date:   Thu Apr 18 10:03:18 2013 +0300

    Convert README to Markdown markup (and rename: .org -> .md)
---
 Makefile                |    7 +-
 README.org => README.md |  332 ++++++++++++++++++++++-------------------------
 2 files changed, 161 insertions(+), 178 deletions(-)

diff --git a/Makefile b/Makefile
index 069d088..0ba30de 100644
--- a/Makefile
+++ b/Makefile
@@ -5,7 +5,7 @@ DESC := General interface for text checkers
 VERSION := $(shell date +%Y.%-m.%-d)
 MAIN := $(BASE).el
 PKG := $(BASE)-pkg.el
-FILES := $(MAIN) $(PKG) COPYING README.org README
+FILES := $(MAIN) $(PKG) COPYING README
 NAME := $(BASE)-$(VERSION)
 
 elpa: $(NAME).tar
@@ -22,9 +22,8 @@ $(PKG):
                "$(BASE)" "$(VERSION)" "$(DESC)" >$@
        @cat $@
 
-README: README.org
-       emacs -Q --batch --file $< --funcall org-export-as-ascii
-       mv -f -- address@hidden $@
+README: README.md
+       cp -f -- $< $@
 
 tag:
        git tag -s $(VERSION) -m 'Version $(VERSION)' HEAD
diff --git a/README.org b/README.md
similarity index 53%
rename from README.org
rename to README.md
index ff7c880..efd7eb7 100644
--- a/README.org
+++ b/README.md
@@ -1,10 +1,11 @@
-#+TITLE: Wcheck Mode
-#+OPTIONS: author:nil email:nil timestamp:nil
-#+LANGUAGE: en
+Wcheck Mode
+===========
 
-General-purpose text-checker interface for Emacs text editor
+**General-purpose text-checker interface for Emacs text editor**
 
-* Introduction
+
+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
@@ -20,10 +21,11 @@ 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 Wcheck mode's configuration different configuration units are called
-/languages/. In terms of a spelling checker it is natural to think of
+_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 a specific text
 checking purpose.
@@ -31,11 +33,11 @@ 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
+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
+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.
@@ -46,7 +48,7 @@ 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
+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
@@ -58,7 +60,8 @@ 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?
+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
@@ -78,67 +81,64 @@ 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
+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=):
+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`):
 
-#+BEGIN_SRC emacs-lisp
-  (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)
-#+END_SRC
+    (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)
 
-* Configuration and basic usage
+Configuration and basic usage
+-----------------------------
 
-The internal documentation of variable =wcheck-language-data= has a
+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=).
+_wcheck_ (`M-x customize-group RET wcheck RET`).
 
 It might be convenient to bind Wcheck mode commands to some easily
 accessible keys, for example:
 
-#+BEGIN_SRC emacs-lisp
-  (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)
-#+END_SRC
-
-Interactive command =wcheck-mode= toggles the text-checker minor mode
-for the current buffer. Command =wcheck-change-language= is used to
-switch languages and command =wcheck-actions= (or the right mouse
+    (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 minor mode
+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
+`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
+`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
+for marked text. Function `wcheck-query-language-data` can be used for
 querying effective configuration data for any language.
 
-* Examples
+Examples
+--------
 
-Here are some examples on how you can fill the =wcheck-language-data=
+Here are some examples on how you can fill the `wcheck-language-data`
 variable. The value is a list of language configurations:
 
-#+BEGIN_SRC emacs-lisp
-  (setq wcheck-language-data
-        '(("language"
-           ...)
-          ("another language"
-           ...)))
-#+END_SRC
+    (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
@@ -151,37 +151,33 @@ 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
+`wcheck-parser-ispell-suggestions` to parse the output and populate the
 actions (spelling suggestions) menu for user.
 
-#+BEGIN_SRC emacs-lisp
-  ("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))
-#+END_SRC
+    ("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:
+`my-finnish-syntax-table`. It could be defined like this:
 
-#+BEGIN_SRC emacs-lisp
-  (defvar my-finnish-syntax-table
-    (copy-syntax-table text-mode-syntax-table))
+    (defvar my-finnish-syntax-table
+      (copy-syntax-table text-mode-syntax-table))
 
-  (modify-syntax-entry ?- "w" my-finnish-syntax-table)
-#+END_SRC
+    (modify-syntax-entry ?- "w" my-finnish-syntax-table)
 
-It copies =text-mode-syntax-table= (which Wcheck mode uses by default)
+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.
@@ -190,82 +186,74 @@ 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 below is similar to the "British English"
 configuration above except that Enchant spell-checker is used and
-=action-parser= is a custom function (which will be defined later).
-
-#+BEGIN_SRC emacs-lisp
-  ("British English"
-   (program . "/usr/bin/enchant")
-   (args "-l" "-d" "en_GB")
-   (action-program . "/usr/bin/enchant")
-   (action-args "-a" "-d" "en_GB")
-   (action-parser . enchant-suggestions-menu))
-#+END_SRC
-
-The action parser is custom function =enchant-suggestions-menu=. It will
-call =wcheck-parser-ispell-suggestions= and then add "Add to dictionary"
+`action-parser` is a custom function (which will be defined later).
+
+    ("British English"
+     (program . "/usr/bin/enchant")
+     (args "-l" "-d" "en_GB")
+     (action-program . "/usr/bin/enchant")
+     (action-args "-a" "-d" "en_GB")
+     (action-parser . enchant-suggestions-menu))
+
+The action parser is custom function `enchant-suggestions-menu`. It will
+call `wcheck-parser-ispell-suggestions` and then add "Add to dictionary"
 option in the front of the spelling suggestions list. Choosing that
 option from the actions menu will call function
-=enchant-add-to-dictionary= (will be defined later).
+`enchant-add-to-dictionary` (will be defined later).
 
-#+BEGIN_SRC emacs-lisp
-  (defun enchant-suggestions-menu (marked-text)
-    (cons (cons "[Add to dictionary]" 'enchant-add-to-dictionary)
-          (wcheck-parser-ispell-suggestions)))
-#+END_SRC
+    (defun enchant-suggestions-menu (marked-text)
+      (cons (cons "[Add to dictionary]" 'enchant-add-to-dictionary)
+            (wcheck-parser-ispell-suggestions)))
 
-Now we need to define the function =enchant-add-to-dictionary=. Below is
+Now we need to define the function `enchant-add-to-dictionary`. Below is
 an example that works in GNU/Linux systems (with Enchant spell-checker).
 For British English language the user dictionary file is
-=~/.config/enchant/en_GB.dic=. Actually the language code is extracted
-automatically from =wcheck-language-data= variable, so the same function
+`~/.config/enchant/en_GB.dic`. Actually the language code is extracted
+automatically from `wcheck-language-data` variable, so the same function
 works with any Enchant language.
 
 (With small modifications it should work with other spelling checkers
 and operating systems.)
 
-#+BEGIN_SRC emacs-lisp
-  (defvar enchant-dictionaries-dir "~/.config/enchant")
-
-  (defun enchant-add-to-dictionary (marked-text)
-    (let* ((word (aref marked-text 0))
-           (language (aref marked-text 4))
-           (file (let ((code (nth 1 (member "-d" (wcheck-query-language-data
-                                                  language 'action-args)))))
-                   (when (stringp code)
-                     (concat (file-name-as-directory enchant-dictionaries-dir)
-                             code ".dic")))))
-
-      (when (and file (file-writable-p file))
-        (with-temp-buffer
-          (insert word) (newline)
-          (append-to-file (point-min) (point-max) file)
-          (message "Added word \"%s\" to the %s dictionary"
-                   word language)))))
-#+END_SRC
+    (defvar enchant-dictionaries-dir "~/.config/enchant")
+
+    (defun enchant-add-to-dictionary (marked-text)
+      (let* ((word (aref marked-text 0))
+             (language (aref marked-text 4))
+             (file (let ((code (nth 1 (member "-d" (wcheck-query-language-data
+                                                    language 'action-args)))))
+                     (when (stringp code)
+                       (concat (file-name-as-directory 
enchant-dictionaries-dir)
+                               code ".dic")))))
+
+        (when (and file (file-writable-p file))
+          (with-temp-buffer
+            (insert word) (newline)
+            (append-to-file (point-min) (point-max) file)
+            (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= option and feature is used to build an action menu with
+`identity` which just returns its argument unchanged. The
+`action-program` option and feature is used to build an action menu with
 just one option: remove the whitespace. It replaces the original
 whitespace string with empty string.
 
-#+BEGIN_SRC emacs-lisp
-  ("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)))
-#+END_SRC
+    ("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"
@@ -273,67 +261,63 @@ which marks only "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
+`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.
 
-#+BEGIN_SRC emacs-lisp
-  ("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)))
-#+END_SRC
+    ("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 in buffer and creating an action menu which has option to
 start composing mail to that address. Here's the language configuration:
 
-#+BEGIN_SRC emacs-lisp
-  ("email"
-   (program . email-address-detect)
-   (face . highlight)
-   (case-fold . t)
-   (regexp-start . "\\<")
-   (regexp-body . "address@hidden")
-   (regexp-end . "\\>")
-   (regexp-discard . "")
-   (action-program . email-action-menu)
-   (read-or-skip-faces
-    (nil)))
-#+END_SRC
+    ("email"
+     (program . email-address-detect)
+     (face . highlight)
+     (case-fold . t)
+     (regexp-start . "\\<")
+     (regexp-body . "address@hidden")
+     (regexp-end . "\\>")
+     (regexp-discard . "")
+     (action-program . email-action-menu)
+     (read-or-skip-faces
+      (nil)))
 
 Then the needed functions:
 
-#+BEGIN_SRC emacs-lisp
-  (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-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))))))
-#+END_SRC
+    (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.
 
-* The source code repository
+The source code repository
+--------------------------
 
-GitHub repository URL: <[[https://github.com/tlikonen/wcheck-mode]]>
+GitHub repository URL: <https://github.com/tlikonen/wcheck-mode>
 
-The branch named /master/ is the release branch and it should always be
+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.
+branches and possibly merged to _master_ when they are ready.
 
-* Copyright and license
+Copyright and license
+---------------------
 
 Copyright (C) 2009-2013 Teemu Likonen <address@hidden>
 
@@ -347,4 +331,4 @@ 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]]>
+The license text: <http://www.gnu.org/licenses/gpl-3.0.html>