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

Dan Higgins higgins at nceas.ucsb.edu
Thu Dec 1 10:46:42 PST 2005 

Chad & Nandita,
    If I look at the example that edward indicated I see the following 
(fragment)
        <configure>
          <?plotml <!DOCTYPE plot PUBLIC "-//UC Berkeley//DTD PlotML 1//EN"
                  "http://ptolemy.eecs.berkeley.edu/xml/dtd/PlotML_1.dtd">
               <plot>
                <title>Sequence Plotter</title>
                <xLabel>DFH</xLabel>
                <yLabel>HFD</yLabel>
                <xRange min="0.0" max="5.0"/>
                <yRange min="1.0" max="6.0"/>
               </plot>?>
        </configure>
Note the use of a Processing Instruction (<?) under configure to make 
the xml valid! We should probably do the same thing with our documentation.

Dan



Chad Berkley wrote:

> 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 
>>>
>>>
>>>
>>>
>>
>>
>>


-- 
*******************************************************************
Dan Higgins                                  higgins at nceas.ucsb.edu
http://www.nceas.ucsb.edu/    Ph: 805-893-5127
National Center for Ecological Analysis and Synthesis (NCEAS) Marine Science Building - Room 3405
Santa Barbara, CA 93195
*******************************************************************

More information about the Kepler-dev mailing list