branch: master
commit 3032337831cf466e80578c0161e6de660263ed9b
Author: Noam Postavsky <npost...@users.sourceforge.net>
Commit: Noam Postavsky <npost...@users.sourceforge.net>
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
