On 14 May 2010 13:40, Hannes Magnusson <hannes.magnus...@gmail.com> wrote:
> On Thu, May 13, 2010 at 15:00, Richard Quadling
> <rquadl...@googlemail.com> wrote:
>> So, I would like to use a role on the methodsynopsis to indicate OOP
>> or PROC use. This will allow me to include only the OOP methodsynopsis
>> via the xinclude in the event of method overloading.
>>
>> Changing
>>
>> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook)
>> xpointer(id('class.xyz')/db:refentry/db:refsec...@role='description']/descendant::db:methodsynopsis[1])"
>> />
>>
>> to
>>
>> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook)
>> xpointer(id('class.xyz')/db:refentry/db:refsec...@role='description']/descendant::db:constructorsynopsis)"
>> />
>> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook)
>> xpointer(id('class.xyz')/db:refentry/db:refsec...@role='description']/descendant::db:destructorsynopsis)"
>> />
>> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook)
>> xpointer(id('class.xyz')/db:refentry/db:refsec...@role='description']/descendant::db:methodsynops...@role='oop'])"
>> />
>>
>
> I like it.
>
> It has always bothered me that functions use <methodsynopsis>. In the
> beginning it was <funcsynopsis>, but I can't find any discussion on
> why it was changed. The <funcdef> model does fit well for us.. But
> like you said, that would be a major change.
>
> -Hannes
>
Thank you Hannes for the feedback.
I've got change for this which I'm just finalising.
It should mean that we don't need to add role="oop" to all the
methods, only role="procedural" to the procedural
methodsysonpsis/constructorsynopsis/destructorsynopsis, so less work
for the translators.
Essentially
xxxsynopsis[not(@role='procedural')]
says exclude where the role = procedural. This allows through those
with no role and those that may now be 'oop' due to my last commit.
And for excluding private inherited methods....
methodsynopsis[not(@role='procedural') and not(modifier='private')]
and something similar for fieldsynopsis.
Just testing this at the moment, but should allow us to fully include
all inheritable methods/properties a lot easier.
I think we could also standardise this whole class structure by
something like ...
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook)
xpointer(id('class.datetimezone')/db:refentry/db:refsec...@role='description']/descendant::db:constructorsynopsis[not(@role='procedural')])">
<xi:fallback><classsynopsisinfo role="comment">No
constructor</classsynopsisinfo></xi:fallback>
</xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook)
xpointer(id('class.datetimezone')/db:refentry/db:refsec...@role='description']/descendant::db:destructorsynopsis[not(@role='procedural')])">
<xi:fallback><classsynopsisinfo role="comment">No
destructor</classsynopsisinfo></xi:fallback>
</xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook)
xpointer(id('class.datetimezone')/db:refentry/db:refsec...@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])">
<xi:fallback><classsynopsisinfo role="comment">No
methods</classsynopsisinfo></xi:fallback>
</xi:include>
So the only editing needed is the class name and you get all the
documentation for this class, with a simple comment about the lack of
constructor|destructor|methods when they are not present. The current
rendering of <classsynopsisinfo role="comment"> isn't right, so a
different role may be required (role="informational" ... hmmm ...) and
have a simpler styling for it.
Of course just using
<xi:fallback />
would also be enough to allow for a standard way to include the class
methods without worrying about if they exist (which is what I'm
currently leaving it as so the output is the same).
--
-----
Richard Quadling
"Standing on the shoulders of some very clever giants!"
EE : http://www.experts-exchange.com/M_248814.html
EE4Free : http://www.experts-exchange.com/becomeAnExpert.jsp
Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731
ZOPA : http://uk.zopa.com/member/RQuadling
