helpful icon indicating copy to clipboard operation
helpful copied to clipboard

Docstrings should not double-escape strings

Open yuhan0 opened this issue 1 year ago • 0 comments

As pointed out in https://github.com/Wilfred/helpful/issues/197#issuecomment-1030905340, when a docstring contains a quoted string, the contents of that string should already be double-escaped such that its printed representation is correctly escaped (and can be copy-pasted etc.). This is the case for all built-in Emacs docs, I was especially tripped up by this section in the documentation of font-lock-keywords, rendered in helpful as:

For example, an element of the form highlights (if not already
highlighted):

 "\\\\\\=<foo\\\\\\=>"
  Discrete occurrences of "foo" in the value of the variable
  font-lock-keyword-face.

 ("fu\\\\(bar\\\\)" . 1)
  Substring "bar" within all occurrences of "fubar" in the
  value of font-lock-keyword-face.

and in its intended presentation by describe-variable as:

For example, an element of the form highlights (if not already
highlighted):

 "\\<foo\\>"
  Discrete occurrences of "foo" in the value of the variable
  ‘font-lock-keyword-face’.

 ("fu\\(bar\\)" . 1)
  Substring "bar" within all occurrences of "fubar" in the
  value of ‘font-lock-keyword-face’.

The motivating example for the change was in fact an inaccuracy in one of Counsel's docstrings, and has since been fixed:https://github.com/abo-abo/swiper/commit/11609248ef7730d76820fbf85b59bf4cb5f0c280

yuhan0 avatar May 11 '23 16:05 yuhan0