Re: Re: [PATCH] Solving the exception problem (<reference>s without <refentry>s)

On Thu, Jul 24, 2008 at 11:31, Richard Quadling <rquadling@googlemail.com> wrote: > > > > > 2008/7/23 Hannes Magnusson <hannes.magnusson@gmail.com> >> >> Last chance for objections... committing in 10.. 9.. :) >> >> -Hannes >> >> On Mon, Jul 21, 2008 at 21:45, Hannes Magnusson >> <hannes.magnusson@gmail.com> wrote: >> > 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 >> > > > Initially, we did say that our docs would be DB5. And I remember you saying > in IRC that DocBook5 + some extensions !== DocBook5. Indeed. But we simply do not have another way to solve this problem and rather then waiting another year I decided to fixed it. Besides, we've been talking about this for a long long time. This commit will probably set precedence for future enhancements like this, which we should had done long time ago. > How about putting it to DB.org themselves? Like I did for the grouped > parameter mechanism? That got accepted and will allow us to describe our > optional parameters correctly (though PhD will need amending to cope with > it). Exception/Class/Extension/.. references do not exist in the Docbook grammar. Adding only a single element is not enough for docbook. It would require lot more thought and time and discussion to design a proper programming language documentation grammar. -Hannes