X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=src%2Flibpspp%2Fi18n.h;h=8f3113d47715b97da567bb309f25860c8237d11f;hb=fb3464df9f4cf3926cfa6aea00a5010d78ce0d70;hp=d41ef1ef2c80046f15d84404db542a038e072c5a;hpb=9eb07d79cfaa5a147a708df832c9c9164be4c312;p=pspp

diff --git a/src/libpspp/i18n.h b/src/libpspp/i18n.h
index d41ef1ef2c..8f3113d477 100644
--- a/src/libpspp/i18n.h
+++ b/src/libpspp/i18n.h
@@ -17,6 +17,115 @@
 #ifndef I18N_H
 #define I18N_H
 
+/*
+
+  PSPP has three ``working'' locales:
+
+  * The user interface locale.
+
+    This is the locale which is visible to the person using pspp.  Error
+    messages and confidence indications are written in this locale.  For
+    example ``Cannot open file'' will be written in the user interface locale.
+
+    This locale is set from the environment of the user who starts PSPP or from
+    the system locale if not set.
+
+  * The output locale.
+
+    This locale should be visible to the person reading a report generated by
+    pspp.  Non-data related strings (e.g., "Page number", "Standard Deviation"
+    etc.) appear in this locale.
+
+  * The data locale.
+
+    Only the character encoding is relevant.
+
+    This locale is the one associated with the data being analysed.  The only
+    important aspect of this locale is the character encoding.  (It might also
+    be desirable for the LC_COLLATE category to be used for the purposes of
+    sorting data.)  The dictionary pertaining to the data contains a field
+    denoting the encoding.  Any string data stored in a "union value" is
+    encoded in the dictionary's character set.
+
+  Each of these locales may, at different times take separate (or identical)
+  values.  So for example, a French statistician can use pspp to prepare a
+  report in the English language, using a datafile which has been created by a
+  Japanese researcher hence uses a Japanese character set.
+
+  It's rarely, if ever, necessary to interrogate the system to find out the
+  values of the 3 locales.  However it's important to be aware of the source
+  (destination) locale when reading (writing) string data.  When transferring
+  data between a source and a destination, the appropriate recoding must be
+  performed.
+
+  System Files
+  ============
+
+  '.sav' files contain a field which is supposed to identify the encoding of
+  the data they contain.  However, many files produced by early versions of
+  spss set this to "2" (ASCII) regardless of the encoding of the data.  Later
+  versions contain an additional record (the "Character Encoding Record")
+  describing the encoding.  When a system file is read, the dictionary's
+  encoding is set using information gleaned from the system file.  If the
+  encoding cannot be determined or would be unreliable, then it remains unset.
+
+  GUI
+  ===
+
+  The psppire graphic user interface is written using the GTK+ api, for which
+  all strings must be encoded in UTF-8.  All strings passed to the GTK+/GLib
+  library functions (except for filenames) must be UTF-8 encoded otherwise
+  errors will occur.  Thus, for the purposes of programming PSPPIRE, the user
+  interface locale should be assumed to be UTF-8, even if setlocale() and/or
+  nl_langinfo indicates otherwise.
+
+  Filenames
+  ---------
+
+  The GLib API has some special functions for dealing with filenames.  Strings
+  returned from functions like gtk_file_chooser_dialog_get_name() are not, in
+  general, encoded in UTF-8, but in "filename" encoding.  If that filename is
+  passed to another GLib function which expects a filename, no conversion is
+  necessary.  If it's passed to a function for the purposes of displaying it
+  (e.g. in a window's title-bar) it must be converted to UTF-8 (there is a
+  special function for this: g_filename_display_name or g_filename_basename).
+  If however, a filename needs to be passed outside of GTK+/GLib, e.g.  to
+  fopen, it must be converted to the local system encoding.
+
+  Existing Locale Handling Functions
+  ==================================
+
+  The major aspect of locale handling which the programmer has to consider is
+  that of character encoding.  recode_string() is the main function for
+  changing the encoding of strings.
+
+  To minimise the number of conversions required, and to simplify design, PSPP
+  attempts to store all internal strings in UTF-8 encoding.  Thus, when reading
+  system and portable files (or any other data source), the following items are
+  immediately converted to UTF-8
+
+  * Variable names
+  * Variable labels
+  * Value labels
+
+  Conversely, when writing system files, these are converted back to the
+  encoding of that system file.
+
+  String data stored in "union value"s are left in their original encoding.
+  These are converted for display later by data_out().
+
+  Quirks
+  ======
+
+  For historical reasons, not all locale handling follows POSIX conventions.
+  This makes it difficult (impossible?) to elegantly handle issues.  For
+  example, it would make sense for the GUI's datasheet to display numbers
+  formatted according to LC_NUMERIC.  Instead however there is data_out(),
+  which uses settings_get_decimal_char() function instead of the locale's
+  decimal separator.  Similarly, formatting of monetary values is displayed in
+  a PSPP/SPSS-specific fashion instead of using LC_MONETARY.
+*/
+
 #include "libpspp/compiler.h"
 #include "libpspp/str.h"
 #include <stdbool.h>