--- /dev/null
+<refentry id="{@id}">
+ <refnamediv>
+ <refname>Frequently Asked Questions (FAQ)</refname>
+ <refpurpose>Quick answers to common questions</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <authorblurb>
+ <para>
+ <author>
+ <firstname>Martin</firstname>
+ <surname>Geisler</surname>
+ </author>
+ {@link mailto:mgeisler@users.sourceforge.net
+ mgeisler@users.sourceforge.net}
+ </para>
+ </authorblurb>
+ </refsynopsisdiv>
+
+ {@toc}
+
+<refsect1 id="{@id pel-acronym}">
+
+ <title>What does PEL stand for?</title>
+
+ <para>PEL is an acronym for "PHP Exif Library". Sound simple
+ enough, doesn't it?</para>
+
+ <para>But did you realise that PEL is an acronym consisting of two
+ acronyms, one of which is recursive! So "PEL" actually stands for
+ "PHP Hypertext Preprocessor Exchangeable image file format Library".
+ Pyh!</para>
+</refsect1>
+
+
+<refsect1 id="{@id exif-vs-exif}">
+
+ <title>What's the business with EXIF vs. Exif?</title>
+
+ <para>Well, since Exif is an acronym for "Exchangeable image file
+ format" and thus you would expect it to be spelled "EXIF", just like
+ "JPEG" which is an acronym for Joint Photographic Experts
+ Group.</para>
+
+ <para>But the Exif standards spell Exif as "Exif" and so does PEL,
+ at least since version 0.9. But should they ever decide to update
+ their acronym to "EXIF" then PEL will revert... Luckily it does not
+ affect the acronym PEL itself :-)</para>
+
+</refsect1>
+
+
+<refsect1 id="{@id why-php5}">
+ <title>Why does PEL require PHP version 5?</title>
+
+ <para>The support for object-oriented programming was completely
+ overhauled with the introduction of PHP 5 in July 2004. The changes
+ included both semantic changes and syntaxtical changes to the PHP
+ language.</para>
+
+ <para>The semantic change was the use of object references per
+ default. This change means that when you do</para>
+
+ <programlisting role="php">
+ <![CDATA[
+$object_a = $ifd->getEntry(PelTag::IMAGE_DESCRIPTION);
+$object_a->setValue('This is my new description.');
+$object_b = $ifd->getEntry(PelTag::IMAGE_DESCRIPTION);
+ ]]>
+ </programlisting>
+
+ <para>then <literal>$object_a</literal> and
+ <literal>$object_b</literal> will both reference <emphasis>the
+ same</emphasis> element. In particular, you will see that
+ <literal>$object_b->getValue()</literal> returns the string just
+ stored in <literal>$object_a</literal> (since they are the same
+ object). With PHP 4 you would have gotten two different objects,
+ which is generally not what you want.</para>
+
+ <para>The syntaxtical changes from PHP 5 to PHP 4 include the
+ addition of access modifiers to object fields (the private,
+ protected, and public keywords), object constants, constructors
+ named <literal>__construct()</literal>, interfaces and abstract
+ classes, and exceptions. PEL uses all these new features to the
+ fullest, which means that PHP 4 doesn't understand the code.</para>
+
+ <para>If your provider is still using PHP 4, then you should ask
+ them to upgrade. PHP 5 has been declared stable since July 2004 and
+ all major PHP applications ({@link http://www.wordpress.org
+ WordPress}, {@link http://gallery.menalto.com/ Gallery},
+ {@link http://phpwiki.sourceforge.net/ PhpWiki},
+ {@link http://www.phpmyadmin.net/ phpMyAdmin}, etc...), have been
+ upgraded to work with PHP 5, so an upgrade should not bring you any
+ problems, just more features and better performance.</para>
+
+</refsect1>
+
+
+<refsect1 id="{@id fatal-php4-errors}">
+
+ <title>Why do I get fatal errors from PHP?</title>
+
+ <para>If you get a fatal error when trying to use PEL, then your
+ installation of PHP might be too old. PEL requires PHP version 5.
+ Please see the question "{@tutorial faq.pkg#why-php5}" for more
+ information.</para>
+
+</refsect1>
+
+
+<refsect1 id="{@id call-on-non-object}">
+ <title>What does "<literal>Call to a member function
+ <function>f</function> on a non-object</literal>" (where
+ <function>f</function> is <literal>getTiff()</literal> or
+ <literal>setValue()</literal>) mean?</title>
+
+ <para>This is the error PHP gives when you call a method on a
+ variable which is not an object.</para>
+
+ <para>PEL uses objects to represent the entire structure of a JPEG
+ image, and many of the methods defined on those objects return other
+ objects. In particular, the method {@link PelJpeg::getExif()}
+ returns a {@link PelExif} object and {@link PelIfd::getEntry()}
+ returns a {@link PelEntry} object.</para>
+
+ <para>But both methods can return <literal>null</literal> if no such
+ section or entry exist. The correct way to use them is thus
+ something along the lines of:</para>
+
+ <programlisting role="php">
+ <![CDATA[
+$exif = $jpeg->getExif();
+if ($exif != null) {
+ $tiff = $exif->getTiff();
+ /* Do something with the TIFF data. */
+} else {
+ /* Sorry --- no Exif data found. */
+}
+ ]]>
+ </programlisting>
+
+ <para>The same principle applies to the return values of
+ {@link PelIfd::getEntry()} and all other methods which return
+ objects.</para>
+
+</refsect1>
+
+
+<refsect1 id="{@id IPTC-entries}">
+
+ <title>Does PEL handle IPTC entries?</title>
+
+ <para>No, PEL only deals with Exif data, and no such extension is
+ planned. Try taking at look at the
+ {@link http://www.ozhiker.com/electronics/pjmt/ PHP JPEG Metadata
+ Toolkit} which should handle IPTC along with a huge number of other
+ metadata formats.</para>
+
+</refsect1>
+
+
+<refsect1 id="{@id missing-Gettext}">
+
+ <title>Why does Gettext not work?</title>
+
+ <para>PEL uses Gettext for localization, and thus your system must
+ fulfill a few requirements:</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>PHP must have support for the
+ {@link http://www.php.net/manual/en/ref.gettext.php Gettext
+ extension}. Most installations of PHP already has this, but
+ please double-check with <function>
+ {@link http://www.php.net/manual/en/function.phpinfo.php
+ phpinfo}</function> before asking for help on the
+ mailinglist.</para>
+ </listitem>
+
+ <listitem>
+ <para>The system must be setup to generate locales for the
+ languages into which PEL has been translated. Again, most
+ commercial webhosts would have their systems configured to deal
+ with all locales, but if you're installing PEL on your own
+ server you'll probably have to reconfigure it.</para>
+
+ <para>How to configure the locales differ from system to system.
+ With the {@link http://www.debian.net/ Debian GNU/Linux}
+ distribution you should run</para>
+
+ <programlisting>
+ dpkg-reconfigure locales
+ </programlisting>
+
+ <para>and then select all locales that you want your system to
+ support.</para>
+
+ <para>Restart your webserver after changing the locale setup to
+ make the changes effective.</para>
+
+ </listitem>
+
+ </orderedlist>
+
+</refsect1>
+
+
+<refsect1 id="{@id error-handling}">
+
+ <title>How to deal with broken images?</title>
+
+ <para>By default PEL will try to load as much from an image as
+ possible and continue dispite any errors found. The Exif standard
+ mandates certain formats and lengths for some entries, and sometimes
+ these requirements are violated.</para>
+
+ <para>The strictness of PEL is controlled by the the method
+ {@link Pel::setStrictParsing()}. The default is non-strict parsing.
+ In this mode, PEL will not throw exceptions for parse errors but
+ instead store them for later inspection via the
+ {@link Pel::getExceptions()} method.</para>
+
+ <para>With an argument of <literal>true</literal> to
+ {@link Pel::setStrictParsing()} you make PEL throw exceptions upon
+ parse errors.</para>
+
+ <para>This may all sound very complex, but it is actually fairly
+ simple for most uses: have PEL load your images in non-strict mode
+ and check for errors afterwards, if necessary.</para>
+
+ <para>Please note that even if PEL is in non-strict mode it might
+ throw exceptions while parsing an image, for example if the image
+ cannot be recognized a JPEG or TIFF image. So it is always
+ necessary to wrap calls to PEL in a try-catch block.</para>
+
+</refsect1>
+
+
+<refsect1 id="{@id commercial-use}">
+
+ <title>Can I use PEL for a commercial application?</title>
+
+ <para>Yes, no problem as long as you do not distribute your
+ application under another license than the GNU GPL.</para>
+
+ <para>As you should know, PEL is licensed to you under the
+ conditions of the GNU GPL. The license deals
+ <emphasis>only</emphasis> with the distribution of PEL and any
+ derivative works based on PEL, the license has nothing to say over
+ how you may use PEL.</para>
+
+ <para>So if you do not distribute your code, then you can use it for
+ whatever you want, including writing a website (commercial or not)
+ that integrates PEL. Please see
+ {@link http://www.gnu.org/licenses/gpl-faq.html#GPLRequireSourcePostedPublic
+ this question} in the GPL FAQ.</para>
+
+</refsect1>
+
+
+<refsect1 id="{@id unanswered-question}">
+
+ <title>My question is not answered here!</title>
+
+ <para>Please ask your questions on the
+ {@link http://lists.sourceforge.net/lists/listinfo/pel-devel PEL
+ Development List}. If an answer is found, then the FAQ will be
+ updated.</para>
+
+</refsect1>
+
+
+</refentry>
projects / yaffs-website / blobdiff