210update.txt

Updating packages for 2.1.0
===========================

Package maintainers should be aware of the following changes scheduled
to appear in 2.1.0 sometime in April 2005.


1) It is possible to run R in UTF-8 and other non-European locales.
   This necessitates some changes to packages that use other than
   ASCII character strings, even for personal names.  The principal
   difference is that in UTF-8 more that one byte may be needed to
   represent a character, and indeed all non-ASCII characters need at
   least two.  On the other hand, ASCII characters can only occur as
   themselves and never as part of multi-byte sequences: the latter is
   not the case in some Asian locales.

   - .Rd pages with non-ASCII strings (often personal names) should
     declare the encoding via \encoding.

  -  Other text documentation, especially the DESCRIPTION file, should
     use ASCII only if possible, and failing that Latin-1 (and not,
     say, UTF-8).

  -  R code should be ASCII.  Do not use non-ASCII characters in
     object names, for example, for if someone runs your package
     in the C locale it will fail.

  -  Names in data objects (e.g. in .rda files) are problematic.  It
     is likely that by release time these will be treated as in
     Latin-1.

  -  C code that does character-by-character access can request an
     particular encoding via the ENCODING= argument to .C.  However,
     this is not guaranteed to honoured but is likely to be so in
     multi-byte character encodings such as UTF-8.


2) There is now support for the translation of	C and R warning/error
   messages.  See the new section in `Writing R Extensions' on
   guidelines for writing such messages to make them translatable.

   Error/warning messages in C code need to be marked for translation
   as described in `Writing R Extensions'.  Unless your package has a
   namespace, R stop/warning() messages need a 'domain' argument
   added, and in any package unnecessary uses of paste() need to be
   removed or explicit calls to gettext() added.




Graphics Devices
================

This section applies to graphics devices in packages.  The standard
package 'grDevices' and the X11 device in src/modules/X11 provide
reference examples.

a) There is a new graphics engine API version for tracking changes
   to the graphics API in <R_ext/GraphicsEngine.h> and 
   <R_ext/GraphicsDevice.h>.

   As a minimum, a call to R_GE_checkVersionOrDie(R_GE_version) 
   should be added to device start-up code, which means that an 
   error will be generated if the package is run on an R 
   installation with a different graphics API version.

   More sophisticated handling of version mismatches is possible
   by calling R_GE_getVersion() to obtain the graphics API 
   version for the R session.

b) Ensure that the NewDevDesc structure is allocated with calloc(), or
   otherwise zeroed so that unused elements are null pointers.

c) R can be run in multi-byte locales such as Linux UTF-8 locales and
   Japanese versions of Windows.  In such locales

   - the text string passed to the device's strWidth and text functions
     may be a multibyte string and will need to be interpreted correctly
     (except for the symbol face 5, in Adobe Symbol encoding as now).

   - the character number passed to the metricinfo function may be a
     number greater than 255 giving the Unicode code point of the
     character/glyph required.

Support for these extensions can be conditionalized at compile time by
SUPPORT_MBCS (defined in Rconfig.h) and at run time by the Rboolean
extern mbcslocale.  If it is necessary to handle UTF-8 locales
separately, use the Rboolean extern utf8locale.