"Special Properties" when matching for Properties in a search

"Special Properties" when matching for Properties in a search

[Gustav Wikström]

Hi list!

When matching for tags and properties using C-c / m there is the
option to match for Special Properties. Is there a complete list of
these special properties somewhere?

I was thinking that "7.2 Special Properties" in the manual would be
that list, but then noticed a property possible to use for searches,
but not available in that list (the LEVEL-property). Is that property
just missing from there?

/Gustav

Re: "Special Properties" when matching for Properties in a search

[Bastien]

Hi Gustav,

Gustav Wikström <gustav.erik@gmail.com> writes:

> When matching for tags and properties using C-c / m there is the
> option to match for Special Properties. Is there a complete list of
> these special properties somewhere?
>
> I was thinking that "7.2 Special Properties" in the manual would be
> that list, but then noticed a property possible to use for searches,
> but not available in that list (the LEVEL-property). Is that property
> just missing from there?

Mhhh... no, AFAIK the "LEVEL" property is a special-special property:
you can use it in search constructs, but not in column view (which is 
the primary context for the 7.2 manual section.)

But I'd say that's the only property missing here.  I'm short of good
ideas on how to improve the manual here.

-- 
 Bastien

Re: "Special Properties" when matching for Properties in a search

[Gustav Wikström]

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

Ok thanks!

As I brought this up, I might just as well provide a way of clarifying
this for the manual.

On Mon, Jul 1, 2013 at 12:04 AM, Bastien <bzg@gnu.org> wrote:
> Hi Gustav,
>
> Gustav Wikström <gustav.erik@gmail.com> writes:
>
>> When matching for tags and properties using C-c / m there is the
>> option to match for Special Properties. Is there a complete list of
>> these special properties somewhere?
>>
>> I was thinking that "7.2 Special Properties" in the manual would be
>> that list, but then noticed a property possible to use for searches,
>> but not available in that list (the LEVEL-property). Is that property
>> just missing from there?
>
> Mhhh... no, AFAIK the "LEVEL" property is a special-special property:
> you can use it in search constructs, but not in column view (which is
> the primary context for the 7.2 manual section.)
>
> But I'd say that's the only property missing here.  I'm short of good
> ideas on how to improve the manual here.
>
> --
>  Bastien

[-- Attachment #2: manual-diff.txt --]
[-- Type: text/plain, Size: 1695 bytes --]

	Modified   doc/org.texi
diff --git a/doc/org.texi b/doc/org.texi
index 5f50ef6..64553e1 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -8045,15 +8045,18 @@ You may also test for properties (@pxref{Properties and Columns}) at the same
 time as matching tags.  The properties may be real properties, or special
 properties that represent other metadata (@pxref{Special properties}).  For
 example, the ``property'' @code{TODO} represents the TODO keyword of the
-entry.  Or, the ``property'' @code{LEVEL} represents the level of an entry.
-So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines
-that have the tag @samp{boss} and are @emph{not} marked with the TODO keyword
-DONE@.  In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not
-count the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
-The ITEM special property cannot currently be used in tags/property
+entry and the ``propety'' @code{PRIORITY} represents the PRIORITY keyword of
+the entry.  The ITEM special property cannot currently be used in tags/property
 searches@footnote{But @pxref{x-agenda-skip-entry-regexp,
 ,skipping entries based on regexp}.}.

+Except the @pxref{Special properties}, one other ``property'' can also be
+used. @code{LEVEL} represents the level of an entry. So a search
+@samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines that have
+the tag @samp{boss} and are @emph{not} marked with the TODO keyword DONE@.
+In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not count
+the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
+
 Here are more examples:

 @table @samp

Re: "Special Properties" when matching for Properties in a search

[Bastien]

Hi Gustav,

Gustav Wikström <gustav.erik@gmail.com> writes:

> As I brought this up, I might just as well provide a way of clarifying
> this for the manual.

Applied, thanks.

-- 
 Bastien

Re: "Special Properties" when matching for Properties in a search

[Nick Dokos]

Gustav Wikström <gustav.erik@gmail.com> writes:

> When matching for tags and properties using C-c / m there is the
> option to match for Special Properties. Is there a complete list of
> these special properties somewhere?
>

The section you found in the manual and the value of
org-special-properties would seem the logical places to look for such a
complete list.

However, there are some discrepancies in the two. There seem to be some
"very special" properties that are mentioned in the doc but not in the
variable.

> I was thinking that "7.2 Special Properties" in the manual would be
> that list, but then noticed a property possible to use for searches,
> but not available in that list (the LEVEL-property). Is that property
> just missing from there?
>

I think so: LEVEL is mentioned in neither place, although it is
mentioned in sec. 10.3.3, "Matching tags and properties, which I presume
is where you found it. It should probably be added to sec. 7.2, and
maybe added to org-special-properties.

Here's my census of special properties from these three places:

--8<---------------cut here---------------start------------->8---
* Special properties

| Name         | doc sec. 7.2 | org-special-properties | other places     |
|--------------+--------------+------------------------+------------------|
| ID           | yes          | no                     |                  |
| TODO         | yes          | yes                    | yes (sec 10.3.3) |
| TAGS         | yes          | yes                    |                  |
| ALLTAGS      | yes          | yes                    |                  |
| CATEGORY     | yes          | no                     | yes (sec 10.3.3) |
| PRIORITY     | yes          | yes                    | yes (sec 10.3.3) |
| DEADLINE     | yes          | yes                    | yes (sec 10.3.3) |
| SCHEDULED    | yes          | yes                    | yes (sec 10.3.3) |
| CLOSED       | yes          | yes                    |                  |
| TIMESTAMP    | yes          | yes                    |                  |
| TIMESTAMP_IA | yes          | yes                    |                  |
| CLOCKSUM     | yes          | yes                    |                  |
| CLOCKSUM_T   | yes          | yes                    |                  |
| BLOCKED      | yes          | yes                    |                  |
| ITEM         | yes          | no                     | yes (sec 10.3.3) |
| FILE         | yes          | yes                    |                  |
| LEVEL        | no           | no                     | yes (sec 10.3.3) |
--8<---------------cut here---------------end--------------->8---

Are there others? Should org-special-properties include them all?

-- 
Nick