From 6dda536f9f7e1d4bb9b5bbe6a1b7f3fe6d06a00e Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Thu, 15 Aug 2019 09:18:10 +0200 Subject: [PATCH] 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. --- doc/org-manual.org | 17 ++++++++++------- lisp/org-colview.el | 5 ++++- lisp/org.el | 12 ++++++++++++ 3 files changed, 26 insertions(+), 8 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index c0a91ab3e..81d86dd30 100644 --- a/doc/org-manual.org +++ b/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 diff --git a/lisp/org-colview.el b/lisp/org-colview.el index d52e553be..351d2bcbb 100644 --- a/lisp/org-colview.el +++ b/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) diff --git a/lisp/org.el b/lisp/org.el index 132c1d6c1..dcb6579ae 100644 --- a/lisp/org.el +++ b/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,