[elpa] externals/xr c7c861f 07/12: Describe diagnostics in README (taken from relint/README)

[Mattias Engdegård]

branch: externals/xr
commit c7c861f96ccc9359a844b7950be0b7f6dcf8376d
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>

    Describe diagnostics in README (taken from relint/README)
    
    This duplicates the descriptions but makes more sense for xr as an
    independent package.
---
 README | 196 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 196 insertions(+)

diff --git a/README b/README
index 2533d53..ee1dd89 100644
--- a/README
+++ b/README
@@ -16,6 +16,7 @@ arguments to skip-chars-forward and skip-chars-backward.
 
 The xr package can be used interactively or by other code as a library.
 
+
 * Example
 
   (xr-pp "\\`\\(?:[^^]\\|\\^\\(?: \\*\\|\\[\\)\\)")
@@ -27,12 +28,14 @@ The xr package can be used interactively or by other code 
as a library.
            (seq "^"
                 (or " *" "["))))
 
+
 * Installation
 
   From GNU ELPA (https://elpa.gnu.org/packages/xr.html):
 
     M-x package-install RET xr RET
 
+
 * Interface
 
   Functions parsing regexp strings:
@@ -51,6 +54,199 @@ The xr package can be used interactively or by other code 
as a library.
   
    xr-pp-rx-to-str  --  pretty-print rx expression to string
   
+
+* 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
+  - Repetition of option
+  - Optional repetition
+  - Optional option
+  
+    A repetition construct is applied to an expression that is already
+    repeated, such as a*+ or \(x?\)?. These expressions can be written
+    with a single repetition and often indicate a different mistake,
+    perhaps a missing backslash.
+
+    When a repetition construct is ? or ??, it is termed 'option'
+    instead; the principle is the same.
+
+  - 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.
+
+  - Repetition subsumes/subsumed by preceding repetition
+
+    An repeating expression matches a superset or subset of what the
+    previous expression matches, in such a way that one of them is
+    unnecessary. For example, [ab]+a* matches the same text as [ab]+,
+    so the a* could be removed without changing the meaning of the
+    regexp.
+
+  - First/last item in repetition subsumes last/first item (wrapped)
+
+    The first and last items in a repeated sequence, being effectively
+    adjacent, match a superset or subset of each other, which makes
+    for an unexpected inefficiency. For example, \(?:a*c[ab]+\)* can
+    be seen as a*c[ab]+a*c[ab]+... where the [ab]+a* in the middle is
+    a slow way of writing [ab]+ which is made worse by the outer
+    repetition. The general remedy is to move the subsumed item out of
+    the repeated sequence, resulting in a*\(?:c[ab]+\)* in the example
+    above.
+
+  - End-of-line anchor followed by non-newline
+  - Non-newline followed by line-start anchor
+
+    A pattern that does not match a newline occurs right after an
+    end-of-line anchor ($) or before a line-start anchor (^).
+    This combination can never match.
+
+  - End-of-text anchor followed by non-empty pattern
+
+    A pattern that only matches a non-empty string occurs right after
+    an end-of-text anchor (\'). This combination can never match.
+
+  - 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 a literal hyphen 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
+  - Optional zero-width assertion
+
+    A repetition operator was applied to a zero-width assertion, like
+    ^ or \<, which is completely pointless. The error may be a missing
+    escaping backslash.
+
+  - Repetition of expression matching an empty string
+  - Optional expression matching an empty string
+
+    A repetition operator was applied to a sub-expression that could
+    match the empty string; this is not necessarily wrong, but such
+    constructs run very slowly on Emacs's regexp engine. Consider
+    rewriting them into a form where the repeated expression cannot
+    match the empty string.
+
+    Example: \(?:a*b*\)* is equivalent to the much faster \(?:a\|b\)*.
+
+    Another example: \(?:a?b*\)? is better written a?b*. 
+
+    In general, A?, where A matches the empty string, can be
+    simplified to just A.
+
+  - Unnecessarily escaped 'X'
+
+    A character is backslash-escaped in a skip set despite not being
+    one of the three special characters - (hyphen), \ (backslash) and
+    ^ (caret). It could be unnecessary, or a backslash that should
+    have been escaped.
+
+  - Single-element range 'X-X'
+
+    A range in a skip set has identical first and last elements. It is
+    rather pointless to have it as a range.
+
+  - Stray '\\' at end of string
+
+    A single backslash at the end of a skip set is always ignored;
+    double it if you want a literal backslash to be included.
+
+  - Suspect skip set framed in '[...]'
+
+    A skip set appears to be enclosed in [...], as if it were a
+    regexp. Skip sets are not regexps and do not use brackets. To
+    include the brackets themselves, put them next to each other.
+
+  - Suspect character class framed in '[...]'
+
+    A skip set contains a character class enclosed in double pairs of
+    square brackets, as if it were a regexp. Character classes in skip
+    sets are written inside a single pair of square brackets, like
+    [:digit:].
+
+  - Empty set matches nothing
+
+    The empty string is a skip set that does not match anything, and
+    is therefore pointless.
+
+  - Negated empty set matches anything
+
+    The string "^" is a skip set that matches anything, and is therefore
+    pointless.
+
+
 * See also
 
   The relint package (https://elpa.gnu.org/packages/relint.html) uses xr