Suggested manual changes - section 7.2 Special Properties

Suggested manual changes - section 7.2 Special Properties

[Tommy Kelly]

After figuring out, with help on Reddit (ht: Adam), some nuances
affecting timestamps, column
mode, and the Special Properties TIMESTAMP, and TIMESTAMP_IA, I think
the following
modifications to section 7.2 (Special Properties) of the manual would
be worthwhile.

As it stands, the relevant part reads as follows:
'TIMESTAMP'     The first keyword-less timestamp in the entry.
'TIMESTAMP_IA'  The first inactive timestamp in the entry.

Both are slightly incorrect and that can be fixed by changing to the following:
'TIMESTAMP'     The first inactive keyword-less timestamp in the entry.
'TIMESTAMP_IA'  The first inactive keyword-less timestamp in the entry.

In addition, the following three clarifying details would be useful
(the last of them is required)
perhaps as a footnote:

For both TIMESTAMP and TIMESTAMP_IA: the word "first" refers to the
first occurrence in the entry, not the earliest in time; the prefix
'CLOCK:' at the beginning of a clock entry is considered a keyword in
this context; and timestamps inside property drawers are ignored.

regards.

P.S. I'm not familiar enough with the various moving parts to provide
the above as a proper
git patch. However, FWIW, I did the following. I modified a local copy
of org-manual.org and then I ensured that at least a PDF export
(produced using 'C-c C-e l p', but only the section
in question) looked sensible. Then I produced a diff-based patch file.
Here it is, in case its
of any use:

#### START OF PATCHFILE ####
--- work/git/org-mode/doc/org-manual.org        2022-10-06 11:49:32
+++ org-manual-changed.org      2024-01-27 22:44:36
@@ -5353,8 +5353,8 @@
 | =PRIORITY=     | The priority of the entry, a string with a single
letter.      |
 | =SCHEDULED=    | The scheduling timestamp.
            |
 | =TAGS=         | The tags defined directly in the headline.
            |
-| =TIMESTAMP=    | The first keyword-less timestamp in the entry.
            |
-| =TIMESTAMP_IA= | The first inactive timestamp in the entry.
            |
+| =TIMESTAMP=    | The first active keyword-less timestamp in the
entry.[fn::For both TIMESTAMP and TIMESTAMP_IA: the word "first"
refers to the first occurrence in the entry, not the earliest in time;
the prefix 'CLOCK:' at the beginning of a clock entry is considered a
keyword in this context; and timestamps inside property drawers are
ignored.]          |
+| =TIMESTAMP_IA= | The first inactive keyword-less timestamp in the
entry.        |
 | =TODO=         | The TODO keyword of the entry.
            |

  ** Property Searches
#### END OF PATCHFILE ####

Re: Suggested manual changes - section 7.2 Special Properties

[Tommy Kelly]

I wrote:
> As it stands, the relevant part reads as follows:
> 'TIMESTAMP'     The first keyword-less timestamp in the entry.
> 'TIMESTAMP_IA'  The first inactive timestamp in the entry.
>
> Both are slightly incorrect and that can be fixed by changing to the following:
> 'TIMESTAMP'     The first inactive keyword-less timestamp in the entry.
> 'TIMESTAMP_IA'  The first inactive keyword-less timestamp in the entry.

Sigh. My correction for TIMESTAMP was itself, of course, incorrect! It
should have been:

'TIMESTAMP'     The first active keyword-less timestamp in the entry.

The patchfile I provided did not have that error.
-

Re: Suggested manual changes - section 7.2 Special Properties

[Matt]

Thank you for your suggestions.  Unfortunately, I'm not yet familiar with this part of Org.  Can you give a link to the Reddit thread where this was discussed?

--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode

Re: Suggested manual changes - section 7.2 Special Properties

[Tommy Kelly]

[-- Attachment #1: Type: text/plain, Size: 1018 bytes --]

> Can you give a link to the Reddit thread
> where this was discussed?

It’s here:
https://www.reddit.com/r/orgmode/s/3viPfF78Lr

In a nutshell, I was trying to understand how to have one of the columns in
column mode be the creation date of each headline. I thought that because I
almost always insert a clock entry when I create (using org-capture) a new
item then I already had the required timestamp — the first one in the clock
entry. However, it turns out that timestamp isn’t usable, and so the thread
was me looking for help in figuring out the best way to do it.

—


On Sun, Jan 28, 2024 at 02:39 Matt <matt@excalamus.com> wrote:

> Thank you for your suggestions.  Unfortunately, I'm not yet familiar with
> this part of Org.  Can you give a link to the Reddit thread where this was
> discussed?
>
> --
> Matt Trzcinski
> Emacs Org contributor (ob-shell)
> Learn more about Org mode at https://orgmode.org
> Support Org development at https://liberapay.com/org-mode
>
>

[-- Attachment #2: Type: text/html, Size: 2665 bytes --]

Re: Suggested manual changes - section 7.2 Special Properties

[Matt]

Ihor, I think this would be a good topic to go over in the monthly meet up, especially if no one is able to follow up further on this by then.

 ---- On Mon, 29 Jan 2024 04:37:33 +0100  Tommy Kelly  wrote --- 

 > It’s here: https://www.reddit.com/r/orgmode/s/3viPfF78Lr
 > In a nutshell, I was trying to understand how to have one of the columns in column mode be the creation date of each headline. I thought that because I almost always insert a clock entry when I create (using org-capture) a new item then I already had the required timestamp — the first one in the clock entry. However, it turns out that timestamp isn’t usable, and so the thread was me looking for help in figuring out the best way to do it.

Thank you very much.  

Unfortunately, my knowledge of this part of Org isn't enough to give meaningful feedback at the moment.

I should also say that I appreciate the effort and thoughtfulness you've put into this.  Definite bonus points :)  If I'm able to find the time to read up on this part of Org, I'd be happy  to work with you further on this.

--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode

Re: Suggested manual changes - section 7.2 Special Properties

[Ihor Radchenko]

Tommy Kelly <tommy.kelly@verilab.com> writes:

> After figuring out, with help on Reddit (ht: Adam), some nuances
> affecting timestamps, column
> mode, and the Special Properties TIMESTAMP, and TIMESTAMP_IA, I think
> the following
> modifications to section 7.2 (Special Properties) of the manual would
> be worthwhile.
> ....
> #### START OF PATCHFILE ####

Applied, onto main, with minor markup amendments.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=055ed4a2f
Thanks for your contribution!

You are now listed as an Org contributor.
https://git.sr.ht/~bzg/worg/commit/9c26ec3e

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Suggested manual changes - section 7.2 Special Properties

[Ihor Radchenko]

Tommy Kelly <tommy.kelly@verilab.com> writes:

> It’s here:
> https://www.reddit.com/r/orgmode/s/3viPfF78Lr
>
> In a nutshell, I was trying to understand how to have one of the columns in
> column mode be the creation date of each headline. I thought that because I
> almost always insert a clock entry when I create (using org-capture) a new
> item then I already had the required timestamp — the first one in the clock
> entry. However, it turns out that timestamp isn’t usable, and so the thread
> was me looking for help in figuring out the best way to do it.

Column view is currently not flexible enough to retrieve data that is
not a known property from property drawer or from special properties.

In theory, we might modify `org-columns--collect-values' to allow
user-defined special properties.

This might be something similar to `org-columns-summary-types', but to
allow custom functions that retrieve property value.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>