Revision: 857
http://vcs.pcre.org/viewvc?view=rev&revision=857
Author: ph10
Date: 2012-01-07 17:39:10 +0000 (Sat, 07 Jan 2012)
Log Message:
-----------
Documentation.
Modified Paths:
--------------
code/trunk/NEWS
code/trunk/doc/pcrebuild.3
Modified: code/trunk/NEWS
===================================================================
--- code/trunk/NEWS 2012-01-07 17:02:55 UTC (rev 856)
+++ code/trunk/NEWS 2012-01-07 17:39:10 UTC (rev 857)
@@ -5,11 +5,25 @@
------------
Release 8.30 introduces a major new feature: support for 16-bit character
-strings, compiled as a separate library. There are no new features in the 8-bit
-library, but some bugs have been mended. However, note that the pcre_info()
-function, which has been obsolete for over 10 years, has been removed.
+strings, compiled as a separate library. There are a few changes to the
+8-bit library, in addition to some bug fixes.
+. The pcre_info() function, which has been obsolete for over 10 years, has
+ been removed.
+. When a compiled pattern was saved to a file and later reloaded on a host
+ with different endianness, PCRE used automatically to swap the bytes in some
+ of the data fields. With the advent of the 16-bit library, where more of this
+ swapping is needed, it is no longer done automatically. Instead, the bad
+ endianness is detected and a specific error is given. The user can then call
+ a new function called pcre_pattern_to_host_byte_order() (or an equivalent
+ 16-bit function) to do the swap.
+
+. In UTF-8 mode, the values 0xd800 to 0xdfff are not legal Unicode
+ code points and are now faulted. (They are the so-called "surrogates"
+ that are reserved for coding high values in UTF-16.)
+
+
Release 8.21 12-Dec-2011
------------------------
Modified: code/trunk/doc/pcrebuild.3
===================================================================
--- code/trunk/doc/pcrebuild.3 2012-01-07 17:02:55 UTC (rev 856)
+++ code/trunk/doc/pcrebuild.3 2012-01-07 17:39:10 UTC (rev 857)
@@ -32,6 +32,27 @@
exists as well, but as it specifies the default, it is not described.
.
.
+.SH "BUILDING 8-BIT and 16-BIT LIBRARIES"
+.rs
+.sp
+By default, a library called \fBlibpcre\fP is built, containing functions that
+take string arguments contained in vectors of bytes, either as single-byte
+characters, or interpreted as UTF-8 strings. You can also build a separate
+library, called \fBlibpcre16\fP, in which strings are contained in vectors of
+16-bit data units and interpreted either as single-unit characters or UTF-16
+strings, by adding
+.sp
+ --enable-pcre16
+.sp
+to the \fBconfigure\fP command. If you do not want the 8-bit library, add
+.sp
+ --disable-pcre8
+.sp
+as well. At least one of the two libraries must be built. Note that the C++ and
+POSIX wrappers are for the 8-bit library only, and that \fBpcregrep\fP is an
+8-bit program. None of these are built if you select only the 16-bit library.
+.
+.
.SH "BUILDING SHARED AND STATIC LIBRARIES"
.rs
.sp
@@ -47,46 +68,53 @@
.SH "C++ SUPPORT"
.rs
.sp
-By default, the \fBconfigure\fP script will search for a C++ compiler and C++
-header files. If it finds them, it automatically builds the C++ wrapper library
-for PCRE. You can disable this by adding
+By default, if the 8-bit library is being built, the \fBconfigure\fP script
+will search for a C++ compiler and C++ header files. If it finds them, it
+automatically builds the C++ wrapper library (which supports only 8-bit
+strings). You can disable this by adding
.sp
--disable-cpp
.sp
to the \fBconfigure\fP command.
.
.
-.SH "UTF-8 SUPPORT"
+.SH "UTF-8 and UTF-16 SUPPORT"
.rs
.sp
-To build PCRE with support for UTF-8 Unicode character strings, add
+To build PCRE with support for UTF Unicode character strings, add
.sp
- --enable-utf8
+ --enable-utf
.sp
-to the \fBconfigure\fP command. Of itself, this does not make PCRE treat
-strings as UTF-8. As well as compiling PCRE with this option, you also have
-have to set the PCRE_UTF8 option when you call the \fBpcre_compile()\fP
-or \fBpcre_compile2()\fP functions.
+to the \fBconfigure\fP command. This setting applies to both libraries, adding
+support for UTF-8 to the 8-bit library and support for UTF-16 to the 16-bit
+library. It is not possible to build one library with UTF support and the other
+without in the same configuration. (For backwards compatibility, --enable-utf8
+is a synonym of --enable-utf.)
.P
-If you set --enable-utf8 when compiling in an EBCDIC environment, PCRE expects
+Of itself, this setting does not make PCRE treat strings as UTF-8 or UTF-16. As
+well as compiling PCRE with this option, you also have have to set the
+PCRE_UTF8 or PCRE_UTF16 option when you call one of the pattern compiling
+functions.
+.P
+If you set --enable-utf when compiling in an EBCDIC environment, PCRE expects
its input to be either ASCII or UTF-8 (depending on the runtime option). It is
not possible to support both EBCDIC and UTF-8 codes in the same version of the
-library. Consequently, --enable-utf8 and --enable-ebcdic are mutually
+library. Consequently, --enable-utf and --enable-ebcdic are mutually
exclusive.
.
.
.SH "UNICODE CHARACTER PROPERTY SUPPORT"
.rs
.sp
-UTF-8 support allows PCRE to process character values greater than 255 in the
-strings that it handles. On its own, however, it does not provide any
+UTF support allows the libraries to process character codepoints up to 0x10ffff
+in the strings that they handle. On its own, however, it does not provide any
facilities for accessing the properties of such characters. If you want to be
able to use the pattern escapes \eP, \ep, and \eX, which refer to Unicode
character properties, you must add
.sp
--enable-unicode-properties
.sp
-to the \fBconfigure\fP command. This implies UTF-8 support, even if you have
+to the \fBconfigure\fP command. This implies UTF support, even if you have
not explicitly requested it.
.P
Including Unicode property support adds around 30K of tables to the PCRE
@@ -168,7 +196,7 @@
.SH "POSIX MALLOC USAGE"
.rs
.sp
-When PCRE is called through the POSIX interface (see the
+When the 8-bit library is called through the POSIX interface (see the
.\" HREF
\fBpcreposix\fP
.\"
@@ -193,14 +221,15 @@
metacharacter). By default, two-byte values are used for these offsets, leading
to a maximum size for a compiled pattern of around 64K. This is sufficient to
handle all but the most gigantic patterns. Nevertheless, some people do want to
-process truyl enormous patterns, so it is possible to compile PCRE to use
+process truly enormous patterns, so it is possible to compile PCRE to use
three-byte or four-byte offsets by adding a setting such as
.sp
--with-link-size=3
.sp
-to the \fBconfigure\fP command. The value given must be 2, 3, or 4. Using
-longer offsets slows down the operation of PCRE because it has to load
-additional bytes when handling them.
+to the \fBconfigure\fP command. The value given must be 2, 3, or 4. For the
+16-bit library, a value of 3 is rounded up to 4. Using longer offsets slows
+down the operation of PCRE because it has to load additional data when handling
+them.
.
.
.SH "AVOIDING EXCESSIVE STACK USAGE"
@@ -301,7 +330,7 @@
to the \fBconfigure\fP command. This setting implies
--enable-rebuild-chartables. You should only use it if you know that you are in
an EBCDIC environment (for example, an IBM mainframe operating system). The
---enable-ebcdic option is incompatible with --enable-utf8.
+--enable-ebcdic option is incompatible with --enable-utf.
.
.
.SH "PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT"
@@ -371,7 +400,7 @@
.SH "SEE ALSO"
.rs
.sp
-\fBpcreapi\fP(3), \fBpcre_config\fP(3).
+\fBpcreapi\fP(3), \fBpcre16\fP, \fBpcre_config\fP(3).
.
.
.SH AUTHOR
@@ -388,6 +417,6 @@
.rs
.sp
.nf
-Last updated: 06 September 2011
-Copyright (c) 1997-2011 University of Cambridge.
+Last updated: 07 January 2012
+Copyright (c) 1997-2012 University of Cambridge.
.fi
