[kepler-dev] Request for adding documentation on Kepler Actors

[Chad Berkley]

This is what edward told me about that earlier:

"There is ConfigurableAttribute.
The plotter uses this for example to include "foreign" XML as
a parameter value for the actor.  To see it, put a SequentialPlotter
actor in a model, change its formatting (by clicking on the format
button in the plot), and look at the resulting XML.
The fact that the plotter's CDATA is XML is irrelevant...
It could be arbitrary text (almost)."

I'm not crazy about the idea of creating invalid documents though.  I'm 
not sure how to do this otherwise.

chad

Dan Higgins wrote:
> Hi All,
>     I am concerned that the indicated method for adding documentation 
> create invalid MOML. MOML code created when a workflow is saved in 
> Kelper include the Doctype element
> 
> <!DOCTYPE entity PUBLIC "-//UC Berkeley//DTD MoML 1//EN"
>     "http://ptolemy.eecs.berkeley.edu/xml/dtd/MoML_1.dtd">
> 
> If you look at the MOML_1.dtd, you see that the configure element is 
> defined as
> 
> <!ELEMENT configure (#PCDATA)>
> <!ATTLIST configure source CDATA #IMPLIED>
> 
> We thus cannot add elements under it. If I try validating the sample 
> constant.xml on the Wiki with the DOCTYPE added (using Xerces) I get the 
> following errors
> 
> C:\xerces-2_7_1>java -cp 
> ./;xercesImpl.jar;xercesSamples.jar;xml-apis.jar;resolv
> er.jar sax.Counter -v data/constant.xml
> [Error] constant.xml:17:18: Element type "description" must be declared.
> [Error] constant.xml:17:25: Element type "brief" must be declared.
> [Error] constant.xml:20:16: Element type "algorithm" must be declared.
> [Error] constant.xml:21:19: Element type "typicalUsage" must be declared.
> [Error] constant.xml:22:13: Element type "author" must be declared.
> [Error] constant.xml:23:13: Element type "author" must be declared.
> [Error] constant.xml:24:14: Element type "project" must be declared.
> [Error] constant.xml:25:14: The content of element type "property" must 
> match "(
> configure|doc|property|rename)*".
> [Error] constant.xml:36:20: Element type "description" must be declared.
> [Error] constant.xml:39:16: The content of element type "property" must 
> match "(
> configure|doc|property|rename)*".
> [Error] constant.xml:48:20: Element type "description" must be declared.
> [Error] constant.xml:51:16: The content of element type "property" must 
> match "(
> configure|doc|property|rename)*".
> [Error] constant.xml:60:20: Element type "description" must be declared.
> [Error] constant.xml:63:16: The content of element type "property" must 
> match "(
> configure|doc|property|rename)*".
> [Error] constant.xml:72:20: Element type "description" must be declared.
> [Error] constant.xml:74:16: The content of element type "property" must 
> match "(
> configure|doc|property|rename)*".
> [Error] constant.xml:81:20: Element type "description" must be declared.
> [Error] constant.xml:83:21: Element type "defaultValue" must be declared.
> [Error] constant.xml:84:16: The content of element type "property" must 
> match "(
> configure|doc|property|rename)*".
> 
> 
> It may be that Kepler/Ptolemy never really validate the MOML instances 
> so this does not create a problem for current use, but should we be 
> creating invalid XML documents?
> 
> Dan
> 
> 
> ------
> 
> nmangal at sdsc.edu wrote:
> 
> 
>>Hello Kepler-Developers,
>>
>>For implementing Kepler documentation framework, we have implemented xslt
>>processors which based on actorList.moml and
>>actor kar files produce respective html MAN pages for all kepler actors.
>>However the current MAN pages ,which are
>>similar to javadoc in formatting , are currently lacking the main
>>function/purpose of the actor and authors etc.
>>
>>I request all Kepler developers to kindly add the above information in 3-4
>>lines on their respective actor's entities , to help the Kepler MAN pages
>>be
>>even more helpful for Kepler users and beginners. We are trying to
>>incorporate the above MAN pages for the upcoming Kepler release.
>>
>>Kindly follow the following steps to add documentation to your actor MAN
>>pages:
>>
>>1) Get an CVS updated version of actorList.moml
>>  (configs\ptolemy\configs\kepler)
>>2) For each actor entity that you have recently developed or in the past
>>add the following XML information
>>  under the "documentation" property
>>
>>  Sample Constant Actor Entity Documentation:
>>
>>   <!-- Documentation regarding the actor's overall functionality. -->
>> <property name="documentation"
>>class="org.kepler.moml.DocumentationAttribute">
>>   <configure>
>>   <description><brief>Produces a constant value on each fire
>>cycle.</brief>  The constant value is set by the user as
>>                a parameter of the actor, or defaults to an integer value
>>of 1 if unset.
>>   </description>
>>   <algorithm>Examines the &quot;value&quot; parameter and emits it on
>>the ouput port during each fire event.</algorithm>
>>   <typicalUsage>Used to parameterize other models that take constant
>>values as inputs.</typicalUsage>
>>   <author>Yuhong Xiong</author>
>>   <author>Edward A. Lee</author>
>>   <project>Ptolemy II</project>
>>   </configure>
>> </property>
>>
>>
>>3) Build the KSW library , Kepler to make sure there was so invalid
>>XML/other errors.
>>4) Check in the actorList.moml files into CVS.
>>
>>You are free to add additional nodes under the root configure node to
>>further describe your actor.
>>If you have any further questions please feel free to email me at
>>nmangal at sdsc.edu
>>
>>Thank you for your co-operation.
>>Sincerely,
>>Nandita Mangal.
>>
>>
>>_______________________________________________
>>Kepler-dev mailing list
>>Kepler-dev at ecoinformatics.org
>>http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev
>>
>> 
>>
> 
> 
>