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

Dan Higgins higgins at nceas.ucsb.edu
Thu Dec 1 11:06:57 PST 2005 

Matt,
    I understand your point. Problem is that PIs appear a lot in current 
Ptolemy MOML files, so we are not inventing anything new by using them. 
And I fear that changing the MoML DTD may make Kepler incompatible with 
Ptolemy at some point. (Just a thought.)

Dan

Matt Jones wrote:

> I think the PI is a bad idea.  I wouldn't be surprised if PIs sometime 
> get eliminated from XML altogether sometime in the future.  I'd much 
> rather see a change to the MoML DTD than to use this PI hack.  This 
> would have the added benefit of allowing us to define the schema for 
> the documentation element so that people had a guide to follow. 
> Alternatively, the element could be defined as ANY to allow for 
> element content in there too.
>
> Matt
>
> Dan Higgins wrote:
>
>> 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