OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: Re: DOCBOOK: ClassSynopsis revisited again


Norman Walsh wrote:
> 
> / Dmitry Tsitelov <cit@comcon.spb.ru> was heard to say:
> 
> I think we need a wrapper for each case.
> 
> | 2. In such structured declaration, wrapper for first classname  should
> | be different from other wrappers, shouldn't it.
> 
> I don't think that the base classname warrants a different
> tag. I don't think it would be wrong, exactly, to do that, but
> it would add additional tags that would have exactly the same
> presentation in 999/1000 cases.

Hm, I thought that using different wrapper for class under description
is more useful because of:

1. In many cases it could be rendered not like others (boldfaced,
rendered in   looks-like-title way) 
2. Suppose, you search document for all classes, described in it:
   Is it much simple to search for <baseclass>...</baseclass> (or other
first-class-name-wrapper) than search for "first occurrence of OOClass
in ClassSynopsis", isn't it?
3. Is it more simple to process different tags in rendering engine than
analyze context 
	of wrapper occurrence?  

> | 3. May be it will be convenient to allow simple
> | class/interface/exception references (without modifiers) at the same
> | level as wrappers?
> 
> Perhaps, but that gives the poor author more ways to do the same
> thing and that just means more ways to become confused.

Accepted.

> | After all, more general thoughts. I think, current model of class
> | synopsis is rather weak. Let's keep in mind, that such structure in real
> | book intended not only to reproduce syntax of class declaration, but to
> | _document_ class. In FuncSynopsis we have a chance to place some remarks
> | about function  immediately after syntax representation: In optional
> | FuncSynopsis info, or after FuncSynopsis element. But current model of
> | classsynopsis is pure syntax skeleton.
> 
> ClassSynopsis has ClassSynopsisInfo for the same purpose.

Yes, but ClassSynopsis isn't attached to field/method. 

> | In many published books, we'll see class descriptions much more
> | complicated than current classsynopsis model:
> |
> | class Rectangle_with_data: virtual Shape, virtual Data_container
> | {
> | // contractors
> |
> |    Rectangle_with_data();  // default constructor ...
> |       ...
> 
> Yes, but I don't know of any sort of general model that we could
> hope to develop that would handle cases like this.
> 
> Should we drop the whole thing and just use <programlisting> for
> structures as complex as class synopses?

No, I just think, it may be useful to have an info-tag in
Field/.../MethodSynopsis models.

Sincerely,
Dmitry Tsitelov



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC