Description:
------------
the preg_match documentation and its relatives assume that the reader knows what all the special characters mean that make up a possible regular expression. I know that "everybody" knows perl -- except that a lot of people don't, and I know that "everybody" uses regular expressions, except that I wouldn't know if a perl regular expression would be the same as a lex regular expression.

PS. your obsoleted regular expression functions are well documented. but those regular expressions don't work here, so I presume something has changed, although I wouldn't know what.

PPS. when I was googling for answers, I found somebody who said that an ! meant something about an assertion, but neither he nor I understood what that might mean. 

Reproduce code:
---------------
---
From manual page: function.preg-match
---
@^(?:http://)?([^/]+)@i

Expected result:
----------------
The man page says that I should expect this to match on the domain name part of a url.

What I expected was some place that said 
@ means .......
^ means .......
( means .......
and so on.

Actual result:
--------------
confusion. The examples don't mean much when you don't know what the special characters mean.