From 97d94b3c09a83c4471dc33eb129dc7945f48d6dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gustavo=20Andr=C3=A9=20dos=20Santos=20Lopes?=
 <cataphract@php.net>
Date: Fri, 20 Nov 2009 17:07:32 +0000
Subject: [PATCH] Updated PECL rar documentation for version 2.0.0.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@291095 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/rar/book.xml                        |  3 +-
 reference/rar/functions/rar-comment-get.xml   | 71 +++++++++++++++
 reference/rar/functions/rar-entry-get.xml     | 10 ++-
 reference/rar/functions/rar-list.xml          |  3 +-
 reference/rar/functions/rar-open.xml          |  6 +-
 reference/rar/rarentry.xml                    | 70 +++++++++++++++
 .../rar-extract.xml => rarentry/extract.xml}  | 25 ++++--
 .../rar-getattr.xml => rarentry/getattr.xml}  | 12 +--
 .../rar-getcrc.xml => rarentry/getcrc.xml}    | 32 ++++++-
 .../getfiletime.xml}                          |  6 +-
 .../gethostos.xml}                            | 10 +--
 .../getmethod.xml}                            | 10 +--
 .../rar-getname.xml => rarentry/getname.xml}  | 23 +++--
 .../getpackedsize.xml}                        | 39 +++++++-
 reference/rar/rarentry/getstream.xml          | 89 +++++++++++++++++++
 .../getunpackedsize.xml}                      | 41 +++++++--
 .../getversion.xml}                           |  8 +-
 reference/rar/versions.xml                    | 24 ++---
 18 files changed, 416 insertions(+), 66 deletions(-)
 create mode 100644 reference/rar/functions/rar-comment-get.xml
 create mode 100644 reference/rar/rarentry.xml
 rename reference/rar/{functions/rar-extract.xml => rarentry/extract.xml} (73%)
 rename reference/rar/{functions/rar-getattr.xml => rarentry/getattr.xml} (88%)
 rename reference/rar/{functions/rar-getcrc.xml => rarentry/getcrc.xml} (57%)
 rename reference/rar/{functions/rar-getfiletime.xml => rarentry/getfiletime.xml} (85%)
 rename reference/rar/{functions/rar-gethostos.xml => rarentry/gethostos.xml} (84%)
 rename reference/rar/{functions/rar-getmethod.xml => rarentry/getmethod.xml} (80%)
 rename reference/rar/{functions/rar-getname.xml => rarentry/getname.xml} (74%)
 rename reference/rar/{functions/rar-getpackedsize.xml => rarentry/getpackedsize.xml} (58%)
 create mode 100644 reference/rar/rarentry/getstream.xml
 rename reference/rar/{functions/rar-getunpackedsize.xml => rarentry/getunpackedsize.xml} (57%)
 rename reference/rar/{functions/rar-getversion.xml => rarentry/getversion.xml} (85%)

diff --git a/reference/rar/book.xml b/reference/rar/book.xml
index b6f3a1fd51..662b700d5d 100644
--- a/reference/rar/book.xml
+++ b/reference/rar/book.xml
@@ -14,7 +14,7 @@
    Rar is a powerful and effective archiver created by Eugene Roshal. 
    This extension gives you possibility to read Rar archives but
    doesn't support writing Rar archives, because this is not supported 
-   by UnRar library and is directly prohibited by it's license.
+   by the UnRar library and is directly prohibited by its license.
   </para>
   <para>
    More information about Rar and UnRar can be found at <link
@@ -26,6 +26,7 @@
  &reference.rar.setup;
  &reference.rar.constants;
  &reference.rar.examples;
+ &reference.rar.rarentry;
  <!-- FIXME: Apparently this extension has some classes -->
  &reference.rar.reference;
 
diff --git a/reference/rar/functions/rar-comment-get.xml b/reference/rar/functions/rar-comment-get.xml
new file mode 100644
index 0000000000..f00accf447
--- /dev/null
+++ b/reference/rar/functions/rar-comment-get.xml
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 288721 $ -->
+<refentry xml:id="function.rar-comment-get" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>rar_comment_get</refname>
+  <refpurpose>Get comment text from the Rar archive</refpurpose>
+ </refnamediv>
+ 
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>RarEntry</type><methodname>rar_comment_get</methodname>
+   <methodparam><type>resource</type><parameter>rar_file</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Get the comment stored in the Rar archive. It may be up to 64 KiB long.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>rar_file</parameter></term>
+     <listitem>
+      <para>
+       A Rar file resource, opened with <function>rar_open</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the comment or &null; if there is none.
+  </para>
+  <note>
+    <para>
+      Rar has currently no support for unicode comments. The encoding of the
+      result of this function is not specified, but it will probably be
+      Windows-1252.
+    </para>
+  </note>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/rar/functions/rar-entry-get.xml b/reference/rar/functions/rar-entry-get.xml
index 9a980b9d74..8c1538e396 100644
--- a/reference/rar/functions/rar-entry-get.xml
+++ b/reference/rar/functions/rar-entry-get.xml
@@ -36,16 +36,24 @@
       <para>
        Path to the entry within the Rar archive.
       </para>
+      <note>
+        <para>The path must be the same returned by
+        <function>RarEntry::getName</function>.</para>
+     </note>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
+  <note>
+    <para>You can also get entry objects using
+    <function>rar_list</function>.</para>
+  </note>
  </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   <function>rar_entry_get</function> returns entry object or &false; on error.
+   <function>rar_entry_get</function> returns entry object &return.falseforfailure;.
   </para>
  </refsect1>
 
diff --git a/reference/rar/functions/rar-list.xml b/reference/rar/functions/rar-list.xml
index 99e01cb294..ae170d463f 100644
--- a/reference/rar/functions/rar-list.xml
+++ b/reference/rar/functions/rar-list.xml
@@ -36,7 +36,8 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   <function>rar_list</function> returns array of entries or &false; on error.
+   <function>rar_list</function> returns array of <type>RarEntry</type> objects
+   &return.falseforfailure;.
   </para>
  </refsect1>
 
diff --git a/reference/rar/functions/rar-open.xml b/reference/rar/functions/rar-open.xml
index 0b93915e7c..a9aa471bb7 100644
--- a/reference/rar/functions/rar-open.xml
+++ b/reference/rar/functions/rar-open.xml
@@ -40,12 +40,16 @@
     </varlistentry>
    </variablelist>
   </para>
+  <warning>
+      <para>Prior to version 2.0.0, this function would not handle relative
+      paths correctly. Use <function>realpath</function> as a word-around.</para>
+  </warning>
  </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   <function>rar_open</function> returns Rar file resource or &false; on error.
+   <function>rar_open</function> returns Rar file resource &return.falseforfailure;.
   </para>
  </refsect1>
 
diff --git a/reference/rar/rarentry.xml b/reference/rar/rarentry.xml
new file mode 100644
index 0000000000..748baee44e
--- /dev/null
+++ b/reference/rar/rarentry.xml
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 288721 $ -->
+<phpdoc:classref xmlns:phpdoc="http://php.net/ns/phpdoc" xml:id="class.rarentry" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <title>The <classname>RarEntry</classname> class</title>
+ <titleabbrev>RarEntry</titleabbrev>
+ 
+ <partintro>
+ 
+<!-- {{{ RarEntry intro -->
+  <section xml:id="rarentry.intro">
+   &reftitle.intro;
+   <para>
+    A Rar entry, representing a compressed file inside a Rar archive.
+   </para>
+  </section>
+<!-- }}} -->
+ 
+  <section xml:id="rarentry.synopsis">
+   &reftitle.classsynopsis;
+
+<!-- {{{ Synopsis -->
+   <classsynopsis>
+    <ooclass><classname>RarEntry</classname></ooclass>
+
+<!-- {{{ Class synopsis -->
+    <classsynopsisinfo>
+     <ooclass>
+      <classname>RarEntry</classname>
+     </ooclass>
+    </classsynopsisinfo>
+<!-- }}} -->
+    <classsynopsisinfo role="comment">Properties</classsynopsisinfo>
+
+    
+    <classsynopsisinfo role="comment">Methods</classsynopsisinfo>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.rarentry')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
+    
+   </classsynopsis>
+<!-- }}} -->
+
+  </section>
+
+ </partintro>
+
+
+ &reference.rar.entities.rarentry;
+
+</phpdoc:classref>
+ 
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
+
diff --git a/reference/rar/functions/rar-extract.xml b/reference/rar/rarentry/extract.xml
similarity index 73%
rename from reference/rar/functions/rar-extract.xml
rename to reference/rar/rarentry/extract.xml
index 7375c7feac..74c12b7ee8 100644
--- a/reference/rar/functions/rar-extract.xml
+++ b/reference/rar/rarentry/extract.xml
@@ -1,15 +1,15 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.rar-extract" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.rarentry-extract" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
-  <refname>Rar::extract</refname>
+  <refname>RarEntry::extract</refname>
   <refpurpose>Extract entry from the archive</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
   &reftitle.description;
   <classsynopsis>
-   <ooclass><classname>Rar</classname></ooclass>
+   <ooclass><classname>RarEntry</classname></ooclass>
    <methodsynopsis>
     <type>bool</type><methodname>extract</methodname>
     <methodparam><type>string</type><parameter>dir</parameter></methodparam>
@@ -17,7 +17,7 @@
    </methodsynopsis>
   </classsynopsis>
   <para>
-   <function>Rar::extract</function> extracts entry's data to the
+   <function>RarEntry::extract</function> extracts entry's data to the
    <parameter>dir</parameter>. It will create new file in the specified
    <parameter>dir</parameter> with the name identical to the entry's name.
   </para>
@@ -31,7 +31,10 @@
      <term><parameter>dir</parameter></term>
      <listitem>
       <para>
-       Path to the directory where files should be extracted.
+       Path to the directory where files should be extracted. This parameter is
+       considered if and only if <parameter>filepath</parameter> is not. If both
+       parameters are empty an extraction to the current directory will be
+       attempted.
       </para>
      </listitem>
     </varlistentry>
@@ -39,14 +42,18 @@
      <term><parameter>filepath</parameter></term>
      <listitem>
       <para>
-       If parameter <parameter>filepath</parameter> is specified instead
-       <parameter>dir</parameter>, <function>Rar::extract</function> will extract
-       entry's data to the specified file.
+       Path (relative or absolute) containing the directory and filename of the
+       extracted file. This parameter overrides both the parameter
+       <parameter>dir</parameter> and the original file name.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
+  <warning>
+      <para>Prior to version 2.0.0, this function would not handle relative
+      paths correctly. Use <function>realpath</function> as a word-around.</para>
+  </warning>
  </refsect1>
 
  <refsect1 role="returnvalues">
@@ -60,7 +67,7 @@
   &reftitle.examples;
   <para>
    <example>
-    <title><function>Rar::extract</function> example</title>
+    <title><function>RarEntry::extract</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
diff --git a/reference/rar/functions/rar-getattr.xml b/reference/rar/rarentry/getattr.xml
similarity index 88%
rename from reference/rar/functions/rar-getattr.xml
rename to reference/rar/rarentry/getattr.xml
index b75f8daa73..9227575ca2 100644
--- a/reference/rar/functions/rar-getattr.xml
+++ b/reference/rar/rarentry/getattr.xml
@@ -1,22 +1,22 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.rar-getattr" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.rarentry-getattr" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
-  <refname>Rar::getAttr</refname>
+  <refname>RarEntry::getAttr</refname>
   <refpurpose>Get attributes of the entry</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
   &reftitle.description;
   <classsynopsis>
-   <ooclass><classname>Rar</classname></ooclass>
+   <ooclass><classname>RarEntry</classname></ooclass>
    <methodsynopsis>
     <type>int</type><methodname>getAttr</methodname>
     <void/>
    </methodsynopsis>
   </classsynopsis>
   <para>
-   <function>Rar::getAttr</function> returns attributes of the archive
+   <function>RarEntry::getAttr</function> returns attributes of the archive
    entry. 
   </para>
  </refsect1>
@@ -32,7 +32,7 @@
   &reftitle.examples;
   <para>
    <example>
-    <title><function>Rar::getAttr</function> example</title>
+    <title><function>RarEntry::getAttr</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -98,7 +98,7 @@ rar_close($rar_file);
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><xref linkend="function.rar-gethostos" /></member>
+    <member><xref linkend="function.rarentry-gethostos" /></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/rar/functions/rar-getcrc.xml b/reference/rar/rarentry/getcrc.xml
similarity index 57%
rename from reference/rar/functions/rar-getcrc.xml
rename to reference/rar/rarentry/getcrc.xml
index ba09e18332..44a644ed23 100644
--- a/reference/rar/functions/rar-getcrc.xml
+++ b/reference/rar/rarentry/getcrc.xml
@@ -1,22 +1,22 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.rar-getcrc" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.rarentry-getcrc" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
-  <refname>Rar::getCrc</refname>
+  <refname>RarEntry::getCrc</refname>
   <refpurpose>Get CRC of the entry</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
   &reftitle.description;
   <classsynopsis>
-   <ooclass><classname>Rar</classname></ooclass>
+   <ooclass><classname>RarEntry</classname></ooclass>
    <methodsynopsis>
     <type>int</type><methodname>getCrc</methodname>
     <void/>
    </methodsynopsis>
   </classsynopsis>
   <para>
-   <function>Rar::getCrc</function> returns CRC of the archive entry.
+   <function>RarEntry::getCrc</function> returns CRC of the archive entry.
   </para>
  </refsect1>
 
@@ -27,6 +27,30 @@
   </para>
  </refsect1>
 
+  <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>2.0.0</entry>
+       <entry>
+        This method now returns correct values for multiple volume archives.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/rar/functions/rar-getfiletime.xml b/reference/rar/rarentry/getfiletime.xml
similarity index 85%
rename from reference/rar/functions/rar-getfiletime.xml
rename to reference/rar/rarentry/getfiletime.xml
index feff983c7a..fdf1bc5960 100644
--- a/reference/rar/functions/rar-getfiletime.xml
+++ b/reference/rar/rarentry/getfiletime.xml
@@ -1,15 +1,15 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.rar-getfiletime" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.rarentry-getfiletime" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
-  <refname>Rar::getFileTime</refname>
+  <refname>RarEntry::getFileTime</refname>
   <refpurpose>Get entry last modification time</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
   &reftitle.description;
   <classsynopsis>
-   <ooclass><classname>Rar</classname></ooclass>
+   <ooclass><classname>RarEntry</classname></ooclass>
    <methodsynopsis>
     <type>string</type><methodname>getFileTime</methodname>
     <void/>
diff --git a/reference/rar/functions/rar-gethostos.xml b/reference/rar/rarentry/gethostos.xml
similarity index 84%
rename from reference/rar/functions/rar-gethostos.xml
rename to reference/rar/rarentry/gethostos.xml
index 2c0c06441a..95b366b2cc 100644
--- a/reference/rar/functions/rar-gethostos.xml
+++ b/reference/rar/rarentry/gethostos.xml
@@ -1,22 +1,22 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.rar-gethostos" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.rarentry-gethostos" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
-  <refname>Rar::getHostOs</refname>
+  <refname>RarEntry::getHostOs</refname>
   <refpurpose>Get entry host OS</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
   &reftitle.description;
   <classsynopsis>
-   <ooclass><classname>Rar</classname></ooclass>
+   <ooclass><classname>RarEntry</classname></ooclass>
    <methodsynopsis>
     <type>int</type><methodname>getHostOs</methodname>
     <void/>
    </methodsynopsis>
   </classsynopsis>
   <para>
-   <function>Rar::getHostOs</function> return code of the host OS of the
+   <function>RarEntry::getHostOs</function> return code of the host OS of the
    archive entry.
   </para>
  </refsect1>
@@ -32,7 +32,7 @@
   &reftitle.examples;
    <para>
    <example>
-    <title><function>Rar::getHostOs</function> example</title>
+    <title><function>RarEntry::getHostOs</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
diff --git a/reference/rar/functions/rar-getmethod.xml b/reference/rar/rarentry/getmethod.xml
similarity index 80%
rename from reference/rar/functions/rar-getmethod.xml
rename to reference/rar/rarentry/getmethod.xml
index bcb104528b..7db0ef7a41 100644
--- a/reference/rar/functions/rar-getmethod.xml
+++ b/reference/rar/rarentry/getmethod.xml
@@ -1,22 +1,22 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.rar-getmethod" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.rarentry-getmethod" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
-  <refname>Rar::getMethod</refname>
+  <refname>RarEntry::getMethod</refname>
   <refpurpose>Get pack method of the entry</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
   &reftitle.description;
   <classsynopsis>
-   <ooclass><classname>Rar</classname></ooclass>
+   <ooclass><classname>RarEntry</classname></ooclass>
    <methodsynopsis>
     <type>int</type><methodname>getMethod</methodname>
     <void/>
    </methodsynopsis>
   </classsynopsis>
   <para>
-   <function>Rar::getMethod</function> returns number of the method used when adding
+   <function>RarEntry::getMethod</function> returns number of the method used when adding
    current archive entry.
   </para>
  </refsect1>
@@ -32,7 +32,7 @@
   &reftitle.examples;
   <para>
    <example>
-    <title><function>Rar::getMethod</function> example</title>
+    <title><function>RarEntry::getMethod</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
diff --git a/reference/rar/functions/rar-getname.xml b/reference/rar/rarentry/getname.xml
similarity index 74%
rename from reference/rar/functions/rar-getname.xml
rename to reference/rar/rarentry/getname.xml
index efa3517056..dadc268382 100644
--- a/reference/rar/functions/rar-getname.xml
+++ b/reference/rar/rarentry/getname.xml
@@ -1,22 +1,22 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.rar-getname" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.rarentry-getname" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
-  <refname>Rar::getName</refname>
+  <refname>RarEntry::getName</refname>
   <refpurpose>Get name of the entry</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
   &reftitle.description;
   <classsynopsis>
-   <ooclass><classname>Rar</classname></ooclass>
+   <ooclass><classname>RarEntry</classname></ooclass>
    <methodsynopsis>
     <type>string</type><methodname>getName</methodname>
     <void/>
    </methodsynopsis>
   </classsynopsis>
   <para>
-   <function>Rar::getName</function> returns full name of the archive entry.
+   <function>RarEntry::getName</function> returns full name of the archive entry.
   </para>
  </refsect1>
 
@@ -55,16 +55,27 @@
   &reftitle.examples;
   <para>
    <example>
-    <title><function>Rar::getName</function> example</title>
+    <title><function>RarEntry::getName</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
 
+//this example is safe even in pages not encoded in UTF-8
+//for those encoded in UTF-8, the call to mb_convert_encoding is unnecessary
+
 $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
 
 $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
 
-echo "Entry name: " . $entry->getName();
+echo "Entry name: " . mb_convert_encoding(
+    htmlentities(
+        $entry->getName(),
+        ENT_COMPAT,
+        "UTF-8"
+    ),
+    "HTML-ENTITIES",
+    "UTF-8"
+);
 
 ?>
 ]]>
diff --git a/reference/rar/functions/rar-getpackedsize.xml b/reference/rar/rarentry/getpackedsize.xml
similarity index 58%
rename from reference/rar/functions/rar-getpackedsize.xml
rename to reference/rar/rarentry/getpackedsize.xml
index 8c03216131..a1fef56e62 100644
--- a/reference/rar/functions/rar-getpackedsize.xml
+++ b/reference/rar/rarentry/getpackedsize.xml
@@ -1,15 +1,15 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.rar-getpackedsize" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.rarentry-getpackedsize" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
-  <refname>Rar::getPackedSize</refname>
+  <refname>RarEntry::getPackedSize</refname>
   <refpurpose>Get packed size of the entry</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
   &reftitle.description;
   <classsynopsis>
-   <ooclass><classname>Rar</classname></ooclass>
+   <ooclass><classname>RarEntry</classname></ooclass>
    <methodsynopsis>
     <type>int</type><methodname>getPackedSize</methodname>
     <void/>
@@ -18,6 +18,11 @@
   <para>
    Get packed size of the archive entry.
   </para>
+  <note>
+    <para>Note that on platforms with 32-bit longs (that includes Windows
+    x64), the maximum size returned is capped at 2 GiB. Check the constant
+    <constant>PHP_INT_MAX</constant>.</para>
+  </note>
  </refsect1>
 
  <refsect1 role="returnvalues">
@@ -27,11 +32,37 @@
   </para>
  </refsect1>
 
+  <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>2.0.0</entry>
+       <entry>
+        This method now returns correct values of packed sizes bigger than 2 GiB
+        on platforms with 64-bit <type>integer</type>s and never
+        returns negative values on other platforms.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
    <example>
-    <title><function>Rar::getPackedSize</function> example</title>
+    <title><function>RarEntry::getPackedSize</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
diff --git a/reference/rar/rarentry/getstream.xml b/reference/rar/rarentry/getstream.xml
new file mode 100644
index 0000000000..297cbc5154
--- /dev/null
+++ b/reference/rar/rarentry/getstream.xml
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: -1 $ -->
+<refentry xml:id="function.rarentry-getstream" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>RarEntry::getStream</refname>
+  <refpurpose>Get file handler for entry.</refpurpose>
+ </refnamediv>
+ 
+ <refsect1 role="description">
+  &reftitle.description;
+  <classsynopsis>
+   <ooclass><classname>RarEntry</classname></ooclass>
+   <methodsynopsis>
+    <type>string</type><methodname>getStream</methodname>
+    <void/>
+   </methodsynopsis>
+  </classsynopsis>
+  <para>
+   <function>RarEntry::getStream</function> returns a file handler that
+   supports read operations. This handler provides on-the-fly decompression
+   for this entry.
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   The file handler &return.falseforfailure;.
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>RarEntry::getStream</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+$rar_file = rar_open('example.rar');
+if ($rar_file === false)
+    die("Failed to open Rar archive");
+
+$entry = rar_entry_get($rar_file, 'Dir/file.txt');
+if ($entry === false)
+    die("Failed to find such entry");
+
+$stream = $entry->getStream();
+if ($stream === false)
+    die("Failed to obtain stream.");
+
+while (!feof($stream)) {
+	$buff = fread($stream, 8192);
+	if ($buff !== false)
+		echo $buff;
+	else
+		break; //fread error
+}
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/rar/functions/rar-getunpackedsize.xml b/reference/rar/rarentry/getunpackedsize.xml
similarity index 57%
rename from reference/rar/functions/rar-getunpackedsize.xml
rename to reference/rar/rarentry/getunpackedsize.xml
index 06ec930888..07532cadfc 100644
--- a/reference/rar/functions/rar-getunpackedsize.xml
+++ b/reference/rar/rarentry/getunpackedsize.xml
@@ -1,15 +1,15 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.rar-getunpackedsize" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.rarentry-getunpackedsize" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
-  <refname>Rar::getUnpackedSize</refname>
+  <refname>RarEntry::getUnpackedSize</refname>
   <refpurpose>Get unpacked size of the entry</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
   &reftitle.description;
   <classsynopsis>
-   <ooclass><classname>Rar</classname></ooclass>
+   <ooclass><classname>RarEntry</classname></ooclass>
    <methodsynopsis>
     <type>int</type><methodname>getUnpackedSize</methodname>
     <void/>
@@ -18,6 +18,11 @@
   <para>
    Get unpacked size of the archive entry.
   </para>
+  <note>
+    <para>Note that on platforms with 32-bit longs (that includes Windows
+    x64), the maximum size returned is capped at 2 GiB. Check the constant
+    <constant>PHP_INT_MAX</constant>.</para>
+  </note>
  </refsect1>
 
  <refsect1 role="returnvalues">
@@ -27,11 +32,37 @@
   </para>
  </refsect1>
 
- <refsect1 role="returnvalues">
+  <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>2.0.0</entry>
+       <entry>
+        This method now returns correct values of unpacked sizes bigger than
+        2 GiB on platforms with 64-bit <type>integer</type>s and never
+        returns negative values on other platforms.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
   &reftitle.returnvalues;
   <para>
    <example>
-    <title><function>Rar::getUnpackedSize</function> example</title>
+    <title><function>RarEntry::getUnpackedSize</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
diff --git a/reference/rar/functions/rar-getversion.xml b/reference/rar/rarentry/getversion.xml
similarity index 85%
rename from reference/rar/functions/rar-getversion.xml
rename to reference/rar/rarentry/getversion.xml
index 3c96403fdd..500f9e8ead 100644
--- a/reference/rar/functions/rar-getversion.xml
+++ b/reference/rar/rarentry/getversion.xml
@@ -1,15 +1,15 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.rar-getversion" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.rarentry-getversion" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
-  <refname>Rar::getVersion</refname>
+  <refname>RarEntry::getVersion</refname>
   <refpurpose>Get version of the archiver used to add the entry</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
   &reftitle.description;
   <classsynopsis>
-   <ooclass><classname>Rar</classname></ooclass>
+   <ooclass><classname>RarEntry</classname></ooclass>
    <methodsynopsis>
     <type>int</type><methodname>getVersion</methodname>
     <void/>
@@ -31,7 +31,7 @@
   &reftitle.examples;
   <para>
    <example>
-    <title><function>Rar::getVersion</function> example</title>
+    <title><function>RarEntry::getVersion</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
diff --git a/reference/rar/versions.xml b/reference/rar/versions.xml
index 239ddfabcc..550546f40a 100644
--- a/reference/rar/versions.xml
+++ b/reference/rar/versions.xml
@@ -4,22 +4,24 @@
   Do NOT translate this file
 -->
 <versions>
- <function name='Rar::extract' from='PECL rar &gt;= 0.1'/>
- <function name='Rar::getattr' from='PECL rar &gt;= 0.1'/>
- <function name='Rar::getattr' from='PECL rar &gt;= 0.1'/>
- <function name='Rar::getcrc' from='PECL rar &gt;= 0.1'/>
- <function name='Rar::getfiletime' from='PECL rar &gt;= 0.1'/>
- <function name='Rar::gethostos' from='PECL rar &gt;= 0.1'/>
- <function name='Rar::getmethod' from='PECL rar &gt;= 0.1'/>
- <function name='Rar::getname' from='PECL rar &gt;= 0.1'/>
- <function name='Rar::getpackedsize' from='PECL rar &gt;= 0.1'/>
- <function name='Rar::getunpackedsize' from='PECL rar &gt;= 0.1'/>
- <function name='Rar::getversion' from='PECL rar &gt;= 0.1'/>
+ <function name='RarEntry::extract' from='PECL rar &gt;= 0.1'/>
+ <function name='RarEntry::getStream' from='PECL rar &gt;= 2.0.0'/>
+ <function name='RarEntry::getattr' from='PECL rar &gt;= 0.1'/>
+ <function name='RarEntry::getattr' from='PECL rar &gt;= 0.1'/>
+ <function name='RarEntry::getcrc' from='PECL rar &gt;= 0.1'/>
+ <function name='RarEntry::getfiletime' from='PECL rar &gt;= 0.1'/>
+ <function name='RarEntry::gethostos' from='PECL rar &gt;= 0.1'/>
+ <function name='RarEntry::getmethod' from='PECL rar &gt;= 0.1'/>
+ <function name='RarEntry::getname' from='PECL rar &gt;= 0.1'/>
+ <function name='RarEntry::getpackedsize' from='PECL rar &gt;= 0.1'/>
+ <function name='RarEntry::getunpackedsize' from='PECL rar &gt;= 0.1'/>
+ <function name='RarEntry::getversion' from='PECL rar &gt;= 0.1'/>
 
  <function name='rar_close' from='PECL rar &gt;= 0.1'/>
  <function name='rar_list' from='PECL rar &gt;= 0.1'/>
  <function name='rar_open' from='PECL rar &gt;= 0.1'/>
  <function name='rar_entry_get' from='PECL rar &gt;= 0.1'/>
+ <function name='rar_comment_get' from='PECL rar &gt;= 2.0.0'/>
 </versions>
 
 <!-- Keep this comment at the end of the file