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

[Dan Higgins]

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