[elpa] master 3032337 37/51: Improve rendering of docstrings in manual's reference section

[Noam Postavsky]

branch: master
commit 3032337831cf466e80578c0161e6de660263ed9b
Author: Noam Postavsky <address@hidden>
Commit: Noam Postavsky <address@hidden>

    Improve rendering of docstrings in manual's reference section
    
    * doc/yas-doc-helper.el (yas--org-raw-html): Accept an ATTRS argument.
    (yas--document-symbol): Render variables with <code
    class='variable>... and functions with <code
    class='function'>... instead of =...=.  Render indented lisp
    forms (recognized as lines beginning 4+ spaces followed by open paren)
    with #+BEGIN_SRC elisp...#+END_SRC.  Render \\{keymap} with
    substitute-command-keys and #+BEGIN_EXAMPOE...#+END_EXAMPLE.  Link
    "Info node `(manul) Node Name'" to gnu.org manual page.
    * yasnippet.el (yas-prompt-functions): Add spaces to make example lisp
    form be recognized as lisp.
---
 doc/yas-doc-helper.el | 54 ++++++++++++++++++++++++++++++++++++++++++---------
 yasnippet.el          |  2 +-
 2 files changed, 46 insertions(+), 10 deletions(-)

diff --git a/doc/yas-doc-helper.el b/doc/yas-doc-helper.el
index 00b2d00..f48628f 100644
--- a/doc/yas-doc-helper.el
+++ b/doc/yas-doc-helper.el
@@ -31,13 +31,14 @@
     (require 'ox-publish))
 (require 'yasnippet) ; docstrings must be loaded
 
-(defun yas--org-raw-html (tag content)
+(defun yas--org-raw-html (tag content &optional attrs)
   ;; in version 8.0 org-mode changed the export syntax, see
   ;; http://orgmode.org/worg/org-8.0.html#sec-8-1
   (format (if (version< org-version "8.0.0")
               "@<%s>%s@</%s>"                ; old: @<tag>
             "@@html:<%s>@@%s@@html:</%s>@@") ; new: @@html:<tag>@@
-          tag content tag))
+          (concat tag (if attrs " ") attrs)
+          content tag))
 
 (defun yas--document-symbol (symbol level)
   (let* ((stars (make-string level ?*))
@@ -45,14 +46,17 @@
                     (mapcar #'symbol-name (help-function-arglist symbol t))))
          (heading (cond ((fboundp symbol)
                          (format
-                          "%s =%s= (%s)\n" stars symbol
+                          "%s %s (%s)\n" stars (yas--org-raw-html "code" 
symbol "class='function'")
                           (mapconcat (lambda (a)
                                        (format (if (string-prefix-p "&" a)
-                                                   "/%s/" "=%s=") a))
+                                                   "/%s/" "=%s=")
+                                               a))
                                      args " ")))
                         (t
-                         (format "%s =%s=\n" stars symbol))))
+                         (format "%s %s\n" stars
+                                 (yas--org-raw-html "code" symbol 
"class='variable'")))))
          (after-heading (format ":PROPERTIES:\n:CUSTOM_ID: %s\n:END:" symbol))
+         (text-quoting-style 'grave)
          (body (or (cond ((fboundp symbol)
                           (let ((doc-synth (car-safe (get symbol 
'function-documentation))))
                             (if (functionp doc-synth)
@@ -64,10 +68,17 @@
                           (format "*WARNING*: no symbol named =%s=" symbol)))
                    (format "*WARNING*: no doc for symbol =%s=" symbol)))
          (case-fold-search nil))
-    ;; do some transformations on the body:
+    ;; Do some transformations on the body:
     ;; ARGxxx becomes @<code>arg@</code>xxx
     ;; FOO becomes /foo/
     ;; `bar' becomes [[#bar][=bar=]]
+    ;;    (...) becomes #+BEGIN_SRC elisp (...) #+END_SRC
+    ;; Info node `(some-manual) Node Name' becomes
+    ;; 
[[https://www.gnu.org/software/emacs/manual/html_node/some-manual/Node-Name.html]
+    ;;  [(some-manual) Node Name]]
+    ;;
+    ;; This is fairly fragile, though it seems to be working for
+    ;; now...
     (setq body (replace-regexp-in-string
                 "\\<\\([A-Z][-A-Z0-9]+\\)\\(\\sw+\\)?\\>"
                 #'(lambda (match)
@@ -82,14 +93,39 @@
                         match1)))
                 body t t 1)
           body (replace-regexp-in-string
-                "`\\([a-z-]+\\)'"
+                "\\\\{[^}]+}"
+                (lambda (match)
+                  (concat "#+BEGIN_EXAMPLE\n"
+                          (substitute-command-keys match)
+                          "#+END_EXAMPLE\n"))
+                body t t)
+          body (substitute-command-keys body)
+          body (replace-regexp-in-string
+                "Info node `(\\([-a-z]+\\)) \\([A-Za-z0-9 ]+\\)'"
+                (lambda (match)
+                  (let* ((manual (match-string 1 match))
+                         (node (match-string 2 match))
+                         (html-node (replace-regexp-in-string " " "-" node t 
t)))
+                    (format "Info node\
+ [[https://www.gnu.org/software/emacs/manual/html_node/%s/%s.html][(%s) %s]]"
+                            manual html-node manual node)))
+                body t t)
+          body (replace-regexp-in-string
+                "`\\([-a-z]+\\)'"
                 #'(lambda (match)
                     (let* ((name (downcase (match-string 1 match)))
-                           (sym (intern name)))
+                           (sym (intern-soft name)))
                       (if (memq sym yas--exported-syms)
                           (format "[[#%s][=%s=]]" name name)
                         (format "=%s=" name))))
-                body t))
+                body t t)
+          body (replace-regexp-in-string
+                "\n\n    +(.+\\(?:\n    +.+\\)*"
+                (lambda (match)
+                  (concat "\n#+BEGIN_SRC elisp\n"
+                          match
+                          "\n#+END_SRC\n"))
+                body t t))
     ;; output the paragraph
     (concat heading after-heading "\n" body)))
 
diff --git a/yasnippet.el b/yasnippet.el
index 11bc270..6a27812 100644
--- a/yasnippet.el
+++ b/yasnippet.el
@@ -237,7 +237,7 @@ nil.
 - To signal that the user quit the prompting process, you can
 signal `quit' with
 
-  (signal \\='quit \"user quit!\")."
+    (signal \\='quit \"user quit!\")"
   :type '(repeat function))
 
 (defcustom yas-indent-line 'auto