OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[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