branch: externals/relint
commit 5217d9a73a27d953d5eaef6cf5bca9501e7b9a27
Author: Mattias Engdegård
Commit: Mattias Engdegård
Use a plain-text README file instead of README.org
It is much easier to read than a .org file in plain text, and not much
worse than github's htmlised version.
---
README | 251 +
README.org | 216
2 files changed, 251 insertions(+), 216 deletions(-)
diff --git a/README b/README
new file mode 100644
index 000..8621923
--- /dev/null
+++ b/README
@@ -0,0 +1,251 @@
+relint -- Emacs regexp mistake finder
+=
+
+Relint scans elisp files for mistakes in regexps, including deprecated
+syntax and bad practice. It also checks the regexp-like arguments to
+skip-chars-forward, skip-chars-backward, skip-syntax-forward and
+skip-syntax-backward.
+
+* Usage
+
+ Check a single file:
+
+M-x relint-file
+
+ Check all .el files in a directory tree:
+
+M-x relint-directory
+
+ Check current buffer:
+
+M-x relint-current-buffer
+
+ From batch mode:
+
+emacs -batch -l relint.el -f relint-batch FILES-AND-DIRS...
+
+ where directories are scanned recursively.
+ (Options for finding relint and xr need to be added after
+ -batch, either -f package-initialize or -L DIR.)
+
+ In the ~*relint*~ buffer, pressing "g" will re-run the same check.
+
+* Installation
+
+ From GNU ELPA (https://elpa.gnu.org/packages/relint.html):
+
+M-x package-install RET relint RET
+
+ Relint requires the package xr (https://elpa.gnu.org/packages/xr.html);
+ it will be installed automatically.
+
+* What the diagnostics mean
+
+ - Unescaped literal 'X'
+
+A special character is taken literally because it occurs in a
+position where it does not need to be backslash-escaped. It is
+good style to do so anyway (assuming that it should occur as a
+literal character).
+
+ - Escaped non-special character 'X'
+
+A character is backslash-escaped even though this is not necessary
+and does not turn it into a special sequence. Maybe the backslash
+was in error, or should be doubled if a literal backslash was
+expected.
+
+ - Duplicated 'X' inside character alternative
+
+A character occurs twice inside [...]; this is obviously
+pointless. In particular, backslashes are not special inside
+[...]; they have no escaping power, and do not need to be escaped
+in order to include a literal backslash.
+
+ - Repetition of repetition
+
+A repetition construct is applied to an expression that is already
+repeated, such as a*+ (? counts as repetition here). Such
+expressions can be written with a single repetition and often
+indicate a different mistake, such as missing backslashes.
+
+ - Reversed range 'Y-X' matches nothing
+
+The last character of a range precedes the first and therefore
+includes no characters at all (not even the endpoints). Most such
+ranges are caused by a misplaced hyphen.
+
+ - Character 'B' included in range 'A-C'
+
+A range includes a character that also occurs individually. This
+is often caused by a misplaced hyphen.
+
+ - Ranges 'A-M' and 'D-Z' overlap
+
+Two ranges have at least one character in common. This is often
+caused by a misplaced hyphen.
+
+ - Two-character range 'A-B'
+
+A range only consists of its two endpoints, since they have
+consecutive character codes. This is often caused by a misplaced
+hyphen.
+
+ - Duplicated character class '[:class:]'
+
+A character class occurs twice in a single character alternative
+or skip set.
+
+ - Duplicated alternative branch
+
+The same expression occurs in two different branches, like in
+A\|A. This has the effect of only including it once.
+
+ - Branch matches superset/subset of a previous branch
+
+A branch in an or-expression matches a superset or subset of what
+another branch matches, like in [ab]\|a. This means that one of
+the branches can be eliminated without changing the meaning of the
+regexp.
+
+ - Uncounted repetition
+
+The construct A\{,\} repeats A zero or more times which was
+probably not intended.
+
+ - Implicit zero repetition
+
+The construct A\{\} only matches the empty string, which was
+probably not intended.
+
+ - Suspect '[' in char alternative
+
+This warning indicates badly-placed square brackets in a character
+alternative, as in [A[B]C]. A literal ] must come first
+(possibly after a negating ^).
+
+ - Literal '-' not first or last
+
+It is good style to put literal hyphens last in character
+alternatives and skip sets, to clearly indicate that it was not
+intended as part of a range.
+
+ - Repetition of zero-width assertion
+
+A repetition operator was applied to a zero-width assertion, like
+^ or \<,
