[kepler-dev] Request for adding documentation on Kepler Actors
Edward A. Lee
eal at eecs.berkeley.edu
Thu Dec 1 13:19:09 PST 2005
Dan:
Unfortunately, at the time we did this, the <? doesn't strictly speaking
make this valid... In my opinion, it should, but the last I looked,
according to a strict reading of the standard, it does not.
We did, in fact, bend the rules of XML. Things may
have changed in the standard, however...
I consider this a defect of XML... We could make a validating
parser happy by avoiding XML, as in:
<configure>
title: Sequence Plotter
xLabel: DFH
yLabel: HFD
xRange: min="0.0" max="5.0"
yRange: min="1.0" max="6.0"
</configure>
Then we could write a custom parser for the plotter, thus reverting
to the bad-old-days before XML...
Strange that XML would force you to do this to get valid XML...
The real reason is that it didn't occur to them that there might
be good reasons for mixing schemas...
Edward
At 10:46 AM 12/1/2005 -0800, 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 "value" 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