source: basicnet/textweb/links.xml@ e6c872e

<?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 links-download-http "http://links.twibright.com/download/links-&Links-version;.tar.bz2">
  <!ENTITY links-download-ftp  " ">
  <!ENTITY links-md5sum        "8c4bc1ebbf4962d290df8218bfc21413">
  <!ENTITY links-size          "4.1 MB">
  <!ENTITY links-buildsize     "25 MB">
  <!ENTITY links-time          "0.3 SBU">
]>

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

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Links-&Links-version;</title>

  <indexterm zone="Links">
    <primary sortas="a-Links">Links</primary>
  </indexterm>

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

    <para><application>Links</application> is a text and graphics mode
    WWW browser. It includes support for rendering
    tables and frames, features background downloads, can display colors
    and has many other features.</para>
    
    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&links-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&links-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &links-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &links-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &links-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &links-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing='compact'>
      <listitem>
        <para>Recommended patch: <ulink
          url="&gentoo-ftp-repo;/links-&Links-version;-utf8.diff.bz2"/></para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Do I Need the Patch?</bridgehead>

      <para>In text mode, unpatched <application>Links</application> cannot be
      configured to use UTF-8 or other multibyte encodings for the terminal
      input/output. This limitation renders <application>Links</application>
      useless as a text-based browser in multibyte locales. See general
      discussion of this type of issue in the
      <xref linkend="locale-not-valid-option"/> section
      on the <xref linkend="locale-issues"/> page.</para>

      <para>The patch adds the <quote>UTF-8 I/O</quote> configuration option.
      With this option enabled, <application>Links</application> first renders
      the page using an 8-bit character set configured by the user, and then
      converts from this character set to UTF-8. The opposite conversion is
      applied to user input. This approach works if there is an 8-bit character
      set that contains all the characters that the user considers to be
      important. Such character set does not exist, e.g., for Chinese
      hieroglyphs, or when it is required to display both Cyrillic and Greek
      characters.</para>

    <bridgehead renderas="sect3">Do I Have to Enable Graphics Support?</bridgehead>
      <para>In graphical mode, <application>Links</application> displays text
      correctly even in UTF-8 locales, if all characters exist in the built-in
      font used by <application>Links</application>. This font contains
      Basic Latin, Latin-1 Supplement (without superscripts and vulgar
      fractions), Latin Extended-A, Latin Extended-B (partially), Greek,
      Cyrillic and Hebrew characters. Form submission in non-ISO-8859-1
      locales is handled correctly when running in X11-based graphical mode.
      Input handlers for other graphics drivers (fb, directfb, svgalib) either
      misinterpret non-ASCII characters, or don't allow them
      at all.</para>

      <para>The patch has no effect on <application>Links</application>
      behavior in graphical mode.</para>

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

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended"><xref linkend="gpm"/>, and
    <xref linkend="openssl"/>.</para>
    <!-- pcre was used in previous versions only, for javascript
    <xref linkend="pcre"/>
    -->
   <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">Support of graphical mode requires at least one of
    <xref linkend="gpm"/> (to be used with a framebuffer-based console),
    <ulink url="http://www.svgalib.org/">SVGAlib</ulink>,
    <!-- SDL support is removed upstream until someone fixes it
    <xref linkend="sdl"/>,
    -->
    <ulink url="http://www.directfb.org/">DirectFB</ulink>, and
    <xref linkend="x-window-system"/>. For decoding various image formats,
    <application>Links</application> can utilize
    <xref linkend="libpng"/>,
    <xref linkend="libjpeg"/>, and
    <xref linkend="libtiff"/>.</para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/LinksBrowser"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Links</title>
   
   <para>If desired, apply the patch:</para>

<screen><userinput>bzcat ../links-&Links-version;-utf8.diff.bz2 | patch -p1 &amp;&amp;
cd intl &amp;&amp;
./gen-intl &amp;&amp; ./synclang &amp;&amp;
cd ..
</userinput></screen>
   
   <para>Install <application>Links</application> by running the following
    commands:</para>

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

    <para>This package does not come with a test suite.</para>

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

<screen role='root'><userinput>make install &amp;&amp;
install -v -d -m755 /usr/share/doc/links-&Links-version; &amp;&amp;
install -v -m644 doc/links_cal/* KEYS BRAILLE_HOWTO \
    /usr/share/doc/links-&Links-version;</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>
    
    <para><command>./gen-intl &amp;&amp; ./synclang</command>: These commands
    regenerate the language table.</para>
    
    <para><option>--enable-graphics</option>: This switch enables support
    for graphics mode.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Links</title>

    <sect3 id="links-config">
      <title>Config Files</title>

      <para><filename>~/.links/*</filename></para>

      <indexterm zone="Links links-config">
        <primary sortas="e-AA.links/*">~/.links/*</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para><application>Links</application> stores its configuration in per-user
      files in the <filename class="directory">~/.links</filename> directory. These
      files are created automatically when <command>links</command> is run for the
      first time.</para>
      
      <para>For the correct display of non-ASCII characters,
      <application>Links</application> has to be configured through the menu
      (accessible by pressing the ESC key), as follows:</para>
      
      <itemizedlist>
        <listitem>
          <para>If running <application>Links</application> in the text mode in a
          UTF-8 based locale, go to the <quote>Setup &gt; Terminal options</quote>
          menu item and check the <quote>UTF-8 I/O</quote> box.</para>
        </listitem>
        <listitem>
          <para>If running <application>Links</application> in the text mode,
          go to the <quote>Setup &gt; Character set</quote> menu item and select
          the character set that matches your locale or, if you use UTF-8 based
          locale, the character set that contains all characters that you want
          <application>Links</application> to be able to display.</para>
        </listitem>
        <listitem>
          <para>Optionally, go to the <quote>Setup &gt; Language</quote> menu
          and select the user interface language.</para>
        </listitem>
        <listitem>
          <para>Finally, select the <quote>Setup &gt; Save options</quote>
          menu item.</para>
        </listitem>
      </itemizedlist>

    </sect3>

  </sect2>

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

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

      <seglistitem>
        <seg>links</seg>
        <seg>None</seg>
        <seg>/usr/share/doc/links-&Links-version;</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="links">
        <term><command>links</command></term>
        <listitem>
          <para>is a text and graphics mode WWW browser.</para>
          <indexterm zone="Links links">
            <primary sortas="b-links">links</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>