[elpa] externals/org 55767b792e 3/4: org-agenda.el: Show document title in outline path

[ELPA Syncer]

branch: externals/org
commit 55767b792ee7dce41e43e6a48d48813dd9ad7f7c
Author: Mikhail Skorzhinskii <mskorzhinskii@eml.cc>
Commit: Ihor Radchenko <yantar92@posteo.net>

    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 e96aa482b8..eee7f44282 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 3bac539655..6c0be68ac6 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 f51e6d6d91..e93a812104 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))