Hi Thomas,
>>>I suppose that the IDL-Reference Properties are ordered at the moment >>>using the occurrence of the properties in the IDL-File. The good point >>>about this is that you can group together things like RightMargin and >>>LeftMargin but for someone who is looking for a property it would be >>>much more useful to have the properties sorted alphabetically.
I just tell some thoughts I have spontaneously.
Finding a Property ------------------
Let's see some use cases:
1. I know the property name and look for the documentation:
The reference has an index. There one can look for any property (or else) alphabetically ordered.
2. I am studying a service with <= 7 properties and look for a specific property:
For up to 7-8 properties there is not really a difference for the human brain, if they are anyhow ordered or not. The finding time is the same.
So the order by context (left,rigth etc.) makes sense.
3. I am studying a service with > 8 properties and look for a specific property:
Going back to the global index to search for the property is obviously unpleasant.
CTRL F in the browser will help.
But having an alphabetical list would be faster and more convenient.
The same three cases exist of course for searching methods in interfaces, interfaces in services, constants in constant groups etc.
Before I start to develop anything about that, my first question would be: How often occurs each of the above three use cases?
So, how many lists of properties, methods, constants etc. do we have with a length >8? How often are they used?
In other words: Would alphabetical lists really be needed?
I don't know, but for the moment lets assume, they would.
Now, if we want both lists, context-ordered and alphabetical ordered, where to put them?
If I need to recreate the whole output that is inconvenient.
I also think that for many cases I want the context-order, so having only the alphabetical version would not help much.
So both lists need to exist parallel. Where?
Possibility 1: For each list with more than 8 members, there is link to an alphabetical list (may be on bottom of the page)
Possibility 2: One could put links to context-ordered and alphabetical ordered lists beside each other into the menu on top of page.
Possibility 3-n: Your ideas. ;-)
However there would be needed some significance, that whatever possibility we choose, it really helps more than it hurts.
For instance, Poss.2: It is easier to get oriented among a few menu items. If we would double the items in the submenu on top of each page (one alpha-odered item, one not), that submenu becomes a tiny bit more difficult to understand and to handle in _every_ access to the reference. Would that be worth the little improvement in cases where we have 9-50 properties?
Technical Possibilities of Autodoc ---------------------------------- (I am the author of Autodoc, the tool that currently creates the reference.)
Autodoc could produce XML output anyway, as this may be useful for
many different cases, though in the moment I haven't anything special in mind. This is not difficult, but would need some time. And it rises some questions, like: Is there already an existing standard for representing IDL types, methods etc. in XML? If yes, one should use it.
Actually creating XML ouput is planned to be realised already anyway.
Adding alphabetical lists like in one of the possibilities described above would be easy as well .
Best regards, Nikolai
-- Nikolai Pretzell Sun Microsystems Inc. Software Engineer Hamburg, Germany
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
