From 12da8c1ccd1efa9c4f1282d213a46f93bf10410d Mon Sep 17 00:00:00 2001
From: Mikhail Skorzhinskii <mskorzhinskii@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       |  6 ++++++
 lisp/org-agenda.el | 12 +++++++++---
 lisp/org.el        | 12 +++++++++---
 3 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index e96aa482b..7b64f1b9d 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -324,6 +324,12 @@ value of ~org-babel-clojure-backend~. For example:
 #+end_src
 
 ** New options
+*** 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
+instead of the file name at the beginning of the outline. The title of
+the document can be set by special keyword =#+title:=.
+
 *** New custom settings =org-icalendar-scheduled-summary-prefix= and =org-icalendar-deadline-summary-prefix=
 
 These settings allow users to define prefixes for exported summary
diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index 3bac53965..6c0be68ac 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -1068,9 +1068,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." title)))
 
 (defcustom org-agenda-start-with-entry-text-mode nil
   "The initial value of entry-text-mode in a newly created agenda window."
@@ -9468,7 +9474,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 f51e6d6d9..e93a81210 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7437,10 +7437,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 \"/\".
@@ -7448,6 +7450,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
@@ -7459,7 +7462,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