[PATCH 1/2] Remove link to Emacs' regexp syntax

[PATCH 1/2] Remove link to Emacs' regexp syntax

[Diogo F. S. Ramos]

Linking to Emacs' regexps as an example of regexp syntax gives the
wrong impression that Guile supports it, which is not true.

* doc/ref/api-regex.texi: Remove link to Emacs' regexp syntax
---
 doc/ref/api-regex.texi | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/doc/ref/api-regex.texi b/doc/ref/api-regex.texi
index 082fb87..f95eddb 100644
--- a/doc/ref/api-regex.texi
+++ b/doc/ref/api-regex.texi
@@ -14,10 +14,7 @@
 
 A @dfn{regular expression} (or @dfn{regexp}) is a pattern that
 describes a whole class of strings.  A full description of regular
-expressions and their syntax is beyond the scope of this manual;
-an introduction can be found in the Emacs manual (@pxref{Regexps,
-, Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or
-in many general Unix reference books.
+expressions and their syntax is beyond the scope of this manual.
 
 If your system does not include a POSIX regular expression library,
 and you have not linked Guile with a third-party regexp library such
-- 
1.9.1

[PATCH 2/2] Add reference to the lack of "non-greedy" variants

[Diogo F. S. Ramos]

While describing special characters, remind the reader that
"non-greedy" variants are not supported.  They might not be familiar
with POSIX extended regular expression and expect it to work.

* doc/ref/api-regex.texi: Add "non-greedy" observation
---
 doc/ref/api-regex.texi | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/doc/ref/api-regex.texi b/doc/ref/api-regex.texi
index f95eddb..b14c2b3 100644
--- a/doc/ref/api-regex.texi
+++ b/doc/ref/api-regex.texi
@@ -38,10 +38,11 @@ regex))}.
 @node Regexp Functions
 @subsection Regexp Functions
 
-By default, Guile supports POSIX extended regular expressions.
-That means that the characters @samp{(}, @samp{)}, @samp{+} and
-@samp{?} are special, and must be escaped if you wish to match the
-literal characters.
+By default, Guile supports POSIX extended regular expressions.  That
+means that the characters @samp{(}, @samp{)}, @samp{+} and @samp{?} are
+special, and must be escaped if you wish to match the literal characters
+and there is no support for ``non-greedy'' variants of @samp{*},
+@samp{+} or @samp{?}.
 
 This regular expression interface was modeled after that
 implemented by SCSH, the Scheme Shell.  It is intended to be
-- 
1.9.1

Re: [PATCH 2/2] Add reference to the lack of "non-greedy" variants

[Taylan Ulrich Bayırlı/Kammer]

"Diogo F. S. Ramos" <dfsr@riseup.net> writes:

> While describing special characters, remind the reader that
> "non-greedy" variants are not supported.  They might not be familiar
> with POSIX extended regular expression and expect it to work.

Going by that logic, might they not expect a lot more?  (Say, if all
they know about regexps is PCRE, for example.)  Intuition says that it's
enough to specify "POSIX extended regular expressions", because they're
a very clearly defined type of regexp.  (Don't be fooled by the word
"extended", POSIX rigorously defines a type of regexp called "extended
regular expressions", aka ERE.)

Taylan

Re: [PATCH 2/2] Add reference to the lack of "non-greedy" variants

[Diogo F. S. Ramos]

> "Diogo F. S. Ramos" <dfsr@riseup.net> writes:
>
>> While describing special characters, remind the reader that
>> "non-greedy" variants are not supported.  They might not be familiar
>> with POSIX extended regular expression and expect it to work.
>
> Going by that logic, might they not expect a lot more?  (Say, if all
> they know about regexps is PCRE, for example.)  Intuition says that it's
> enough to specify "POSIX extended regular expressions", because they're
> a very clearly defined type of regexp.  (Don't be fooled by the word
> "extended", POSIX rigorously defines a type of regexp called "extended
> regular expressions", aka ERE.)

The documentation is already pointing out that some characters are
special, so adding the "non-greedy" observation is not special in this
case and IMO it's an expected feature from regexps.

Your observation makes me think I didn't go far enough.  If users expect
Perl regexps, we should warn them that Guile's is not.

Ultimately, I think Guile should document its own regexp syntax.


These changes have been inspired by the article "Teach, Don't Tell" [1],
and its accompanying texts.  Someone posted it at #guile, but I can't
remember their name now, I'm sorry.

[1]  http://stevelosh.com/blog/2013/09/teach-dont-tell/

Re: [PATCH 2/2] Add reference to the lack of "non-greedy" variants

[Taylan Ulrich Bayırlı/Kammer]

"Diogo F. S. Ramos" <dfsr@riseup.net> writes:

> The documentation is already pointing out that some characters are
> special, so adding the "non-greedy" observation is not special in this
> case and IMO it's an expected feature from regexps.

I'd rather say that *both* the mention of those characters, and the
mention of non-greediness being unsupported, are special cases. :-)

Maybe we should just remove both and only provide a link to the
specification of POSIX ERE, or clarify that "POSIX extended regular
expressions" are a specific type of regexp (and not the possible
misinterpretation which is "an (ad-hoc) extended version of POSIX
regexps") so that users can search for documentation on them by
themselves.

(Many Unix-like systems have a man-page for regexps; IIRC GNU+Linux
distros tend to have a "regex" man-page which describe both POSIX BRE
(Basic RE) and ERE, and I see the three BSDs all have an "re_format"
man-page (linked to by the regex(3) man-page) which also describes those
two.)

By the way I see that the mention of POSIX ERE happens only in section
6.15.1 and not directly in the intro 6.15, which instead misleadingly
links to Emacs regexps.

Also, I never expect non-greediness support from regexps, because I've
"grown up" as a Unix-like OS user and shell scripter, so it's POSIX BRE
(sed, grep) and ERE (grep, awk) for me.  This probably goes for many
people.

> Your observation makes me think I didn't go far enough.  If users
> expect Perl regexps, we should warn them that Guile's is not.
>
> Ultimately, I think Guile should document its own regexp syntax.

Like I said, "POSIX ERE" is an absolute specification.  We might still
want to distribute a copy of it so users can access it more easily, but
on the other hand the manual implies that the supported regexp format
actually depends on what regexp library Guile was compiled with.  (Or am
I misinterpreting paragraph 2 of 6.15 plus paragraph 1 of 6.15.1 which
says "by default"?)

My proposal would be to remove the Emacs link in 6.15, add a paragraph
that has a sole, clear mention of POSIX ERE, and remove the first
paragraph of 6.15.1, or keep its first sentence because it's crucial
information so the redundancy with the preceding section doesn't hurt.

Taylan

Re: [PATCH 2/2] Add reference to the lack of "non-greedy" variants

[Diogo F. S. Ramos]

Does anyone else have an opinion on this and patch 1/2?  Even if it's to
drop them.

Re: [PATCH 2/2] Add reference to the lack of "non-greedy" variants

[Andy Wingo]

Oh my goodness Diogo, this patch and the one before were applied by no
one :( Our bad.  I just applied them, as they are small.  In the future
please nag over IRC, and if you have bigger patches please let's start
the copyright assignment process; find me on IRC to get that done.

We'll try to do better in the future; it would be hard to do worse.

Andy

On Wed 26 Mar 2014 04:27, "Diogo F. S. Ramos" <dfsr@riseup.net> writes:

> While describing special characters, remind the reader that
> "non-greedy" variants are not supported.  They might not be familiar
> with POSIX extended regular expression and expect it to work.
>
> * doc/ref/api-regex.texi: Add "non-greedy" observation
> ---
>  doc/ref/api-regex.texi | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
>
> diff --git a/doc/ref/api-regex.texi b/doc/ref/api-regex.texi
> index f95eddb..b14c2b3 100644
> --- a/doc/ref/api-regex.texi
> +++ b/doc/ref/api-regex.texi
> @@ -38,10 +38,11 @@ regex))}.
>  @node Regexp Functions
>  @subsection Regexp Functions
>  
> -By default, Guile supports POSIX extended regular expressions.
> -That means that the characters @samp{(}, @samp{)}, @samp{+} and
> -@samp{?} are special, and must be escaped if you wish to match the
> -literal characters.
> +By default, Guile supports POSIX extended regular expressions.  That
> +means that the characters @samp{(}, @samp{)}, @samp{+} and @samp{?} are
> +special, and must be escaped if you wish to match the literal characters
> +and there is no support for ``non-greedy'' variants of @samp{*},
> +@samp{+} or @samp{?}.
>  
>  This regular expression interface was modeled after that
>  implemented by SCSH, the Scheme Shell.  It is intended to be