libstdc++-v3/doc/xml/manual/messages.xml

   1 <section xmlns="http://docbook.org/ns/docbook" version="5.0"
   2          xml:id="manual.localization.facet.messages" xreflabel="Messages">
   3 <?dbhtml filename="messages.html"?>
   4
   5 <info><title>messages</title>
   6   <keywordset>
   7     <keyword>
   8       ISO C++
   9     </keyword>
  10     <keyword>
  11       messages
  12     </keyword>
  13   </keywordset>
  14 </info>
  15
  16
  17
  18 <para>
  19 The std::messages facet implements message retrieval functionality
  20 equivalent to Java's java.text.MessageFormat .using either GNU gettext
  21 or IEEE 1003.1-200 functions.
  22 </para>
  23
  24 <section xml:id="facet.messages.req"><info><title>Requirements</title></info>
  25
  26
  27 <para>
  28 The std::messages facet is probably the most vaguely defined facet in
  29 the standard library. It's assumed that this facility was built into
  30 the standard library in order to convert string literals from one
  31 locale to the other. For instance, converting the "C" locale's
  32 <code>const char* c = "please"</code> to a German-localized <code>"bitte"</code>
  33 during program execution.
  34 </para>
  35
  36 <blockquote>
  37 <para>
  38 22.2.7.1 - Template class messages [lib.locale.messages]
  39 </para>
  40 </blockquote>
  41
  42 <para>
  43 This class has three public member functions, which directly
  44 correspond to three protected virtual member functions.
  45 </para>
  46
  47 <para>
  48 The public member functions are:
  49 </para>
  50
  51 <para>
  52 <code>catalog open(const string&amp;, const locale&amp;) const</code>
  53 </para>
  54
  55 <para>
  56 <code>string_type get(catalog, int, int, const string_type&amp;) const</code>
  57 </para>
  58
  59 <para>
  60 <code>void close(catalog) const</code>
  61 </para>
  62
  63 <para>
  64 While the virtual functions are:
  65 </para>
  66
  67 <para>
  68 <code>catalog do_open(const string&amp;, const locale&amp;) const</code>
  69 </para>
  70 <blockquote>
  71 <para>
  72 <emphasis>
  73 -1- Returns: A value that may be passed to get() to retrieve a
  74 message, from the message catalog identified by the string name
  75 according to an implementation-defined mapping. The result can be used
  76 until it is passed to close().  Returns a value less than 0 if no such
  77 catalog can be opened.
  78 </emphasis>
  79 </para>
  80 </blockquote>
  81
  82 <para>
  83 <code>string_type do_get(catalog, int, int, const string_type&amp;) const</code>
  84 </para>
  85 <blockquote>
  86 <para>
  87 <emphasis>
  88 -3- Requires: A catalog cat obtained from open() and not yet closed.
  89 -4- Returns: A message identified by arguments set, msgid, and dfault,
  90 according to an implementation-defined mapping. If no such message can
  91 be found, returns dfault.
  92 </emphasis>
  93 </para>
  94 </blockquote>
  95
  96 <para>
  97 <code>void do_close(catalog) const</code>
  98 </para>
  99 <blockquote>
 100 <para>
 101 <emphasis>
 102 -5- Requires: A catalog cat obtained from open() and not yet closed.
 103 -6- Effects: Releases unspecified resources associated with cat.
 104 -7- Notes: The limit on such resources, if any, is implementation-defined.
 105 </emphasis>
 106 </para>
 107 </blockquote>
 108
 109
 110 </section>
 111
 112 <section xml:id="facet.messages.design"><info><title>Design</title></info>
 113
 114
 115 <para>
 116 A couple of notes on the standard.
 117 </para>
 118
 119 <para>
 120 First, why is <code>messages_base::catalog</code> specified as a typedef
 121 to int? This makes sense for implementations that use
 122 <code>catopen</code> and define <code>nl_catd</code> as int, but not for
 123 others. Fortunately, it's not heavily used and so only a minor irritant.
 124 This has been reported as a possible defect in the standard (LWG 2028).
 125 </para>
 126
 127 <para>
 128 Second, by making the member functions <code>const</code>, it is
 129 impossible to save state in them. Thus, storing away information used
 130 in the 'open' member function for use in 'get' is impossible. This is
 131 unfortunate.
 132 </para>
 133
 134 <para>
 135 The 'open' member function in particular seems to be oddly
 136 designed. The signature seems quite peculiar. Why specify a <code>const
 137 string&amp; </code> argument, for instance, instead of just <code>const
 138 char*</code>? Or, why specify a <code>const locale&amp;</code> argument that is
 139 to be used in the 'get' member function? How, exactly, is this locale
 140 argument useful? What was the intent? It might make sense if a locale
 141 argument was associated with a given default message string in the
 142 'open' member function, for instance. Quite murky and unclear, on
 143 reflection.
 144 </para>
 145
 146 <para>
 147 Lastly, it seems odd that messages, which explicitly require code
 148 conversion, don't use the codecvt facet. Because the messages facet
 149 has only one template parameter, it is assumed that ctype, and not
 150 codecvt, is to be used to convert between character sets.
 151 </para>
 152
 153 <para>
 154 It is implicitly assumed that the locale for the default message
 155 string in 'get' is in the "C" locale. Thus, all source code is assumed
 156 to be written in English, so translations are always from "en_US" to
 157 other, explicitly named locales.
 158 </para>
 159
 160 </section>
 161
 162 <section xml:id="facet.messages.impl"><info><title>Implementation</title></info>
 163
 164
 165   <section xml:id="messages.impl.models"><info><title>Models</title></info>
 166
 167   <para>
 168     This is a relatively simple class, on the face of it. The standard
 169     specifies very little in concrete terms, so generic
 170     implementations that are conforming yet do very little are the
 171     norm. Adding functionality that would be useful to programmers and
 172     comparable to Java's java.text.MessageFormat takes a bit of work,
 173     and is highly dependent on the capabilities of the underlying
 174     operating system.
 175   </para>
 176
 177   <para>
 178     Three different mechanisms have been provided, selectable via
 179     configure flags:
 180   </para>
 181
 182 <itemizedlist>
 183    <listitem>
 184      <para>
 185        generic
 186      </para>
 187      <para>
 188        This model does very little, and is what is used by default.
 189      </para>
 190    </listitem>
 191
 192    <listitem>
 193      <para>
 194        gnu
 195      </para>
 196      <para>
 197        The gnu model is complete and fully tested. It's based on the
 198        GNU gettext package, which is part of glibc. It uses the
 199        functions <code>textdomain, bindtextdomain, gettext</code> to
 200        implement full functionality. Creating message catalogs is a
 201        relatively straight-forward process and is lightly documented
 202        below, and fully documented in gettext's distributed
 203        documentation.
 204      </para>
 205    </listitem>
 206
 207    <listitem>
 208      <para>
 209        ieee_1003.1-200x
 210      </para>
 211      <para>
 212        This is a complete, though untested, implementation based on
 213        the IEEE standard. The functions <code>catopen, catgets,
 214        catclose</code> are used to retrieve locale-specific messages
 215        given the appropriate message catalogs that have been
 216        constructed for their use. Note, the script <code>
 217        po2msg.sed</code> that is part of the gettext distribution can
 218        convert gettext catalogs into catalogs that
 219        <code>catopen</code> can use.
 220    </para>
 221    </listitem>
 222 </itemizedlist>
 223
 224 <para>
 225 A new, standards-conformant non-virtual member function signature was
 226 added for 'open' so that a directory could be specified with a given
 227 message catalog. This simplifies calling conventions for the gnu
 228 model.
 229 </para>
 230
 231   </section>
 232
 233   <section xml:id="messages.impl.gnu"><info><title>The GNU Model</title></info>
 234
 235
 236   <para>
 237     The messages facet, because it is retrieving and converting
 238     between characters sets, depends on the ctype and perhaps the
 239     codecvt facet in a given locale. In addition, underlying "C"
 240     library locale support is necessary for more than just the
 241     <code>LC_MESSAGES</code> mask: <code>LC_CTYPE</code> is also
 242     necessary. To avoid any unpleasantness, all bits of the "C" mask
 243     (i.e. <code>LC_ALL</code>) are set before retrieving messages.
 244   </para>
 245
 246   <para>
 247     Making the message catalogs can be initially tricky, but become
 248     quite simple with practice. For complete info, see the gettext
 249     documentation. Here's an idea of what is required:
 250   </para>
 251
 252 <itemizedlist>
 253    <listitem>
 254      <para>
 255        Make a source file with the required string literals that need
 256        to be translated. See <code>intl/string_literals.cc</code> for
 257        an example.
 258      </para>
 259    </listitem>
 260
 261    <listitem>
 262      <para>
 263        Make initial catalog (see "4 Making the PO Template File" from
 264        the gettext docs).</para>
 265    <para>
 266    <code> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code>
 267    </para>
 268    </listitem>
 269
 270    <listitem>
 271      <para>Make language and country-specific locale catalogs.</para>
 272    <para>
 273    <code>cp libstdc++.pot fr_FR.po</code>
 274    </para>
 275    <para>
 276    <code>cp libstdc++.pot de_DE.po</code>
 277    </para>
 278    </listitem>
 279
 280    <listitem>
 281      <para>
 282        Edit localized catalogs in emacs so that strings are
 283        translated.
 284      </para>
 285    <para>
 286    <code>emacs fr_FR.po</code>
 287    </para>
 288    </listitem>
 289
 290    <listitem>
 291      <para>Make the binary mo files.</para>
 292    <para>
 293    <code>msgfmt fr_FR.po -o fr_FR.mo</code>
 294    </para>
 295    <para>
 296    <code>msgfmt de_DE.po -o de_DE.mo</code>
 297    </para>
 298    </listitem>
 299
 300    <listitem>
 301      <para>Copy the binary files into the correct directory structure.</para>
 302    <para>
 303    <code>cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++.mo</code>
 304    </para>
 305    <para>
 306    <code>cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++.mo</code>
 307    </para>
 308    </listitem>
 309
 310    <listitem>
 311      <para>Use the new message catalogs.</para>
 312    <para>
 313    <code>locale loc_de("de_DE");</code>
 314    </para>
 315    <para>
 316    <code>
 317    use_facet&lt;messages&lt;char&gt; &gt;(loc_de).open("libstdc++", locale(), dir);
 318    </code>
 319    </para>
 320    </listitem>
 321 </itemizedlist>
 322
 323   </section>
 324 </section>
 325
 326 <section xml:id="facet.messages.use"><info><title>Use</title></info>
 327
 328  <para>
 329    A simple example using the GNU model of message conversion.
 330  </para>
 331
 332 <programlisting>
 333 #include &lt;iostream&gt;
 334 #include &lt;locale&gt;
 335 using namespace std;
 336
 337 void test01()
 338 {
 339   typedef messages&lt;char&gt;::catalog catalog;
 340   const char* dir =
 341   "/mnt/egcs/build/i686-pc-linux-gnu/libstdc++/po/share/locale";
 342   const locale loc_de("de_DE");
 343   const messages&lt;char&gt;&amp; mssg_de = use_facet&lt;messages&lt;char&gt; &gt;(loc_de);
 344
 345   catalog cat_de = mssg_de.open("libstdc++", loc_de, dir);
 346   string s01 = mssg_de.get(cat_de, 0, 0, "please");
 347   string s02 = mssg_de.get(cat_de, 0, 0, "thank you");
 348   cout &lt;&lt; "please in german:" &lt;&lt; s01 &lt;&lt; '\n';
 349   cout &lt;&lt; "thank you in german:" &lt;&lt; s02 &lt;&lt; '\n';
 350   mssg_de.close(cat_de);
 351 }
 352 </programlisting>
 353
 354 </section>
 355
 356 <section xml:id="facet.messages.future"><info><title>Future</title></info>
 357
 358
 359 <itemizedlist>
 360 <listitem>
 361   <para>
 362     Things that are sketchy, or remain unimplemented:
 363   </para>
 364    <itemizedlist>
 365       <listitem>
 366         <para>
 367           _M_convert_from_char, _M_convert_to_char are in flux,
 368           depending on how the library ends up doing character set
 369           conversions. It might not be possible to do a real character
 370           set based conversion, due to the fact that the template
 371           parameter for messages is not enough to instantiate the
 372           codecvt facet (1 supplied, need at least 2 but would prefer
 373           3).
 374         </para>
 375       </listitem>
 376
 377       <listitem>
 378         <para>
 379           There are issues with gettext needing the global locale set
 380           to extract a message. This dependence on the global locale
 381           makes the current "gnu" model non MT-safe. Future versions
 382           of glibc, i.e. glibc 2.3.x will fix this, and the C++ library
 383           bits are already in place.
 384         </para>
 385       </listitem>
 386    </itemizedlist>
 387 </listitem>
 388
 389 <listitem>
 390   <para>
 391     Development versions of the GNU "C" library, glibc 2.3 will allow
 392     a more efficient, MT implementation of std::messages, and will
 393     allow the removal of the _M_name_messages data member. If this is
 394     done, it will change the library ABI. The C++ parts to support
 395     glibc 2.3 have already been coded, but are not in use: once this
 396     version of the "C" library is released, the marked parts of the
 397     messages implementation can be switched over to the new "C"
 398     library functionality.
 399   </para>
 400 </listitem>
 401 <listitem>
 402   <para>
 403     At some point in the near future, std::numpunct will probably use
 404     std::messages facilities to implement truename/falsename
 405     correctly. This is currently not done, but entries in
 406     libstdc++.pot have already been made for "true" and "false" string
 407     literals, so all that remains is the std::numpunct coding and the
 408     configure/make hassles to make the installed library search its
 409     own catalog. Currently the libstdc++.mo catalog is only searched
 410     for the testsuite cases involving messages members.
 411   </para>
 412 </listitem>
 413
 414 <listitem>
 415   <para> The following member functions:</para>
 416
 417    <para>
 418    <code>
 419         catalog
 420         open(const basic_string&lt;char&gt;&amp; __s, const locale&amp; __loc) const
 421    </code>
 422    </para>
 423
 424    <para>
 425    <code>
 426    catalog
 427    open(const basic_string&lt;char&gt;&amp;, const locale&amp;, const char*) const;
 428    </code>
 429    </para>
 430
 431    <para>
 432    Don't actually return a "value less than 0 if no such catalog
 433    can be opened" as required by the standard in the "gnu"
 434    model. As of this writing, it is unknown how to query to see
 435    if a specified message catalog exists using the gettext
 436    package.
 437    </para>
 438 </listitem>
 439 </itemizedlist>
 440
 441 </section>
 442
 443 <bibliography xml:id="facet.messages.biblio"><info><title>Bibliography</title></info>
 444
 445
 446   <biblioentry>
 447     <citetitle>
 448       The GNU C Library
 449     </citetitle>
 450     <author><personname><surname>McGrath</surname><firstname>Roland</firstname></personname></author>
 451     <author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author>
 452     <copyright>
 453       <year>2007</year>
 454       <holder>FSF</holder>
 455     </copyright>
 456     <pagenums>Chapters 6 Character Set Handling, and 7 Locales and Internationalization
 457     </pagenums>
 458   </biblioentry>
 459
 460   <biblioentry>
 461     <citetitle>
 462       Correspondence
 463     </citetitle>
 464     <author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author>
 465     <copyright>
 466       <year>2002</year>
 467       <holder/>
 468     </copyright>
 469   </biblioentry>
 470
 471   <biblioentry>
 472     <citetitle>
 473       ISO/IEC 14882:1998 Programming languages - C++
 474     </citetitle>
 475     <copyright>
 476       <year>1998</year>
 477       <holder>ISO</holder>
 478     </copyright>
 479   </biblioentry>
 480
 481   <biblioentry>
 482     <citetitle>
 483       ISO/IEC 9899:1999 Programming languages - C
 484     </citetitle>
 485
 486     <copyright>
 487       <year>1999</year>
 488       <holder>ISO</holder>
 489     </copyright>
 490   </biblioentry>
 491
 492   <biblioentry>
 493       <title>
 494         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 495               xlink:href="http://www.opengroup.org/austin">
 496       System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
 497         </link>
 498       </title>
 499         <copyright>
 500       <year>2008</year>
 501       <holder>
 502         The Open Group/The Institute of Electrical and Electronics
 503         Engineers, Inc.
 504       </holder>
 505     </copyright>
 506   </biblioentry>
 507
 508   <biblioentry>
 509     <citetitle>
 510       The C++ Programming Language, Special Edition
 511     </citetitle>
 512     <author><personname><surname>Stroustrup</surname><firstname>Bjarne</firstname></personname></author>
 513     <copyright>
 514       <year>2000</year>
 515       <holder>Addison Wesley, Inc.</holder>
 516     </copyright>
 517     <pagenums>Appendix D</pagenums>
 518     <publisher>
 519       <publishername>
 520         Addison Wesley
 521       </publishername>
 522     </publisher>
 523   </biblioentry>
 524
 525   <biblioentry>
 526     <citetitle>
 527       Standard C++ IOStreams and Locales
 528     </citetitle>
 529     <subtitle>
 530       Advanced Programmer's Guide and Reference
 531     </subtitle>
 532     <author><personname><surname>Langer</surname><firstname>Angelika</firstname></personname></author>
 533     <author><personname><surname>Kreft</surname><firstname>Klaus</firstname></personname></author>
 534     <copyright>
 535       <year>2000</year>
 536       <holder>Addison Wesley Longman, Inc.</holder>
 537     </copyright>
 538     <publisher>
 539       <publishername>
 540         Addison Wesley Longman
 541       </publishername>
 542     </publisher>
 543   </biblioentry>
 544
 545   <biblioentry>
 546       <title>
 547         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 548               xlink:href="http://java.sun.com/reference/api/index.html">
 549         API Specifications, Java Platform
 550         </link>
 551       </title>
 552
 553     <pagenums>java.util.Properties, java.text.MessageFormat,
 554 java.util.Locale, java.util.ResourceBundle
 555     </pagenums>
 556   </biblioentry>
 557
 558
 559   <biblioentry>
 560       <title>
 561         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 562               xlink:href="http://www.gnu.org/software/gettext">
 563       GNU gettext tools, version 0.10.38, Native Language Support
 564       Library and Tools.
 565         </link>
 566       </title>
 567
 568   </biblioentry>
 569
 570 </bibliography>
 571
 572 </section>