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: Dmitry Tsitelov <cit at comcon dot spb dot ru>
- Date: Fri, 03 Mar 2000 13:07:01 +0300
- References: <8368-Fri18Feb2000083732-0500-ndw@nwalsh.com> <38B15537.F0F283B0@comcon.spb.ru> <6288-Thu02Mar2000172921-0500-ndw@nwalsh.com>
- Reply-To: docbook at lists dot oasis-open dot org
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