source: general/genlib/libidn.xml@ 39f916fc

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY libidn-download-http "http://josefsson.org/libidn/releases/libidn-&libidn-version;.tar.gz">
  <!ENTITY libidn-download-ftp  "ftp://alpha.gnu.org/pub/gnu/libidn/libidn-&libidn-version;.tar.gz">
  <!ENTITY libidn-md5sum        "4991ab5ce647c89fa4812d9a1700a8f6">
  <!ENTITY libidn-size          "2.0 MB">
  <!ENTITY libidn-buildsize     "18.3 MB">
  <!ENTITY libidn-time          "0.2 SBU">
]>

<sect1 id="libidn" xreflabel="libidn-&libidn-version;">
  <?dbhtml filename="libidn.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
    <keywordset>
      <keyword role="package">libidn-&libidn-version;.tar</keyword>
      <keyword role="ftpdir">libidn</keyword>
    </keywordset>
  </sect1info>

  <title>Libidn-&libidn-version;</title>

  <indexterm zone="libidn">
    <primary sortas="a-Libidn">Libidn</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Libidn</title>

    <para><application>Libidn</application> is a package designed for
    internationalized string handling based on the <ulink
    url="http://josefsson.org/cgi-bin/rfcmarkup?url=http://www.ietf.org/rfc/rfc3454.txt">
    Stringprep</ulink>, <ulink
    url="http://josefsson.org/cgi-bin/rfcmarkup?url=http://www.ietf.org/rfc/rfc3492.txt">
    Punycode</ulink>, <ulink
    url="http://josefsson.org/cgi-bin/rfcmarkup?url=http://www.ietf.org/rfc/rfc3490.txt">
    IDNA</ulink> and <ulink
    url="http://josefsson.org/cgi-bin/rfcmarkup?url=http://josefsson.org/cgi-bin/viewcvs.cgi/*checkout*/libidn/doc/specifications/draft-hoffman-idn-reg-02.txt">
    TLD</ulink> specifications defined by the Internet Engineering Task Force
    (IETF) Internationalized Domain Names (IDN) working group, used for
    internationalized domain names. This is useful for converting data from the
    system's native representation into UTF-8, transforming Unicode strings
    into ASCII strings, allowing applications to use certain ASCII name labels
    (beginning with a special prefix) to represent non-ASCII name labels, and
    converting entire domain names to and from the ASCII Compatible Encoding
    (ACE) form.</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&libidn-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&libidn-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &libidn-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &libidn-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &libidn-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &libidn-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Libidn Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="emacs"/>,
    <xref linkend="pkgconfig"/>,
    <xref linkend="gtk-doc"/>,
    a Java compiler&mdash;one of (looked for in this order)
    <xref linkend="gcc"/> (for <command>gcj</command>),
    <ulink url="http://jikes.sourceforge.net/">Jikes</ulink> or
    <xref linkend="jdk"/>,
    and a C# compiler&mdash;<ulink
    url="http://www.mono-project.com/Main_Page">Mono</ulink> or
    <ulink url="http://www.southern-storm.com.au/portable_net.html">
    DotGNU Portable.NET</ulink></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Libidn</title>

    <para>Install <application>Libidn</application> by running the following
    commands:</para>

<screen><userinput>./configure --prefix=/usr &amp;&amp;
make</userinput></screen>

    <para>If you have <xref linkend="tex"/> installed and wish to create a
    text version of the documentation, issue the following commands:</para>

<screen><userinput>cd doc &amp;&amp;
makeinfo --plaintext -o libidn.txt libidn.texi &amp;&amp;
cd ..</userinput></screen>

    <para>To test the results, issue: <command>make check</command>.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install &amp;&amp;
find doc -name "Makefile*" -exec rm {} \; &amp;&amp;

install -v -m755 -d \
    /usr/share/doc/libidn-&libidn-version;/{api,java,specifications,tld} &amp;&amp;
install -v -m644 doc/components* \
                 doc/libidn.{pdf,ps,html} \
    /usr/share/doc/libidn-&libidn-version; &amp;&amp;
install -v -m644 doc/reference/html/* \
    /usr/share/doc/libidn-&libidn-version;/api &amp;&amp;
install -v -m644 doc/specifications/* \
    /usr/share/doc/libidn-&libidn-version;/specifications &amp;&amp;
install -v -m644 doc/tld/* /usr/share/doc/libidn-&libidn-version;/tld &amp;&amp;
cp -v -R doc/java/* /usr/share/doc/libidn-&libidn-version;/java</userinput></screen>

    <para>If you created the text documentation, install it using the following
    command as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -m644 doc/libidn.txt /usr/share/doc/libidn-&libidn-version;</userinput></screen>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Program</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directory</segtitle>

      <seglistitem>
        <seg>idn</seg>
        <seg>libidn.[so,a] and optionally, Java and C# modules</seg>
        <seg>/usr/share/doc/libidn-&libidn-version;</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="idn">
        <term><command>idn</command></term>
        <listitem>
          <para>is a command line interface to the internationalized domain
          name library.</para>
          <indexterm zone="libidn idn">
            <primary sortas="b-idn">idn</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libidn-lib">
        <term><filename class='libraryfile'>libidn.[so,a]</filename></term>
        <listitem>
          <para> contains a generic Stringprep implementation that does Unicode
          3.2 NFKC normalization, mapping and prohibitation of characters, and
          bidirectional character handling. Profiles for Nameprep, iSCSI, SASL
          and XMPP are included as well as support for Punycode and ASCII
          Compatible Encoding (ACE) via IDNA. A mechanism to define Top-Level
          Domain (TLD) specific validation tables, and to compare strings
          against those tables, as well as default tables for some TLDs are
          included.</para>
          <indexterm zone="libidn libidn-lib">
            <primary sortas="c-libidn">libidn.[so,a]</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>