[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