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

   1 <sect1 id="manual.localization.facet.codecvt" xreflabel="codecvt">
   2 <?dbhtml filename="codecvt.html"?>
   3
   4 <sect1info>
   5   <keywordset>
   6     <keyword>
   7       ISO C++
   8     </keyword>
   9     <keyword>
  10       codecvt
  11     </keyword>
  12   </keywordset>
  13 </sect1info>
  14
  15 <title>codecvt</title>
  16
  17 <para>
  18 The standard class codecvt attempts to address conversions between
  19 different character encoding schemes. In particular, the standard
  20 attempts to detail conversions between the implementation-defined wide
  21 characters (hereafter referred to as wchar_t) and the standard type
  22 char that is so beloved in classic <quote>C</quote> (which can now be
  23 referred to as narrow characters.)  This document attempts to describe
  24 how the GNU libstdc++ implementation deals with the conversion between
  25 wide and narrow characters, and also presents a framework for dealing
  26 with the huge number of other encodings that iconv can convert,
  27 including Unicode and UTF8. Design issues and requirements are
  28 addressed, and examples of correct usage for both the required
  29 specializations for wide and narrow characters and the
  30 implementation-provided extended functionality are given.
  31 </para>
  32
  33 <sect2 id="facet.codecvt.req" xreflabel="facet.codecvt.req">
  34 <title>Requirements</title>
  35
  36 <para>
  37 Around page 425 of the C++ Standard, this charming heading comes into view:
  38 </para>
  39
  40 <blockquote>
  41 <para>
  42 22.2.1.5 - Template class codecvt
  43 </para>
  44 </blockquote>
  45
  46 <para>
  47 The text around the codecvt definition gives some clues:
  48 </para>
  49
  50 <blockquote>
  51 <para>
  52 <emphasis>
  53 -1- The class codecvt&lt;internT,externT,stateT&gt; is for use when
  54 converting from one codeset to another, such as from wide characters
  55 to multibyte characters, between wide character encodings such as
  56 Unicode and EUC.
  57 </emphasis>
  58 </para>
  59 </blockquote>
  60
  61 <para>
  62 Hmm. So, in some unspecified way, Unicode encodings and
  63 translations between other character sets should be handled by this
  64 class.
  65 </para>
  66
  67 <blockquote>
  68 <para>
  69 <emphasis>
  70 -2- The stateT argument selects the pair of codesets being mapped between.
  71 </emphasis>
  72 </para>
  73 </blockquote>
  74
  75 <para>
  76 Ah ha! Another clue...
  77 </para>
  78
  79 <blockquote>
  80 <para>
  81 <emphasis>
  82 -3- The instantiations required in the Table ??
  83 (lib.locale.category), namely codecvt&lt;wchar_t,char,mbstate_t&gt; and
  84 codecvt&lt;char,char,mbstate_t&gt;, convert the implementation-defined
  85 native character set. codecvt&lt;char,char,mbstate_t&gt; implements a
  86 degenerate conversion; it does not convert at
  87 all. codecvt&lt;wchar_t,char,mbstate_t&gt; converts between the native
  88 character sets for tiny and wide characters. Instantiations on
  89 mbstate_t perform conversion between encodings known to the library
  90 implementor.  Other encodings can be converted by specializing on a
  91 user-defined stateT type. The stateT object can contain any state that
  92 is useful to communicate to or from the specialized do_convert member.
  93 </emphasis>
  94 </para>
  95 </blockquote>
  96
  97 <para>
  98 At this point, a couple points become clear:
  99 </para>
 100
 101 <para>
 102 One: The standard clearly implies that attempts to add non-required
 103 (yet useful and widely used) conversions need to do so through the
 104 third template parameter, stateT.</para>
 105
 106 <para>
 107 Two: The required conversions, by specifying mbstate_t as the third
 108 template parameter, imply an implementation strategy that is mostly
 109 (or wholly) based on the underlying C library, and the functions
 110 mcsrtombs and wcsrtombs in particular.</para>
 111 </sect2>
 112
 113 <sect2 id="facet.codecvt.design" xreflabel="facet.codecvt.design">
 114 <title>Design</title>
 115
 116 <sect3 id="codecvt.design.wchar_t_size" xreflabel="codecvt.design.wchar_t_size">
 117     <title><type>wchar_t</type> Size</title>
 118
 119     <para>
 120       The simple implementation detail of wchar_t's size seems to
 121       repeatedly confound people. Many systems use a two byte,
 122       unsigned integral type to represent wide characters, and use an
 123       internal encoding of Unicode or UCS2. (See AIX, Microsoft NT,
 124       Java, others.) Other systems, use a four byte, unsigned integral
 125       type to represent wide characters, and use an internal encoding
 126       of UCS4. (GNU/Linux systems using glibc, in particular.) The C
 127       programming language (and thus C++) does not specify a specific
 128       size for the type wchar_t.
 129     </para>
 130
 131     <para>
 132       Thus, portable C++ code cannot assume a byte size (or endianness) either.
 133     </para>
 134   </sect3>
 135
 136 <sect3 id="codecvt.design.unicode" xreflabel="codecvt.design.unicode">
 137   <title>Support for Unicode</title>
 138   <para>
 139     Probably the most frequently asked question about code conversion
 140     is: &quot;So dudes, what's the deal with Unicode strings?&quot;
 141     The dude part is optional, but apparently the usefulness of
 142     Unicode strings is pretty widely appreciated. Sadly, this specific
 143     encoding (And other useful encodings like UTF8, UCS4, ISO 8859-10,
 144     etc etc etc) are not mentioned in the C++ standard.
 145   </para>
 146
 147   <para>
 148     A couple of comments:
 149   </para>
 150
 151   <para>
 152     The thought that all one needs to convert between two arbitrary
 153     codesets is two types and some kind of state argument is
 154     unfortunate. In particular, encodings may be stateless. The naming
 155     of the third parameter as stateT is unfortunate, as what is really
 156     needed is some kind of generalized type that accounts for the
 157     issues that abstract encodings will need. The minimum information
 158     that is required includes:
 159   </para>
 160
 161   <itemizedlist>
 162     <listitem>
 163       <para>
 164         Identifiers for each of the codesets involved in the
 165         conversion. For example, using the iconv family of functions
 166         from the Single Unix Specification (what used to be called
 167         X/Open) hosted on the GNU/Linux operating system allows
 168         bi-directional mapping between far more than the following
 169         tantalizing possibilities:
 170       </para>
 171
 172       <para>
 173         (An edited list taken from <code>`iconv --list`</code> on a
 174         Red Hat 6.2/Intel system:
 175       </para>
 176
 177 <blockquote>
 178 <programlisting>
 179 8859_1, 8859_9, 10646-1:1993, 10646-1:1993/UCS4, ARABIC, ARABIC7,
 180 ASCII, EUC-CN, EUC-JP, EUC-KR, EUC-TW, GREEK-CCIcode, GREEK, GREEK7-OLD,
 181 GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3,
 182 ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8,
 183 ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14,
 184 ISO-8859-15, ISO-10646, ISO-10646/UCS2, ISO-10646/UCS4,
 185 ISO-10646/UTF-8, ISO-10646/UTF8, SHIFT-JIS, SHIFT_JIS, UCS-2, UCS-4,
 186 UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8,
 187 UTF-16, UTF8, UTF16).
 188 </programlisting>
 189 </blockquote>
 190
 191 <para>
 192 For iconv-based implementations, string literals for each of the
 193 encodings (i.e. &quot;UCS-2&quot; and &quot;UTF-8&quot;) are necessary,
 194 although for other,
 195 non-iconv implementations a table of enumerated values or some other
 196 mechanism may be required.
 197 </para>
 198 </listitem>
 199
 200 <listitem><para>
 201  Maximum length of the identifying string literal.
 202 </para></listitem>
 203
 204 <listitem><para>
 205  Some encodings require explicit endian-ness. As such, some kind
 206   of endian marker or other byte-order marker will be necessary. See
 207   &quot;Footnotes for C/C++ developers&quot; in Haible for more information on
 208   UCS-2/Unicode endian issues. (Summary: big endian seems most likely,
 209   however implementations, most notably Microsoft, vary.)
 210 </para></listitem>
 211
 212 <listitem><para>
 213  Types representing the conversion state, for conversions involving
 214   the machinery in the &quot;C&quot; library, or the conversion descriptor, for
 215   conversions using iconv (such as the type iconv_t.)  Note that the
 216   conversion descriptor encodes more information than a simple encoding
 217   state type.
 218 </para></listitem>
 219
 220 <listitem><para>
 221  Conversion descriptors for both directions of encoding. (i.e., both
 222   UCS-2 to UTF-8 and UTF-8 to UCS-2.)
 223 </para></listitem>
 224
 225 <listitem><para>
 226  Something to indicate if the conversion requested if valid.
 227 </para></listitem>
 228
 229 <listitem><para>
 230  Something to represent if the conversion descriptors are valid.
 231 </para></listitem>
 232
 233 <listitem><para>
 234  Some way to enforce strict type checking on the internal and
 235   external types. As part of this, the size of the internal and
 236   external types will need to be known.
 237 </para></listitem>
 238 </itemizedlist>
 239 </sect3>
 240
 241 <sect3 id="codecvt.design.issues" xreflabel="codecvt.design.issues">
 242   <title>Other Issues</title>
 243 <para>
 244 In addition, multi-threaded and multi-locale environments also impact
 245 the design and requirements for code conversions. In particular, they
 246 affect the required specialization codecvt&lt;wchar_t, char, mbstate_t&gt;
 247 when implemented using standard &quot;C&quot; functions.
 248 </para>
 249
 250 <para>
 251 Three problems arise, one big, one of medium importance, and one small.
 252 </para>
 253
 254 <para>
 255 First, the small: mcsrtombs and wcsrtombs may not be multithread-safe
 256 on all systems required by the GNU tools. For GNU/Linux and glibc,
 257 this is not an issue.
 258 </para>
 259
 260 <para>
 261 Of medium concern, in the grand scope of things, is that the functions
 262 used to implement this specialization work on null-terminated
 263 strings. Buffers, especially file buffers, may not be null-terminated,
 264 thus giving conversions that end prematurely or are otherwise
 265 incorrect. Yikes!
 266 </para>
 267
 268 <para>
 269 The last, and fundamental problem, is the assumption of a global
 270 locale for all the &quot;C&quot; functions referenced above. For something like
 271 C++ iostreams (where codecvt is explicitly used) the notion of
 272 multiple locales is fundamental. In practice, most users may not run
 273 into this limitation. However, as a quality of implementation issue,
 274 the GNU C++ library would like to offer a solution that allows
 275 multiple locales and or simultaneous usage with computationally
 276 correct results. In short, libstdc++ is trying to offer, as an
 277 option, a high-quality implementation, damn the additional complexity!
 278 </para>
 279
 280 <para>
 281 For the required specialization codecvt&lt;wchar_t, char, mbstate_t&gt; ,
 282 conversions are made between the internal character set (always UCS4
 283 on GNU/Linux) and whatever the currently selected locale for the
 284 LC_CTYPE category implements.
 285 </para>
 286
 287 </sect3>
 288
 289 </sect2>
 290
 291 <sect2 id="facet.codecvt.impl" xreflabel="facet.codecvt.impl">
 292 <title>Implementation</title>
 293
 294 <para>
 295 The two required specializations are implemented as follows:
 296 </para>
 297
 298 <para>
 299 <code>
 300 codecvt&lt;char, char, mbstate_t&gt;
 301 </code>
 302 </para>
 303 <para>
 304 This is a degenerate (i.e., does nothing) specialization. Implementing
 305 this was a piece of cake.
 306 </para>
 307
 308 <para>
 309 <code>
 310 codecvt&lt;char, wchar_t, mbstate_t&gt;
 311 </code>
 312 </para>
 313
 314 <para>
 315 This specialization, by specifying all the template parameters, pretty
 316 much ties the hands of implementors. As such, the implementation is
 317 straightforward, involving mcsrtombs for the conversions between char
 318 to wchar_t and wcsrtombs for conversions between wchar_t and char.
 319 </para>
 320
 321 <para>
 322 Neither of these two required specializations deals with Unicode
 323 characters. As such, libstdc++ implements a partial specialization
 324 of the codecvt class with and iconv wrapper class, encoding_state as the
 325 third template parameter.
 326 </para>
 327
 328 <para>
 329 This implementation should be standards conformant. First of all, the
 330 standard explicitly points out that instantiations on the third
 331 template parameter, stateT, are the proper way to implement
 332 non-required conversions. Second of all, the standard says (in Chapter
 333 17) that partial specializations of required classes are a-ok. Third
 334 of all, the requirements for the stateT type elsewhere in the standard
 335 (see 21.1.2 traits typedefs) only indicate that this type be copy
 336 constructible.
 337 </para>
 338
 339 <para>
 340 As such, the type encoding_state is defined as a non-templatized, POD
 341 type to be used as the third type of a codecvt instantiation. This
 342 type is just a wrapper class for iconv, and provides an easy interface
 343 to iconv functionality.
 344 </para>
 345
 346 <para>
 347 There are two constructors for encoding_state:
 348 </para>
 349
 350 <para>
 351 <code>
 352 encoding_state() : __in_desc(0), __out_desc(0)
 353 </code>
 354 </para>
 355 <para>
 356 This default constructor sets the internal encoding to some default
 357 (currently UCS4) and the external encoding to whatever is returned by
 358 nl_langinfo(CODESET).
 359 </para>
 360
 361 <para>
 362 <code>
 363 encoding_state(const char* __int, const char* __ext)
 364 </code>
 365 </para>
 366
 367 <para>
 368 This constructor takes as parameters string literals that indicate the
 369 desired internal and external encoding. There are no defaults for
 370 either argument.
 371 </para>
 372
 373 <para>
 374 One of the issues with iconv is that the string literals identifying
 375 conversions are not standardized. Because of this, the thought of
 376 mandating and or enforcing some set of pre-determined valid
 377 identifiers seems iffy: thus, a more practical (and non-migraine
 378 inducing) strategy was implemented: end-users can specify any string
 379 (subject to a pre-determined length qualifier, currently 32 bytes) for
 380 encodings. It is up to the user to make sure that these strings are
 381 valid on the target system.
 382 </para>
 383
 384 <para>
 385 <code>
 386 void
 387 _M_init()
 388 </code>
 389 </para>
 390 <para>
 391 Strangely enough, this member function attempts to open conversion
 392 descriptors for a given encoding_state object. If the conversion
 393 descriptors are not valid, the conversion descriptors returned will
 394 not be valid and the resulting calls to the codecvt conversion
 395 functions will return error.
 396 </para>
 397
 398 <para>
 399 <code>
 400 bool
 401 _M_good()
 402 </code>
 403 </para>
 404
 405 <para>
 406 Provides a way to see if the given encoding_state object has been
 407 properly initialized. If the string literals describing the desired
 408 internal and external encoding are not valid, initialization will
 409 fail, and this will return false. If the internal and external
 410 encodings are valid, but iconv_open could not allocate conversion
 411 descriptors, this will also return false. Otherwise, the object is
 412 ready to convert and will return true.
 413 </para>
 414
 415 <para>
 416 <code>
 417 encoding_state(const encoding_state&amp;)
 418 </code>
 419 </para>
 420
 421 <para>
 422 As iconv allocates memory and sets up conversion descriptors, the copy
 423 constructor can only copy the member data pertaining to the internal
 424 and external code conversions, and not the conversion descriptors
 425 themselves.
 426 </para>
 427
 428 <para>
 429 Definitions for all the required codecvt member functions are provided
 430 for this specialization, and usage of codecvt&lt;internal character type,
 431 external character type, encoding_state&gt; is consistent with other
 432 codecvt usage.
 433 </para>
 434
 435 </sect2>
 436
 437 <sect2 id="facet.codecvt.use" xreflabel="facet.codecvt.use">
 438 <title>Use</title>
 439 <para>A conversions involving string literal.</para>
 440
 441 <programlisting>
 442   typedef codecvt_base::result                  result;
 443   typedef unsigned short                        unicode_t;
 444   typedef unicode_t                             int_type;
 445   typedef char                                  ext_type;
 446   typedef encoding_state                          state_type;
 447   typedef codecvt&lt;int_type, ext_type, state_type&gt; unicode_codecvt;
 448
 449   const ext_type*       e_lit = "black pearl jasmine tea";
 450   int                   size = strlen(e_lit);
 451   int_type              i_lit_base[24] =
 452   { 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184,
 453     27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696,
 454     25856, 24832, 2560
 455   };
 456   const int_type*       i_lit = i_lit_base;
 457   const ext_type*       efrom_next;
 458   const int_type*       ifrom_next;
 459   ext_type*             e_arr = new ext_type[size + 1];
 460   ext_type*             eto_next;
 461   int_type*             i_arr = new int_type[size + 1];
 462   int_type*             ito_next;
 463
 464   // construct a locale object with the specialized facet.
 465   locale                loc(locale::classic(), new unicode_codecvt);
 466   // sanity check the constructed locale has the specialized facet.
 467   VERIFY( has_facet&lt;unicode_codecvt&gt;(loc) );
 468   const unicode_codecvt&amp; cvt = use_facet&lt;unicode_codecvt&gt;(loc);
 469   // convert between const char* and unicode strings
 470   unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1");
 471   initialize_state(state01);
 472   result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next,
 473                      i_arr, i_arr + size, ito_next);
 474   VERIFY( r1 == codecvt_base::ok );
 475   VERIFY( !int_traits::compare(i_arr, i_lit, size) );
 476   VERIFY( efrom_next == e_lit + size );
 477   VERIFY( ito_next == i_arr + size );
 478 </programlisting>
 479
 480 </sect2>
 481
 482 <sect2 id="facet.codecvt.future" xreflabel="facet.codecvt.future">
 483 <title>Future</title>
 484 <itemizedlist>
 485 <listitem>
 486   <para>
 487    a. things that are sketchy, or remain unimplemented:
 488       do_encoding, max_length and length member functions
 489       are only weakly implemented. I have no idea how to do
 490       this correctly, and in a generic manner.  Nathan?
 491 </para>
 492 </listitem>
 493
 494 <listitem>
 495   <para>
 496    b. conversions involving std::string
 497   </para>
 498    <itemizedlist>
 499       <listitem><para>
 500       how should operators != and == work for string of
 501       different/same encoding?
 502       </para></listitem>
 503
 504       <listitem><para>
 505       what is equal? A byte by byte comparison or an
 506       encoding then byte comparison?
 507       </para></listitem>
 508
 509       <listitem><para>
 510       conversions between narrow, wide, and unicode strings
 511       </para></listitem>
 512    </itemizedlist>
 513 </listitem>
 514 <listitem><para>
 515    c. conversions involving std::filebuf and std::ostream
 516 </para>
 517    <itemizedlist>
 518       <listitem><para>
 519       how to initialize the state object in a
 520       standards-conformant manner?
 521       </para></listitem>
 522
 523                 <listitem><para>
 524       how to synchronize the &quot;C&quot; and &quot;C++&quot;
 525       conversion information?
 526       </para></listitem>
 527
 528                 <listitem><para>
 529       wchar_t/char internal buffers and conversions between
 530       internal/external buffers?
 531       </para></listitem>
 532    </itemizedlist>
 533 </listitem>
 534 </itemizedlist>
 535 </sect2>
 536
 537
 538 <bibliography id="facet.codecvt.biblio" xreflabel="facet.codecvt.biblio">
 539 <title>Bibliography</title>
 540
 541   <biblioentry>
 542     <title>
 543       The GNU C Library
 544     </title>
 545
 546     <author>
 547       <surname>McGrath</surname>
 548       <firstname>Roland</firstname>
 549     </author>
 550     <author>
 551       <surname>Drepper</surname>
 552       <firstname>Ulrich</firstname>
 553     </author>
 554
 555     <copyright>
 556       <year>2007</year>
 557       <holder>FSF</holder>
 558     </copyright>
 559     <pagenums>Chapters 6 Character Set Handling and 7 Locales and Internationalization</pagenums>
 560
 561   </biblioentry>
 562
 563   <biblioentry>
 564     <title>
 565       Correspondence
 566     </title>
 567
 568     <author>
 569       <surname>Drepper</surname>
 570       <firstname>Ulrich</firstname>
 571     </author>
 572
 573     <copyright>
 574       <year>2002</year>
 575       <holder></holder>
 576     </copyright>
 577   </biblioentry>
 578
 579   <biblioentry>
 580     <title>
 581       ISO/IEC 14882:1998 Programming languages - C++
 582     </title>
 583
 584     <copyright>
 585       <year>1998</year>
 586       <holder>ISO</holder>
 587     </copyright>
 588   </biblioentry>
 589
 590   <biblioentry>
 591     <title>
 592       ISO/IEC 9899:1999 Programming languages - C
 593     </title>
 594
 595     <copyright>
 596       <year>1999</year>
 597       <holder>ISO</holder>
 598     </copyright>
 599   </biblioentry>
 600
 601   <biblioentry>
 602     <title>
 603       System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
 604     </title>
 605
 606     <copyright>
 607       <year>1999</year>
 608       <holder>
 609       The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder>
 610     </copyright>
 611
 612     <biblioid>
 613       <ulink url="http://www.opennc.org/austin/docreg.html">
 614       </ulink>
 615     </biblioid>
 616
 617   </biblioentry>
 618
 619   <biblioentry>
 620     <title>
 621       The C++ Programming Language, Special Edition
 622     </title>
 623
 624     <author>
 625       <surname>Stroustrup</surname>
 626       <firstname>Bjarne</firstname>
 627     </author>
 628
 629     <copyright>
 630       <year>2000</year>
 631       <holder>Addison Wesley, Inc.</holder>
 632     </copyright>
 633     <pagenums>Appendix D</pagenums>
 634
 635     <publisher>
 636       <publishername>
 637         Addison Wesley
 638       </publishername>
 639     </publisher>
 640
 641   </biblioentry>
 642
 643
 644   <biblioentry>
 645     <title>
 646       Standard C++ IOStreams and Locales
 647     </title>
 648     <subtitle>
 649       Advanced Programmer's Guide and Reference
 650     </subtitle>
 651
 652     <author>
 653       <surname>Langer</surname>
 654       <firstname>Angelika</firstname>
 655     </author>
 656
 657     <author>
 658       <surname>Kreft</surname>
 659       <firstname>Klaus</firstname>
 660     </author>
 661
 662     <copyright>
 663       <year>2000</year>
 664       <holder>Addison Wesley Longman, Inc.</holder>
 665     </copyright>
 666
 667     <publisher>
 668       <publishername>
 669         Addison Wesley Longman
 670       </publishername>
 671     </publisher>
 672
 673   </biblioentry>
 674
 675   <biblioentry>
 676     <title>
 677       A brief description of Normative Addendum 1
 678     </title>
 679
 680     <author>
 681       <surname>Feather</surname>
 682       <firstname>Clive</firstname>
 683     </author>
 684
 685     <pagenums>Extended Character Sets</pagenums>
 686     <biblioid>
 687       <ulink url="http://www.lysator.liu.se/c/na1.html">
 688       </ulink>
 689     </biblioid>
 690
 691   </biblioentry>
 692
 693   <biblioentry>
 694     <title>
 695       The Unicode HOWTO
 696     </title>
 697
 698     <author>
 699       <surname>Haible</surname>
 700       <firstname>Bruno</firstname>
 701     </author>
 702
 703     <biblioid>
 704       <ulink url="ftp://ftp.ilog.fr/pub/Users/haible/utf8/Unicode-HOWTO.html">
 705       </ulink>
 706     </biblioid>
 707
 708   </biblioentry>
 709
 710   <biblioentry>
 711     <title>
 712       UTF-8 and Unicode FAQ for Unix/Linux
 713     </title>
 714
 715     <author>
 716       <surname>Khun</surname>
 717       <firstname>Markus</firstname>
 718     </author>
 719
 720     <biblioid>
 721       <ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">
 722       </ulink>
 723     </biblioid>
 724
 725   </biblioentry>
 726
 727
 728 </bibliography>
 729
 730 </sect1>