[elpa] externals/xr d7325b3 2/5: Edit the package doc comment

[Mattias Engdegård]

branch: externals/xr
commit d7325b3c1fe2e8a64c0057e6d790aa46d7c27700
Author: Mattias Engdegård <address@hidden>
Commit: Mattias Engdegård <address@hidden>

    Edit the package doc comment
---
 xr.el | 61 ++++++++++++++++++++++++++++---------------------------------
 1 file changed, 28 insertions(+), 33 deletions(-)

diff --git a/xr.el b/xr.el
index 410de13..55465e9 100644
--- a/xr.el
+++ b/xr.el
@@ -31,54 +31,51 @@
 ;; Please refer to `rx' for more information about the notation.
 ;;
 ;; In addition to Emacs regexps, this package can also parse and
-;; troubleshoot skip set strings, which are arguments to
+;; find mistakes in skip set strings, which are arguments to
 ;; `skip-chars-forward' and `skip-chars-backward'.
 ;;
-;; The exported functions for regexps are:
+;; The exported functions are:
 ;;
+;;  Regexps:
 ;;  `xr'               - returns the converted rx expression
 ;;  `xr-pp'            - converts to rx and pretty-prints
 ;;  `xr-lint'          - finds mistakes in a regexp string
 ;;
-;; For skip sets we also have:
-;;
+;;  Skip sets:
 ;;  `xr-skip-set'      - return the converted rx expression
 ;;  `xr-skip-set-pp'   - converts to rx and pretty-prints
 ;;  `xr-skip-set-lint' - finds mistakes in a skip set string
 ;;
-;; There is finally the generally useful:
-;;
+;;  General:
 ;;  `xr-pp-rx-to-str' - pretty-prints an rx expression to a string
 ;;
-;; Suggested use is from an interactive elisp buffer.
-;;
 ;; Example (regexp found in compile.el):
 ;;
 ;;   (xr-pp "\\`\\(?:[^^]\\|\\^\\(?: \\*\\|\\[\\)\\)")
 ;; =>
 ;;   (seq bos
-;;        (or
-;;         (not (any "^"))
-;;         (seq "^"
-;;              (or " *" "["))))
+;;        (or (not (any "^"))
+;;            (seq "^"
+;;                 (or " *" "["))))
 ;;
-;; The rx notation admits many synonyms; the xr functions mostly
-;; prefer brief variants, such as `seq' to `sequence' and `nonl' to
-;; `not-newline'.  The user is encouraged to edit the result for
-;; maximum readability, consistency and personal preference when
-;; replacing existing regexps in elisp code.
+;; The rx notation admits many synonyms. The user is encouraged to
+;; edit the result for maximum readability, consistency and personal
+;; preference when replacing existing regexps in elisp code.
 
 ;; Related work:
 ;;
 ;; The `lex' package, a lexical analyser generator, provides the
-;; `lex-parse-re' function which performs a similar task, but does not
-;; attempt to handle all the edge cases of Elisp's regexp syntax or
-;; pretty-print the result.
+;; `lex-parse-re' function which translates regexps to rx, but does
+;; not attempt to handle all the edge cases of Elisp's regexp syntax
+;; or pretty-print the result.
+;;
+;; The `pcre2el' package, a regexp syntax converter and interactive
+;; regexp explainer, could also be used for translating regexps to rx.
+;; `xr' is narrower in scope but more accurate for the purpose of
+;; parsing Emacs regexps and printing the results in rx form.
 ;;
-;; The `pcre2el' package, a regexp syntax converter and interactive regexp
-;; explainer, could also be used for the same tasks. `xr' is narrower in
-;; scope but more accurate for the purpose of parsing Emacs regexps and
-;; printing the results in rx form.
+;; Neither of these packages parse skip-set strings or provide
+;; mistake-finding functions.
 
 ;;; Code:
 
@@ -606,17 +603,15 @@
 
 ;; Grammar for skip-set strings:
 ;;
-;; skip-set ::= `^'? item*
+;; skip-set ::= `^'? item* dangling?
 ;; item     ::= range | single
-;; range    ::= single `-' end
-;; single   ::= (any char but `\')
-;;            | `\' (any char)
-;; end      ::= single | `\'
+;; range    ::= single `-' endpoint
+;; single   ::= {any char but `\'}
+;;            | `\' {any char}
+;; endpoint ::= single | `\'
+;; dangling ::= `\'
 ;;
-;; The grammar is ambiguous, resolved left-to-right:
-;; - a leading ^ is always a negation marker
-;; - an item is always a range if possible
-;; - an end is only `\' if last in the string
+;; Ambiguities in the above are resolved greedily left-to-right.
 
 (defun xr--parse-skip-set-buffer (warnings)
   ;; An ad-hoc check, but one that catches lots of mistakes.