Initial documentation

Initial version of the phpdoc compatible documentation. We still have to add a lot of examples and description, but basically the call parameters of all methods are documented. Signed-off-by: David Soria Parra <dsp@php.net>
dsp · May 14, 2008 · 544393e · 544393e
1 parent 435156d
commit 544393e
Show file tree

Hide file tree

Showing 27 changed files with 1,361 additions and 0 deletions.
diff --git a/manual/Makefile b/manual/Makefile
@@ -0,0 +1,24 @@
+# 
+all: html
+
+confcheck:
+	@if test "x$(PHPDOC)" = "x"; then echo PHPDOC not set; exit 3; fi
+
+manual.xml: manual.xml.in
+	sed -e's:@PHPDOC@:$(PHPDOC):g' < manual.xml.in > manual.xml
+
+html: confcheck manual.xml
+	rm -rf html; mkdir html
+	SP_ENCODING=XML SP_CHARSET_FIXED=YES openjade -D $(PHPDOC) -wno-idref -c $(PHPDOC)/docbook/docbook-dsssl/catalog -c $(PHPDOC)/phpbook/phpbook-dsssl/defaults/catalog -d $(PHPDOC)/phpbook/phpbook-dsssl/html.dsl -V use-output-dir -t sgml $(PHPDOC)/phpbook/phpbook-xml/phpdocxml.dcl manual.xml
+
+bightml: confcheck manual.xml
+	rm -rf html; mkdir html
+	SP_ENCODING=XML SP_CHARSET_FIXED=YES openjade -D $(PHPDOC) -wno-idref -c $(PHPDOC)/docbook/docbook-dsssl/catalog -c $(PHPDOC)/phpbook/phpbook-dsssl/defaults/catalog -d $(PHPDOC)/phpbook/phpbook-dsssl/html.dsl -V nochunks -t sgml $(PHPDOC)/phpbook/phpbook-xml/phpdocxml.dcl manual.xml > manual.html
+
+tex: manual.tex
+
+manual.tex: confcheck manual.xml
+	SP_ENCODING=XML SP_CHARSET_FIXED=YES openjade -D $(PHPDOC) -wno-idref -c $(PHPDOC)/docbook/docbook-dsssl/catalog -c $(PHPDOC)/phpbook/phpbook-dsssl/defaults/catalog -d $(PHPDOC)/phpbook/phpbook-dsssl/print.dsl -t tex $(PHPDOC)/phpbook/phpbook-xml/phpdocxml.dcl manual.xml
+
+pdf: manual.tex
+	pdfjadetex manual.tex && pdfjadetex manual.tex && pdfjadetex manual.tex
diff --git a/manual/manual.xml.in b/manual/manual.xml.in
@@ -0,0 +1,37 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'
+          '@PHPDOC@/dtds/dbxml-4.1.2/docbookx.dtd' [
+
+<!-- Add translated specific definitions and snippets -->
+<!ENTITY % language-defs     SYSTEM '@PHPDOC@/en/language-defs.ent'>
+<!ENTITY % language-snippets SYSTEM '@PHPDOC@/en/language-snippets.ent'>
+
+%language-defs;
+%language-snippets;
+
+<!-- Fallback to English definitions and snippets (in case of missing translation) -->
+<!ENTITY % language-defs.default     SYSTEM '@PHPDOC@/en/language-defs.ent'>
+<!ENTITY % language-snippets.default SYSTEM '@PHPDOC@/en/language-snippets.ent'>
+<!ENTITY % extensions.default        SYSTEM '@PHPDOC@/en/extensions.ent'>
+
+%language-defs.default;
+%language-snippets.default;
+%extensions.default;
+
+<!-- All global entities for the XML files -->
+<!ENTITY % global.entities  SYSTEM '@PHPDOC@/entities/global.ent'>
+
+<!ENTITY % file.entities      SYSTEM './file-entities.ent'>
+
+<!-- Include all external DTD parts defined previously -->
+%global.entities;
+%file.entities;
+
+<!-- Autogenerated missing entites and IDs to make build work -->
+<!ENTITY % missing-entities  SYSTEM '@PHPDOC@/entities/missing-entities.ent'>
+%missing-entities;
+]>
+
+<book id='manual' lang='en'>
+   &reference.taglib.reference;
+</book>
diff --git a/manual/taglib/book.xml b/manual/taglib/book.xml
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision:$ -->
+<!-- Purpose: utilspec.audio -->
+<!-- Membership: pecl -->
+
+<book xml:id="book.taglib" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>TagLib</title>
+ <preface xml:id="intro.taglib">
+  &reftitle.intro;
+  <para>
+    The module enables you to read and write ID3v1, ID3v2 and Ogg tags.
+    It is build using the taglib extension from the KDE project.
+  </para>
+  <note>
+   <para>
+     At the moment taglib is able to read ID3v1 and ID3v2 tags. 
+     There is no write support at the moment.
+   </para>
+  </note>
+  <note>
+    <para>
+      This extension doesnot run under windows.
+    </para>
+  </note>
+ </preface>
+ &reference.taglib.setup;
+ &reference.taglib.examples;
+ &reference.taglib.tag;
+ &reference.taglib.mpegfile;
+ &reference.taglib.id3v2frame;
+ &reference.taglib.id3v2attachedpictureframe;
+</book>
+
+<!-- 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:"../../../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/manual/taglib/configure.xml b/manual/taglib/configure.xml
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision:$ -->
+<section xml:id="taglib.installation" xmlns="http://docbook.org/ns/docbook">
+ &reftitle.install;
+ <para>
+  Taglib support in PHP is not enabled by default. You will need to
+  configure PHP <option role="configure">--with-taglib[=DIR]</option>
+ </para>
+ <note>
+  <simpara>
+    Taglib is part of PECL.
+  </simpara>
+ </note>
+</section>
+
+<!-- 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:"../../../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/manual/taglib/examples.xml b/manual/taglib/examples.xml
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision:$ -->
+
+<chapter xml:id="taglib.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ &reftitle.examples;
+ <para>
+   The example read an ID3v2 tag from an MP3 and saves it's attached
+   cover.
+ </para>
+ <example>
+  <title>Small Taglib Example</title>
+  <programlisting role="php">
+<![CDATA[
+<?php
+$taglib = new TagLib_MPEG_File('example.mp3');
+$frames = $taglib->getID3v2Tag()->getFrameList();
+if (isset($frames['APIC'])) {
+  $frames['APIC']->savePicture('example.png');
+} else {
+  die("No picture frame");
+}
+?>
+]]>
+  </programlisting>
+ </example>
+</chapter>
+
+<!-- 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:"../../../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/manual/taglib/id3v2attachedpictureframe.xml b/manual/taglib/id3v2attachedpictureframe.xml
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision:$ -->
+<reference xml:id="class.id3v2attachedpictureframe" 
+	   xmlns="http://docbook.org/ns/docbook" 
+	   xmlns:xlink="http://www.w3.org/1999/xlink" 
+	   xmlns:xi="http://www.w3.org/2001/XInclude">
+  <title>The Taglib ID3v2_AttachedPictureFrame class</title>
+  <titleabbrev>Taglib_ID3v2_AttachedPictureFrame</titleabbrev>
+  <partintro>
+    <section xml:id="id3v2attachedpictureframe.intro">
+      &reftitle.intro;
+      <para>
+        Represents an APIC frame. APIC frames contain attached pictures in various
+        formats. Usually the picture is stored in PNG or JPEG format. You can use
+        the <function>getMimeType</function> to determine the type.
+     </para>
+      <note>
+        <para>
+          At the moment only APIC frames of ID3v2.3 and ID3v2.4 are supported. ID3v2.2 
+          as usual written by iTunes are NOT supported. This is a limitation of taglib.
+        </para>
+      </note>
+   </section>
+   <section xml:id="id3v2attachedpictureframe.synopsis">
+     &reftitle.classsynopsis;
+     <classsynopsis>
+       <ooclass>
+         <classname>Taglib_ID3v2_AttachedPictureFrame</classname>
+       </ooclass>
+       <classsynopsisinfo>
+         <ooclass>
+           <classname>Taglib_ID3v2_AttachedPictureFrame</classname>
+         </ooclass>
+       </classsynopsisinfo>
+       <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.id3v2attachedpictureframe')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />        
+     </classsynopsis>
+   </section>
+</partintro>
+&reference.taglib.entities.id3v2attachedpictureframe;
+</reference>
+
+<!-- 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:"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/manual/taglib/id3v2attachedpictureframe/getDescription.xml b/manual/taglib/id3v2attachedpictureframe/getDescription.xml
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision:$ -->
+<refentry xml:id="id3v2attachedpictureframe.getDescription" xmlns="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>TagLib_ID3v2_AttachedPictureFrame::getDescription</refname>
+    <refpurpose>Returns a description for the picture in a picture frame</refpurpose>
+  </refnamediv>
+  <refsect1 role="description">
+    &reftitle.description;
+    <methodsynopsis>
+      <modifier>public</modifier>
+      <type>string</type>
+      <methodname>TagLib_ID3v2_AttachedPictureFrame::getDescription</methodname>
+      <void/>
+    </methodsynopsis>
+    <para>
+      Returns the attached description for a picture frame in an ID3v2.x frame.
+    </para>
+  </refsect1>
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+    Returns a description for the picture in a picture frame
+  </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:"../../../../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/manual/taglib/id3v2attachedpictureframe/getMimeType.xml b/manual/taglib/id3v2attachedpictureframe/getMimeType.xml
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision:$ -->
+<refentry xml:id="id3v2attachedpictureframe.getMimeType" xmlns="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>TagLib_ID3v2_AttachedPictureFrame::getMimeType</refname>
+    <refpurpose>Returns the mime type of the picture</refpurpose>
+  </refnamediv>
+  <refsect1 role="description">
+    &reftitle.description;
+    <methodsynopsis>
+      <modifier>public</modifier>
+      <type>string</type>
+      <methodname>TagLib_ID3v2_AttachedPictureFrame::getMimeType</methodname>
+      <void/>
+    </methodsynopsis>
+    <para>
+      Returns the mime type of the image represented by the attached picture frame.
+    </para>
+    <para>
+      Please notice that this method might return different types. While ID3v2.2 
+      have a mime type that doesn't start with "image/", ID3v2.3 and v2.4 usually
+      start with "image/". Therefore the method might return "image/png" for IDv2.3 frames
+      and just "PNG" for ID3v2.2 frames. 
+    </para>
+    <para>
+      Notice that even the frame is an attached picture, the mime type might not be set
+      and therefore an empty string might be returned.
+    </para>
+  </refsect1>
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+    Returns the mime type of the image represented by the attached picture frame.
+  </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:"../../../../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
+-->