I believe PHP documentation is a place to document PHP, not a tutorial for using regular expressions. Regex syntax or usage has nothing to do with PHP itself. The documentation seems targeted to people who already know regular expressions and focus on how to apply their knowledge to particular regex implementation, as implementations differ slightly between each other.

However, I think that the documentation may be improved by adding some sort of topics list with short descriptions. People may not know all the names ("anchor", "delimiter" etc.) if they were learning regex by practice.

> documentation of regexp is difficult to read:
> - it is separated to several pages. there is no way to search.
> - it is very long, there are irrelevant paragraphs.
> - i did not found a simple syntax diagram.

That is so because PCRE is a very complex (and powerful) library,
and even more so due to its evolving nature (what has to be
documented as well). See also the page "How to find more
information about PHP"[1].

Patches and *concrete* hints to improve the documentation are
welcome (see <http://doc.php.net/tutorial/joining.php>). It is,
however, not really useful to state that the documentation (or a
complete chapter for that matter) is generally bad; that is too
subjective (I've heard otherwise, anyway).

[1] <http://php.net/manual/en/about.more.php>