[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
scratch/shortdoc d1ff4cc: Allow headings and rearrange the strings
From: |
Lars Ingebrigtsen |
Subject: |
scratch/shortdoc d1ff4cc: Allow headings and rearrange the strings |
Date: |
Sun, 13 Sep 2020 16:18:23 -0400 (EDT) |
branch: scratch/shortdoc
commit d1ff4cc9cf0a69eb96fc6098336b6b71526c963b
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>
Allow headings and rearrange the strings
---
lisp/emacs-lisp/shortdoc.el | 178 +++++++++++++++++++++++++-------------------
1 file changed, 101 insertions(+), 77 deletions(-)
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 071002b..b9d0cf2 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -52,7 +52,8 @@ FUNCTIONS is a list of elements on the form:
(fun
:no-manual BOOL
:args ARGS
- :example FORM)
+ :example EXAMPLE-FORM
+ :result RESULT-FORM)
BOOL should be non-nil if the function isn't documented in the
manual.
@@ -60,13 +61,42 @@ manual.
ARGS is optional, and the functions definition is displayed
instead in not present.
-There can be any number of :example/:result pairs."
- `(progn
+If EXAMPLE-FORM isn't a string, it will be printed with `prin1',
+and then evaled to give a result, which is also printed. If it's
+a string, it'll be inserted as is. In that case, there should be
+a form that says what the result should be.
+
+There can be any number of :example/:result elements."
+ `(eval-and-compile
(setq shortdoc--groups (delq (assq ',group shortdoc--groups)
shortdoc--groups))
(push (cons ',group ',functions) shortdoc--groups)))
(define-short-documentation-group string
+ "Making Strings"
+ (make-string
+ :example "(make-string 5 ?x)"
+ :result "xxxxx")
+ (string
+ :example "(string ?a ?b ?c)"
+ :result "abc")
+ (concat
+ :example (concat "foo" "bar" "zot"))
+ (string-join
+ :example (string-join '("foo" "bar" "zot") " "))
+ (mapconcat
+ :example (mapconcat (lambda (a) (concat "[" a "]"))
+ '("foo" "bar" "zot") " "))
+ (format
+ :example (format "This number is %d" 4))
+ "Manipulating Strings"
+ (substring
+ :example (substring "foobar" 0 3)
+ :example (substring "foobar" 3))
+ (split-string
+ :example (split-string "foo bar")
+ :example (split-string "|foo|bar|" "|")
+ :example (split-string "|foo|bar|" "|" t))
(string-trim
:no-manual t
:args (string)
@@ -78,24 +108,26 @@ There can be any number of :example/:result pairs."
(string-trim-right
:no-manual t
:example (string-trim-right "barkss" "s+"))
- (concat
- :example (concat "foo" "bar" "zot"))
- (string-join
- :example (string-join '("foo" "bar" "zot") " "))
- (mapconcat
- :example (mapconcat (lambda (a) (concat "[" a "]"))
- '("foo" "bar" "zot") " "))
- (make-string
- :example (make-string 5 ?x))
- (string
- :example (string ?a ?b ?c))
- (substring
- :example (substring "foobar" 0 3)
- :example (substring "foobar" 3))
+ (string-truncate-left
+ :example (string-truncate-left "longstring" 8))
+ (string-remove-suffix
+ :example (string-remove-suffix "bar" "foobar"))
+ (string-remove-prefix
+ :example (string-remove-prefix "foo" "foobar"))
+ (reverse
+ :example (reverse "foo"))
(substring-no-properties
:example (substring (propertize "foobar" 'face 'bold) 0 3))
+ "Predicates for String"
(string-equal
:example (string-equal "foo" "foo"))
+ (stringp
+ :example "(stringp ?a)"
+ :result t)
+ (string-empty-p
+ :example (string-empty-p ""))
+ (string-blank-p
+ :example (string-blank-p " \n"))
(string-lessp
:example (string-lessp "foo" "bar"))
(string-greaterp
@@ -106,6 +138,7 @@ There can be any number of :example/:result pairs."
:example (string-prefix-p "foo" "foobar"))
(string-suffix-p
:example (string-suffix-p "bar" "foobar"))
+ "Case Manipulation"
(upcase
:example (upcase "foo"))
(downcase
@@ -114,35 +147,18 @@ There can be any number of :example/:result pairs."
:example (capitalize "foo bar zot"))
(upcase-initials
:example (upcase-initials "The CAT in the hAt"))
+ "Converting Strings"
(string-to-number
:example (string-to-number "42")
:example (string-to-number "deadbeef" 16))
(number-to-string
:example (number-to-string 42))
+ "Data About Strings"
(length
:example (length "foo"))
- (reverse
- :example (reverse "foo"))
(seq-position
- :example (seq-position "foobarzot" ?z))
- (format
- :example (format "This number is %d" 4))
- (stringp
- :example (stringp ?a))
- (string-empty-p
- :example (string-empty-p ""))
- (string-blank-p
- :example (string-blank-p " \n"))
- (string-truncate-left
- :example (string-truncate-left "longstring" 8))
- (string-remove-suffix
- :example (string-remove-suffix "bar" "foobar"))
- (string-remove-prefix
- :example (string-remove-prefix "foo" "foobar"))
- (split-string
- :example (split-string "foo bar")
- :example (split-string "|foo|bar|" "|")
- :example (split-string "|foo|bar|" "|" t)))
+ :example "(seq-position \"foobarzot\" ?z)"
+ :result 6))
(defun shortdoc-display-group (group)
"Pop to a buffer and display short documentation for functions in GROUP."
@@ -155,48 +171,56 @@ There can be any number of :example/:result pairs."
(button-mode)
(mapc
(lambda (data)
- (let ((function (pop data))
- (start-section (point)))
- ;; Function calling convention.
- (insert "(")
- (if (getf data :no-manual)
- (insert (symbol-name function))
- (insert-text-button
- (symbol-name function)
- 'face 'button
- 'action (lambda (_)
- (info-lookup-symbol function 'emacs-lisp-mode))))
- (dolist (param (or (plist-get data :args)
- (help-function-arglist function t)))
- (insert " " (symbol-name param)))
- (insert ")\n")
- ;; Doc string.
- (insert " "
- (or (plist-get data :doc)
- (car (split-string (documentation function) "\n"))))
- (insert "\n\n")
- (add-face-text-property start-section (point) 'shortdoc-section t)
- (let ((start (point))
- (print-escape-newlines t))
- (cl-loop for (type value) on data by #'cddr
- when (eq type :example)
- do (progn
- (insert " ")
- (prin1 value (current-buffer))
- (insert "\n")
- (insert " => ")
- (prin1 (eval value) (current-buffer))
- (insert "\n"))
- when (eq type :result)
- do (progn
- (insert " => ")
- (prin1 value (current-buffer))
- (insert "\n")))
- (put-text-property start (point) 'face 'shortdoc-example))
- (insert "\n")))
+ (if (stringp data)
+ (insert (propertize
+ (concat data "\n\n")
+ 'face '(variable-pitch (:height 1.3 :weight bold))))
+ (shortdoc--display-function data)))
(cdr (assq group shortdoc--groups))))
(goto-char (point-min)))
+(defun shortdoc--display-function (data)
+ (let ((function (pop data))
+ (start-section (point)))
+ ;; Function calling convention.
+ (insert "(")
+ (if (getf data :no-manual)
+ (insert (symbol-name function))
+ (insert-text-button
+ (symbol-name function)
+ 'face 'button
+ 'action (lambda (_)
+ (info-lookup-symbol function 'emacs-lisp-mode))))
+ (dolist (param (or (plist-get data :args)
+ (help-function-arglist function t)))
+ (insert " " (symbol-name param)))
+ (insert ")\n")
+ ;; Doc string.
+ (insert " "
+ (or (plist-get data :doc)
+ (car (split-string (documentation function) "\n"))))
+ (insert "\n\n")
+ (add-face-text-property start-section (point) 'shortdoc-section t)
+ (let ((start (point))
+ (print-escape-newlines t))
+ (cl-loop for (type value) on data by #'cddr
+ when (eq type :example)
+ do (if (stringp value)
+ (insert " " value "\n")
+ (insert " ")
+ (prin1 value (current-buffer))
+ (insert "\n")
+ (insert " => ")
+ (prin1 (eval value) (current-buffer))
+ (insert "\n"))
+ when (eq type :result)
+ do (progn
+ (insert " => ")
+ (prin1 value (current-buffer))
+ (insert "\n")))
+ (put-text-property start (point) 'face 'shortdoc-example))
+ (insert "\n")))
+
(defun shortdoc-function-groups (function)
"Return all shortdoc groups FUNCTION appears in."
(cl-loop for group in shortdoc--groups
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- scratch/shortdoc d1ff4cc: Allow headings and rearrange the strings,
Lars Ingebrigtsen <=