[Patch] Show org file title in org-clock clocktable

[Patch] Show org file title in org-clock clocktable

[Duy Nguyen]

[-- Attachment #1.1: Type: text/plain, Size: 1489 bytes --]

Hello,

Please find attached a patch to allow users to show the org file titles
(i.e. the value of #+title) instead of the file name in the org-clock
clocktable.

I created this patch as I am using a combination of org-roam and org-agenda
to manage my tasks, where each project has its own org-roam file (and
therefore, a #+title). For my work I also need to generate weekly time
reports, with my todos spread over different org(-roam) files. I think the
clocktable looks nicer with the org file title than the name generated by
org-roam, which also has some other irrelevant information (for the
clocktable) in it such as date and time created. I believe this feature
could be useful for other users as well who have their tasks spread over
multiple org-roam files like me. The feature can easily be used by adding
":filetitle t" as an option in the clocktable.

Please note that the org-clock-get-file-prop function is heavily inspired
by vulpea-buffer-prop-get from the vulpea package - I just copied it over
and made some adjustments to make it work for the envisioned use case.

As I am relatively new to emacs / elisp and this is my first patch
submission ever, I am open to feedback on my patch or on how I did this
submission in general.

Special thanks to Ihor, who provided me with hints on how to solve this
issue and inspired me to submit a patch (original post
<https://www.reddit.com/r/orgmode/comments/wlz2yc/showing_org_document_title_in_orgclockreports/>
).

Thanks,

Duy

[-- Attachment #1.2: Type: text/html, Size: 1700 bytes --]

[-- Attachment #2: 0001-lisp-org-clock.el-Show-file-title-in-org-clock-clock.patch --]
[-- Type: application/octet-stream, Size: 2875 bytes --]

From ede10f5f6103cb5802a734df9525b7b47c26c8aa Mon Sep 17 00:00:00 2001
From: Duy Nguyen <duynguyen@Duys-MBP.home>
Date: Fri, 12 Aug 2022 18:40:10 +0200
Subject: [PATCH] lisp/org-clock.el: Show file title in org-clock clocktable

* lisp/org-clock.el (org-clocktable-defaults): Add default value for
new clocktable option `:filetitle'.
(org-clock-get-file-prop): Add new function to extract title of org file.
(org-clocktable-write-default): Print org file name in clocktable if
`:filetitle' is set to `t'.

Allow user to show org file title instead of file name in the
clocktable.  If the file does not have a title defined, the file name
will be shown in the clocktable.

TINYCHANGE
---
 lisp/org-clock.el | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/lisp/org-clock.el b/lisp/org-clock.el
index 362abe358..7424e3a83 100644
--- a/lisp/org-clock.el
+++ b/lisp/org-clock.el
@@ -324,6 +324,7 @@ string as argument."
    :link nil
    :narrow '40!
    :indent t
+   :filetitle nil
    :hidefiles nil
    :formula nil
    :timestamp nil
@@ -2469,6 +2470,23 @@ the currently selected interval size."
 	  (org-update-dblock)
 	  t)))))
 
+;;;###autoload
+(defun org-clock-get-file-prop (file-name name)
+  "Get a property from FILE-NAME called NAME as a string. Returns
+short FILE-NAME if property is not found."
+  (with-current-buffer (find-file-noselect file-name)
+    (org-with-point-at 1
+      (if (re-search-forward (concat "^#\\+" name ": \\(.*\\)")
+                             (point-max) t)
+          (let ((value (string-trim
+                        (buffer-substring-no-properties
+                         (match-beginning 1)
+                         (match-end 1)))))
+            (unless (string-empty-p value)
+              value))
+        (let ((value (file-name-nondirectory file-name)))
+          value)))))
+
 ;;;###autoload
 (defun org-dblock-write:clocktable (params)
   "Write the standard clocktable."
@@ -2584,6 +2602,7 @@ from the dynamic block definition."
 	 (emph (plist-get params :emphasize))
 	 (compact? (plist-get params :compact))
 	 (narrow (or (plist-get params :narrow) (and compact? '40!)))
+	 (filetitle (plist-get params :filetitle))
 	 (level? (and (not compact?) (plist-get params :level)))
 	 (timestamp (plist-get params :timestamp))
 	 (tags (plist-get params :tags))
@@ -2723,7 +2742,9 @@ from the dynamic block definition."
 			     (if (eq formula '%) " %s |" "")
 			     "\n")
 
-		     (file-name-nondirectory file-name)
+                     (if filetitle
+                         (org-clock-get-file-prop file-name "title")
+                       (file-name-nondirectory file-name))
 		     (if level?    "| " "") ;level column, maybe
 		     (if timestamp "| " "") ;timestamp column, maybe
 		     (if tags      "| " "") ;tags column, maybe
-- 
2.32.1 (Apple Git-133)

Re: [Patch] Show org file title in org-clock clocktable

[Ihor Radchenko]

Duy Nguyen <ddnguyen2101@gmail.com> writes:

> Please find attached a patch to allow users to show the org file titles
> (i.e. the value of #+title) instead of the file name in the org-clock
> clocktable.

Thanks for the contribution!

> I created this patch as I am using a combination of org-roam and org-agenda
> to manage my tasks, where each project has its own org-roam file (and
> therefore, a #+title). For my work I also need to generate weekly time
> reports, with my todos spread over different org(-roam) files. I think the
> clocktable looks nicer with the org file title than the name generated by
> org-roam, which also has some other irrelevant information (for the
> clocktable) in it such as date and time created. I believe this feature
> could be useful for other users as well who have their tasks spread over
> multiple org-roam files like me. The feature can easily be used by adding
> ":filetitle t" as an option in the clocktable.

Sounds reasonable.

> Please note that the org-clock-get-file-prop function is heavily inspired
> by vulpea-buffer-prop-get from the vulpea package - I just copied it over
> and made some adjustments to make it work for the envisioned use case.

Please use the built-in org-collect-keywords instead.

> Allow user to show org file title instead of file name in the
> clocktable.  If the file does not have a title defined, the file name
> will be shown in the clocktable.

This is a user-facing change and should be documented in etc/ORG-NEWS file.


-- 
Ihor Radchenko,
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

Re: [Patch] Show org file title in org-clock clocktable

[Duy Nguyen]

[-- Attachment #1.1: Type: text/plain, Size: 511 bytes --]

>
> Please use the built-in org-collect-keywords instead.
>

Thanks for the pointer, I changed the function in the attached patch.

This is a user-facing change and should be documented in etc/ORG-NEWS file.


Updated both the etc/ORG-NEWS and the doc/org-manual.org files.

Not sure how you normally go about updates to submitted patches. For this
time, I just updated the patch by amending the commit of the previous patch
I sent. Please let me know another approach is preferable going forward.

Thanks,
Duy

[-- Attachment #1.2: Type: text/html, Size: 955 bytes --]

[-- Attachment #2: 0001-lisp-org-clock.el-Show-file-title-in-org-clock-clock.patch --]
[-- Type: application/octet-stream, Size: 3999 bytes --]

From 45882f233d961aadbcbc88ee28ba3aac8599296a Mon Sep 17 00:00:00 2001
From: Duy Nguyen <duynguyen@Duys-MBP.home>
Date: Fri, 12 Aug 2022 18:40:10 +0200
Subject: [PATCH] lisp/org-clock.el: Show file title in org-clock clocktable

* lisp/org-clock.el (org-clocktable-defaults): Add default value for
new clocktable option `:filetitle'.
(org-clock-get-file-title): Add new function to extract title of org file.
(org-clocktable-write-default): Print org file name in clocktable if
`:filetitle' is set to `t'.

* doc/org-manual.org (The clock table): Include new `:filetitle'
option in manual for clock table.

* etc/ORG-NEWS (New =:filetitle= option for clock table): Include new
`:filetitle' option for clock table.

Allow user to show org file title instead of file name in the
clocktable.  If the file does not have a title defined, the file name
will be shown in the clocktable.

TINYCHANGE
---
 doc/org-manual.org |  4 ++++
 etc/ORG-NEWS       | 13 +++++++++++++
 lisp/org-clock.el  | 16 +++++++++++++++-
 3 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 466718e6e..046da3790 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -6797,6 +6797,10 @@ using the =:formatter= parameter.
 
   Indent each headline field according to its level.
 
+- =:filetitle= ::
+
+  Show title in the file column if the file has a =#+title=.
+ 
 - =:hidefiles= ::
 
   Hide the file column when multiple files are used to produce the
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 00fe101dc..e9585617e 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -270,6 +270,19 @@ example,
 
 prints a sub-bibliography containing the book entries with =ai= among
 their keywords.
+*** New =:filetitle= option for clock table
+
+The =:filetitle= option for clock tables can be set to =t= to show org
+file title (set by =#+title:=) in the ~File~ column instead of the
+file name. For example:
+
+#+begin_src org
+#+BEGIN: clocktable :scope agenda :maxlevel 2 :block thisweek :filetitle t
+#+end_src
+
+If a file does not have a title, the table will show the file name
+instead.
+
 ** New options
 *** A new custom setting =org-hide-drawer-startup= to control initial folding state of drawers
 
diff --git a/lisp/org-clock.el b/lisp/org-clock.el
index 362abe358..5baa730f8 100644
--- a/lisp/org-clock.el
+++ b/lisp/org-clock.el
@@ -324,6 +324,7 @@ string as argument."
    :link nil
    :narrow '40!
    :indent t
+   :filetitle nil
    :hidefiles nil
    :formula nil
    :timestamp nil
@@ -2469,6 +2470,16 @@ the currently selected interval size."
 	  (org-update-dblock)
 	  t)))))
 
+;;;###autoload
+(defun org-clock-get-file-title (file-name)
+  "Get the file title from FILE-NAME as a string. Returns short
+FILE-NAME if title is not found."
+  (with-current-buffer (find-file-noselect file-name)
+    (let ((title (org-collect-keywords '("title"))))
+      (if (null title)
+          (file-name-nondirectory file-name)
+        (nth 1 (assoc "TITLE" title))))))
+
 ;;;###autoload
 (defun org-dblock-write:clocktable (params)
   "Write the standard clocktable."
@@ -2584,6 +2595,7 @@ from the dynamic block definition."
 	 (emph (plist-get params :emphasize))
 	 (compact? (plist-get params :compact))
 	 (narrow (or (plist-get params :narrow) (and compact? '40!)))
+	 (filetitle (plist-get params :filetitle))
 	 (level? (and (not compact?) (plist-get params :level)))
 	 (timestamp (plist-get params :timestamp))
 	 (tags (plist-get params :tags))
@@ -2723,7 +2735,9 @@ from the dynamic block definition."
 			     (if (eq formula '%) " %s |" "")
 			     "\n")
 
-		     (file-name-nondirectory file-name)
+                     (if filetitle
+                         (org-clock-get-file-title file-name)
+                       (file-name-nondirectory file-name))
 		     (if level?    "| " "") ;level column, maybe
 		     (if timestamp "| " "") ;timestamp column, maybe
 		     (if tags      "| " "") ;tags column, maybe
-- 
2.32.1 (Apple Git-133)

Re: [Patch] Show org file title in org-clock clocktable

[Ihor Radchenko]

Duy Nguyen <ddnguyen2101@gmail.com> writes:

> Not sure how you normally go about updates to submitted patches. For this
> time, I just updated the patch by amending the commit of the previous patch
> I sent. Please let me know another approach is preferable going forward.

This is ok.

Ideally, you can also assign reroll count (version) to the patch and add
something like [PATCH v2] to the subject. But this is optional.

> From 45882f233d961aadbcbc88ee28ba3aac8599296a Mon Sep 17 00:00:00 2001
> From: Duy Nguyen <duynguyen@Duys-MBP.home>
> Date: Fri, 12 Aug 2022 18:40:10 +0200
> Subject: [PATCH] lisp/org-clock.el: Show file title in org-clock clocktable

Thanks for the update! I have some more comments.

> diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
> index 00fe101dc..e9585617e 100644
> --- a/etc/ORG-NEWS
> +++ b/etc/ORG-NEWS
> @@ -270,6 +270,19 @@ example,
>  
>  prints a sub-bibliography containing the book entries with =ai= among
>  their keywords.
> +*** New =:filetitle= option for clock table
> +
> +The =:filetitle= option for clock tables can be set to =t= to show org
> +file title (set by =#+title:=) in the ~File~ column instead of the
> +file name. For example:

We usually use ~code~ for Elisp symbols and code. So, =t= -> ~t~ and
~File~ -> "File". See doc/Documentation_Standards.org

> +#+begin_src org
> +#+BEGIN: clocktable :scope agenda :maxlevel 2 :block thisweek :filetitle t
> +#+end_src

Please, escape #+BEGIN with comma: ,#+BEGIN.
(this is done automatically if you use C-c ' to edit the src block)

> +;;;###autoload
> +(defun org-clock-get-file-title (file-name)
> +  "Get the file title from FILE-NAME as a string. Returns short
> +FILE-NAME if title is not found."
> +  (with-current-buffer (find-file-noselect file-name)
> +    (let ((title (org-collect-keywords '("title"))))
> +      (if (null title)
> +          (file-name-nondirectory file-name)
> +        (nth 1 (assoc "TITLE" title))))))

By convention, we consider a document title to be concatenation of all
the values of #+TITLE keyword inside buffer. That is

#+TITLE: This is
#+TITLE: a title
#+TITLE: written in multiple
#+TITLE: lines

See org-macro--find-keyword-value and org-macro--collect-macros.
You may even make use of the fact that
(assoc "title" org-macro-templates) should give you the document title
without any extra analysis.

-- 
Ihor Radchenko,
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

[PATCH v2] Show org file title in org-clock clocktable

[Duy Nguyen]

[-- Attachment #1.1: Type: text/plain, Size: 481 bytes --]

>
> We usually use ~code~ for Elisp symbols and code. So, =t= -> ~t~ and
> ~File~ -> "File". See doc/Documentation_Standards.org


Please, escape #+BEGIN with comma: ,#+BEGIN.
> (this is done automatically if you use C-c ' to edit the src block)


By convention, we consider a document title to be concatenation of all
> the values of #+TITLE keyword inside buffer.


Thank you once again for your comments Ihor. Please find attached a new
patch with your comments addressed.

Duy

[-- Attachment #1.2: Type: text/html, Size: 987 bytes --]

[-- Attachment #2: v2-0001-lisp-org-clock.el-Show-file-title-in-org-clock-cl.patch --]
[-- Type: application/x-patch, Size: 4037 bytes --]

Re: [PATCH v2] Show org file title in org-clock clocktable

[Ihor Radchenko]

Duy Nguyen <ddnguyen2101@gmail.com> writes:

> Thank you once again for your comments Ihor. Please find attached a new
> patch with your comments addressed.

Thanks!

> +    (let ((macros (org-macro--collect-macros)))
> +      (let ((title (assoc-default "title" macros)))

It is not a good idea to call internal function (with "--" in name) from
a different file. Such functions are a subject of change without notice.

`org-macro-templates' is always initialized when Org mode is active, and
you can rely on its value.

-- 
Ihor Radchenko,
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

Re: [PATCH v3] Show org file title in org-clock clocktable

[Duy Nguyen]

[-- Attachment #1.1: Type: text/plain, Size: 623 bytes --]

>
> It is not a good idea to call internal function (with "--" in name) from
> a different file. Such functions are a subject of change without notice.
>
> `org-macro-templates' is always initialized when Org mode is active, and
> you can rely on its value.
>

Thanks for letting me know. The reason I chose that method is because the
org-macro-templates are not updated immediately after I change the title
and save the file. However, I think I found a solution using
org-macro-initialize-templates and org-macro-templates. Please see the
attached patch. Hope this is OK, otherwise please let me know how to
improve.

Duy

[-- Attachment #1.2: Type: text/html, Size: 883 bytes --]

[-- Attachment #2: v3-0001-lisp-org-clock.el-Show-file-title-in-org-clock-cl.patch --]
[-- Type: application/x-patch, Size: 4030 bytes --]

Re: [PATCH v3] Show org file title in org-clock clocktable

[Ihor Radchenko]

Duy Nguyen <ddnguyen2101@gmail.com> writes:

> Thanks for letting me know. The reason I chose that method is because the
> org-macro-templates are not updated immediately after I change the title
> and save the file. However, I think I found a solution using
> org-macro-initialize-templates and org-macro-templates. Please see the
> attached patch. Hope this is OK, otherwise please let me know how to
> improve.

Thanks for the update!
Applied onto main via 2cc2d8f1f with amendments.
I fixed on double space "  " between sentences, removed autoload cookie
(that function is not used outside org-clock), and altered the docstring
making the first line a single sentence and clarifying about the return
value a bit.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=2cc2d8f1f6265d12c92b734931f2e3e417276b05

-- 
Ihor Radchenko,
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

Re: [PATCH v3] Show org file title in org-clock clocktable

[Duy Nguyen]

> Thanks for the update!
> Applied onto main via 2cc2d8f1f with amendments.
> I fixed on double space "  " between sentences, removed autoload cookie
> (that function is not used outside org-clock), and altered the docstring
> making the first line a single sentence and clarifying about the return
> value a bit.
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=2cc2d8f1f6265d12c92b734931f2e3e417276b05

Thank you so much for your guidance throughout this patch, hopefully I
will be able to contribute to better patches myself in the future!

Duy

Re: [PATCH v3] Show org file title in org-clock clocktable

[Duy Nguyen]

[-- Attachment #1: Type: text/plain, Size: 664 bytes --]

Duy Nguyen <ddnguyen2101@gmail.com> writes:

>> Thanks for the update!
>> Applied onto main via 2cc2d8f1f with amendments.
>> I fixed on double space "  " between sentences, removed autoload cookie
>> (that function is not used outside org-clock), and altered the docstring
>> making the first line a single sentence and clarifying about the return
>> value a bit.
>> <https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=2cc2d8f1f6265d12c92b734931f2e3e417276b05>
>
> Thank you so much for your guidance throughout this patch, hopefully I
> will be able to contribute to better patches myself in the future!
>
> Duy

Thanks man!


Regards,


---

*Duy*

Re: [PATCH v3] Show org file title in org-clock clocktable

[Duy Nguyen]

[-- Attachment #1: Type: text/plain, Size: 773 bytes --]

Duy Nguyen <ddnguyen2101@gmail.com> writes:

> Duy Nguyen <ddnguyen2101@gmail.com> writes:
>
>>> Thanks for the update!
>>> Applied onto main via 2cc2d8f1f with amendments.
>>> I fixed on double space "  " between sentences, removed autoload cookie
>>> (that function is not used outside org-clock), and altered the docstring
>>> making the first line a single sentence and clarifying about the return
>>> value a bit.
>>> <https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=2cc2d8f1f6265d12c92b734931f2e3e417276b05>
>>
>> Thank you so much for your guidance throughout this patch, hopefully I
>> will be able to contribute to better patches myself in the future!
>>
>> Duy
>
> Thanks man!
>
>
> Regards,
>
>
> ---
>
> *Duy*

That works!


Regards,


---

Duy

Re: [PATCH v3] Show org file title in org-clock clocktable

[Duy Nguyen]

[-- Attachment #1: Type: text/plain, Size: 897 bytes --]

That is fine, thanks.

Regards,
Duy


Duy Nguyen <ddnguyen2101@gmail.com> writes:

> Duy Nguyen <ddnguyen2101@gmail.com> writes:
>
>> Duy Nguyen <ddnguyen2101@gmail.com> writes:
>>
>>>> Thanks for the update!
>>>> Applied onto main via 2cc2d8f1f with amendments.
>>>> I fixed on double space "  " between sentences, removed autoload cookie
>>>> (that function is not used outside org-clock), and altered the docstring
>>>> making the first line a single sentence and clarifying about the return
>>>> value a bit.
>>>> <https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=2cc2d8f1f6265d12c92b734931f2e3e417276b05>
>>>
>>> Thank you so much for your guidance throughout this patch, hopefully I
>>> will be able to contribute to better patches myself in the future!
>>>
>>> Duy
>>
>> Thanks man!
>>
>>
>> Regards,
>>
>>
>> ---
>>
>> *Duy*
>
> That works!
>
>
> Regards,
>
>
> ---
>
> Duy