Manual 7.5.3 Capturing column view outdated

Manual 7.5.3 Capturing column view outdated

[Axel Kielhorn]

Hello,

while exchanging mails with Uwe Brauer I discovered some errors in the manual:

7.5.3 Capturing column view

links to 

A.6 Dynamic Blocks

which describes

org-dynamic-block-insert-dblock

But this commands does not know about columnview

Further down it says:

C-c C-x i (org-insert-columns-dblock)
Insert a dynamic block capturing a column view. Prompt for the scope or ID of the view.

This binding does not exist for me, "C-c C-x i" is undefined.
Should it be defined?
There is no key binding for clocktable.
(Well, the manual (8.4.2) says „C-c C-x C-r“ is a binding, but my emacs disagrees.)[*]

The commands

org-insert-columns-dblock

is obsolete, the new commands is

org-columns-insert-dblock

The command is available in the menu:

<Org><TAGS and Properties>

It would be nice to have this information in the manual as well.

[*] While comparing columnview and clocktable I discovered that C-c C-x x clocktable doesn’t work either.
The command to create a clocktable (org-clock-report) is available in the menu as well.

Greetings
Axel

[PATCH 0/4] dynamic block-related fixes

[Kyle Meyer]

Axel Kielhorn writes:

> while exchanging mails with Uwe Brauer I discovered some errors in the manual:
>
> 7.5.3 Capturing column view
>
> links to 
>
> A.6 Dynamic Blocks
>
> which describes
>
> org-dynamic-block-insert-dblock
>
> But this commands does not know about columnview

It does, but it will only offer "columnview" as an option until after
org-colview.el is loaded.

> Further down it says:
>
> C-c C-x i (org-insert-columns-dblock)
> Insert a dynamic block capturing a column view. Prompt for the scope or ID of the view.
>
> This binding does not exist for me, "C-c C-x i" is undefined.
> Should it be defined?

It was removed in 34b71a0ca (Add a dispatcher command for inserting
dynamic blocks, 2018-12-23), but the manual wasn't adjusted.

> There is no key binding for clocktable.
> (Well, the manual (8.4.2) says „C-c C-x C-r“ is a binding, but my emacs disagrees.)[*]

Same here.

> The commands
>
> org-insert-columns-dblock
>
> is obsolete, the new commands is
>
> org-columns-insert-dblock

True, that should have been updated in 3debe06bd (Rename
`org-insert-columns-dblock' into `org-columns-insert-dblock',
2016-02-17).

> The command is available in the menu:
>
> <Org><TAGS and Properties>
>
> It would be nice to have this information in the manual as well.
>
> [*] While comparing columnview and clocktable I discovered that C-c C-x x clocktable doesn’t work either.
> The command to create a clocktable (org-clock-report) is available in the menu as well.

The follow series (in particular the first and third patch) hopefully
resolves the above issues.  I think it should remove the need for this
last point, as 'C-c C-x x' should offer clocktable and columnview
candidates even before the associated library is loaded.

base-commit: f3c137a69797b0432db4dd887c547b2d69c4ed4d
-- 
2.26.1

[PATCH 1/4] manual: Remove stale information about dynamic block bindings

[Kyle Meyer]

* doc/org-manual.org (Capturing column view): Replace stale binding
with mention of org-dynamic-block-insert-dblock, and refer to
org-columns-insert-dblock rather than its obsolete variant.
(The clock table): Prune references to stale binding, rewrite
org-dynamic-block-insert-dblock key sequence in a clearer manner, and
add a dedicated entry for org-clock-report.

These bindings were replaced in 34b71a0ca (Add a dispatcher command
for inserting dynamic blocks, 2018-12-23).

Reported-by: Axel Kielhorn <org-mode@axelkielhorn.de>
<id:3CE37EF0-6C7A-4CC0-AFEE-2B82296D63E1@axelkielhorn.de>
---
 doc/org-manual.org | 30 ++++++++++++++++++++----------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index c668db32f..92a526ba6 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5647,13 +5647,17 @@ *** Capturing column view
 
 The following commands insert or update the dynamic block:
 
-- {{{kbd(C-c C-x i)}}} (~org-insert-columns-dblock~) ::
+- ~org-columns-insert-dblock~ ::
 
-  #+kindex: C-c C-x i
-  #+findex: org-insert-columns-dblock
+  #+kindex: C-c C-x x
+  #+findex: org-columns-insert-dblock
   Insert a dynamic block capturing a column view.  Prompt for the
   scope or ID of the view.
 
+  This command can be invoked by calling
+  ~org-dynamic-block-insert-dblock~ ({{{kbd(C-c C-x x)}}}) and
+  selecting "columnview" (see [[*Dynamic Blocks]]).
+
 - {{{kbd(C-c C-c)}}} {{{kbd(C-c C-x C-u)}}} (~org-dblock-update~) ::
 
   #+kindex: C-c C-c
@@ -6488,13 +6492,19 @@ *** The clock table
 information.  Such a report is called a /clock table/, because it is
 formatted as one or several Org tables.
 
-You can insert, or update, a clock table through Org dynamic blocks
-insert command (see [[*Dynamic Blocks]]), by pressing {{{kbd(C-c C-x
-x c l o c k t a b l e RET)}}}.  When called with a prefix argument,
-jump to the first clock table in the current document and update it.
-The clock table includes archived trees.
-
 #+attr_texinfo: :sep ,
+- ~org-clock-report~ ::
+
+  #+kindex: C-c C-x x
+  #+findex: org-clock-report
+  Insert or update a clock table.  When called with a prefix argument,
+  jump to the first clock table in the current document and update it.
+  The clock table includes archived trees.
+
+  This command can be invoked by calling
+  ~org-dynamic-block-insert-dblock~ ({{{kbd(C-c C-x x)}}}) and
+  selecting "clocktable" (see [[*Dynamic Blocks]]).
+
 - {{{kbd(C-c C-c)}}} or {{{kbd(C-c C-x C-u)}}} (~org-dblock-update~) ::
 
   #+kindex: C-c C-c
@@ -6519,7 +6529,7 @@ *** The clock table
   =:block= is =today=, it is shifted to =today-1=, etc.
 
 Here is an example of the frame for a clock table as it is inserted
-into the buffer with the {{{kbd(C-c C-x C-r)}}} command:
+into the buffer by ~org-clock-report~:
 
 #+cindex: @samp{BEGIN clocktable}
 #+begin_example
-- 
2.26.1

[PATCH 2/4] orgcard: Update binding for org-columns-insert-dblock

[Kyle Meyer]

As of 34b71a0ca (Add a dispatcher command for inserting dynamic
blocks, 2018-12-23), the binding was removed and the command is
available via org-dynamic-block-insert-dblock.
---
 doc/orgcard.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/orgcard.tex b/doc/orgcard.tex
index fa233b620..121a86442 100644
--- a/doc/orgcard.tex
+++ b/doc/orgcard.tex
@@ -513,7 +513,7 @@ \section{Properties and Column View}
 \key{special commands in property lines}{C-c C-c}
 \key{next/previous allowed value}{S-LEFT/RIGHT}
 \key{turn on column view}{C-c C-x C-c}
-\key{capture columns view in dynamic block}{C-c C-x i}
+\key{capture columns view in dynamic block}{C-c C-x}
 
 \key{quit column view}{q}
 \key{show full value}{v}
-- 
2.26.1

[PATCH 3/4] Autoload dynamic block definitions

[Kyle Meyer]

* lisp/org-clock.el:
* lisp/org-colview.el: Autoload call to org-dynamic-block-define.

The dynamic block dispatcher added in 34b71a0ca (Add a dispatcher
command for inserting dynamic blocks, 2018-12-23) offers an entry for
"clocktable" and "columnview" only after the corresponding library is
loaded.  However, before that commit, the autoloaded org-clock-report
and org-columns-insert-dblock commands were accessible via plain key
bindings.  Restore the ability to access these commands before the
associated library is loaded.

Reported-by: Axel Kielhorn <org-mode@axelkielhorn.de>
<id:3CE37EF0-6C7A-4CC0-AFEE-2B82296D63E1@axelkielhorn.de>
---
 lisp/org-clock.el   | 5 ++++-
 lisp/org-colview.el | 5 ++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/lisp/org-clock.el b/lisp/org-clock.el
index a95c85437..690ba05b2 100644
--- a/lisp/org-clock.el
+++ b/lisp/org-clock.el
@@ -2068,7 +2068,10 @@ (defun org-clock-report (&optional arg)
     (start (goto-char start)))
   (org-update-dblock))
 
-(org-dynamic-block-define "clocktable" #'org-clock-report)
+;;;###autoload
+(eval-after-load 'org
+  '(progn
+     (org-dynamic-block-define "clocktable" #'org-clock-report)))
 
 (defun org-day-of-week (day month year)
   "Return the day of the week as an integer."
diff --git a/lisp/org-colview.el b/lisp/org-colview.el
index e967154ab..3569b231b 100644
--- a/lisp/org-colview.el
+++ b/lisp/org-colview.el
@@ -1550,7 +1550,10 @@ (defun org-columns-insert-dblock ()
 		     (id)))))
   (org-update-dblock))
 
-(org-dynamic-block-define "columnview" #'org-columns-insert-dblock)
+;;;###autoload
+(eval-after-load 'org
+  '(progn
+     (org-dynamic-block-define "columnview" #'org-columns-insert-dblock)))
 
 \f
 ;;; Column view in the agenda
-- 
2.26.1

[PATCH 4/4] org: Retain prefix arg when dispatching dynamic block commands

[Kyle Meyer]

* lisp/org.el (org-dynamic-block-insert-dblock): Add an interactive-p
argument that is non-nil for interactive calls and signals to call the
dynamic block function interactively.

org-clock-report takes a prefix argument.  When it had a regular
binding, this was easy to access.  As of 34b71a0ca (Add a dispatcher
command for inserting dynamic blocks, 2018-12-23), its only "binding"
is through the dynamic block dispatcher.  Make it possible to supply a
prefix argument in that context too.
---
 lisp/org.el | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index bf82a49cc..751223f06 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -9652,15 +9652,18 @@ (defun org-dynamic-block-define (type func)
     (`nil (push (cons type func) org-dynamic-block-alist))
     (def (setcdr def func))))
 
-(defun org-dynamic-block-insert-dblock (type)
+(defun org-dynamic-block-insert-dblock (type &optional interactive-p)
   "Insert a dynamic block of type TYPE.
 When used interactively, select the dynamic block types among
-defined types, per `org-dynamic-block-define'."
+defined types, per `org-dynamic-block-define'.  If INTERACTIVE-P
+is non-nil, call the dynamic block function interactively."
   (interactive (list (completing-read "Dynamic block: "
-				      (org-dynamic-block-types))))
+				      (org-dynamic-block-types))
+		     t))
   (pcase (org-dynamic-block-function type)
     (`nil (error "No such dynamic block: %S" type))
-    ((and f (pred functionp)) (funcall f))
+    ((and f (pred functionp))
+     (if interactive-p (call-interactively f) (funcall f)))
     (_ (error "Invalid function for dynamic block %S" type))))
 
 (defun org-dblock-update (&optional arg)
-- 
2.26.1

Re: [PATCH 2/4] orgcard: Update binding for org-columns-insert-dblock

[Axel Kielhorn]

Hi Kyle!

Thanks for the quick reaction.

> Am 05.05.2020 um 06:15 schrieb Kyle Meyer <kyle@kyleam.com>:
> 
> As of 34b71a0ca (Add a dispatcher command for inserting dynamic
> blocks, 2018-12-23), the binding was removed and the command is
> available via org-dynamic-block-insert-dblock.
> ---
> doc/orgcard.tex | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/doc/orgcard.tex b/doc/orgcard.tex
> index fa233b620..121a86442 100644
> --- a/doc/orgcard.tex
> +++ b/doc/orgcard.tex
> @@ -513,7 +513,7 @@ \section{Properties and Column View}
> \key{special commands in property lines}{C-c C-c}
> \key{next/previous allowed value}{S-LEFT/RIGHT}
> \key{turn on column view}{C-c C-x C-c}
> -\key{capture columns view in dynamic block}{C-c C-x i}
> +\key{capture columns view in dynamic block}{C-c C-x}

That should be {C-c C-x x}

Orgcard.tex still has 
\key{insert/update table with clock report}{C-c C-x C-r}

that should be:

\key{insert/update table with clock report}{C-c C-x x}

Everything else is fine.

Greetings 
Axel

Re: [PATCH 2/4] orgcard: Update binding for org-columns-insert-dblock

[Kyle Meyer]

Axel Kielhorn writes:

>> diff --git a/doc/orgcard.tex b/doc/orgcard.tex
>> index fa233b620..121a86442 100644
>> --- a/doc/orgcard.tex
>> +++ b/doc/orgcard.tex
>> @@ -513,7 +513,7 @@ \section{Properties and Column View}
>> \key{special commands in property lines}{C-c C-c}
>> \key{next/previous allowed value}{S-LEFT/RIGHT}
>> \key{turn on column view}{C-c C-x C-c}
>> -\key{capture columns view in dynamic block}{C-c C-x i}
>> +\key{capture columns view in dynamic block}{C-c C-x}
>
> That should be {C-c C-x x}

Oops, thanks for catching my typo.

> Orgcard.tex still has 
> \key{insert/update table with clock report}{C-c C-x C-r}
>
> that should be:
>
> \key{insert/update table with clock report}{C-c C-x x}

Guh, I'm not sure how I botched my search for that last night.  Thanks.

Re: [PATCH 0/4] dynamic block-related fixes

[Kyle Meyer]

Pushed with fixes for the orgcard issues Axel noted and dropping the
notmuch message ID prefix that I unintentionally included in two commit
messages.


Range-diff:

1:  6f990dbc4 ! 1:  861ffb313 manual: Remove stale information about dynamic block bindings
    @@ Commit message
         for inserting dynamic blocks, 2018-12-23).
     
         Reported-by: Axel Kielhorn <org-mode@axelkielhorn.de>
    -    <id:3CE37EF0-6C7A-4CC0-AFEE-2B82296D63E1@axelkielhorn.de>
    +    <3CE37EF0-6C7A-4CC0-AFEE-2B82296D63E1@axelkielhorn.de>
     
      ## doc/org-manual.org ##
     @@ doc/org-manual.org: *** Capturing column view
2:  4ef9d38f5 ! 2:  c53ff9b25 orgcard: Update binding for org-columns-insert-dblock
    @@ doc/orgcard.tex: \section{Properties and Column View}
      \key{next/previous allowed value}{S-LEFT/RIGHT}
      \key{turn on column view}{C-c C-x C-c}
     -\key{capture columns view in dynamic block}{C-c C-x i}
    -+\key{capture columns view in dynamic block}{C-c C-x}
    ++\key{capture columns view in dynamic block}{C-c C-x x}
      
      \key{quit column view}{q}
      \key{show full value}{v}
    +@@ doc/orgcard.tex: \section{Timestamps}
    + \key{stop/cancel clock on current item}{C-c C-x C-o/x}
    + \key{display total subtree times}{C-c C-x C-d}
    + \key{remove displayed times}{C-c C-c}
    +-\key{insert/update table with clock report}{C-c C-x C-r}
    ++\key{insert/update table with clock report}{C-c C-x C-x}
    + 
    + \section{Agenda Views}
    + 
3:  fcbc16a5f ! 3:  8368c38e0 Autoload dynamic block definitions
    @@ Commit message
         associated library is loaded.
     
         Reported-by: Axel Kielhorn <org-mode@axelkielhorn.de>
    -    <id:3CE37EF0-6C7A-4CC0-AFEE-2B82296D63E1@axelkielhorn.de>
    +    <3CE37EF0-6C7A-4CC0-AFEE-2B82296D63E1@axelkielhorn.de>
     
      ## lisp/org-clock.el ##
     @@ lisp/org-clock.el: (defun org-clock-report (&optional arg)
4:  79d13a221 = 4:  f4fed7ea0 org: Retain prefix arg when dispatching dynamic block commands

Re: Manual 7.5.3 Capturing column view outdated

[Bastien]

Hi Axel,

Axel Kielhorn <org-mode@axelkielhorn.de> writes:

> while exchanging mails with Uwe Brauer I discovered some errors in
> the manual:

just a note to say it has been fixed by Kyle a while ago:
https://code.orgmode.org/bzg/org-mode/commit/861ffb31

Sorry if a confirmation has already been sent, I could not find it in
the list.

-- 
 Bastien

Re: Manual 7.5.3 Capturing column view outdated

[Kyle Meyer]

Bastien writes:

> Axel Kielhorn <org-mode@axelkielhorn.de> writes:
>
>> while exchanging mails with Uwe Brauer I discovered some errors in
>> the manual:
>
> just a note to say it has been fixed by Kyle a while ago:
> https://code.orgmode.org/bzg/org-mode/commit/861ffb31
>
> Sorry if a confirmation has already been sent, I could not find it in
> the list.

Downstream of the message to which you've replied, there were a few
patches along with a review by Axel.  I'm not sure why they're not
showing up on your end, but I can see them in the places I've checked:

  https://lists.gnu.org/archive/html/emacs-orgmode/2020-05/msg00042.html
  https://yhetil.org/orgmode/3CE37EF0-6C7A-4CC0-AFEE-2B82296D63E1@axelkielhorn.de/T/#u
  gmane.io nntp via Gnus

Anyway, thanks for pointing to the commit.  It's better to have extra
confirmation than no confirmation :)