This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: ClassSynopsis revisited again


/ Dmitry Tsitelov <cit@comcon.spb.ru> was heard to say:
| 1. Should classparam (or it's substitute) allow any kind of
| class/exception/interface   description, or we need wrapper for each
| case? 

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.

| 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.

| 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.

| 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?

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | The fundamental delusion of
http://www.oasis-open.org/docbook/ | humanity is to suppose that I am
Chair, DocBook Technical Committee | here and you are out
                                   | there.--Yasutani Roshi


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]