Assigning to Darren to set out the format to be used for the xml documentation
structure based on our discussion today.  Once done, reassign to me for
processing ... although Sacha may end up doing the actual work ;)

Created an attachment (id=10) [details]
HTML version of proposal

Created an attachment (id=11) [details]
DocBook version of proposal

Darren, good start.  I have given it a quick read and it looks like an excellent
framework.  There are a few issues that will need to be dealt with as we go, but
I think we have the basics.

I need some feedback from Sacha on widget Events (previously undocumented),
these do need to be integrated.  Also from Sacha, any other feedback on the
structure would be appreciated.

My initial comments:

1. (formatting issue) some of the sample tags have commas between the
attributes, ie:

<widgetdoc name="WidgetName", group="WidgetGroup">
                            ^
this is not valid XML.

2. language tag will not need a 'default' attribute

3. the purpose of attribute type attribute is not clear to me.  I expect this is
coming from the attribute groups in the existing documentation?  This happened
because many widgets happened to share these 'base' attributes because they
inherit functionality and state from the Widget class.  It seemed to me that
there was no point in documenting these 'base' attributes in every widget. 
Inheritance is, unfortunately, not the only mechanism by which these shared
attributes are included.  We will need to introduce an additional attribute in
the widgetdoc to indicate 'inheritance' (parentClass="Widget" for example).  We
will also need to introduce an additional tag like <includes/> that indicates
that a widget 'includes' common attributes (and javascript and HTML) from some
source.  These 'includes' could be documented separately.  They are not full
widgets but they supply similar functionality.  For example, there is a utility
class called Link.php that provides a widget with the ability to launch some
arbitrary code when activated.  I would image that we would have Link.doc.xml
and in a widget that uses Link.php, we would have <includes target="Link"/> ..
this would be a simple href to the Link entry on the output page.

4. there is no notation for capturing 'sub tags'.  Sub tags are valid XML tags
contained within the widget tag, for instance:

<cwc2 type="quickzoom">
  <zoom ..../>
</cwc2>

There is no way to document the sub tags "zoom" in the current system and this
needs to be added to the new system.  In this example, the "zoom" tag could have
an arbitrary number of attributes.  We have not yet nested more than one level,
but it is also possible, so our system should be capable of handling it.  I
suggest "<childtags>" that contains 0 or more <tag> entries.  This makes me
think that we need a <tag> level in the main widget doc.  So the new structure
could be:

<widgetdoc>
  <tag>
    <attribute name=""
type="[string|stringlist|integer|float|boolean|rgbcolor|hexcolor]"
mandatory="[true|false]">
      <description></description>
      <values> <!-- for string list -->
        <value name=""/>
      </values>
      <range start="" end=""/> <!-- for integer/float -->
    </attribute>
    <children>
      <tag/>
    <children>
  </tag>
</widgetdoc>

5. javascript functions can take parameters.  These should be documented also:

<jsfunction name="NavSetActiveTool">
  <description>
  Set the active navigation tool for a particular group of tools.
  </description>
  <parameters>
    <parameter name="" type="[expected variable type (string, int, array,
object, etc]" default="">description here</parameter>
  </parameters>
</jsfunction>     

6. There are a number of places where you have used something like jsfuncdesc, I
would prefer to use <description>.  If we ever get around to building a schema
for this document (which we should), then this will be much easier.  A
description will always follow the same rules.  All elements that will follow
the same rules for nesting and content should be called the same thing.

7. Nesting elements.  Not sure about this, but in general I think it may be
nicer to nest multiple elements inside a container element.  For instance:

<tags>
  <tag/>
  <tag/>
</tags>

rather than
<tag/>
<tag/>

While it looks a little more verbose, I think it would display more nicely in an
xml editor because you can 'collapse' the <tags> element to work on other
things.  I think it will also be easier for validation (schema) and for
programmatically generating the output.

I think I will leave it there for now :)  Can you make these changes and then
incorporate widget Events when Sacha provides info on them to you.

Created an attachment (id=12) [details]
Very simple XSLT file used to format the output of the XML document.

Created an attachment (id=13) [details]
Fixed version of the XML document.

The one in the HTML documentation contained some typo. Also added a event as an
example.

OK Everyone: 

I've made all the changes that Paul and Sacha asked for. Please review the new 
document which I've attached. 

Thanks. 

Darren

Created an attachment (id=14) [details]
HTML version of Draft 2

Created an attachment (id=15) [details]
DocBook version of Draft 2

To Address the issue of Widget Dependencies the following sections should be
considered for the doc.xml specifications. I had a quick chat with Paul and he
agrees with this. How we implement/organize this has yet to be determined, but I
will try to outline this.

Here is a list of new sections/ documentation issues that need to be addressed:

1) <SharedResource/> list the Shared Resources that are related to the widget.
i.	required="true|false" XML parameter describing weather the Shared Resource is
required for the widget to work.
ii.	Comment= how and why there is a dependency (optional)
iii.	Description or link to the Shared Resources Documentation.

2) < OtherWidgets /> list Other Widgets that are required for the widget to
function.
i.	Comment= how and why there is a dependency (optional)
ii.	Description or link to the Shared Resources Documentation.

3) <SubWidgets/> Widgets required to be grouped together in order for all of the
widgets to work. No single widget of this group can work on its own.

4) <PHPScipts/> list php files found in /htdocs/widgets/ that are required for
the particular widget eg. Button.php, CatalogSearch.php
i.	Parameter stating weather the script is strictly only used by that widget or
that other widgets in this script.
iii.	Comment= how and why there is a dependency (optional)
iv.	Description or link to the PHP Scripts Documentation.

5) <PHPutilities/> list of required PHP utilities required by the widget.
i.	Comment= how and why there is a dependency (optional)
ii.	Description or link to the PHP Utilities Documentation.

6) <DataResources/> List of dbf or other data like files that are required for
the widget.
i.	Comment= how and why there is a dependency (optional)
ii.	Description or link to the Data Resources Documentation.

7) <JavaVariables /> List of Java Variables required for the Widget.

8) <JavaInclude /> List of Java *.jar files required for the Widget.

This is mostly a list of components that are required to de Documented. How this
is done will have to be hashed out. 

New Attribute parameter Type

The Attribute definition section requires and additional parameter within
<attribute>
Currently there is: 
<attribute name=”VISIBLE” required=”false”>
There need a parameter to hold the parameter value type eg. Boolean, Char,
Integer, Array, Color (RGB|HEX), Image path.

<attribute name=”VISIBLE” required=”false” type=”Boolean”>

For Image Path is required what relative path is from eg. Relative to template,
chameleon.php, or others like drawmap.php ;)  

Hi Chris:

I have a question about your recent request for changes to the widget 
documentation scheme. 

>New Attribute parameter Type
>
>The Attribute definition section requires and additional parameter within
><attribute>
>Currently there is:
><attribute name=”VISIBLE” required=”false”>
>There need a parameter to hold the parameter value type eg. Boolean, Char,
>Integer, Array, Color (RGB|HEX), Image path.
>
><attribute name=”VISIBLE” required=”false” type=”Boolean”>

Change made to document. Thanks. 

>For Image Path is required what relative path is from eg. Relative to template,
>chameleon.php, or others like drawmap.php ;)

This is the one I don't quite understand. Is specifying what relative path is 
used for an image really necessary in the *widget documentation*? Doesn't 
Chameleon automatically look for the image file in several places in a certain 
order (such as, template directory, then Chameleon directory, then ....)? 

If that is the case, then this isn't widget-specific and this document doesn't 
need to be altered, I think. 

Created an attachment (id=16) [details]
HTML version of Draft 3

Created an attachment (id=17) [details]
DocBook version of Draft 3

Darren, there are quite a few cases where paths of things are relative, and it
should always be explained what they are relative to.  In the case of images,
there are several possibilities but I don't think it searches a set of paths for
images.  Legend templates are another good example.  PHP/MapScript assumes that
the legend template path is specified relative to the map file.  But the user
may or may not know this, and so it should be relative to the template, which
makes sense for a non-mapserver savvy user ... but if it is a mapserver-aware
user, then they may expect it to be relative to the map file.  There are more
like this too.

I'm not sure that this warrants its own tag, but it should certainly be
something that is reviewed for every attribute that is a path to some file,
either web or file system, and it should be explicitly stated unless there is a
very convincing reason why it shouldn't.  Even in the case of searching for
files, the search path should be described.

Shouldn't those documents be in CVS somewhere instead of being attached to this
bug?  Paul, can you please point the location where you think they should be?

Daniel, This a known issue, and will be discussed next Tuesday between Darren,
Jeff and me. Darren wishes to discusses things first before we start putting
everything into CVS. 

Daniel, you are correct.  I asked Darren to put the original proposal in this
bug not thinking about the implications.  Since we are on draft 3, it really
doesn't make sense any more.  The current location for this would probably be in
the html directory of chameleon since it will form the base example to use for
documenting all widgets.  That being said, I am not entirely sure that this will
ever be in cvs, as this document will be auto-generated for each widget.  Or
maybe this should be used by the auto-generator?  Still need to think this one
through!

*** Bug 134 has been marked as a duplicate of this bug. ***

As discused with Paul, I'll build a toold (based on the old one) to generate the
documentation skeleton of all widget in the new XML format.

Make the change to the HelpWidget to open the new XML file instead of the old doc.

Widget documentation, will be stored in a "doc" directory in the same directory
of the widget.

That's all I have right now.

My last comment mention that doc is stored in "doc" directory. That's not true.
But it probably may be that way. Widgets directory structure should be discussed
in an other bug.

I'll close this bug since the main issue is solved.

new version of the widget docs has been created and currently under
development.