source: general/graphlib/poppler.xml@ f3429309

<?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 poppler-download-http "http://poppler.freedesktop.org/poppler-&poppler-version;.tar.xz">
  <!ENTITY poppler-download-ftp       " ">
  <!ENTITY poppler-md5sum             "c635e1742202cbbd9182cb0255d95652">
  <!ENTITY poppler-size               "1.6 MB (additional 9 MB for the test suite)">
  <!ENTITY poppler-buildsize          "293 MB (with Qt4 and Qt5 libraries, and tests)">
  <!ENTITY poppler-time               "2.0 SBU (with Qt4 and Qt5 libraries, and tests)">


  <!ENTITY poppler-data-version       "0.4.7">

  <!ENTITY poppler-data-download-http "http://poppler.freedesktop.org/poppler-data-&poppler-data-version;.tar.gz">
  <!ENTITY poppler-data-md5sum        "636a8f2b9f6df9e7ced8ec0946961eaf">
  <!ENTITY poppler-data-size          "4.0 MB">
  <!ENTITY poppler-data-buildsize     "24 MB">
  <!ENTITY poppler-data-time          "less than 0.1 SBU">
]>

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

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

  <title>Poppler-&poppler-version;</title>

  <indexterm zone="poppler">
    <primary sortas="a-Poppler">Poppler</primary>
  </indexterm>

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

    <para>
      The <application>Poppler</application> package contains a PDF rendering
      library and command line tools used to manipulate PDF files. This is
      useful for providing PDF rendering functionality as a shared library.
    </para>

    &lfs78_checked;

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

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>

    <itemizedlist spacing="compact">
      <title>Poppler Encoding Data</title>
      <listitem>
        <para>
          Download (HTTP): <ulink url="&poppler-data-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &poppler-data-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &poppler-data-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &poppler-data-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &poppler-data-time;
        </para>
      </listitem>
    </itemizedlist>

    <para>
      The additional package consists of encoding files for use with
      <application>Poppler</application>. The encoding files are optional and
      <application>Poppler</application> will automatically read them if they
      are present. When installed, they enable
      <application>Poppler</application> to render CJK and Cyrillic properly.
    </para>

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

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="fontconfig"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="cairo"/>,
      <xref linkend="libjpeg"/>,
      <xref linkend="libpng"/>, and
      <xref linkend="openjpeg"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="curl"/>,
      <xref linkend="gobject-introspection"/>,
      <xref linkend="gtk-doc"/>,
      <xref linkend="gtk2"/>,
      <xref linkend="lcms"/> or <xref linkend="lcms2"/>,
      <xref linkend="libtiff"/>,
      <xref linkend="openjpeg2"/>
      (preference is for OpenJPEG1, due to regressions with OpenJPEG2),
      <xref linkend="qt4"/> (the <filename>libpoppler-qt4.so</filename> library
      is needed for PDF support in <application>Okular</application>), and
      <xref linkend="qt5"/>
    </para>

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

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

    <para>
      In order to optionally run the test suite, an additional download using
      <xref linkend="git"/> is necessary.
    </para>

<screen><userinput>rm -rf testfiles &amp;&amp;
git clone git://git.freedesktop.org/git/poppler/test testfiles</userinput></screen>

    <note><para>

      This package can be optionally built with support for only one version of
      Qt4 or Qt5. If you have only one, no modification is necessary. If both
      are installed, and you wish support for only one, before executing the
      <command>configure</command> command given below, use this command to
      select Qt4:

      <screen><userinput>source /usr/bin/setqt4</userinput></screen>

      or this to select Qt5:

      <screen><userinput>source /usr/bin/setqt5</userinput></screen>
    </para></note>

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

<screen><userinput>MOCQT4=$QT4DIR/bin/moc                  \
MOCQT5=$QT5DIR/bin/moc                  \
./configure --prefix=/usr               \
            --sysconfdir=/etc           \
            --disable-static            \
            --enable-build-type=release \
            --enable-cmyk               \
            --enable-xpdf-headers       \
            --with-testdatadir=$PWD/testfiles &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>LC_ALL=en_US.UTF-8 make check</command>.
    </para>

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

<screen role="root"><userinput>make install</userinput></screen>

    <para>
      To install the documentation, run the following commands as
      <systemitem class="username">root</systemitem>:
    </para>

<screen role="root"><userinput>install -v -m755 -d        /usr/share/doc/poppler-&poppler-version; &amp;&amp;
install -v -m644 README*   /usr/share/doc/poppler-&poppler-version; &amp;&amp;
cp -vr glib/reference/html /usr/share/doc/poppler-&poppler-version;</userinput></screen>

<!-- ==== Poppler Data ====== -->
    <bridgehead renderas="sect3">Poppler Data</bridgehead>

    <para>
      If you downloaded the additional encoding data package, install it by
      issuing the following commands as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen><userinput>tar -xf ../poppler-data-&poppler-data-version;.tar.gz &amp;&amp;
cd poppler-data-&poppler-data-version;</userinput></screen>

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

<screen role="root"><userinput>make prefix=/usr install</userinput></screen>

  </sect2>

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

    <para>
      <envar>MOCQT4=$QT4DIR/bin/moc</envar> and
      <envar>MOCQT5=$QT5DIR/bin/moc</envar>:
      These environment variables are necessary, for linking with the two Qt
      versions, if both are installed.  If only one Qt version is installed or
      you wish to link to only one version, you can remove them, although this
      is not necessary.
    </para>

    <para>
      <parameter>--enable-build-type=release</parameter>: This switch is used
      to apply a higher level of compiler optimizations. Other options are:
      [<option>relwithdebinfo/debug/debugfull/profile</option>]
    </para>

    <para>
      <parameter>--enable-cmyk</parameter>:
      Include support for CMYK rasterization.
    </para>

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

    <para>
      <parameter>--enable-xpdf-headers</parameter>: Install some old
      <application>Xpdf</application> headers required by certain programs (e.g.
      <application>Okular</application>, <application>LibreOffice</application>
      and <application>Inkscape</application>).
    </para>

    <para>
      <parameter>--with-testdatadir=$PWD/testfiles</parameter>: Tell the test
      programs where the auxillary files are located.
    </para>

    <para>
      <option>--enable-libcurl</option>: Use libcurl for HTTP support.
    </para>

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

    <para>
      <command>LC_ALL=en_US.UTF-8 make check</command>: Run the test suite.
      The environment variable LC_ALL=en_US.UTF-8 is only needed if the
      default locale does not include UTF-8.
    </para>

  </sect2>

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

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

      <seglistitem>
        <seg>
          pdfdetach, pdffonts, pdfimages, pdfinfo, pdfseparate,
          pdftocairo, pdftohtml, pdftoppm, pdftops, pdftotext,
          pdfunite, and poppler-glib-demo
        </seg>
        <seg>
          libpoppler.so,
          libpoppler-cpp.so,
          libpoppler-glib.so,
          libpoppler-qt4.so, and
          libpoppler-qt5.so
        </seg>
        <seg>
          /usr/include/poppler,
          /usr/share/poppler,
          /usr/share/gtk-doc/html/poppler, and
          /usr/share/doc/poppler-&poppler-version;
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="pdfdetach">
        <term><command>pdfdetach</command></term>
        <listitem>
          <para>
            lists or extracts embedded files from PDF files.
          </para>
          <indexterm zone="poppler pdfdetach">
            <primary sortas="b-pdfdetach">pdfdetach</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pdffonts">
        <term><command>pdffonts</command></term>
        <listitem>
          <para>
            lists the fonts used in a PDF file along with various information
            for each font.
          </para>
          <indexterm zone="poppler pdffonts">
            <primary sortas="b-pdffonts">pdffonts</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pdfimages">
        <term><command>pdfimages</command></term>
        <listitem>
          <para>
            saves images from a PDF file as PPM, PBM, or JPEG files.
          </para>
          <indexterm zone="poppler pdfimages">
            <primary sortas="b-pdfimages">pdfimages</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pdfinfo">
        <term><command>pdfinfo</command></term>
        <listitem>
          <para>
            prints the contents of the 'Info' dictionary (plus some other useful
            information) from a PDF file.
          </para>
          <indexterm zone="poppler pdfinfo">
            <primary sortas="b-pdfinfo">pdfinfo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pdfseparate">
        <term><command>pdfseparate</command></term>
        <listitem>
          <para>
            extracts single pages from a PDF file.
          </para>
          <indexterm zone="poppler pdfseparate">
            <primary sortas="b-pdseparate">pdfseparate</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pdftocairo">
        <term><command>pdftocairo</command></term>
        <listitem>
          <para>
            converts a PDF file to one of several formats (PNG, JPEG, PDF, PS,
            EPS, SVG) using the cairo output device of the poppler library.
          </para>
          <indexterm zone="poppler pdftocairo">
            <primary sortas="b-pdftocairo">pdftocairo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pdftohtml">
        <term><command>pdftohtml</command></term>
        <listitem>
          <para>
            converts a PDF file to HTML.
          </para>
          <indexterm zone="poppler pdftohtml">
            <primary sortas="b-pdftohtml">pdftohtml</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pdftoppm">
        <term><command>pdftoppm</command></term>
        <listitem>
          <para>
            converts PDF files to PBM, PGM and PPM formats.
          </para>
          <indexterm zone="poppler pdftoppm">
            <primary sortas="b-pdftoppm">pdftoppm</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pdftops">
        <term><command>pdftops</command></term>
        <listitem>
          <para>
            converts PDF files to Postscript format.
          </para>
          <indexterm zone="poppler pdftops">
            <primary sortas="b-pdftops">pdftops</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pdftotext">
        <term><command>pdftotext</command></term>
        <listitem>
          <para>
            converts PDF files to plain text.
          </para>
          <indexterm zone="poppler pdftotext">
            <primary sortas="b-pdftotext">pdftotext</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pdfunite">
        <term><command>pdfunite</command></term>
        <listitem>
          <para>
            merges several PDF files, in the order of their occurrence on the
            command line, to one PDF output file.
          </para>
          <indexterm zone="poppler pdfunite">
            <primary sortas="b-pdfunite">pdfunite</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="poppler-glib-demo">
        <term><command>poppler-glib-demo</command></term>
        <listitem>
          <para>
            is a tool to demonstrate the API, and for use when debugging and
            testing <application>Poppler</application>.
          </para>
          <indexterm zone="poppler poppler-glib-demo">
            <primary sortas="b-poppler-glib-demo">poppler-glib-demo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpoppler">
        <term><filename class="libraryfile">libpoppler.so</filename></term>
        <listitem>
          <para>
            contains the API functions to render PDF files.
          </para>
          <indexterm zone="poppler libpoppler">
            <primary sortas="c-libpoppler">libpoppler.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpoppler-cpp">
        <term><filename class="libraryfile">libpoppler-cpp.so</filename></term>
        <listitem>
          <para>
            is a C++ backend for rendering PDF files.
          </para>
          <indexterm zone="poppler libpoppler-cpp">
            <primary sortas="c-libpoppler-cpp">libpoppler-cpp.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpoppler-glib">
        <term><filename class="libraryfile">libpoppler-glib.so</filename></term>
        <listitem>
          <para>
            is a wrapper library used to interface the PDF rendering functions
            with <application>GTK+</application>.
          </para>
          <indexterm zone="poppler libpoppler-glib">
            <primary sortas="c-libpoppler-glib">libpoppler-glib.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpoppler-qt4">
        <term><filename class="libraryfile">libpoppler-qt4.so</filename></term>
        <listitem>
          <para>
            is a wrapper library used to interface the PDF rendering functions
            with <application>Qt</application>4.
          </para>
          <indexterm zone="poppler libpoppler-qt4">
            <primary sortas="c-libpoppler-qt4">libpoppler-qt4.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpoppler-qt5">
        <term><filename class="libraryfile">libpoppler-qt5.so</filename></term>
        <listitem>
          <para>
            is a wrapper library used to interface the PDF rendering functions
            with <application>Qt</application>5.
          </para>
          <indexterm zone="poppler libpoppler-qt5">
            <primary sortas="c-libpoppler-qt5">libpoppler-qt5.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>