<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
     <!ENTITY % local SYSTEM "local.ent">
     %local;
     <!ENTITY % entities SYSTEM "entities.ent">
     %entities;
     <!ENTITY % idcommon SYSTEM "common/common.ent">
     %idcommon;
]>
<refentry id="yaz-iconv">
 <refentryinfo>
  <productname>YAZ</productname>
  <productnumber>&version;</productnumber>
  <orgname>Index Data</orgname>
 </refentryinfo>

 <refmeta>
  <refentrytitle>yaz-iconv</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="manual">Commands</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>yaz-iconv</refname>
  <refpurpose>YAZ Character set conversion utility</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>yaz-iconv</command>
   <arg choice="opt"><option>-f <replaceable>from</replaceable></option></arg>
   <arg choice="opt"><option>-t <replaceable>to</replaceable></option></arg>
   <arg choice="opt"><option>-v</option></arg>
   <arg choice="opt" rep="repeat">file</arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1><title>DESCRIPTION</title>
  <para>
   <command>yaz-iconv</command> converts data in the character
   set specified by <replaceable>from</replaceable> to output in
   the character set as specified by <replaceable>to</replaceable>.
  </para>
  <para>
   This <command>yaz-iconv</command> utility is similar to the
   <command>iconv</command> found on many POSIX systems (Glibc, Solaris, etc).
  </para>
  <para>
   If no <replaceable>file</replaceable> is specified,
   <command>yaz-iconv</command> reads from standard input.
  </para>
 </refsect1>

 <refsect1><title>OPTIONS</title>

  <variablelist>
   <varlistentry>
    <term>-f<replaceable>from</replaceable>]</term>
    <listitem><para>
      Specify the character set <replaceable>from</replaceable>
      of the input file.
      Should be used in conjunction with option <literal>-t</literal>.
     </para></listitem>
   </varlistentry>

   <varlistentry>
    <term>-t<replaceable>to</replaceable>]</term>
    <listitem><para>
      Specify the character set <replaceable>of</replaceable>
      of the output.
      Should be used in conjunction with option <literal>-f</literal>.
     </para></listitem>
   </varlistentry>

   <varlistentry>
    <term>-v</term>
    <listitem><para>
      Print more information about the conversion process.
     </para></listitem>
   </varlistentry>

  </variablelist>
 </refsect1>

 <refsect1><title>ENCODINGS</title>
  <para>
   The yaz-iconv command and the API as defined in
   <filename>yaz/yaz-iconv.h</filename> is a wrapper for the
   library system call iconv. But YAZ' iconv utility also implements
   conversions on its own. The table below lists characters sets (or encodings)
   that are supported by YAZ. Each character set is marked with either
   <emphasis>encode</emphasis> or <emphasis>decode</emphasis>. If
   an encoding is encode-enabled, YAZ may convert <emphasis>to</emphasis>
   the designated encoding. If an encoding is decode-enabled, YAZ
   may convert <emphasis>from</emphasis> the designated encoding.
  </para>
  <variablelist>
   <varlistentry>
    <term>marc8 (encode, decode)</term>
    <listitem>
     <para>
      The <ulink url="&url.marc8;">MARC8</ulink> encoding as defined by
      the Library of Congress. Most MARC21/USMARC records use this encoding.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>marc8s (encode, decode)</term>
    <listitem>
     <para>
      Like MARC8 but conversion prefers non-combined characters
      in the Latin-1 plane over combined characters.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>marc8lossy (encode)</term>
    <listitem>
     <para>
      Lossy encoding of MARC-8.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>marc8lossless (encode)</term>
    <listitem>
     <para>
      Lossless encoding of MARC8.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>utf8 (encode, decode)</term>
    <listitem>
     <para>
      The most commonly used UNICODE encoding on the Internet.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>iso8859-1 (encode, decode)</term>
    <listitem>
     <para>
      ISO-8859-1, AKA Latin-1.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>iso5426 (decode)</term>
    <listitem>
     <para>
      ISO 5426. Some MARC records (UNIMARC) use this encoding.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>iso5428:1984 (encode, decode)</term>
    <listitem>
     <para>
      ISO 5428:1984.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>advancegreek (encode, decode)</term>
    <listitem>
     <para>
      An encoding for Greek in use by some vendors (Advance).
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>danmarc (decode)</term>
    <listitem>
     <para>
      <ulink url="&url.danmarc.charset;">Danmarc (in danish)</ulink> is
      an encoding based on UNICODE which is used for DanMARC2 records.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1><title>EXAMPLES</title>
  <para>
   The following command converts from ISO-8859-1 (Latin-1) to
   UTF-8.
   <screen>
    yaz-iconv -f ISO-8859-1 -t UTF-8 &lt;input.lst &gt;output.lst
   </screen>
  </para>
 </refsect1>

 <refsect1><title>FILES</title>
  <para>
   <filename><replaceable>prefix</replaceable>/bin/yaz-iconv</filename>
  </para>
  <para>
   <filename><replaceable>prefix</replaceable>/include/yaz/yaz-iconv.h</filename>
  </para>
 </refsect1>
 <refsect1><title>SEE ALSO</title>
  <para>
   yaz(7)
   iconv(1)
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: nxml
nxml-child-indent: 1
End:
-->
