[nongnu] elpa/racket-mode fc3f83ca77: Improve documentation about delimiter modes

[ELPA Syncer]

branch: elpa/racket-mode
commit fc3f83ca777e4ffa9939ddf244c9663c5cf4326d
Author: Greg Hendershott <git@greghendershott.com>
Commit: Greg Hendershott <git@greghendershott.com>

    Improve documentation about delimiter modes
    
    Improve on previous commit for issue #676.
    
    Such as any of paredit, smartparens, electric-pair, etc.
---
 doc/racket-mode.org  |  6 +++++-
 doc/racket-mode.texi | 21 ++++++++++++++++++---
 racket-hash-lang.el  | 14 ++++++++++++--
 3 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/doc/racket-mode.org b/doc/racket-mode.org
index 6c948d81b2..59047b5469 100644
--- a/doc/racket-mode.org
+++ b/doc/racket-mode.org
@@ -288,7 +288,7 @@ Indentation can be customized in a way similar to lisp-mode 
and scheme-mode: {{{
 ** paredit
 
 #+BEGIN_QUOTE
-Note: If you use {{{ref(racket-hash-lang-mode)}}}, you can use 
~racket-hash-lang-mode-hook~ to enable/disable paredit based on the specific 
#lang.
+Note: If you use {{{ref(racket-hash-lang-mode)}}}, see 
{{{ref(racket-hash-lang-module-language-hook)}}} for how to enable/disable 
paredit based on the specific #lang.
 #+END_QUOTE
 
 If you use [[https://melpa.org/#/paredit][paredit]], you might want to add 
keybindings to ~paredit-mode-map~:
@@ -327,6 +327,10 @@ If you want to use paredit with interactive modes, their 
advice is to remove the
 
 ** smartparens
 
+#+BEGIN_QUOTE
+Note: If you use {{{ref(racket-hash-lang-mode)}}}, see 
{{{ref(racket-hash-lang-module-language-hook)}}} for how to enable/disable 
smartparens based on the specific #lang.
+#+END_QUOTE
+
 If instead of paredit you prefer 
[[https://melpa.org/#/smartparens][smartparens]], you can use the default 
configuration it provides for Lisp modes generally and for Racket Mode 
specifically:
 
 #+BEGIN_SRC lisp
diff --git a/doc/racket-mode.texi b/doc/racket-mode.texi
index c73ef12f44..b4d8efa2a6 100644
--- a/doc/racket-mode.texi
+++ b/doc/racket-mode.texi
@@ -717,7 +717,7 @@ Indentation can be customized in a way similar to lisp-mode 
and scheme-mode: @re
 @section paredit
 
 @quotation
-Note: If you use @ref{racket-hash-lang-mode}, you can use 
@code{racket-hash-lang-mode-hook} to enable/disable paredit based on the 
specific #lang.
+Note: If you use @ref{racket-hash-lang-mode}, see 
@ref{racket-hash-lang-module-language-hook} for how to enable/disable paredit 
based on the specific #lang.
 
 @end quotation
 
@@ -762,6 +762,11 @@ If you want to use paredit with interactive modes, their 
advice is to remove the
 @node smartparens
 @section smartparens
 
+@quotation
+Note: If you use @ref{racket-hash-lang-mode}, see 
@ref{racket-hash-lang-module-language-hook} for how to enable/disable 
smartparens based on the specific #lang.
+
+@end quotation
+
 If instead of paredit you prefer @uref{https://melpa.org/#/smartparens, 
smartparens}, you can use the default configuration it provides for Lisp modes 
generally and for Racket Mode specifically:
 
 @lisp
@@ -3255,6 +3260,16 @@ suitable for the module language:
   (add-hook 'racket-hash-lang-module-language-hook #'my-hook)
 @end lisp
 
+A similar tactic can be used for @code{smartparens} or
+@code{electric-pair-mode}. In general, none of these
+delimiter-matching modes is likely to work well unless the
+hash-lang uses racket for drracket:grouping-position, in which
+case @ref{racket-hash-lang-mode} uses the classic @ref{racket-mode}
+syntax-table for the buffer. Otherwise you should not enable one
+of these modes, and isntead just use the simple delimiter
+matching built into @ref{racket-hash-lang-mode}; see
+@ref{racket-hash-lang-pairs}.
+
 As another example, if you prefer richer font-lock than just
 tokens, choices include:
 
@@ -3271,8 +3286,8 @@ the module language hook locally set
 
 @itemize
 @item
-Or, use some of @ref{racket-mode}s regexp search-based
-fontification for some module languages:
+Or, use some of the regexp search-based fontification from
+classic @ref{racket-mode} for rackety module languages:
 @end itemize
 
 @lisp
diff --git a/racket-hash-lang.el b/racket-hash-lang.el
index ea1b864727..7d3f8b40d4 100644
--- a/racket-hash-lang.el
+++ b/racket-hash-lang.el
@@ -137,6 +137,16 @@ suitable for the module language:
   (add-hook \\='racket-hash-lang-module-language-hook #\\='my-hook)
 #+END_SRC
 
+A similar tactic can be used for `smartparens' or
+`electric-pair-mode'. In general, none of these
+delimiter-matching modes is likely to work well unless the
+hash-lang uses racket for drracket:grouping-position, in which
+case `racket-hash-lang-mode' uses the classic `racket-mode'
+syntax-table for the buffer. Otherwise you should not enable one
+of these modes, and instead just use the simple delimiter
+matching built into `racket-hash-lang-mode'; see
+`racket-hash-lang-pairs'.
+
 As another example, if you prefer richer font-lock than just
 tokens, choices include:
 
@@ -148,8 +158,8 @@ tokens, choices include:
   (setq-local racket-xp-add-binding-faces t)
 #+END_SRC
 
-- Or, use some of `racket-mode's regexp search-based
-  fontification for some module languages:
+- Or, use some of the regexp search-based fontification from
+  classic `racket-mode' for rackety module languages:
 
 #+BEGIN_SRC elisp
   (require \\='racket-font-lock)