* [FR] org-colview.el, add annotation for functions summary-types
@ 2024-08-08 17:53 Sławomir Grochowski
2024-08-10 13:03 ` Ihor Radchenko
0 siblings, 1 reply; 8+ messages in thread
From: Sławomir Grochowski @ 2024-08-08 17:53 UTC (permalink / raw)
To: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 860 bytes --]
Dear all,
When the user wants to add a new column (or edit an existing one), he
executes the command `org-columns-new'. Then he can enter or select a few
'column attributes' (see in manual https://orgmode.org/org.html#Column-attributes-1).
One of the attributes is "SUMMARY-TYPE". This attribute can be selected
from the list of very enigmatic symbols such as "+", "$", "X"
which do not convey any information to the user. So, I have prepared a
solution that will address this issue.
For each symbol, the 'docstring' of the function assigned to that symbol
will be displayed. For example:
"+ -- Compute the sum of VALUES."
"$ -- Compute the sum of VALUES, with two decimals."
What do you think about this solution?
I also included a question in the commit message regarding the function
`org-columns--first-line-docstring' that I created.
Patch below:
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: patch --]
[-- Type: text/x-diff, Size: 3504 bytes --]
From 1725dddfc6e574737f1b79f2ba93d5fa6b09cffb Mon Sep 17 00:00:00 2001
From: Slawomir Grochowski <slawomir.grochowski@gmail.com>
Date: Sat, 3 Aug 2024 19:53:25 +0200
Subject: [PATCH] lisp/org-colview.el: add annotation for summary-types
* org-colview.el (org-columns--first-line-docstring): add function that
retrieves the first line of function's docstring.
I have not found a function that would do such a simple thing, it seems
to me that such functionality is often used but there is no special
function for it? I couldn't find one, so I wrote my own. But it is a
general-purpose function and should not be located in org-colview.
(org-columns--summary-types-annotate): add function that return
annotation for one of the summary-type function in
`org-columns-summary-types-all'.
(org-columns-new): refactor: extract variable (append
org-columns-summary-types org-columns-summary-types-default) to
`org-columns-summary-types-all' because it is used in two places.
---
lisp/org-colview.el | 39 ++++++++++++++++++++++++++++++---------
1 file changed, 30 insertions(+), 9 deletions(-)
diff --git a/lisp/org-colview.el b/lisp/org-colview.el
index ed4d1ee16..50fb72121 100644
--- a/lisp/org-colview.el
+++ b/lisp/org-colview.el
@@ -953,6 +953,24 @@ When COLUMNS-FMT-STRING is non-nil, use it as the column format."
(goto-char (car entry))
(org-columns--display-here (cdr entry)))))))))
+(defun org-columns--first-line-docstring (fun)
+ "Return the first line of the documentation string of FUN."
+ (let* ((docstring (documentation fun))
+ (first-line (car (split-string docstring "\n"))))
+ first-line))
+
+(defun org-columns--summary-types-annotate (fun)
+ "Return annotation for one of the FUN in `org-columns-summary-types-all'.
+
+If FUN is not empty, retrieves the first line of the docstring for FUN
+from the `org-columns-summary-types-all', formats it, and decorates it
+with the `completions-annotations` face."
+ (when (not (string-empty-p fun))
+ (format " -- %s"
+ (propertize (org-columns--first-line-docstring
+ (cdr (assoc fun org-columns-summary-types-all)))
+ 'face 'completions-annotations))))
+
(defun org-columns-new (&optional spec &rest attributes)
"Insert a new column, to the left of the current column.
Interactively fill attributes for new column. When column format
@@ -980,15 +998,18 @@ details."
(number-to-string (nth 2 spec))))))
(and (org-string-nw-p w) (string-to-number w)))
(org-string-nw-p
- (completing-read
- "Summary: "
- (delete-dups
- (cons '("") ;Allow empty operator.
- (mapcar (lambda (x) (list (car x)))
- (append
- org-columns-summary-types
- org-columns-summary-types-default))))
- nil t (nth 3 spec)))
+ (let* ((completion-extra-properties
+ '(:annotation-function org-columns--summary-types-annotate))
+ (org-columns-summary-types-all (append
+ org-columns-summary-types
+ org-columns-summary-types-default)))
+ (completing-read
+ "Summary: "
+ (delete-dups
+ (cons '("") ;Allow empty operator.
+ (mapcar (lambda (x) (list (car x)))
+ org-columns-summary-types-all)))
+ nil t (nth 3 spec))))
(org-string-nw-p
(read-string "Format: " (nth 4 spec))))))))
(if spec
--
2.30.2
[-- Attachment #3: Type: text/plain, Size: 35 bytes --]
Regards,
--
Slawomir Grochowski
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [FR] org-colview.el, add annotation for functions summary-types
2024-08-08 17:53 [FR] org-colview.el, add annotation for functions summary-types Sławomir Grochowski
@ 2024-08-10 13:03 ` Ihor Radchenko
2024-08-15 14:35 ` Sławomir Grochowski
0 siblings, 1 reply; 8+ messages in thread
From: Ihor Radchenko @ 2024-08-10 13:03 UTC (permalink / raw)
To: Sławomir Grochowski; +Cc: emacs-orgmode
Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:
> When the user wants to add a new column (or edit an existing one), he
> executes the command `org-columns-new'. Then he can enter or select a few
> 'column attributes' (see in manual https://orgmode.org/org.html#Column-attributes-1).
> One of the attributes is "SUMMARY-TYPE". This attribute can be selected
> from the list of very enigmatic symbols such as "+", "$", "X"
> which do not convey any information to the user. So, I have prepared a
> solution that will address this issue.
>
> For each symbol, the 'docstring' of the function assigned to that symbol
> will be displayed. For example:
> "+ -- Compute the sum of VALUES."
> "$ -- Compute the sum of VALUES, with two decimals."
>
> What do you think about this solution?
I like the idea.
> * org-colview.el (org-columns--first-line-docstring): add function that
> retrieves the first line of function's docstring.
> I have not found a function that would do such a simple thing, it seems
> to me that such functionality is often used but there is no special
> function for it? I couldn't find one, so I wrote my own. But it is a
> general-purpose function and should not be located in org-colview.
See `help--symbol-completion-table-affixation'.
I'd also prefer using a proper completing-read API instead of
`completion-extra-properties' - by using `completion-extra-properties',
we disallow users from utilizing this variable.
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [FR] org-colview.el, add annotation for functions summary-types
2024-08-10 13:03 ` Ihor Radchenko
@ 2024-08-15 14:35 ` Sławomir Grochowski
2024-08-15 16:48 ` Ihor Radchenko
0 siblings, 1 reply; 8+ messages in thread
From: Sławomir Grochowski @ 2024-08-15 14:35 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
Thank you for your help Ihor.
Ihor Radchenko <yantar92@posteo.net> writes:
> See `help--symbol-completion-table-affixation'.
It's a private function and I need only a part of it.
Should I extract that part and create a new function? Like this below?
(defun first-line-docstring (fun)
(let* ((doc (condition-case nil (documentation fun) (error nil)))
(doc (and doc (substring doc 0 (string-search "\n" doc)))))
(if doc
(format " -- %s" doc)
"")))
Or just copy the needed part and put it in org-columns-new?
> I'd also prefer using a proper completing-read API instead of
> `completion-extra-properties' - by using `completion-extra-properties',
> we disallow users from utilizing this variable.
OK. Based on this example
https://emacs.stackexchange.com/questions/74547/completing-read-search-also-in-annotations
I came up with this snippet below:
(completing-read
"Summary: "
(lambda (s pred flag)
(pcase flag
('t (all-completions s
(mapcar #'car org-columns-summary-types-default)
pred))
('metadata (list 'metadata
(cons 'annotation-function
(lambda (c)
(first-line-docstring
(cdr (assoc c org-columns-summary-types-default))))))))))
Thank you for the feedback.
Regards,
--
Slawomir Grochowski
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [FR] org-colview.el, add annotation for functions summary-types
2024-08-15 14:35 ` Sławomir Grochowski
@ 2024-08-15 16:48 ` Ihor Radchenko
2024-08-15 17:29 ` Sławomir Grochowski
0 siblings, 1 reply; 8+ messages in thread
From: Ihor Radchenko @ 2024-08-15 16:48 UTC (permalink / raw)
To: Sławomir Grochowski; +Cc: emacs-orgmode
Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:
>> See `help--symbol-completion-table-affixation'.
>
> It's a private function and I need only a part of it.
> Should I extract that part and create a new function? Like this below?
>
> (defun first-line-docstring (fun)
> (let* ((doc (condition-case nil (documentation fun) (error nil)))
> (doc (and doc (substring doc 0 (string-search "\n" doc)))))
> (if doc
> (format " -- %s" doc)
> "")))
This would make sense, yes. Probably for org-macs.el
Why not applying faces?
>> I'd also prefer using a proper completing-read API instead of
>> `completion-extra-properties' - by using `completion-extra-properties',
>> we disallow users from utilizing this variable.
>
> OK. Based on this example
> https://emacs.stackexchange.com/questions/74547/completing-read-search-also-in-annotations
> I came up with this snippet below:
>
> (completing-read
> "Summary: "
> (lambda (s pred flag)
> (pcase flag
> ('t (all-completions s
> (mapcar #'car org-columns-summary-types-default)
> pred))
> ('metadata (list 'metadata
> (cons 'annotation-function
> (lambda (c)
> (first-line-docstring
> (cdr (assoc c org-columns-summary-types-default))))))))))
Looks reasonable.
Although, I'd prefer to avoid lambda here and simply make it into a
proper function. Just like `org-tags-completion-function'.
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [FR] org-colview.el, add annotation for functions summary-types
2024-08-15 16:48 ` Ihor Radchenko
@ 2024-08-15 17:29 ` Sławomir Grochowski
2024-08-15 17:41 ` Ihor Radchenko
0 siblings, 1 reply; 8+ messages in thread
From: Sławomir Grochowski @ 2024-08-15 17:29 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> writes:
> Why not applying faces?
Because in case of 'annotation-function':
https://www.gnu.org/software/emacs/manual/html_node/elisp/Programmed-Completion.html
"...Unless this function puts own face on the annotation suffix string,
the completions-annotations face is added by default to that string.
>> (completing-read
>> "Summary: "
>> (lambda (s pred flag)
>> (pcase flag
>> ('t (all-completions s
>> (mapcar #'car org-columns-summary-types-default)
>> pred))
>> ('metadata (list 'metadata
>> (cons 'annotation-function
>> (lambda (c)
>> (first-line-docstring
>> (cdr (assoc c org-columns-summary-types-default))))))))))
>
> Looks reasonable.
> Although, I'd prefer to avoid lambda here and simply make it into a
> proper function. Just like `org-tags-completion-function'.
And this will be private function in colview.el?
With name... `org-columns--completion-summary-types-function' ?
--
Slawomir Grochowski
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [FR] org-colview.el, add annotation for functions summary-types
2024-08-15 17:29 ` Sławomir Grochowski
@ 2024-08-15 17:41 ` Ihor Radchenko
2024-08-16 11:13 ` Sławomir Grochowski
0 siblings, 1 reply; 8+ messages in thread
From: Ihor Radchenko @ 2024-08-15 17:41 UTC (permalink / raw)
To: Sławomir Grochowski; +Cc: emacs-orgmode
Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:
> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> Why not applying faces?
>
> Because in case of 'annotation-function':
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Programmed-Completion.html
> "...Unless this function puts own face on the annotation suffix string,
> the completions-annotations face is added by default to that string.
Ok. But please double-check that it is really the case.
>> Looks reasonable.
>> Although, I'd prefer to avoid lambda here and simply make it into a
>> proper function. Just like `org-tags-completion-function'.
>
> And this will be private function in colview.el?
> With name... `org-columns--completion-summary-types-function' ?
Yup. Maybe `org-columns--summary-types-completion-function'.
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [FR] org-colview.el, add annotation for functions summary-types
2024-08-15 17:41 ` Ihor Radchenko
@ 2024-08-16 11:13 ` Sławomir Grochowski
2024-08-18 9:56 ` Ihor Radchenko
0 siblings, 1 reply; 8+ messages in thread
From: Sławomir Grochowski @ 2024-08-16 11:13 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> writes:
> Ok. But please double-check that it is really the case.
Checked.
So I have those 3 code snipets:
(defun org-columns--summary-types-completion-function (string)
(docstring-first-line
(cdr (assoc string (append
org-columns-summary-types
org-columns-summary-types-default)))))
(completing-read
"Summary: "
(lambda (string pred flag)
(pcase flag
('t (all-completions string
(delete-dups
(cons '("") ;Allow empty operator.
(mapcar #'car (append
org-columns-summary-types
org-columns-summary-types-default))))
pred))
('metadata (list 'metadata
(cons 'annotation-function
'org-columns--summary-types-completion-function))))))
(defun docstring-first-line (fun)
(let* ((doc (condition-case nil (documentation fun) (error nil)))
(doc (and doc (substring doc 0 (string-search "\n" doc)))))
(if doc
(format " -- %s" doc)
"")))
But I have no idea where to put this piece:
(if doc
(format " -- %s" doc)
"")
It should not be in docstring-first-line.
What do you think?
--
Slawomir Grochowski
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [FR] org-colview.el, add annotation for functions summary-types
2024-08-16 11:13 ` Sławomir Grochowski
@ 2024-08-18 9:56 ` Ihor Radchenko
0 siblings, 0 replies; 8+ messages in thread
From: Ihor Radchenko @ 2024-08-18 9:56 UTC (permalink / raw)
To: Sławomir Grochowski; +Cc: emacs-orgmode
Sławomir Grochowski <slawomir.grochowski@gmail.com> writes:
> So I have those 3 code snipets:
>
> (defun org-columns--summary-types-completion-function (string)
> (docstring-first-line
> (cdr (assoc string (append
> org-columns-summary-types
> org-columns-summary-types-default)))))
>
> (completing-read
> "Summary: "
> (lambda (string pred flag)
> ....
This lambda is the completion function.
It is what should go into
`org-columns--summary-types-completion-function'.
> But I have no idea where to put this piece:
>
> (if doc
> (format " -- %s" doc)
> "")
>
> It should not be in docstring-first-line.
> What do you think?
Into `org-columns--summary-types-completion-function'.
Or, if you want, you can create a separate "affixation function" that
will format the suffix and call it from
`org-columns--summary-types-completion-function'.
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2024-08-18 9:56 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-08-08 17:53 [FR] org-colview.el, add annotation for functions summary-types Sławomir Grochowski
2024-08-10 13:03 ` Ihor Radchenko
2024-08-15 14:35 ` Sławomir Grochowski
2024-08-15 16:48 ` Ihor Radchenko
2024-08-15 17:29 ` Sławomir Grochowski
2024-08-15 17:41 ` Ihor Radchenko
2024-08-16 11:13 ` Sławomir Grochowski
2024-08-18 9:56 ` Ihor Radchenko
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).