source: general/genlib/libidn.xml@ eab496c5

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

  <!ENTITY libidn-download-http "&gnu-http;/libidn/libidn-&libidn-version;.tar.gz">
  <!ENTITY libidn-download-ftp  "&gnu-ftp;/libidn/libidn-&libidn-version;.tar.gz">
  <!ENTITY libidn-md5sum        "a9aa7e003665de9c82bd3f9fc6ccf308">
  <!ENTITY libidn-size          "3.3 MB">
  <!ENTITY libidn-buildsize     "25 MB (with tests)">
  <!ENTITY libidn-time          "0.4 SBU (with tests)">
]>

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

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </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://www.ietf.org/rfc/rfc3454.txt">Stringprep</ulink>,
      <ulink url="http://www.ietf.org/rfc/rfc3492.txt">Punycode</ulink> and
      <ulink url="http://www.ietf.org/rfc/rfc3490.txt">IDNA</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>

    &lfs82_checked;

    <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="pth"/>,
      <xref linkend="emacs"/>,
      <xref linkend="gtk-doc"/>,
      <xref linkend="openjdk"/>,
      <xref linkend="valgrind"/>, and
      <!-- DotGNU has been decommisioned. Look again for next  libidn version. -->
      <ulink url="http://www.gnu.org/software/dotgnu/">DotGNU Portable.NET</ulink> or
      <ulink url="http://www.mono-project.com/">Mono</ulink>
    </para>

    <para condition="html" role="usernotes">User Notes:
      <ulink url="&blfs-wiki;/libidn"/>
    </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 --disable-static &amp;&amp;
make</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*" -delete            &amp;&amp;
rm -rf -v doc/{gdoc,idn.1,stamp-vti,man,texi} &amp;&amp;
mkdir -v       /usr/share/doc/libidn-&libidn-version;     &amp;&amp;
cp -r -v doc/* /usr/share/doc/libidn-&libidn-version;</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/static-libraries.xml"/>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/gtk-doc-rebuild.xml"/>

  </sect2>

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

    <segmentedlist>
      <segtitle>Installed Program</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          idn
        </seg>
        <seg>
          libidn.so
        </seg>
        <seg>
          /usr/share/doc/libidn-&libidn-version; and
          /usr/share/gtk-doc/html/libidn
        </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</filename></term>
        <listitem>
          <para>
            contains a generic Stringprep implementation that does Unicode
            3.2 NFKC normalization, mapping and prohibition 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</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>