== Documenting the Unicode support for PHP 6 ==

Due to the massive amount of documentation changes required for
documenting the Unicode support in PHP 6, we need a plan for adding
all this text:

[1] A new role
========================

A new role named unicode with the DocBook XML as follows:

<refsect1 role="unicode">
&reftitle.unicode;
<para>
Information specific to unicode goes here.
</para>
</refsect1>

[2] Placement of this role
========================

This information seems important enough to be placed above either
the examples or changelog. Suggested order is as follows:

description
parameters
returnvalues
exceptions
unicode
changelog
examples
notes
seealso

[3] Placement of "Added in PHP 6"
========================

This information should go into a CHANGELOG. It may seem like
common knowledge that this Unicode support was added in PHP 6 but
it may not be for a casual PHP 4/5 user of the manual page. For
this reason it is recommended that all these manual pages have a
changelog role that includes this information.

[4] A new section: features/unicode.xml
========================

This detailed unicode features section will do the following:

(a) Briefly describe what unicode is
(b) Explain what this feature means to us, the PHP users
(c) Provide basic example uses
(d) Link to various offsite resources, like the Unicode standard

And within each unicode role (for each function) link to this unicode
features section as "further information"

[5] Update related sections
========================

The manual currently has similar/related topics, refer to this support
in the following locations (likely others):

(a) Extensions: mbstring, iconv
(b) Migration from PHP 5 to PHP 6
(c) FAQ
(d) Update the ref.unicode

[6] Track the progress
========================

How we do this is unknown at this time. Could be done via the wiki.

[7] New Doc Style
========================

Since this role is part of the "new doc style" each manual page must
use the new style before the unicode documentation is added to said
function. Consider a huge push to convert the entire manual to the
new style beforehand.

Progress of this conversion can be seen here:

<a href="http://wiki.phpdoc.info/DocSkel/MigrationStatus">http://wiki.phpdoc.info/DocSkel/MigrationStatus</a>

[8] Only modify special behaviors

Only touch a functions documentation if it has some special behavior
in unicode mode (namely the string handling functions), but we don't
need to add a note for "easy" functions like tidy_get_release(), bc_*(),
gmp_*() and so on.