Thank you for suggestion, I seen an announcement about this function, but
somehow forgot about it.
Sending next version of these patches. Changes from the next version:
• Removed my version of title gathering into one existing in org-clock.el
• Split org-clock-get-file-title renaming into separate commit
• More grammar and wording fixes in changelogs
Thanks,
Mikhail
Ihor Radchenko <yanta...@gmail.com> writes:
> Mikhail Skorzhisnkii <mskorzhins...@eml.cc> writes:
>
>>> Also, what will happen in a file like
>>>
>>> #+TITLE: Begin title
>>> #+TITLE: .. end title
>>>
>>> ?
>>
>> Hm, never did this myself. Now concatenate the list of property values. I
>> have
>> tested it and space as a separator looks good, if the intention of several
>> titles is to have one big title.
>>
>> But what if several titles are title and subtitles? We can provide a way
>> control
>> that behaviour, but my gut feeling that it would be a rather confusing.
>
> See org-clock-get-file-title. You can move that function into org.el and
> rename to org-get-file-title.
>From 47c61b597a3064755964d763621616d184c351ad Mon Sep 17 00:00:00 2001
From: Mikhail Skorzhinskii <mskorzhins...@eml.cc>
Date: Mon, 21 Sep 2020 14:53:13 +0200
Subject: [PATCH 3/3] org-refile.el: show refile targets with a title
* lisp/org-refile.el (org-refile-get-targets): Use a document
title (#+TITLE) instead of file or buffer name in outline path, if
a corresponding customisation option is set to 'title. Fallback to a
filename if there is no title in the document.
* lisp/org-refile.el (org-refile-use-outline-path): Add a new option
'title, see above
---
etc/ORG-NEWS | 6 ++++++
lisp/org-refile.el | 17 ++++++++++++++---
testing/lisp/test-org.el | 37 ++++++++++++++++++++++++++++++++++++-
3 files changed, 56 insertions(+), 4 deletions(-)
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 8f57d252f..cc63b679d 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -295,6 +295,12 @@ Use the header argument =:var x=code-block[]= or
to pass the contents of a named code block as a string argument.
** New options
+*** A new option for custom setting =org-refile-use-outline-path= to show document title in refile targets
+
+Setting =org-refile-use-outline-path= to ='title= will show title
+instead of the file name in refile targets. If the documen do not have
+a title, the filename will be used, similar to ='file= option.
+
*** A new option for custom setting =org-agenda-show-outline-path= to show document title
Setting =org-agenda-show-outline-path= to ='title= will show title
diff --git a/lisp/org-refile.el b/lisp/org-refile.el
index 16cff25bd..64f4ef7da 100644
--- a/lisp/org-refile.el
+++ b/lisp/org-refile.el
@@ -160,7 +160,8 @@ When `buffer-name', use the buffer name."
(const :tag "Yes" t)
(const :tag "Start with file name" file)
(const :tag "Start with full file path" full-file-path)
- (const :tag "Start with buffer name" buffer-name)))
+ (const :tag "Start with buffer name" buffer-name)
+ (const :tag "Start with document title" title)))
(defcustom org-outline-path-complete-in-steps t
"Non-nil means complete the outline path in hierarchical steps.
@@ -319,6 +320,11 @@ converted to a headline before refiling."
(push (list (and (buffer-file-name (buffer-base-buffer))
(file-truename (buffer-file-name (buffer-base-buffer))))
f nil nil) tgs))
+ (when (eq org-refile-use-outline-path 'title)
+ (push (list (or (org-get-title)
+ (and f (file-name-nondirectory f)))
+ f nil nil)
+ tgs))
(org-with-wide-buffer
(goto-char (point-min))
(setq org-outline-path-cache nil)
@@ -345,7 +351,12 @@ converted to a headline before refiling."
(and (buffer-file-name (buffer-base-buffer))
(file-name-nondirectory
(buffer-file-name (buffer-base-buffer))))))
- (`full-file-path
+ (`title (list
+ (or (org-get-title)
+ (and (buffer-file-name (buffer-base-buffer))
+ (file-name-nondirectory
+ (buffer-file-name (buffer-base-buffer)))))))
+ (`full-file-path
(list (buffer-file-name
(buffer-base-buffer))))
(`buffer-name
@@ -633,7 +644,7 @@ this function appends the default value from
(tbl (mapcar
(lambda (x)
(if (and (not (member org-refile-use-outline-path
- '(file full-file-path)))
+ '(file full-file-path title)))
(not (equal filename (nth 1 x))))
(cons (concat (car x) extra " ("
(file-name-nondirectory (nth 1 x)) ")")
diff --git a/testing/lisp/test-org.el b/testing/lisp/test-org.el
index 004e89732..d7412f080 100644
--- a/testing/lisp/test-org.el
+++ b/testing/lisp/test-org.el
@@ -6728,7 +6728,42 @@ Paragraph<point>"
(org-test-with-temp-text "* H1"
(let* ((org-refile-use-outline-path 'buffer-name)
(org-refile-targets `((nil :level . 1))))
- (member (buffer-name) (mapcar #'car (org-refile-get-targets)))))))
+ (member (buffer-name) (mapcar #'car (org-refile-get-targets))))))
+ ;; When `org-refile-use-outline-path' is `title', return extracted
+ ;; document title
+ (should
+ (equal '("T" "T/H1")
+ (org-test-with-temp-text-in-file "#+title: T\n* H1"
+ (let* ((org-refile-use-outline-path 'title)
+ (org-refile-targets `((nil :level . 1))))
+ (mapcar #'car (org-refile-get-targets))))))
+ ;; When `org-refile-use-outline-path' is `title' validate that
+ ;; deeper levels are correctly reported too (the same behaviour as
+ ;; 'file)
+ (should
+ (equal '("T" "T/H1" "T/H1/H2" "T/H1/H2/H3" "T/H1")
+ (org-test-with-temp-text-in-file "#+title: T\n* H1\n** H2\n*** H3\n* H1"
+ (let ((org-refile-use-outline-path 'title)
+ (org-refile-targets `((nil :maxlevel . 3))))
+ (mapcar #'car (org-refile-get-targets))))))
+ ;; When `org-refile-use-outline-path' is `title' and document do not
+ ;; have an extracted document title, return just the file name
+ (should
+ (org-test-with-temp-text-in-file "* H1"
+ (let* ((filename (buffer-file-name))
+ (org-refile-use-outline-path 'title)
+ (org-refile-targets `((nil :level . 1))))
+ (member (file-name-nondirectory filename)
+ (mapcar #'car (org-refile-get-targets))))))
+ ;; When `org-refile-use-outline-path' is `title' and document is a
+ ;; temporary buffer without a file, it is still possible to extract
+ ;; a title
+ (should
+ (equal '("T" "T/H1")
+ (org-test-with-temp-text "#+title: T\n* H1\n** H2"
+ (let* ((org-refile-use-outline-path 'title)
+ (org-refile-targets `((nil :level . 1))))
+ (mapcar #'car (org-refile-get-targets)))))))
--
2.35.1
>From 62684b478ae5ceb03f66967fbebcc4d6163c826c Mon Sep 17 00:00:00 2001
From: Mikhail Skorzhinskii <mskorzhins...@eml.cc>
Date: Sat, 12 Sep 2020 18:10:05 +0200
Subject: [PATCH 2/3] org-agenda.el: show document title in outline path
* lisp/org-agenda.el (org-agenda-show-outline-path): Add an option to
show a document title at start of an outline path, instead of a file or
a buffer name.
* lisp/org.el (org-display-outline-path): Show a document title (#+TITLE
value) and an outline path in an echo area if the customisation option
is set to 'title. Fallback to a file or a buffer name if the document
title is absent.
---
etc/ORG-NEWS | 9 ++++-----
lisp/org-agenda.el | 12 +++++++++---
lisp/org.el | 12 +++++++++---
3 files changed, 22 insertions(+), 11 deletions(-)
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 44f0024fb..8f57d252f 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -295,12 +295,11 @@ Use the header argument =:var x=code-block[]= or
to pass the contents of a named code block as a string argument.
** New options
-*** New custom settings =org-icalendar-scheduled-summary-prefix= and =org-icalendar-deadline-summary-prefix=
+*** A new option for custom setting =org-agenda-show-outline-path= to show document title
-These settings allow users to define prefixes for exported summary
-lines in ICS exports. The customization can be used to disable
-the prefixes completely or make them a little bit more verbose
-(e.g. "Deadline: " instead of the default "DL: ").
+Setting =org-agenda-show-outline-path= to ='title= will show title
+instead of the file name at the beginning of the outline. The title of
+the document can be set by special keyword =#+title:=.
*** A new custom setting =org-hide-drawer-startup= to control initial folding state of drawers
diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index 053232078..c817aefd0 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -1061,9 +1061,15 @@ current item's tree, in an indirect buffer."
:type 'boolean)
(defcustom org-agenda-show-outline-path t
- "Non-nil means show outline path in echo area after line motion."
+ "Non-nil means show outline path in echo area after line motion.
+
+If set to 'title, show outline path with prepended document
+title. Fallback to file name is no title is present."
:group 'org-agenda-startup
- :type 'boolean)
+ :type '(choice
+ (const :tag "Don't show outline path in agenda view." nil)
+ (const :tag "Show outline path with prepended file name." t)
+ (const :tag "Show outline path with prepended document title. Fallback to file name is no title is present." title)))
(defcustom org-agenda-start-with-entry-text-mode nil
"The initial value of entry-text-mode in a newly created agenda window."
@@ -9427,7 +9433,7 @@ When called with a prefix argument, include all archive files as well."
(org-agenda-tree-to-indirect-buffer nil)
(org-agenda-show)))
(and org-agenda-show-outline-path
- (org-with-point-at m (org-display-outline-path t))))))
+ (org-with-point-at m (org-display-outline-path org-agenda-show-outline-path))))))
(defun org-agenda-show-tags ()
"Show the tags applicable to the current item."
diff --git a/lisp/org.el b/lisp/org.el
index f3f9c4096..c2b8a2a40 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7429,10 +7429,12 @@ Returns nil if there are no #+TITLE property."
(unless (string= "" title)
title)))))
-(defun org-display-outline-path (&optional file current separator just-return-string)
+(defun org-display-outline-path (&optional file-or-title current separator just-return-string)
"Display the current outline path in the echo area.
-If FILE is non-nil, prepend the output with the file name.
+If FILE-OR-TITLE is 'title, prepend outline with file title. If
+it is non-nil or title is not present in document, prepend
+outline path with the file name.
If CURRENT is non-nil, append the current heading to the output.
SEPARATOR is passed through to `org-format-outline-path'. It separates
the different parts of the path and defaults to \"/\".
@@ -7440,6 +7442,7 @@ If JUST-RETURN-STRING is non-nil, return a string, don't display a message."
(interactive "P")
(let* (case-fold-search
(bfn (buffer-file-name (buffer-base-buffer)))
+ (title-prop (when (eq file-or-title 'title) (org-get-title)))
(path (and (derived-mode-p 'org-mode) (org-get-outline-path)))
res)
(when current (setq path (append path
@@ -7451,7 +7454,10 @@ If JUST-RETURN-STRING is non-nil, return a string, don't display a message."
(org-format-outline-path
path
(1- (frame-width))
- (and file bfn (concat (file-name-nondirectory bfn) separator))
+ (and file-or-title bfn (concat (if (and (eq file-or-title 'title) title-prop)
+ title-prop
+ (file-name-nondirectory bfn))
+ separator))
separator))
(add-face-text-property 0 (length res)
`(:height ,(face-attribute 'default :height))
--
2.35.1
>From 5b15f886b22dc542220b48ae9659c4c2d56dea78 Mon Sep 17 00:00:00 2001
From: Mikhail Skorzhinskii <mskorzhins...@eml.cc>
Date: Thu, 8 Sep 2022 21:29:23 +0200
Subject: [PATCH 1/3] org-clock.el: rename org-clock-get-file-title
* lisp/org.el (org-get-title): A new function to collect a document
title from an org-mode buffer, based on a org-clock-get-file-title
implementation.
* lisp/org.el (org-get-file-title): Moved from the org-clock.el to the
org.el and renamed, preserving the same behaviour and function
signature.
* lisp/org-clock.el (org-clock-get-file-title): Moved and renamed, see
above.
---
etc/ORG-NEWS | 8 ++++++++
lisp/org-clock.el | 12 +-----------
lisp/org.el | 20 ++++++++++++++++++++
3 files changed, 29 insertions(+), 11 deletions(-)
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 3c98e8ba0..44f0024fb 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -332,6 +332,10 @@ event time when the alarm time is set to 0. The default value is
nil -- do not create alarms at the event time.
** New functions and changes in function arguments
+*** New function ~org-get-title~ to get ~#+TITLE:~ property from buffers
+
+A function to collect the document title from the org-mode buffer.
+
*** ~org-fold-show-entry~ does not fold drawers by default anymore
~org-fold-show-entry~ now accepts an optional argument HIDE-DRAWERS.
@@ -399,6 +403,10 @@ Previously, executing PlantUML src blocks always exported to a file. Now, if
exported and an ASCII graph will be inserted below the src block.
** Removed or renamed functions and variables
+*** Rename ~org-clock-get-file-title~ to ~org-get-file-title~
+
+This function is now part of the =org.el= file.
+
*** =org-plantump-executable-args= is renamed and applies to jar as well
The new variable name is =org-plantuml-args=. It now applies to both
diff --git a/lisp/org-clock.el b/lisp/org-clock.el
index b432c7df7..ef0ef2021 100644
--- a/lisp/org-clock.el
+++ b/lisp/org-clock.el
@@ -2473,16 +2473,6 @@ the currently selected interval size."
(org-update-dblock)
t)))))
-(defun org-clock-get-file-title (file-name)
- "Get the file title from FILE-NAME as a string.
-Return short FILE-NAME if #+title keyword is not found."
- (with-current-buffer (find-file-noselect file-name)
- (org-macro-initialize-templates)
- (let ((title (assoc-default "title" org-macro-templates)))
- (if (null title)
- (file-name-nondirectory file-name)
- title))))
-
;;;###autoload
(defun org-dblock-write:clocktable (params)
"Write the standard clocktable."
@@ -2739,7 +2729,7 @@ from the dynamic block definition."
"\n")
(if filetitle
- (org-clock-get-file-title file-name)
+ (org-get-file-title file-name)
(file-name-nondirectory file-name))
(if level? "| " "") ;level column, maybe
(if timestamp "| " "") ;timestamp column, maybe
diff --git a/lisp/org.el b/lisp/org.el
index 34560c83f..f3f9c4096 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7409,6 +7409,26 @@ the default is \"/\"."
(setf (substring fpath (- width 2)) "..")))
fpath))
+(defun org-get-file-title (file-name)
+ "Collect title from `org-mode' FILE-NAME.
+
+Return file name if title does not exist."
+ (or (org-get-title (find-file-noselect file-name))
+ (file-name-nondirectory file-name)))
+
+(defun org-get-title (&optional buffer)
+ "Collect title from the provided `org-mode' BUFFER.
+
+Returns nil if there are no #+TITLE property."
+ (let ((buffer (or (buffer-base-buffer)
+ buffer
+ (current-buffer))))
+ (with-current-buffer buffer
+ (org-macro-initialize-templates)
+ (let ((title (assoc-default "title" org-macro-templates)))
+ (unless (string= "" title)
+ title)))))
+
(defun org-display-outline-path (&optional file current separator just-return-string)
"Display the current outline path in the echo area.
--
2.35.1
