[PATCH] emacs doc: replace `...' with `...` in emacs docstrings for rst

[PATCH] emacs doc: replace `...' with `...` in emacs docstrings for rst

[Tomi Ollila]

Previously ' without preceding \ was replaced with `, to make emacs
document content structure `...' to work with reStructuredText.

But there are also single uses of ' in parts of the extracted
docstrings, so better "restrict" the matching content to `[^']+'.

Dropped checking preceding \ before ' -- it is not needed anymore;
there is now one \' in the docstrings, but outside `...'.

Note: In UTF-8 locales ` and ' may be replaced by some (arguably)
better looking unicode counterparts (by emacs).
---

This also "avoids" the bug building emacs/notmuch-parser.rsti in
Debian 10. The doc content with "... SP's ..." no longer matches
the re which caused emacs to barf then in (replace-match) (*)
there. The bug is still a mystery (and may stay so).

(* used (setq debug-on-error t) to dig a bit of the problem)

 emacs/rstdoc.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/emacs/rstdoc.el b/emacs/rstdoc.el
index 2225aefc..94596061 100644
--- a/emacs/rstdoc.el
+++ b/emacs/rstdoc.el
@@ -68,7 +68,7 @@ (defun rstdoc--insert-docstring (symbol docstring)
 
 (defvar rst--escape-alist
   '( ("\\\\='" . "\\\\'")
-     ("\\([^\\]\\)'" . "\\1`")
+     ("`\\([^']+\\)'" . "`\\1`")
      ("^[[:space:]\t]*$" . "|br|")
      ("^[[:space:]\t]" . "|indent| "))
     "list of (regex . replacement) pairs")
-- 
2.25.2

Re: [PATCH] emacs doc: replace `...' with `...` in emacs docstrings for rst

[Tomi Ollila]

On Mon, Apr 13 2020, Tomi Ollila wrote:

> Previously ' without preceding \ was replaced with `, to make emacs
> document content structure `...' to work with reStructuredText.

The change is good, but comment message crap. 

While trying to make rstdoc.el to load elisp code so that in docstrings
single quotes (') were not changed to their better-looking unicode
counterparts I notices that in `...' the ' in that is not converted
(since it is syntax-highlighted internally by emacs). 

Since that the original version where 's not preceded by \ are converted.
(as rest are already changed) -- ¡¡¡unless the locale is C!!!.

So we really are better just converting `...' to `...` (If we had `:s
w/o ...' then those should be escaped -- but (so far) we don't -- 
doing those is not trivial, but possible).

I'll resend this w/ different commit message later.

(but please review and comment if there is anything wrong before that =)

Tomi

>
> But there are also single uses of ' in parts of the extracted
> docstrings, so better "restrict" the matching content to `[^']+'.
>
> Dropped checking preceding \ before ' -- it is not needed anymore;
> there is now one \' in the docstrings, but outside `...'.
>
> Note: In UTF-8 locales ` and ' may be replaced by some (arguably)
> better looking unicode counterparts (by emacs).
> ---
>
> This also "avoids" the bug building emacs/notmuch-parser.rsti in
> Debian 10. The doc content with "... SP's ..." no longer matches
> the re which caused emacs to barf then in (replace-match) (*)
> there. The bug is still a mystery (and may stay so).
>
> (* used (setq debug-on-error t) to dig a bit of the problem)
>
>  emacs/rstdoc.el | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/emacs/rstdoc.el b/emacs/rstdoc.el
> index 2225aefc..94596061 100644
> --- a/emacs/rstdoc.el
> +++ b/emacs/rstdoc.el
> @@ -68,7 +68,7 @@ (defun rstdoc--insert-docstring (symbol docstring)
>  
>  (defvar rst--escape-alist
>    '( ("\\\\='" . "\\\\'")
> -     ("\\([^\\]\\)'" . "\\1`")
> +     ("`\\([^']+\\)'" . "`\\1`")
>       ("^[[:space:]\t]*$" . "|br|")
>       ("^[[:space:]\t]" . "|indent| "))
>      "list of (regex . replacement) pairs")
> -- 
> 2.25.2