source: general/genlib/libidn.xml@ 10847bb9

<?xml version="1.0" encoding="UTF-8"?>
<!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  " ">
  <!ENTITY libidn-md5sum        "fe061a95ae23979150a692d102dce4ad">
  <!ENTITY libidn-size          "2.5 MB">
  <!ENTITY libidn-buildsize     "19 MB (with tests)">
  <!ENTITY libidn-time          "0.2 SBU (with tests)">
]>

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


  <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="https://www.ietf.org/rfc/rfc3454.txt">Stringprep</ulink>,
      <ulink url="https://www.ietf.org/rfc/rfc3492.txt">Punycode</ulink> and
      <ulink url="https://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>

    &lfs121_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="emacs"/>,
      <xref linkend="gtk-doc"/>,
      <xref linkend="openjdk"/>,
      <xref linkend="valgrind"/>, and
      <ulink url="https://www.mono-project.com/">Mono</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 --disable-static &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, run:
    </para>

<screen remap="test"><userinput>pushd tests  &amp;&amp;
  make check &amp;&amp;
popd </userinput></screen>

    <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"/>

    <para>
      <option>--enable-java</option>: Use this switch to enable building
      the Java implementation of <application>libidn</application>. Note that
      <xref linkend="openjdk"/> must be installed to use this option.
    </para>

  </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>