[BUG] Creating sparse tree with regexp property matches

[BUG] Creating sparse tree with regexp property matches

[Cassio Koshikumo]

Hello all,

I think there's a bug with `org-make-tags-matcher' when creating a sparse tree
using property matching with regular expressions and "or" terms. Take the
example given in the manual:

  +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2
       +With={Sarah|Denny}+SCHEDULED>="<2008-10-11>"

If we isolate just this part:

  +With={Sarah|Denny}

The resulting sparse tree does not match the right
headings. The function generates the following `tagsmatcher':

(progn
  (setq org-cached-props nil)
  (or
   (and
    (member
     #("Denny" 0 5
       (regexp t))
     tags-list))
   (and
    (member "With" tags-list))))

There're checks for "Denny" (as a regexp) and "With" (as a string) --- this is
supposed to be the property name, not a search term. They are both checked for
in `tags-list'. And, finally, "Sarah" is nowhere to be seen.

The problem, as far as I can tell, is that splitting the input at `|' to get the
`orterms' does not work with the regular expression the function uses to find
the constituent parts of each term. In this example, splitting the input at `|'
makes one side get the opening brace and the other the closing brace, while the
regexp expects both being present. Since the regexp doesn't fully match, the
terms are all parsed wrong. (The function doesn't recognize "With" as property
name, for instance.) I'm still messing with it but, for now, don't really know
how to fix the problem. I don't 100% understand the function yet...

Regards,

-- 
Cassio

Re: [BUG] Creating sparse tree with regexp property matches

[Daniel Fleischer]

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

On Wed, Aug 25 2021, Cassio Koshikumo wrote:
> Hello all,
>
> I think there's a bug with `org-make-tags-matcher' when creating a sparse tree
> using property matching with regular expressions and "or" terms. Take the
> example given in the manual:
>
>   +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2
>        +With={Sarah|Denny}+SCHEDULED>="<2008-10-11 Sat>"
>
> If we isolate just this part:
>
>   +With={Sarah|Denny}
>
> The resulting sparse tree does not match the right
> headings. The function generates the following `tagsmatcher':
>
> (progn
>   (setq org-cached-props nil)
>   (or
>    (and
>     (member
>      #("Denny" 0 5
>        (regexp t))
>      tags-list))
>    (and
>     (member "With" tags-list))))
>
> There're checks for "Denny" (as a regexp) and "With" (as a string) --- this is
> supposed to be the property name, not a search term. They are both checked for
> in `tags-list'. And, finally, "Sarah" is nowhere to be seen.
>
> The problem, as far as I can tell, is that splitting the input at `|' to get the
> `orterms' does not work with the regular expression the function uses to find
> the constituent parts of each term. In this example, splitting the input at `|'
> makes one side get the opening brace and the other the closing brace, while the
> regexp expects both being present. Since the regexp doesn't fully match, the
> terms are all parsed wrong. (The function doesn't recognize "With" as property
> name, for instance.) I'm still messing with it but, for now, don't really know
> how to fix the problem. I don't 100% understand the function yet...
>
> Regards,

Hi, the solution is that it's elisp based regex, so OR is indicated with
\| instead of just |. It might be good idea to correct the example.

Best,

*Daniel Fleischer*

Re: [BUG] Creating sparse tree with regexp property matches

[Cassio Koshikumo]

Ah! Can't believe I didn't try that. Well, at least the docs can
benefit from my confusion.

Thanks,

On Wed, Aug 25, 2021 at 6:05 PM Daniel Fleischer <danflscr@gmail.com> wrote:
>
> On Wed, Aug 25 2021, Cassio Koshikumo wrote:
> > Hello all,
> >
> > I think there's a bug with `org-make-tags-matcher' when creating a sparse tree
> > using property matching with regular expressions and "or" terms. Take the
> > example given in the manual:
> >
> >   +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2
> >        +With={Sarah|Denny}+SCHEDULED>="<2008-10-11 Sat>"
> >
> > If we isolate just this part:
> >
> >   +With={Sarah|Denny}
> >
> > The resulting sparse tree does not match the right
> > headings. The function generates the following `tagsmatcher':
> >
> > (progn
> >   (setq org-cached-props nil)
> >   (or
> >    (and
> >     (member
> >      #("Denny" 0 5
> >        (regexp t))
> >      tags-list))
> >    (and
> >     (member "With" tags-list))))
> >
> > There're checks for "Denny" (as a regexp) and "With" (as a string) --- this is
> > supposed to be the property name, not a search term. They are both checked for
> > in `tags-list'. And, finally, "Sarah" is nowhere to be seen.
> >
> > The problem, as far as I can tell, is that splitting the input at `|' to get the
> > `orterms' does not work with the regular expression the function uses to find
> > the constituent parts of each term. In this example, splitting the input at `|'
> > makes one side get the opening brace and the other the closing brace, while the
> > regexp expects both being present. Since the regexp doesn't fully match, the
> > terms are all parsed wrong. (The function doesn't recognize "With" as property
> > name, for instance.) I'm still messing with it but, for now, don't really know
> > how to fix the problem. I don't 100% understand the function yet...
> >
> > Regards,
>
> Hi, the solution is that it's elisp based regex, so OR is indicated with
> \| instead of just |. It might be good idea to correct the example.
>
> Best,
>
> *Daniel Fleischer*



-- 
Cassio Koshikumo

Re: [BUG] Creating sparse tree with regexp property matches

[Timothy]

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

Hi Cassio,

> Ah! Can’t believe I didn’t try that. Well, at least the docs can
> benefit from my confusion.

Would you be interested in making a patch for the docs, or would you rather
leave that to someone else?

All the best,
Timothy

Re: [BUG] Creating sparse tree with regexp property matches

[Daniel Fleischer]

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

Timothy [2021-08-31 Tue 19:27]  wrote:

> Hi Cassio,
>
>> Ah! Can’t believe I didn’t try that. Well, at least the docs can
>> benefit from my confusion.
>
> Would you be interested in making a patch for the docs, or would you rather
> leave that to someone else?

Actually I want to do that. I had an idea to add a node (in org)
"reminding" people that all mentions of regex refer to elisp regex,
which could be different than what people usually know (PCRE) and point
them toward the elisp regex node. I think this point can confuse non
technical people when they are starting to use orgmode and there should
be a mention in the org manual. Most notably are the alternation \|
instead of | and \(...\) grouping instead of (...).

Best, 


*Daniel Fleischer*

Re: [BUG] Creating sparse tree with regexp property matches

[Cassio Koshikumo]

Hey, great! I was going to patch the example (was just reading the commit
guidelines) but I'll leave it in your hands then. Thanks!

Best,

On Tue, Aug 31, 2021 at 9:33 AM Daniel Fleischer <danflscr@gmail.com> wrote:
>
> Timothy [2021-08-31 Tue 19:27]  wrote:
>
> > Hi Cassio,
> >
> >> Ah! Can’t believe I didn’t try that. Well, at least the docs can
> >> benefit from my confusion.
> >
> > Would you be interested in making a patch for the docs, or would you rather
> > leave that to someone else?
>
> Actually I want to do that. I had an idea to add a node (in org)
> "reminding" people that all mentions of regex refer to elisp regex,
> which could be different than what people usually know (PCRE) and point
> them toward the elisp regex node. I think this point can confuse non
> technical people when they are starting to use orgmode and there should
> be a mention in the org manual. Most notably are the alternation \|
> instead of | and \(...\) grouping instead of (...).
>
> Best,
>
>
> *Daniel Fleischer*



-- 
Cassio Koshikumo

Re: [BUG] Creating sparse tree with regexp property matches

[Timothy]

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

Hi Daniel,

>> Would you be interested in making a patch for the docs, or would you rather
>> leave that to someone else?
>
> Actually I want to do that. I had an idea to add a node (in org)
> “reminding” people that all mentions of regex refer to elisp regex,
> which could be different than what people usually know (PCRE) and point
> them toward the elisp regex node. I think this point can confuse non
> technical people when they are starting to use orgmode and there should
> be a mention in the org manual. Most notably are the alternation \|
> instead of | and ... grouping instead of (…).

That sounds like it would be most useful! I look forward to seeing your patch 😀.

All the best,
Timothy

Re: [BUG] Creating sparse tree with regexp property matches

[Daniel Fleischer]

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

Hi Timothy,

Attached is my patch. 

Best,

*Daniel Fleischer*

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual-added-section-about-regular-expressions.patch --]
[-- Type: text/x-patch, Size: 7720 bytes --]

From 05602a3eb453672893e7e92cc0384e1b6b7784aa Mon Sep 17 00:00:00 2001
From: Daniel Fleischer <danflscr@gmail.com>
Date: Tue, 31 Aug 2021 20:01:47 +0300
Subject: [PATCH] org-manual: added section about regular expressions

Telling users it's based on Elisp regular expressions, linking to its
info node and putting some links to this new node in places where regexp
are presented.

Signed-off-by: Daniel Fleischer <danflscr@gmail.com>
---
 doc/org-manual.org | 78 ++++++++++++++++++++++++++++------------------
 1 file changed, 47 insertions(+), 31 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 10e0baa28..38884ad72 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -916,16 +916,16 @@ ** Sparse Trees
   #+kindex: C-c / /
   #+findex: org-occur
   #+vindex: org-remove-highlights-with-change
-  Prompts for a regexp and shows a sparse tree with all matches.  If
-  the match is in a headline, the headline is made visible.  If the
-  match is in the body of an entry, headline and body are made
-  visible.  In order to provide minimal context, also the full
-  hierarchy of headlines above the match is shown, as well as the
-  headline following the match.  Each match is also highlighted; the
-  highlights disappear when the buffer is changed by an editing
-  command, or by pressing {{{kbd(C-c C-c)}}}[fn:8].  When called with
-  a {{{kbd(C-u)}}} prefix argument, previous highlights are kept, so
-  several calls to this command can be stacked.
+  Prompts for a regexp (see [[*Regular Expressions]]) and shows a sparse
+  tree with all matches.  If the match is in a headline, the headline
+  is made visible.  If the match is in the body of an entry, headline
+  and body are made visible.  In order to provide minimal context,
+  also the full hierarchy of headlines above the match is shown, as
+  well as the headline following the match.  Each match is also
+  highlighted; the highlights disappear when the buffer is changed by
+  an editing command, or by pressing {{{kbd(C-c C-c)}}}[fn:8].  When
+  called with a {{{kbd(C-u)}}} prefix argument, previous highlights
+  are kept, so several calls to this command can be stacked.
 
 - {{{kbd(M-g n)}}} or {{{kbd(M-g M-n)}}} (~next-error~) ::
 
@@ -3663,10 +3663,10 @@ ** Search Options in File Links
 
 - =/REGEXP/= ::
 
-  Do a regular expression search for {{{var(REGEXP)}}}.  This uses the
-  Emacs command ~occur~ to list all matches in a separate window.  If
-  the target file is in Org mode, ~org-occur~ is used to create
-  a sparse tree with the matches.
+  Do a regular expression search for {{{var(REGEXP)}}} (see [[*Regular
+  Expressions]]).  This uses the Emacs command ~occur~ to list all
+  matches in a separate window.  If the target file is in Org mode,
+  ~org-occur~ is used to create a sparse tree with the matches.
 
 As a degenerate case, a file link with an empty file name can be used
 to search the current file.  For example, =[[file:::find me]]= does
@@ -4978,8 +4978,9 @@ ** Tag Hierarchy
 
 Furthermore, the members of a group tag can also be regular
 expressions, creating the possibility of a more dynamic and rule-based
-tag structure.  The regular expressions in the group must be specified
-within curly brackets.  Here is an expanded example:
+tag structure (see [[*Regular Expressions]]).  The regular expressions in
+the group must be specified within curly brackets.  Here is an
+expanded example:
 
 #+begin_example
 ,#+TAGS: [ Vision : {V@.+} ]
@@ -5321,7 +5322,7 @@ ** Property Searches
   tree is created with all entries that define this property with the
   given value.  If you enclose the value in curly braces, it is
   interpreted as a regular expression and matched against the property
-  values.
+  values (see [[*Regular Expressions]]).
 
 ** Property Inheritance
 :PROPERTIES:
@@ -8913,8 +8914,9 @@ *** Matching tags and properties
 
 #+cindex: regular expressions, with tags search
 Instead of a tag, you may also specify a regular expression enclosed
-in curly braces.  For example, =work+{^boss.*}= matches headlines that
-contain the tag =:work:= and any tag /starting/ with =boss=.
+in curly braces (see [[*Regular Expressions]]).  For example,
+=work+{^boss.*}= matches headlines that contain the tag =:work:= and
+any tag /starting/ with =boss=.
 
 #+cindex: group tags, as regular expressions
 Group tags (see [[*Tag Hierarchy]]) are expanded as regular expressions.
@@ -8954,7 +8956,7 @@ *** Matching tags and properties
 
 #+begin_example
 +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2
-         +With={Sarah|Denny}+SCHEDULED>="<2008-10-11>"
+         +With={Sarah\|Denny}+SCHEDULED>="<2008-10-11>"
 #+end_example
 
 #+texinfo: @noindent
@@ -8984,7 +8986,7 @@ *** Matching tags and properties
 not =boss=, which also have a priority value =A=, a =Coffee= property
 with the value =unlimited=, an =EFFORT= property that is numerically
 smaller than 2, a =With= property that is matched by the regular
-expression =Sarah|Denny=, and that are scheduled on or after October
+expression =Sarah\|Denny=, and that are scheduled on or after October
 11, 2008.
 
 You can configure Org mode to use property inheritance during
@@ -9362,16 +9364,16 @@ **** Filtering in the agenda
 
   selects entries with category =work= and effort estimates below 10
   minutes, and deselects entries with tag =John= or matching the
-  regexp =plot=.  You can leave =+= out if that does not lead to
-  ambiguities.  The sequence of elements is arbitrary.  The filter
-  syntax assumes that there is no overlap between categories and tags.
-  Otherwise, tags take priority.  If you reply to the prompt with the
-  empty string, all filtering is removed.  If a filter is specified,
-  it replaces all current filters.  But if you call the command with
-  a double prefix argument, or if you add an additional =+= (e.g.,
-  =++work=) to the front of the string, the new filter elements are
-  added to the active ones.  A single prefix argument applies the
-  entire filter in a negative sense.
+  regexp =plot= (see [[*Regular Expressions]]).  You can leave =+= out if
+  that does not lead to ambiguities.  The sequence of elements is
+  arbitrary.  The filter syntax assumes that there is no overlap
+  between categories and tags.  Otherwise, tags take priority.  If you
+  reply to the prompt with the empty string, all filtering is removed.
+  If a filter is specified, it replaces all current filters.  But if
+  you call the command with a double prefix argument, or if you add an
+  additional =+= (e.g., =++work=) to the front of the string, the new
+  filter elements are added to the active ones.  A single prefix
+  argument applies the entire filter in a negative sense.
 
 - {{{kbd(|)}}} (~org-agenda-filter-remove-all~) ::
 
@@ -19242,6 +19244,20 @@ ** Summary of In-Buffer Settings
   #+vindex: org-todo-keywords
   These lines set the TODO keywords and their interpretation in the
   current file.  The corresponding variable is ~org-todo-keywords~.
+  
+** Regular Expressions
+:PROPERTIES:
+:DESCRIPTION: Elisp regular expressions.
+:END:
+#+cindex: regular expressions syntax
+#+cindex: regular expressions, in searches
+
+Org, as an Emacs mode, makes use of Elisp regular expressions for
+searching, matching and filtering.  Elisp regular expressions are
+defined in [[info:elisp::Regular Expressions][Regular Expressions]] and have a somewhat different syntax
+then some common standards.  Most notably, alternation is indicated
+using =\|= and matching groups are denoted by =\(...\)=.  For example
+the string =home\|work= denotes either =home= or =work=.
 
 ** Org Syntax
 :PROPERTIES:

base-commit: 1690fbd88f4d55dc0e3c3af44f9fec534e75b601
-- 
2.33.0

Re: [BUG] Creating sparse tree with regexp property matches

[Timothy]

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

Hi Daniel,

Thanks Daniel, I’ve just had a quick read and it looks good to me. If anyone
else has comments this would be a great time to jump in :)

I haven’t seen `[[info:elisp::page]]' links before, it seems like there’s one
other in the manual. Do you know if they work well with the exported forms of
the manual?

Daniel Fleischer <danflscr@gmail.com> writes:

> Hi Timothy,
>
> Attached is my patch.
>
> Best,
>
> *Daniel Fleischer*
>
> [2. text/x-patch; 0001-org-manual-added-section-about-regular-expressions.patch]…

All the best,
Timothy

Re: [BUG] Creating sparse tree with regexp property matches

[Daniel Fleischer]

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

Timothy [2021-09-01 Wed 18:28]  wrote:

> Hi Daniel,
>
> Thanks Daniel, I’ve just had a quick read and it looks good to me. If anyone
> else has comments this would be a great time to jump in :)
>
> I haven’t seen `<info:elisp::page>' links before, it seems like there’s one
> other in the manual. Do you know if they work well with the exported forms of
> the manual?
>

There's actually another link with a bit different format:
<info:elisp#Invisible Text> 

Testing it: in the PDF it doesn't do anything but in the compiled HTML
file it leads to the right section. In Emacs obviously it will jump
correctly to the info node.

I did "discover" Emacs regular expression node which I think is
friendlier than Elisp's (and contains it) so I'll replace the link; see
Daniel Fleischer

[PATCH] Re: [BUG] Creating sparse tree with regexp property matches

[Daniel Fleischer]

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

Attached is a patch with improvement to documentation regarding regular expressions.

Best,

Daniel Fleischer

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual-added-section-about-regular-expressions.patch --]
[-- Type: text/x-patch, Size: 7673 bytes --]

From d3d1dcbc5f62ea111e7bcd1741114cae6b1280c5 Mon Sep 17 00:00:00 2001
From: Daniel Fleischer <danflscr@gmail.com>
Date: Tue, 31 Aug 2021 20:01:47 +0300
Subject: [PATCH] org-manual: added section about regular expressions

Telling users it's based on Elisp regular expressions, linking to its
info node and putting some links to this new node in places where regexp
are presented.

Signed-off-by: Daniel Fleischer <danflscr@gmail.com>
---
 doc/org-manual.org | 80 ++++++++++++++++++++++++++++------------------
 1 file changed, 49 insertions(+), 31 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 10e0baa28..02eaa10f2 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -916,16 +916,16 @@ ** Sparse Trees
   #+kindex: C-c / /
   #+findex: org-occur
   #+vindex: org-remove-highlights-with-change
-  Prompts for a regexp and shows a sparse tree with all matches.  If
-  the match is in a headline, the headline is made visible.  If the
-  match is in the body of an entry, headline and body are made
-  visible.  In order to provide minimal context, also the full
-  hierarchy of headlines above the match is shown, as well as the
-  headline following the match.  Each match is also highlighted; the
-  highlights disappear when the buffer is changed by an editing
-  command, or by pressing {{{kbd(C-c C-c)}}}[fn:8].  When called with
-  a {{{kbd(C-u)}}} prefix argument, previous highlights are kept, so
-  several calls to this command can be stacked.
+  Prompts for a regexp (see [[*Regular Expressions]]) and shows a sparse
+  tree with all matches.  If the match is in a headline, the headline
+  is made visible.  If the match is in the body of an entry, headline
+  and body are made visible.  In order to provide minimal context,
+  also the full hierarchy of headlines above the match is shown, as
+  well as the headline following the match.  Each match is also
+  highlighted; the highlights disappear when the buffer is changed by
+  an editing command, or by pressing {{{kbd(C-c C-c)}}}[fn:8].  When
+  called with a {{{kbd(C-u)}}} prefix argument, previous highlights
+  are kept, so several calls to this command can be stacked.
 
 - {{{kbd(M-g n)}}} or {{{kbd(M-g M-n)}}} (~next-error~) ::
 
@@ -3663,10 +3663,10 @@ ** Search Options in File Links
 
 - =/REGEXP/= ::
 
-  Do a regular expression search for {{{var(REGEXP)}}}.  This uses the
-  Emacs command ~occur~ to list all matches in a separate window.  If
-  the target file is in Org mode, ~org-occur~ is used to create
-  a sparse tree with the matches.
+  Do a regular expression search for {{{var(REGEXP)}}} (see [[*Regular
+  Expressions]]).  This uses the Emacs command ~occur~ to list all
+  matches in a separate window.  If the target file is in Org mode,
+  ~org-occur~ is used to create a sparse tree with the matches.
 
 As a degenerate case, a file link with an empty file name can be used
 to search the current file.  For example, =[[file:::find me]]= does
@@ -4978,8 +4978,9 @@ ** Tag Hierarchy
 
 Furthermore, the members of a group tag can also be regular
 expressions, creating the possibility of a more dynamic and rule-based
-tag structure.  The regular expressions in the group must be specified
-within curly brackets.  Here is an expanded example:
+tag structure (see [[*Regular Expressions]]).  The regular expressions in
+the group must be specified within curly brackets.  Here is an
+expanded example:
 
 #+begin_example
 ,#+TAGS: [ Vision : {V@.+} ]
@@ -5321,7 +5322,7 @@ ** Property Searches
   tree is created with all entries that define this property with the
   given value.  If you enclose the value in curly braces, it is
   interpreted as a regular expression and matched against the property
-  values.
+  values (see [[*Regular Expressions]]).
 
 ** Property Inheritance
 :PROPERTIES:
@@ -8913,8 +8914,9 @@ *** Matching tags and properties
 
 #+cindex: regular expressions, with tags search
 Instead of a tag, you may also specify a regular expression enclosed
-in curly braces.  For example, =work+{^boss.*}= matches headlines that
-contain the tag =:work:= and any tag /starting/ with =boss=.
+in curly braces (see [[*Regular Expressions]]).  For example,
+=work+{^boss.*}= matches headlines that contain the tag =:work:= and
+any tag /starting/ with =boss=.
 
 #+cindex: group tags, as regular expressions
 Group tags (see [[*Tag Hierarchy]]) are expanded as regular expressions.
@@ -8954,7 +8956,7 @@ *** Matching tags and properties
 
 #+begin_example
 +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2
-         +With={Sarah|Denny}+SCHEDULED>="<2008-10-11>"
+         +With={Sarah\|Denny}+SCHEDULED>="<2008-10-11>"
 #+end_example
 
 #+texinfo: @noindent
@@ -8984,7 +8986,7 @@ *** Matching tags and properties
 not =boss=, which also have a priority value =A=, a =Coffee= property
 with the value =unlimited=, an =EFFORT= property that is numerically
 smaller than 2, a =With= property that is matched by the regular
-expression =Sarah|Denny=, and that are scheduled on or after October
+expression =Sarah\|Denny=, and that are scheduled on or after October
 11, 2008.
 
 You can configure Org mode to use property inheritance during
@@ -9362,16 +9364,16 @@ **** Filtering in the agenda
 
   selects entries with category =work= and effort estimates below 10
   minutes, and deselects entries with tag =John= or matching the
-  regexp =plot=.  You can leave =+= out if that does not lead to
-  ambiguities.  The sequence of elements is arbitrary.  The filter
-  syntax assumes that there is no overlap between categories and tags.
-  Otherwise, tags take priority.  If you reply to the prompt with the
-  empty string, all filtering is removed.  If a filter is specified,
-  it replaces all current filters.  But if you call the command with
-  a double prefix argument, or if you add an additional =+= (e.g.,
-  =++work=) to the front of the string, the new filter elements are
-  added to the active ones.  A single prefix argument applies the
-  entire filter in a negative sense.
+  regexp =plot= (see [[*Regular Expressions]]).  You can leave =+= out if
+  that does not lead to ambiguities.  The sequence of elements is
+  arbitrary.  The filter syntax assumes that there is no overlap
+  between categories and tags.  Otherwise, tags take priority.  If you
+  reply to the prompt with the empty string, all filtering is removed.
+  If a filter is specified, it replaces all current filters.  But if
+  you call the command with a double prefix argument, or if you add an
+  additional =+= (e.g., =++work=) to the front of the string, the new
+  filter elements are added to the active ones.  A single prefix
+  argument applies the entire filter in a negative sense.
 
 - {{{kbd(|)}}} (~org-agenda-filter-remove-all~) ::
 
@@ -19242,6 +19244,22 @@ ** Summary of In-Buffer Settings
   #+vindex: org-todo-keywords
   These lines set the TODO keywords and their interpretation in the
   current file.  The corresponding variable is ~org-todo-keywords~.
+  
+** Regular Expressions
+:PROPERTIES:
+:DESCRIPTION: Elisp regular expressions.
+:END:
+#+cindex: regular expressions syntax
+#+cindex: regular expressions, in searches
+
+Org, as an Emacs mode, makes use of Elisp regular expressions for
+searching, matching and filtering.  Elisp regular expressions have a
+somewhat different syntax then some common standards.  Most notably,
+alternation is indicated using =\|= and matching groups are denoted by
+=\(...\)=.  For example the string =home\|work= matches either =home=
+or =work=.
+
+For more information, see [[info:emacs::Regexps][Regular Expressions in Emacs]].
 
 ** Org Syntax
 :PROPERTIES:
-- 
2.33.0

Re: [PATCH] Re: [BUG] Creating sparse tree with regexp property matches

[Daniel Fleischer]

> Attached is a patch with improvement to documentation regarding regular expressions.

Hi, how do I get the patch approved/committed to org?

-- 

Daniel Fleischer

Re: [PATCH] Re: [BUG] Creating sparse tree with regexp property matches

[Timothy]

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

Hi Daniel,

Thanks for bumping your patch, unfortunately many of us (people who can push to
Org) seem to be stretched a bit thin as of late. I’ve just gone over it, it
reads well IMO and I think looking at the non-trivial changes in your patch it’s
possible to charitably interpret this as <=15 non-trivial lines changed. I’ve
applied this as 6600dc09 on Org master with a tweaked commit message 🙂.

Documentation is vital to communicating what Org offers to users, so thanks
again for going to the effort to clear up a possible point of confusion. Should
you wish to make any further contributions (which would be great!) it would be
very helpful if you could get FSF assignment (see
<https://orgmode.org/contribute.html>), as we can’t accept more than 15 lines of
non-trivial lines as an FSF project.

All the best,
Timothy

Re: [PATCH] Re: [BUG] Creating sparse tree with regexp property matches

[Daniel Fleischer]

Timothy <tecosaur@gmail.com> writes:

> Thanks for bumping your patch, unfortunately many of us (people who can push to
> Org) seem to be stretched a bit thin as of late. I’ve just gone over it, it
> reads well IMO and I think looking at the non-trivial changes in your patch it’s
> possible to charitably interpret this as <=15 non-trivial lines changed. I’ve
> applied this as 6600dc09 on Org master with a tweaked commit message 🙂.
>
> Documentation is vital to communicating what Org offers to users, so thanks
> again for going to the effort to clear up a possible point of confusion. Should
> you wish to make any further contributions (which would be great!) it would be
> very helpful if you could get FSF assignment (see
> <https://orgmode.org/contribute.html>), as we can’t accept more than 15 lines of
> non-trivial lines as an FSF project.

Thanks Timothy for pushing this. I just received my FSF assignment so
looking forward to contributing more.

Best,

-- 

Daniel Fleischer