This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: ClassSynopsis revisited again
- To: docbook at lists dot oasis-open dot org
- Subject: Re: DOCBOOK: ClassSynopsis revisited again
- From: Norman Walsh <ndw at nwalsh dot com>
- Date: Thu, 2 Mar 2000 20:29:21 -0500
- References: <8368-Fri18Feb2000083732-0500-ndw@nwalsh.com> <38B15537.F0F283B0@comcon.spb.ru>
- Reply-To: docbook at lists dot oasis-open dot org
/ 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