Hi all
Attached is a patch to the Docbook DTD which introduces a
phpdoc:exception element inside <book /> elements.
<phpdoc:exception /> is defined exactly like <reference /> except that
<refentry /> is optional for <phpdoc:exception />.
This solves some of the problems we have, namely the problem of
classes, exceptions and extensions that do not define any
methods/functions.
Included in the patch is a fix for HaruException and PDOException.
Furthermore a patch for PhD(0_2) is attached to support the new
element.
If there are no objections I'd like to commit this sometime in the
next couple of days...
-Hannes
Index: docbook/docbook-xml/docbook.dtd
===================================================================
RCS file: /repository/phpdoc/docbook/docbook-xml/docbook.dtd,v
retrieving revision 1.3
diff -u -p -r1.3 docbook.dtd
--- docbook/docbook-xml/docbook.dtd 10 Dec 2007 16:29:47 -0000 1.3
+++ docbook/docbook-xml/docbook.dtd 21 Jul 2008 19:32:07 -0000
@@ -25,6 +25,7 @@
linkend IDREF #IMPLIED
xmlns:xlink CDATA #FIXED 'http://www.w3.org/1999/xlink'
xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'
+ xmlns:phpdoc CDATA #FIXED 'http://php.net/ns/phpdoc'
xlink:href CDATA #IMPLIED
xlink:type CDATA #IMPLIED
xlink:role CDATA #IMPLIED
@@ -2530,7 +2531,7 @@
>
-<!ELEMENT book (((title|titleabbrev|subtitle)*, info?),
(glossary|bibliography|index|toc|dedication|acknowledgements|preface|chapter|appendix|article|colophon|part|reference)+)>
+<!ELEMENT book (((title|titleabbrev|subtitle)*, info?),
(glossary|bibliography|index|toc|dedication|acknowledgements|preface|chapter|appendix|article|colophon|part|reference|phpdoc:exception)+)>
<!ATTLIST book
xmlns CDATA #FIXED "http://docbook.org/ns/docbook";
@@ -2747,6 +2748,18 @@
>
+<!ELEMENT exception (((title|titleabbrev|subtitle)*, info?), partintro?,
(refentry)*)>
+
+<!ATTLIST exception
+ xmlns CDATA #FIXED "http://docbook.org/ns/docbook";
+ role CDATA #IMPLIED
+ %db.common.attributes;
+ %db.common.linking.attributes;
+ status CDATA #IMPLIED
+ label CDATA #IMPLIED
+
+>
+
<!ELEMENT refentry ((indexterm)*, info?, refmeta?, (refnamediv)+,
refsynopsisdiv?, ((refsection)+|(refsect1)+))>
<!ATTLIST refentry
Index: en/reference/haru/haruexception.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/haru/haruexception.xml,v
retrieving revision 1.4
diff -u -p -r1.4 haruexception.xml
--- en/reference/haru/haruexception.xml 26 Dec 2007 18:56:28 -0000 1.4
+++ en/reference/haru/haruexception.xml 21 Jul 2008 19:32:07 -0000
@@ -1,6 +1,9 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.4 $ -->
-<reference xml:id="class.haruexception" xmlns="http://docbook.org/ns/docbook";
xmlns:xlink="http://www.w3.org/1999/xlink";
xmlns:xi="http://www.w3.org/2001/XInclude";>
+<phpdoc:exception xml:id="class.haruexception"
xmlns="http://docbook.org/ns/docbook";
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ xmlns:phpdoc="http://php.net/ns/phpdoc";>
<title>The HaruException class</title>
<titleabbrev>HaruException</titleabbrev>
@@ -35,32 +38,15 @@
</classsynopsisinfo>
<!-- }}} -->
-<!--
-FIXME:
- Once the `Exception` class has been documented with the
- new-ref-struct-style this should be commented in.
<classsynopsisinfo role="comment">Inherits</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook)
xpointer(id('class.exception')/db:refentry/db:[EMAIL
PROTECTED]'description']/descendant::db:methodsynopsis[1])" />
--->
+
</classsynopsis>
<!-- }}} -->
</section>
</partintro>
-<!-- FIXME: !!! This should be removed! -->
- <refentry>
- <refnamediv>
- <refname>HaruException</refname>
- <refpurpose>Dummy page</refpurpose>
- </refnamediv>
- <refsection>
- <title>Dummy</title>
- <para>This is a dummy page created to satisfy Docbook standards</para>
- </refsection>
- </refentry>
- <!--&reference.haru.entities.haruexception;-->
-
-</reference>
+</phpdoc:exception>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Index: en/reference/pdo/book.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/pdo/book.xml,v
retrieving revision 1.4
diff -u -p -r1.4 book.xml
--- en/reference/pdo/book.xml 31 Dec 2007 16:06:50 -0000 1.4
+++ en/reference/pdo/book.xml 21 Jul 2008 19:32:10 -0000
@@ -46,9 +46,7 @@
&reference.pdo.pdo;
&reference.pdo.pdostatement;
- <!-- FIXME: Find out how to deal with classess without any methods
&reference.pdo.pdoexception;
- -->
&reference.pdo.drivers;
Index: en/reference/pdo/pdoexception.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/pdo/pdoexception.xml,v
retrieving revision 1.1
diff -u -p -r1.1 pdoexception.xml
--- en/reference/pdo/pdoexception.xml 31 Dec 2007 14:34:04 -0000 1.1
+++ en/reference/pdo/pdoexception.xml 21 Jul 2008 19:32:10 -0000
@@ -1,7 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
-<reference xml:id="class.pdoexception" xmlns="http://docbook.org/ns/docbook";
xmlns:xlink="http://www.w3.org/1999/xlink";
xmlns:xi="http://www.w3.org/2001/XInclude";>
+<phpdoc:exception xml:id="class.pdoexception"
xmlns="http://docbook.org/ns/docbook";
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ xmlns:phpdoc="http://php.net/ns/phpdoc";>
<title>The PDOException class</title>
<titleabbrev>PDOException</titleabbrev>
@@ -57,7 +60,10 @@
<varname linkend="pdoexception.props.code">code</varname>
</fieldsynopsis><!-- }}} -->
- <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook)
xpointer(id('class.pdoexception')/db:refentry/db:[EMAIL
PROTECTED]'description']/descendant::db:methodsynopsis[1])" />
+ <classsynopsisinfo role="comment">Inherited methods</classsynopsisinfo>
+ <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook)
+ xpointer(id('class.exception')/db:refentry/db:[EMAIL
PROTECTED]'description']/descendant::db:methodsynopsis[1])"
+ />
<!-- FIXME: Enable when RuntimeException gets documented
<classsynopsisinfo role="comment">Inherited methods</classsynopsisinfo>
@@ -86,6 +92,7 @@
<listitem>
<para>
Textual error message. <function>Exception::getMessage</function> to
access it.
+ </para>
</listitem>
</varlistentry><!-- }}} -->
<varlistentry xml:id="pdoexception.props.code"><!-- {{{ -->
@@ -103,9 +110,7 @@
</partintro>
- &reference.pdo.entities.pdoexception;
-
-</reference>
+</phpdoc:exception>
<!-- Keep this comment at the end of the file
Local variables:
Index: config.php
===================================================================
RCS file: /repository/phd/config.php,v
retrieving revision 1.45.2.3
diff -u -p -r1.45.2.3 config.php
--- config.php 5 Jul 2008 19:36:56 -0000 1.45.2.3
+++ config.php 21 Jul 2008 19:32:25 -0000
@@ -140,6 +140,7 @@ $OPTIONS = array (
),
'chunk_extra' => array(
"legalnotice" => true,
+ "phpdoc:exception" => true,
),
'index' => true,
'xml_root' => '.',
Index: themes/php/phpdotnet.php
===================================================================
RCS file: /repository/phd/themes/php/phpdotnet.php,v
retrieving revision 1.53
diff -u -p -r1.53 phpdotnet.php
--- themes/php/phpdotnet.php 4 May 2008 00:36:55 -0000 1.53
+++ themes/php/phpdotnet.php 21 Jul 2008 19:32:25 -0000
@@ -68,6 +68,7 @@ abstract class phpdotnet extends PhDThem
'preface' => 'format_chunk',
'refentry' => 'format_chunk',
'reference' => 'format_container_chunk',
+ 'phpdoc:exception' => 'format_exception_chunk',
'sect1' => 'format_chunk',
'sect2' => 'format_chunk',
'sect3' => 'format_chunk',
@@ -406,6 +407,10 @@ abstract class phpdotnet extends PhDThem
return $content;
}
+ public function format_exception_chunk($open, $name, $attrs, $props) {
+ return $this->format_container_chunk($open, "reference", $attrs,
$props);
+ }
+
public function format_container_chunk_title($open, $name, $attrs) {
if ($open) {
return "<h1>";
