[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: ClassSynopsis revisited again
Looking at ClassSynopsis and considering the more complex case presented by C++ (and perhaps other languages), I'm concerned that the existing structure is too ambiguous. Given: class Rectangle_with_data: virtual Shape, virtual Data_container {...}; We're forced to represent this as: <classsynopsis language="cpp"> <classname>Rectangle_with_data</classname> <modifier>virtual</modifier><classname>Shape</classname> <modifier>virtual</modifier><classname>Data_container</classname> </classsynopsis> This gives us a floating bag of classnames and modifiers and I'm concerned that it may require too much intelligence on the part of the stylesheet to always get this right. In the worst case, it seems you get something like this: <classsynopsis> <modifier>m1</modifier><modifier>m1</modifier><modifier>m1</modifier> <classname>basename</classname> <modifier>m1</modifier><modifier>m1</modifier><modifier>m1</modifier> <classname>super1</classname> <modifier>m1</modifier><modifier>m1</modifier><modifier>m1</modifier> <exceptionname>ex1</exceptionname> <modifier>m1</modifier><modifier>m1</modifier><modifier>m1</modifier> <classname>super2</classname> <modifier>m1</modifier><modifier>m1</modifier><modifier>m1</modifier> <exceptionname>ex1</exceptionname> <modifier>m1</modifier><modifier>m1</modifier><modifier>m1</modifier> <exceptionname>ex2</exceptionname> <modifier>m1</modifier><modifier>m1</modifier><modifier>m1</modifier> <interfacename>in1</interfacename> </classsynopsis> For C++, it appears that you can always rely on modifiers preceding classnames (or exception or interfacenames, presumably) but that may not be true for all the languages someone might want to document. Basically, I think we need a wrapper around some of these things. I can think of a couple of few to do this. One is to slip the modifiers into the classname: <classsynopsis language="cpp"> <classname>Rectangle_with_data</classname> <classname><modifier>virtual</modifier> Shape</classname> <classname><modifier>virtual</modifier> Data_container</classname> </classsynopsis> But this is ugly because the modifiers aren't properly part of the class name, which may confuse search engines, and you need to stick a bit of whitespace in there. The other is to add a wrapper: <classsynopsis language="cpp"> <classname>Rectangle_with_data</classname> <classparam> <modifier>virtual</modifier><classname>Shape</classname> </classparam> <classparam> <modifier>virtual</modifier><classname>Data_container</classname> </classparam> </classsynopsis> This is more markup, but I think the intent is clearer. Would it be clearer still to put the wrapper around the base classname, too? <classsynopsis language="cpp"> <classparam> <classname>Rectangle_with_data</classname> </classparam> <classparam> <modifier>virtual</modifier><classname>Shape</classname> </classparam> <classparam> <modifier>virtual</modifier><classname>Data_container</classname> </classparam> </classsynopsis> Probably. Especially if it's a virtual public class or something. Unfortunately, classparam is hardly a perfect name, and I suppose we'd need to have exceptionparam and implementsparam as well. Ack. Thoughts? Be seeing you, norm -- Norman Walsh <ndw@nwalsh.com> | Graduate school is where you learn http://www.oasis-open.org/docbook/ | to call a spade a leveraged Member, DocBook Editorial Board | tactile-feedback geomass delivery | system.--Martha Koester
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC