RE: [docbook-apps] oointerface - writing a synopsis for a Java interface

["Mauritz Jeanson" <mj@johanneberg.com>]

> -----Original Message-----
> From: Johnson, Eric 
> 
> In looking through the XSL used to generate the classsynopsis 
> element, it looks like the problem is not the inclusion of 
> the word 'interface'. It is the assumption that, at least in 
> the Java/default case, that the synopsis is for a class that 
> is implementing an interface and not an interface by itself.
>  
> I had figured that the reason class="interface" was added to 
> the element was for cases where the author wanted to create a 
> synopsis for an interface and not a class. Was this a mistake 
> on my part?
>  
> The way I addressed this was by adding an <xsl:choose> around 
> the code that generates the text. The first <xsl:when> 
> element uses test="@class=interface" to test for generating 
> just an interface. This case skips over the processing of the 
> ooclass element as this in not needed in this case. The 
> <xsl:otherwise> holds the old code that processes the class case.
>  
> There is also a bug in the FO case that does not add a . 
> between the package name and the interface name.


One reason for the confusion, I think, is that the official documentation
(The Definitive Guide) isn't detailed enough. In particular, there are too
few usage examples and the processing expectations are often a little vague.


Many descriptions of source code-related elements in TDG don't have a single
example. See http://docbook.org/tdg/en/html/classsynopsis.html, for
instance.

/MJ