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

Edward A. Lee eal at eecs.berkeley.edu
Thu Dec 1 14:44:21 PST 2005 

One of the things I really like about the MoML DTD is how short
and simple it is ...

Any reasonable DTD for documentation will likely be much bigger
than the current MoML DTD.  And it seems to me that documentation
really is orthogonal to model structure.  These things really
should be separated.

And a logical consequence of this decision would be that
we should then also include the PlotML DTD for plot
configuration information in the MoML DTD... What about
other configuration information someone might want to
include?

Regrettably, XML policies seem to lead to one universal
uber-DTD which includes every possible schema in it.
Which takes us back to the beginning: A simpler solution is
to not use a validating parser...

(BTW: The MoML parser in Ptolemy II does validate the XML
against the DTD, but it does so in hardwired Java code rather
than using generic validation code.)

Edward

At 11:06 AM 12/1/2005 -0800, Dan Higgins wrote:
>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
>*******************************************************************
>
>
>_______________________________________________
>Kepler-dev mailing list
>Kepler-dev at ecoinformatics.org
>http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev

------------
Edward A. Lee
Professor, Chair of the EE Division, Associate Chair of EECS
231 Cory Hall, UC Berkeley, Berkeley, CA 94720
phone: 510-642-0253 or 510-642-0455, fax: 510-642-2845
eal at eecs.Berkeley.EDU, http://ptolemy.eecs.berkeley.edu/~eal

More information about the Kepler-dev mailing list