branch: externals/tempel
commit a0604e0bed0f6b13202bbcce940269aae2f16a81
Author: mmctl <ker...@mmeijers.com>
Commit: GitHub <nore...@github.com>
Documenting templates with :doc keyword (#178)
* Add :doc keyword for documenting templates.
* Fix case without keywords.
* Add underline to headers and don't recompute documentation
---
README.org | 13 ++++++++-----
tempel.el | 16 +++++++++++++++-
2 files changed, 23 insertions(+), 6 deletions(-)
diff --git a/README.org b/README.org
index 6422d1ed60..34d8da726f 100644
--- a/README.org
+++ b/README.org
@@ -113,15 +113,18 @@ default the file =templates= in the
~user-emacs-directory~ is used, e.g.,
=~/.config/emacs/templates=. The templates are grouped by major mode with
an optional ~:when~ condition. Each template is a list in the concise form of
the
Emacs Tempo syntax. The first element of each list is the name of the template.
-I recommend to use avoid special letters for the template names, since special
+I recommend to avoid special letters for the template names, since special
letters may carry meaning during completion filtering and as such make it
harder
to select the desired template. Thus the name =lett= is better than =let*=.
Behind
the name, the Tempo syntax elements follow.
-In addition, each template may specify a =:pre= and/or =:post= key with a FORM
that
-is evaluated before the template is expanded or after it is finalized,
-respectively. The =:post= form is evaluated in the lexical scope of the
template,
-which means that it can access the template's named fields.
+In addition, /after/ the template elements, each
+template may specify several key/value pairs. Specifically, templates may
+specify =:pre= and/or =:post= keys with a FORM that is evaluated before the
+template is expanded or after it is finalized, respectively. The =:post= form
is
+evaluated in the lexical scope of the template, which means that it can access
+the template's named fields. Beyond that, templates may include a =:doc= key
+with a string that is used as documentation.
The following examples are written on a single line, but this is is of course
not a requirement. Strings can even contain line breaks, which can be useful if
diff --git a/tempel.el b/tempel.el
index 8954d3bfa6..e98290a015 100644
--- a/tempel.el
+++ b/tempel.el
@@ -175,6 +175,20 @@ may be named with `tempel--name' or carry an evaluatable
Lisp expression
((or 'n '& '% 'o) #("\n" 0 1 (face completions-annotations)))
(_ #("_" 0 1 (face shadow))))))
+(defun tempel--print-documentation (elts)
+ "Print documentation of template ELTS."
+ (while (and elts (not (keywordp (car elts))))
+ (pop elts))
+ (plist-get elts :doc))
+
+(defun tempel--insert-doc-buffer-content (elts)
+ "Insert documentation buffer content for template ELTS."
+ (insert (concat (propertize "Preview" 'face '(:underline t)) "\n"))
+ (insert (tempel--print-template elts))
+ (when-let* ((doc (tempel--print-documentation elts)))
+ (insert (concat "\n\n" (propertize "Documentation" 'face '(:underline t))
"\n"))
+ (insert doc)))
+
(defun tempel--annotate (templates width sep name)
"Annotate template NAME given the list of TEMPLATES.
WIDTH and SEP configure the formatting."
@@ -729,7 +743,7 @@ Capf, otherwise like an interactive completion command."
:company-doc-buffer
(apply-partially #'tempel--info-buffer templates
(lambda (elts)
- (insert (tempel--print-template elts))
+ (tempel--insert-doc-buffer-content elts)
(current-buffer)))
:company-location
(apply-partially #'tempel--info-buffer templates
