source: pst/scanning/sane.xml@ d47868a

<?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 sane-be-download-http "http://alioth.debian.org/download.php/2318/sane-backends-&sane-version;.tar.gz">
  <!ENTITY sane-be-download-ftp  "ftp://ftp2.sane-project.org/pub/sane/sane-backends-&sane-version;/sane-backends-&sane-version;.tar.gz">
  <!ENTITY sane-be-download-ftp  "&gentoo-ftp-repo;/sane-backends-&sane-version;.tar.gz">
  <!ENTITY sane-be-md5sum        "8c0936272dcfd4e98c51512699f1c06f">
  <!ENTITY sane-be-size          "4.1 MB">
  <!ENTITY sane-be-buildsize     "71 MB">
  <!ENTITY sane-be-time          "1.5 SBU">

  <!ENTITY sane-fe-version       "1.0.14">
  <!ENTITY sane-fe-download-http "http://alioth.debian.org/download.php/1140/sane-frontends-&sane-fe-version;.tar.gz">
  <!ENTITY sane-fe-download-ftp  "ftp://ftp2.sane-project.org/pub/sane/sane-frontends-&sane-fe-version;/sane-frontends-&sane-fe-version;.tar.gz">
  <!ENTITY sane-fe-md5sum        "c63bf7b0bb5f530cf3c08715db721cd3">
  <!ENTITY sane-fe-size          "231 KB">
  <!ENTITY sane-fe-buildsize     "3.0 MB">
  <!ENTITY sane-fe-time          "less than 0.1 SBU">
]>

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

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

  <title>SANE-&sane-version;</title>

  <indexterm zone="sane">
    <primary sortas="a-SANE">SANE</primary>
  </indexterm>

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

    <para><application>SANE</application> is short for Scanner Access Now Easy.
    Scanner access, however, is far from easy, since every vendor has their own
    protocols. The only known protocol that should bring some unity into this
    chaos is the TWAIN interface, but this is too imprecise to allow a stable
    scanning framework. Therefore, <application>SANE</application> comes with
    its own protocol, and the vendor drivers can't be used.</para>

    <para><application>SANE</application> is split into back ends and front
    ends. The back ends are drivers for the supported scanners and cameras. The
    front ends are user interfaces to access the backends.</para>

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

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

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

    <bridgehead renderas="sect4">Optional (Back Ends)</bridgehead>
    <para role="optional"><xref linkend="libjpeg"/>,
    <xref linkend="libtiff"/>,
    <xref linkend="libusb-compat"/>,
    <ulink url="http://cyberelk.net/tim/libieee1284/">libieee1284</ulink>,
    <ulink url="http://www.gphoto.org/">libgphoto2</ulink>, and
    <xref linkend="tetex"/></para>

    <bridgehead renderas="sect4">Optional (Front Ends)</bridgehead>
    <para role="optional"><xref linkend="x-window-system"/>,
    <xref linkend="gtk2"/>, and
    <xref linkend="gimp"/></para>

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

  </sect2>

  <sect2 role="kernel" id='sane-kernel'>
    <title>Kernel Configuration</title>

    <indexterm zone="sane sane-kernel">
      <primary sortas="d-Scanning-devices">Scanning devices</primary>
    </indexterm>

    <para>To access your scanner, you will probably need the related kernel
    drivers and/or additional support packages. A SCSI scanner will need SCSI
    drivers, a parallel port scanner needs parallel port support (you should
    use enhanced EPP modes) and perhaps <ulink
    url="http://cyberelk.net/tim/libieee1284/">libieee1284</ulink> and a USB
    scanner will need the <xref linkend="libusb"/> package. Ensure you have
    the necessary drivers properly configured to access the devices.</para>

  </sect2>

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

    <sect3>
      <title>Installation of SANE Back Ends</title>

      <para>The <application>SANE</application> daemon should run with its own
      group.  Create this group by issuing the following commands as the
      <systemitem class="username">root</systemitem> user:</para>

<screen><userinput>groupadd -g 70 scanner</userinput></screen>

      <para>Install <application>SANE</application>-backends by
      running the following commands:</para>

<screen><userinput>sed -i 's/SYSFS/ATTRS/g' tools/sane-desc.c &amp;&amp;
./configure --prefix=/usr --sysconfdir=/etc &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 -m 644 -v tools/udev/libsane.rules /etc/udev/rules.d/65-scanner.rules</userinput></screen>

    </sect3>

    <sect3>
      <title>Installation of SANE Front Ends</title>

      <para>The <application>SANE</application>-frontends package
      includes the graphical frontends <command>xscanimage</command> and
      <command>xcam</command>, and a command-line frontend
      <command>scanadf</command>. You don't need this package if you intend
      to use one of the more advanced graphical frontends like
      <xref linkend="xsane"/>. For a list of frontend packages, see
      <ulink url="http://www.sane-project.org/sane-frontends.html"/>.</para>

      <para>To install <application>SANE</application>-frontends,
      use 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 -m644 doc/sane.png xscanimage-icon-48x48-2.png \
    /usr/share/sane</userinput></screen>

      <para>If <application>GIMP</application> was linked into the build and
      you wish <application>GIMP</application> to use
      <command>xscanimage</command> as a scanning plugin, issue the following
      command as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>ln -v -s ../../../../bin/xscanimage /usr/lib/gimp/2.0/plug-ins</userinput></screen>

    </sect3>

  </sect2>

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

    <para><command>sed -i 's/SYSFS/ATTRS/g' tools/sane-desc.c</command>: This 
    command fixes an obsolete <application>udev</application> parameter.</para>

    <para><parameter>--sysconfdir=/etc</parameter>: This switch installs the
    configuration files in <filename class="directory">/etc/sane.d</filename>
    instead of <filename class="directory">/usr/etc/sane.d</filename>.</para>

  </sect2>

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

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

      <para><filename>/etc/sane.d/*.conf</filename></para>

      <indexterm zone="sane sane-config">
        <primary sortas="e-etc-sane.d-conf">/etc/sane.d/*.conf</primary>
      </indexterm>

    </sect3>

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

      <sect4>
        <title>Backend Configuration</title>

        <para>The backend configuration files are located in
        <filename class='directory'>/etc/sane.d</filename>. Information
        for configuring the various backends can be found by using the man(5)
        page for the desired backend. Run
        <command>man sane-<replaceable>&lt;backend&gt;</replaceable></command>,
        substituting the desired backend.</para>

        <para>Add any desired users to the <systemitem
        class="groupname">scanner</systemitem> group.</para>

      </sect4>

      <sect4>
        <title>General Information</title>

        <para>For general information about configuring and using
        <application>SANE</application>, see <command>man sane</command>.
        Linux-2.6.x brings some special issues into the picture. See
        <ulink url="http://www.sane-project.org/README.linux"/> for
        information about using <application>SANE</application> with the
        Linux-2.6.x kernel. For information about USB scanning devices,
        run <command>man sane-usb</command>. For information about SCSI
        devices, run <command>man sane-scsi</command>.</para>

      </sect4>

      <sect4>
        <title>Configuration and setup of the 'saned' daemon</title>

        <para>The <command>saned</command> daemon is not meant to be used for
        untrusted clients. You should provide <xref linkend="tcpwrappers"/>
        and/or <xref linkend="fw-firewall"/> protection to ensure only trusted
        clients access the daemon. Due to the complex security requirements to
        ensure only trusted clients access the daemon, BLFS does not provide
        instructions to configure the <command>saned</command> daemon. If you
        desire to make the daemon available, ensure you provide adequate
        security, configure your <filename>[x]inetd.conf</filename> file and
        send a <userinput>SIGHUP</userinput> to the [x]inetd daemon. Some good
        information for setting up and securing the <command>saned</command>
        daemon can be found at
        <ulink url="http://penguin-breeder.org/sane/saned/"/>.</para>

      </sect4>

    </sect3>

  </sect2>

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

    <bridgehead renderas="sect4">Back Ends:</bridgehead>
    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>gamma4scanimage, sane-config, saned, sane-find-scanner,
        and scanimage</seg>
        <seg>libsane.so and numerous scanner backend modules</seg>
        <seg>/etc/sane.d, /usr/include/sane, /usr/lib/sane, /usr/share/sane,
        and /usr/share/doc/sane-&sane-version;</seg>
      </seglistitem>
    </segmentedlist>

    <bridgehead renderas="sect4">Front Ends:</bridgehead>
    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>scanadf, xcam, and xscanimage</seg>
        <seg><application>GIMP</application> plugin embedded in
        <command>xscanimage</command></seg>
        <seg>None</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="gamma4scanimage">
        <term><command>gamma4scanimage</command></term>
        <listitem>
          <para>creates a gamma table in the format expected by
          <command>scanimage</command>.</para>
          <indexterm zone="sane gamma4scanimage">
            <primary sortas="b-gamma4scanimage">gamma4scanimage</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="sane-config-prog">
        <term><command>sane-config</command></term>
        <listitem>
          <para>is a tool used to determine the compiler and linker
          flags that should be used to compile and link
          <application>SANE</application>.</para>
          <indexterm zone="sane sane-config-prog">
            <primary sortas="b-sane-config">sane-config</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="saned">
        <term><command>saned</command></term>
        <listitem>
          <para>is the <application>SANE</application> daemon that
          allows remote clients to access image acquisition devices
          available on the local host.</para>
          <indexterm zone="sane saned">
            <primary sortas="b-saned">saned</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="sane-find-scanner">
        <term><command>sane-find-scanner</command></term>
        <listitem>
          <para>is a command-line tool to find SCSI and
          USB scanners and determine their device files. Its primary
          purpose is to make sure that scanners can be detected by
          <application>SANE</application> backends.</para>
          <indexterm zone="sane sane-find-scanner">
            <primary sortas="b-sane-find-scanner">sane-find-scanner</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="scanadf">
        <term><command>scanadf</command></term>
        <listitem>
          <para>is a command-line interface to control image acquisition
          devices which are equipped with an automatic document feeder
          (ADF).</para>
          <indexterm zone="sane scanadf">
            <primary sortas="b-scanadf">scanadf</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="scanimage">
        <term><command>scanimage</command></term>
        <listitem>
          <para>is a command line interface for scanning from image acquisition
          devices such as flatbed scanners or cameras. It is also used to list
          the available backend devices.</para>
          <indexterm zone="sane scanimage">
            <primary sortas="b-scanimage">scanimage</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xcam">
        <term><command>xcam</command></term>
        <listitem>
          <para>is a graphical camera front end for
          <application>SANE</application>.</para>
          <indexterm zone="sane xcam">
            <primary sortas="b-xcam">xcam</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xscanimage">
        <term><command>xscanimage</command></term>
        <listitem>
          <para>is a graphical user interface for scanning.</para>
          <indexterm zone="sane xscanimage">
            <primary sortas="b-xscanimage">xscanimage</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libsane">
        <term><filename class='libraryfile'>libsane.so</filename></term>
        <listitem>
          <para>is the application programming interface that is used to
          communicate between frontends and backends.</para>
          <indexterm zone="sane libsane">
            <primary sortas="c-libsane">libsane.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libsane-module">
        <term><filename class='libraryfile'>libsane-*.so</filename></term>
        <listitem>
          <para>modules are backend scanning library plugins used to interface
          with scanning devices. See
          <ulink url="http://www.sane-project.org/sane-supported-devices.html"/>
          for a list of supported backends.</para>
          <indexterm zone="sane libsane-module">
            <primary sortas="c-libsane-module">libsane-*.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>