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

Dan Higgins higgins at nceas.ucsb.edu
Thu Dec 1 14:06:15 PST 2005 

Edward,
    Thanks for the comment. FYI, Xerces 2.7.1 validates a document with 
the '<?' tag inserted at an arbitrary position! This may well be a bug 
in Xerces!

Dan

Edward A. Lee wrote:

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



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