Browse Source

Clear up unclear setting of columns format for the agenda

* lisp/org.el (org-columns-default-format-for-agenda): New option.

* lisp/org-colview.el (org-overriding-columns-format): Updated documentation.
(org-agenda-columns): `Use org-columns-default-format-for-agenda'

* doc/org-manual.org (Using Column View in the Agenda): Fix the
description how to set the columns format for agenda views.
Carsten Dominik 10 months ago
parent
commit
6dda536f9f
3 changed files with 26 additions and 8 deletions
  1. 10 7
      doc/org-manual.org
  2. 4 1
      lisp/org-colview.el
  3. 12 0
      lisp/org.el

+ 10 - 7
doc/org-manual.org

@@ -10589,17 +10589,20 @@ that the entries in the agenda are no longer in their proper outline
 environment.  This causes the following issues:
 
 1.
+   #+vindex: org-columns-default-format-for-agenda
    #+vindex: org-columns-default-format
-   #+vindex: org-overriding-columns-format
    Org needs to make a decision which columns format to use.  Since
    the entries in the agenda are collected from different files, and
-   different files may have different columns formats, this is
-   a non-trivial problem.  Org first checks if the variable
+   different files may have different columns formats, this is a
+   non-trivial problem.  Org first checks if
    ~org-overriding-columns-format~ is currently set, and if so, takes
-   the format from there.  Otherwise it takes the format associated
-   with the first item in the agenda, or, if that item does not have
-   a specific format (defined in a property, or in its file), it uses
-   ~org-columns-default-format~.
+   the format from there.  You should set this variable only in the
+   /local settings section/ of a custom agenda command (see [[*Custom
+   Agenda Views]]) to make it valid for that specific agenda view.  If
+   no such binding exists, it checks, in sequence,
+   ~org-columns-default-format-for-agenda~, the format associated with
+   the first item in the agenda (through a property or a =#+COLUMNS=
+   setting in that buffer) and finally ~org-columns-default-format~.
 
 2.
    #+cindex: @samp{CLOCKSUM}, special property

+ 4 - 1
lisp/org-colview.el

@@ -565,7 +565,9 @@ for the duration of the command.")
 (defvar org-overriding-columns-format nil
   "When set, overrides any other format definition for the agenda.
 Don't set this, this is meant for dynamic scoping.  Set
-`org-local-columns-format' instead.")
+`org-columns-default-format' and `org-columns-default-format-for-agenda'
+instead.  You should use this variable only in the local settings
+section for a custom agenda view.")
 
 (defvar-local org-local-columns-format nil
   "When set, overrides any other format definition for the agenda.
@@ -1566,6 +1568,7 @@ PARAMS is a property list of parameters:
 	  (cond
 	   ((bound-and-true-p org-overriding-columns-format))
 	   ((bound-and-true-p org-local-columns-format))
+	   ((bound-and-true-p org-columns-default-format-for-agenda))
 	   ((let ((m (org-get-at-bol 'org-hd-marker)))
 	      (and m
 		   (or (org-entry-get m "COLUMNS" t)

+ 12 - 0
lisp/org.el

@@ -3142,6 +3142,18 @@ This variable can be set on the per-file basis by inserting a line
   :group 'org-properties
   :type 'string)
 
+(defcustom org-columns-default-format-for-agenda nil
+  "The default column format in an agenda buffer.
+Whis will be used for column view in the agenda unless a format has
+been set by adding `org-overriding-columns-format' to the local
+settings list of a custom agenda view.  When nil, the columns format
+for the first item in the agenda list will be used, or as a fall-back,
+`org-columns-default-format'."
+  :group 'org-properties
+  :type '(choice
+	  (const :tag "No default" nil)
+	  (string :tag "Format string")))
+
 (defcustom org-columns-ellipses ".."
   "The ellipses to be used when a field in column view is truncated.
 When this is the empty string, as many characters as possible are shown,