From 9b90909266a6ff662d38e6ffe5d03dec72f17a79 Mon Sep 17 00:00:00 2001
From: Mehdi Achour <didou@php.net>
Date: Sun, 14 Jan 2007 04:59:01 +0000
Subject: [PATCH] id3: switch to new style

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@227194 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../id3/functions/id3-get-frame-long-name.xml |  40 +++-
 .../functions/id3-get-frame-short-name.xml    |  48 +++--
 reference/id3/functions/id3-get-genre-id.xml  |  46 +++--
 .../id3/functions/id3-get-genre-list.xml      |  28 ++-
 .../id3/functions/id3-get-genre-name.xml      |  42 +++-
 reference/id3/functions/id3-get-tag.xml       |  92 ++++++---
 reference/id3/functions/id3-get-version.xml   |  68 +++++--
 reference/id3/functions/id3-remove-tag.xml    |  69 +++++--
 reference/id3/functions/id3-set-tag.xml       | 179 +++++++++++-------
 9 files changed, 430 insertions(+), 182 deletions(-)

diff --git a/reference/id3/functions/id3-get-frame-long-name.xml b/reference/id3/functions/id3-get-frame-long-name.xml
index 141074f114..38f11df91d 100644
--- a/reference/id3/functions/id3-get-frame-long-name.xml
+++ b/reference/id3/functions/id3-get-frame-long-name.xml
@@ -1,12 +1,12 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <refentry id="function.id3-get-frame-long-name">
  <refnamediv>
   <refname>id3_get_frame_long_name</refname>
   <refpurpose>Get the long name of an ID3v2 frame</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>string</type><methodname>id3_get_frame_long_name</methodname>
    <methodparam><type>string</type><parameter>frameId</parameter></methodparam>
@@ -15,9 +15,30 @@
    <function>id3_get_frame_long_name</function> returns the long name for an
    ID3v2 frame.
   </para>
+ </refsect1>
+ <refsect1 role="parameters">
+  &reftitle.parameters;
   <para>
-
+   <variablelist>
+    <varlistentry>
+     <term><parameter>frameId</parameter></term>
+     <listitem>
+      <para>
+       An ID3v2 frame
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the frame long name or &false; on errors.
+  </para>
+ </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>id3_get_frame_long_name</function> example</title>
@@ -29,9 +50,7 @@ echo $longName;
 ?>
 ]]>
     </programlisting>
-    <para>
-     This will output:
-    </para>
+    &example.outputs;
     <screen>
 <![CDATA[
 Original lyricist(s)/text writer(s)
@@ -39,8 +58,13 @@ Original lyricist(s)/text writer(s)
     </screen>
    </example>
   </para>
+ </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   See also <function>id3_get_frame_short_name</function>.
+   <simplelist>
+    <member><function>id3_get_frame_short_name</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>
diff --git a/reference/id3/functions/id3-get-frame-short-name.xml b/reference/id3/functions/id3-get-frame-short-name.xml
index aeee0635f6..39e96c883d 100644
--- a/reference/id3/functions/id3-get-frame-short-name.xml
+++ b/reference/id3/functions/id3-get-frame-short-name.xml
@@ -1,12 +1,12 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <refentry id="function.id3-get-frame-short-name">
  <refnamediv>
   <refname>id3_get_frame_short_name</refname>
   <refpurpose>Get the short name of an ID3v2 frame</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>string</type><methodname>id3_get_frame_short_name</methodname>
    <methodparam><type>string</type><parameter>frameId</parameter></methodparam>
@@ -15,9 +15,34 @@
    <function>id3_get_frame_short_name</function> returns the short name for an
    ID3v2 frame.
   </para>
+ </refsect1>
+ <refsect1 role="parameters">
+  &reftitle.parameters;
   <para>
-
+   <variablelist>
+    <varlistentry>
+     <term><parameter>frameId</parameter></term>
+     <listitem>
+      <para>
+       An ID3v2 frame
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the frame short name or &false; on errors.
+  </para>
+  <para>
+   The values returned by <function>id3_get_short_name</function> are used in the
+   array returned by <function>id3_get_tag</function>.
+  </para>
+ </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>id3_get_frame_short_name</function> example</title>
@@ -29,9 +54,7 @@ echo $shortName;
 ?>
 ]]>
     </programlisting>
-    <para>
-     This will output:
-    </para>
+    &example.outputs;
     <screen>
 <![CDATA[
 originalLyricist
@@ -39,12 +62,13 @@ originalLyricist
     </screen>
    </example>
   </para>
+ </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   The values returned by <function>id3_get_short_name</function> are used in the
-   array returned by <function>id3_get_tag</function>.
-  </para>
-  <para>
-   See also <function>id3_get_frame_long_name</function>.
+   <simplelist>
+    <member><function>id3_get_frame_long_name</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>
diff --git a/reference/id3/functions/id3-get-genre-id.xml b/reference/id3/functions/id3-get-genre-id.xml
index 6a2f09c5b7..139e2b347a 100644
--- a/reference/id3/functions/id3-get-genre-id.xml
+++ b/reference/id3/functions/id3-get-genre-id.xml
@@ -1,25 +1,43 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="function.id3-get-genre-id">
  <refnamediv>
   <refname>id3_get_genre_id</refname>
   <refpurpose>Get the id for a genre</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>int</type><methodname>id3_get_genre_id</methodname>
    <methodparam><type>string</type><parameter>genre</parameter></methodparam>
   </methodsynopsis>
   <para>
-   <function>id3_get_genre_id</function> returns the id for a genre. If the
-   specified genre is not available in the genre list, <function>id3_get_genre_id</function>
-   will return &false;
+   <function>id3_get_genre_id</function> returns the id for a genre.
   </para>
+ </refsect1>
+ <refsect1 role="parameters">
+  &reftitle.parameters;
   <para>
-   In an ID3 tag, the genre is stored using a integer ranging from 0 to
-   147.
+   <variablelist>
+    <varlistentry>
+     <term><parameter>genre</parameter></term>
+     <listitem>
+      <para>
+       An integer ranging from 0 to 147
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   The genre id or &false; on errors.
+  </para>
+ </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>id3_get_genre_id</function> example</title>
@@ -31,9 +49,7 @@ echo $id;
 ?>
 ]]>
     </programlisting>
-    <para>
-     This will output:
-    </para>
+    &example.outputs;
     <screen>
 <![CDATA[
 20
@@ -41,8 +57,14 @@ echo $id;
     </screen>
    </example>
   </para>
+ </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   See also <function>id3_get_genre_list</function> and <function>id3_get_genre_name</function>.
+   <simplelist>
+    <member><function>id3_get_genre_name</function></member>
+    <member><function>id3_get_genre_list</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>
diff --git a/reference/id3/functions/id3-get-genre-list.xml b/reference/id3/functions/id3-get-genre-list.xml
index 438673e9ad..307eb8e259 100644
--- a/reference/id3/functions/id3-get-genre-list.xml
+++ b/reference/id3/functions/id3-get-genre-list.xml
@@ -1,12 +1,12 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="function.id3-get-genre-list">
  <refnamediv>
   <refname>id3_get_genre_list</refname>
   <refpurpose>Get all possible genre values</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>array</type><methodname>id3_get_genre_list</methodname>
    <void />
@@ -21,6 +21,16 @@
    they may choose one. When updating the ID3 tag you will always have to
    specify the genre as an integer ranging from 0 to 147.
   </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns an array containing all possible genres that may be stored in an
+   ID3 tag.
+  </para>
+ </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>id3_get_genre_list</function> example</title>
@@ -32,9 +42,7 @@ print_r($genres);
 ?>
 ]]>
     </programlisting>
-    <para>
-     This will output:
-    </para>
+    &example.outputs;
     <screen>
 <![CDATA[
 Array
@@ -192,8 +200,14 @@ Array
     </screen>
    </example>
   </para>
+ </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   See also <function>id3_get_genre_name</function> and <function>id3_get_genre_id</function>.
+   <simplelist>
+    <member><function>id3_get_genre_name</function></member>
+    <member><function>id3_get_genre_id</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>
diff --git a/reference/id3/functions/id3-get-genre-name.xml b/reference/id3/functions/id3-get-genre-name.xml
index 4537632b64..131e06985d 100644
--- a/reference/id3/functions/id3-get-genre-name.xml
+++ b/reference/id3/functions/id3-get-genre-name.xml
@@ -1,12 +1,12 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry id="function.id3-get-genre-name">
  <refnamediv>
   <refname>id3_get_genre_name</refname>
   <refpurpose>Get the name for a genre id</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>string</type><methodname>id3_get_genre_name</methodname>
    <methodparam><type>int</type><parameter>genre_id</parameter></methodparam>
@@ -14,10 +14,30 @@
   <para>
    <function>id3_get_genre_name</function> returns the name for a genre id.
   </para>
+ </refsect1>
+ <refsect1 role="parameters">
+  &reftitle.parameters;
   <para>
-   In an ID3 tag, the genre is stored using a integer ranging from 0 to
-   147.
+   <variablelist>
+    <varlistentry>
+     <term><parameter>genre_id</parameter></term>
+     <listitem>
+      <para>
+       An integer ranging from 0 to 147
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the name as a string.
+  </para>
+ </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>id3_get_genre_name</function> example</title>
@@ -29,9 +49,7 @@ echo $genre;
 ?>
 ]]>
     </programlisting>
-    <para>
-     This will output:
-    </para>
+    &example.outputs;
     <screen>
 <![CDATA[
 Alternative
@@ -39,8 +57,14 @@ Alternative
     </screen>
    </example>
   </para>
+ </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   See also <function>id3_get_genre_list</function> and <function>id3_get_genre_id</function>.
+   <simplelist>
+    <member><function>id3_get_genre_list</function></member>
+    <member><function>id3_get_genre_id</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>
diff --git a/reference/id3/functions/id3-get-tag.xml b/reference/id3/functions/id3-get-tag.xml
index 0dcfc3f797..14299473b4 100644
--- a/reference/id3/functions/id3-get-tag.xml
+++ b/reference/id3/functions/id3-get-tag.xml
@@ -1,12 +1,12 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <refentry id="function.id3-get-tag">
  <refnamediv>
   <refname>id3_get_tag</refname>
   <refpurpose>Get all information stored in an ID3 tag</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>array</type><methodname>id3_get_tag</methodname>
    <methodparam><type>string</type><parameter>filename</parameter></methodparam>
@@ -16,14 +16,56 @@
    <function>id3_get_tag</function> is used to get all information stored
    in the id3 tag of the specified file.
   </para>
-  <note>
-   <simpara>Instead of a filename you may also pass a valid stream resource.</simpara>
-  </note>
+ </refsect1>
+ <refsect1 role="parameters">
+  &reftitle.parameters;
   <para>
-   The optional <parameter>version</parameter> parameter allows you to
-   specify the version of the tag as MP3 files may contain both, version 1.x and
-   version 2.x tags.
+   <variablelist>
+    <varlistentry>
+     <term><parameter>filename</parameter></term>
+     <listitem>
+      <para>
+       The path to the MP3 file
+      </para>
+      <para>
+       Instead of a filename you may also pass a valid stream resource
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>version</parameter></term>
+     <listitem>
+      <para>
+       Allows you to specify the version of the tag as MP3 files may contain
+       both, version 1.x and version 2.x tags
+      </para>
+      <para>
+       Since version 0.2 <function>id3_get_tag</function> also supports ID3
+       tags of version 2.2, 2.3 and 2.4. To extract information from these
+       tags, pass one of the constants ID3_V2_2, ID3_V2_3 or ID3_V2_4 as the
+       second parameter.
+       ID3 v2.x tags can contain a lot more information about the MP3 file
+       than ID3 v1.x tags.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns an associative array with various keys like: 
+   <literal>title</literal>, <literal>artist</literal>, ..
+  </para>
+  <para>
+   The key <literal>genre</literal> will contain an integer between 0 and
+   147. You may use <function>id3_get_genre_name</function> to convert it to
+   a human readable string.
+  </para>
+ </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>id3_get_tag</function> example</title>
@@ -35,9 +77,7 @@ print_r($tag);
 ?>
 ]]>
     </programlisting>
-    <para>
-     This will output something like:
-    </para>
+    &example.outputs.similar;
     <screen>
 <![CDATA[
 Array
@@ -51,17 +91,6 @@ Array
 ]]>
     </screen>
    </example>
-  </para>
-  <para>
-    The key <literal>genre</literal> will contain an integer between 0 and 147. You may
-    use <function>id3_get_genre_name</function> to convert it to a human readable string.
-  </para>
-  <para>
-   Since version 0.2 <function>id3_get_tag</function> also supports ID3 tags of version 2.2, 2.3 and 2.4.
-   To extract information from these tags, pass one of the constants ID3_V2_2, ID3_V2_3 or ID3_V2_4 as the
-   second parameter.
-  </para>
-  <para>
    <example>
     <title><function>id3_get_tag</function> example</title>
     <programlisting role="php">
@@ -72,9 +101,7 @@ print_r($tag);
 ?>
 ]]>
     </programlisting>
-    <para>
-     This will output something like:
-    </para>
+    &example.outputs.similar;
     <screen>
 <![CDATA[
 Array
@@ -93,12 +120,15 @@ Array
     </screen>
    </example>
   </para>
+ </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   ID3 v2.x tags can contain a lot more information about the MP3 file than ID3 v1.x tags.
-  </para>
-  <para>
-   See also <function>id3_set_tag</function>,
-   <function>id3_remove_tag</function> and <function>id3_get_version</function>.
+   <simplelist>
+    <member><function>id3_set_tag</function></member>
+    <member><function>id3_remove_tag</function></member>
+    <member><function>id3_get_version</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>
diff --git a/reference/id3/functions/id3-get-version.xml b/reference/id3/functions/id3-get-version.xml
index a0f7217c6f..2453449f6b 100644
--- a/reference/id3/functions/id3-get-version.xml
+++ b/reference/id3/functions/id3-get-version.xml
@@ -1,25 +1,55 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <refentry id="function.id3-get-version">
  <refnamediv>
   <refname>id3_get_version</refname>
   <refpurpose>Get version of an ID3 tag</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>int</type><methodname>id3_get_version</methodname>
    <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   </methodsynopsis>
   <para>
-   <function>id3_get_version</function> retrieves the version(s) of the ID3 tag(s) in
-   the MP3 file. As a tag can contain ID3 v1.x and v2.x tags, the return value of this
-   function should be bitwise compared with the predefined constants <constant>ID3_V1_0</constant>,
-   <constant>ID3_V1_1</constant> and  <constant>ID3_V2</constant>.
+   <function>id3_get_version</function> retrieves the version(s) of the 
+   ID3 tag(s) in the MP3 file.
   </para>
-  <note>
-   <simpara>Instead of a filename you may also pass a valid stream resource.</simpara>
-  </note>
+  <para>
+   If a file contains an ID3 v1.1 tag, it always contains
+   a 1.0 tag, as version 1.1 is just an extension of 1.0.
+  </para>
+ </refsect1>
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>filename</parameter></term>
+     <listitem>
+      <para>
+       The path to the MP3 file
+      </para>
+      <para>
+       Instead of a filename you may also pass a valid stream resource
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the version number of the ID3 tag of the file.
+   As a tag can contain ID3 v1.x and v2.x tags, the return value of this
+   function should be bitwise compared with the predefined constants 
+   <constant>ID3_V1_0</constant>, <constant>ID3_V1_1</constant> and  
+   <constant>ID3_V2</constant>.
+  </para>
+ </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>id3_get_version</function> example</title>
@@ -39,9 +69,7 @@ if ($version & ID3_V2) {
 ?>
 ]]>
     </programlisting>
-    <para>
-     This will output something like:
-    </para>
+    &example.outputs.similar;
     <screen>
 <![CDATA[
 Contains a 1.x tag
@@ -50,13 +78,15 @@ Contains a 1.1 tag
     </screen>
    </example>
   </para>
+ </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-    If a file contains an ID3 v1.1 tag, it always contains
-    a 1.0 tag, as version 1.1 is just an extension of 1.0.
-  </para>
-  <para>
-   See also <function>id3_get_tag</function>, <function>id3_set_tag</function> and
-   <function>id3_remove_tag</function>.
+   <simplelist>
+    <member><function>id3_set_tag</function></member>
+    <member><function>id3_get_tag</function></member>
+    <member><function>id3_remove_tag</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>
diff --git a/reference/id3/functions/id3-remove-tag.xml b/reference/id3/functions/id3-remove-tag.xml
index 6ef5f5c486..caeeb2d892 100644
--- a/reference/id3/functions/id3-remove-tag.xml
+++ b/reference/id3/functions/id3-remove-tag.xml
@@ -1,12 +1,12 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <refentry id="function.id3-remove-tag">
  <refnamediv>
   <refname>id3_remove_tag</refname>
   <refpurpose>Remove an existing ID3 tag</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>id3_remove_tag</methodname>
    <methodparam><type>string</type><parameter>filename</parameter></methodparam>
@@ -14,17 +14,44 @@
   </methodsynopsis>
   <para>
    <function>id3_remove_tag</function> is used to remove the information stored
-   of an ID3 tag. If no tag has been present, it will return &false; and leave the file
-   as it was.
+   of an ID3 tag.
   </para>
-  <note>
-   <simpara>Instead of a filename you may also pass a valid stream resource.</simpara>
-  </note>
+ </refsect1>
+ <refsect1 role="parameters">
+  &reftitle.parameters;
   <para>
-   The optional <parameter>version</parameter> parameter allows you to
-   specify the version of the tag as MP3 files may contain both, version 1.x and
-   version 2.x tags.
+   <variablelist>
+    <varlistentry>
+     <term><parameter>filename</parameter></term>
+     <listitem>
+      <para>
+       The path to the MP3 file
+      </para>
+      <para>
+       Instead of a filename you may also pass a valid stream resource
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>version</parameter></term>
+     <listitem>
+      <para>
+       Allows you to specify the version of the tag as MP3 files may contain
+       both, version 1.x and version 2.x tags.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.success;
+  </para>
+ </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>id3_remove_tag</function> example</title>
@@ -48,17 +75,25 @@ Tag succesfully removed
     </screen>
    </example>
   </para>
+ </refsect1>
+ <refsect1 role="notes">
+  &reftitle.notes;
   <note>
    <simpara>
-    Currently <function>id3_remove_tag</function> only supports
-    version 1.0 and 1.1. If you choose to remove a 1.0 tag and the file
-    contains a 1.1 tag, this tag will be removed, as v1.1 is only an
-    extension of 1.0.
+    Currently <function>id3_remove_tag</function> only supports version 1.0
+    and 1.1. If you choose to remove a 1.0 tag and the file contains a 1.1
+    tag, this tag will be removed, as v1.1 is only an extension of 1.0.
    </simpara>
   </note>
+ </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   See also <function>id3_get_tag</function>,
-   <function>id3_set_tag</function> and <function>id3_get_version</function>.
+   <simplelist>
+    <member><function>id3_set_tag</function></member>
+    <member><function>id3_get_tag</function></member>
+    <member><function>id3_get_version</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>
diff --git a/reference/id3/functions/id3-set-tag.xml b/reference/id3/functions/id3-set-tag.xml
index 32a286874b..cae1e9f3ea 100644
--- a/reference/id3/functions/id3-set-tag.xml
+++ b/reference/id3/functions/id3-set-tag.xml
@@ -1,12 +1,12 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <refentry id="function.id3-set-tag">
  <refnamediv>
   <refname>id3_set_tag</refname>
   <refpurpose>Update information stored in an ID3 tag</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>id3_set_tag</methodname>
    <methodparam><type>string</type><parameter>filename</parameter></methodparam>
@@ -17,14 +17,104 @@
    <function>id3_set_tag</function> is used to change the information stored
    of an ID3 tag. If no tag has been present, it will be added to the file.
   </para>
-  <note>
-   <simpara>Instead of a filename you may also pass a valid stream resource.</simpara>
-  </note>
+ </refsect1>
+ <refsect1 role="parameters">
+  &reftitle.parameters;
   <para>
-   The optional <parameter>version</parameter> parameter allows you to
-   specify the version of the tag as MP3 files may contain both, version 1.x and
-   version 2.x tags.
+   <variablelist>
+    <varlistentry>
+     <term><parameter>filename</parameter></term>
+     <listitem>
+      <para>
+       The path to the MP3 file
+      </para>
+      <para>
+       Instead of a filename you may also pass a valid stream resource
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>tag</parameter></term>
+     <listitem>
+      <para>
+       An associative array of tag keys and values
+      </para>
+      <para>
+       The following keys may be used in the associative array:
+      </para>
+      <para>
+       <table>
+        <title>Keys in the associative array</title>
+        <tgroup cols="3">
+         <thead>
+          <row>
+           <entry>key</entry>
+           <entry>possible value</entry>
+           <entry>available in version</entry>
+          </row>
+         </thead>
+         <tbody>
+          <row>
+           <entry>title</entry>
+           <entry>string with maximum of 30 characters</entry>
+           <entry>v1.0, v1.1</entry>
+          </row>
+          <row>
+           <entry>artist</entry>
+           <entry>string with maximum of 30 characters</entry>
+           <entry>v1.0, v1.1</entry>
+          </row>
+          <row>
+           <entry>album</entry>
+           <entry>string with maximum of 30 characters</entry>
+           <entry>v1.0, v1.1</entry>
+          </row>
+          <row>
+           <entry>year</entry>
+           <entry>4 digits</entry>
+           <entry>v1.0, v1.1</entry>
+          </row>
+          <row>
+           <entry>genre</entry>
+           <entry>integer value between 0 and 147</entry>
+           <entry>v1.0, v1.1</entry>
+          </row>
+          <row>
+           <entry>comment</entry>
+           <entry>string with maximum of 30 characters (28 in v1.1)</entry>
+           <entry>v1.0, v1.1</entry>
+          </row>
+          <row>
+           <entry>track</entry>
+           <entry>integer between 0 and 255</entry>
+           <entry>v1.1</entry>
+          </row>
+         </tbody>
+        </tgroup>
+       </table>
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>version</parameter></term>
+     <listitem>
+      <para>
+       Allows you to specify the version of the tag as MP3 files may contain
+       both, version 1.x and version 2.x tags
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.success;
+  </para>
+ </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>id3_set_tag</function> example</title>
@@ -53,69 +143,24 @@ Tag succesfully updated
     </screen>
    </example>
   </para>
+ </refsect1>
+ <refsect1 role="notes">
+  &reftitle.notes;
   <note>
    <simpara>
-    Currently <function>id3_set_tag</function> only supports
-    version 1.0 and 1.1.
+    Currently <function>id3_remove_tag</function> only supports version 1.0
+    and 1.1. 
    </simpara>
   </note>
+ </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   The following keys may be used in the associative array:
-  </para>
-  <para>
-   <table>
-    <title>Keys in the associative array</title>
-    <tgroup cols="3">
-     <thead>
-      <row>
-       <entry>key</entry>
-       <entry>possible value</entry>
-       <entry>available in version</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>title</entry>
-       <entry>string with maximum of 30 characters</entry>
-       <entry>v1.0, v1.1</entry>
-      </row>
-      <row>
-       <entry>artist</entry>
-       <entry>string with maximum of 30 characters</entry>
-       <entry>v1.0, v1.1</entry>
-      </row>
-      <row>
-       <entry>album</entry>
-       <entry>string with maximum of 30 characters</entry>
-       <entry>v1.0, v1.1</entry>
-      </row>
-      <row>
-       <entry>year</entry>
-       <entry>4 digits</entry>
-       <entry>v1.0, v1.1</entry>
-      </row>
-      <row>
-       <entry>genre</entry>
-       <entry>integer value between 0 and 147</entry>
-       <entry>v1.0, v1.1</entry>
-      </row>
-      <row>
-       <entry>comment</entry>
-       <entry>string with maximum of 30 characters (28 in v1.1)</entry>
-       <entry>v1.0, v1.1</entry>
-      </row>
-      <row>
-       <entry>track</entry>
-       <entry>integer between 0 and 255</entry>
-       <entry>v1.1</entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
-   </para>
-  <para>
-   See also <function>id3_get_tag</function>,
-   <function>id3_remove_tag</function> and <function>id3_get_version</function>.
+   <simplelist>
+    <member><function>id3_remove_tag</function></member>
+    <member><function>id3_get_tag</function></member>
+    <member><function>id3_get_version</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>