Take 2 with John's suggestions. Llrpdef.xsd changes described below.
Change the annotation element to contain the compliance information as a
mandatory boolean attribute. Add a new description element. Perhaps this
was the intent of the appInfo element already. Since this change is not
really backward compatible, we may want to clean that up.
<xs:complexType name="annotation">
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="documentation" type="llrpdef:documentation"/>
<xs:element name="appinfo" type="llrpdef:appinfo"/>
<xs:element name="description" type="llrpdef:description"/>
</xs:choice>
<xs:attribute name="required" type="xs:boolean" use="required"/>
</xs:complexType>
Define the description type to contain any elements from XHTML namespace
and include the copyright as an attribute.
<xs:complexType name="description" mixed="true">
<xs:sequence>
<xs:any namespace="http://www.w3.org/1999/xhtml";
processContents="skip" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="copyright" type="xs:string" use="required"/>
</xs:complexType>
-----Original Message-----
From: [EMAIL PROTECTED]
[mailto:[EMAIL PROTECTED] On Behalf Of
John R. Hogerhuis
Sent: Wednesday, August 29, 2007 10:26 AM
To: LLRP Toolkit Development List
Subject: Re: [ltk-d] documentation in llrpdef.xml [heur]
On 8/29/07, Paul Dietrich <[EMAIL PROTECTED]> wrote:
> We've talked about annotating the llrpdef.xml with the appropriate
> document from LLRP. I wrote an example of how we could annotate in
> the Wiki under
>
> http://llrp-toolkit.wiki.sourceforge.net/LLRP+Protocol+Definition+%28l
> lr
> pdef.xml%29
>
> EPCglobal's copyright does not allow this without permission, so we'll
> have to get formal permission for this annotation. Let's agree on the
> technical representation below and then I'll submit for official
> approval to EPCglobal.
>
> I'll attach the snippet below, but here is what I am thinking.
>
> Include within the annotation tag in llrpdef.xml:
>
> 1) A documentation tag which includes a string which by convention
> will point to the section of the specification. This is to remain
> compatible with the llrpdef.xml we have now
>
> 2) A description tag which contains a string describing the element
> (message, parameter etc)
>
> 3) A compliance tag which contains a string with the compliance
> message from the LLRP spec
>
> 4) A copyright tag which holds the copyright string for 1-3 above.
>
> These would also be available for vendor extensions (1-4 would not be
> required by the schema)
>
> Here is an example annotation.
>
> <annotation>
> <documentation>
> reference 12.1.3 and 16.1.38
> </documentation>
> <description>
> This command is issued by the Client to the Reader. This command sets
> the Reader configuration using the parameters specified in this
command.
> Values passed by the SET_READER_CONFIG SHALL apply for the duration of
> the LLRP connection, or until the values are changed by additional
> SET_READER_CONFIG messages. For example, ROReportSpec defines the
> reporting of ROReport format and trigger for a ROSpec. ROReportSpec
> sent as part of SET_READER_CONFIG becomes the default ROReportSpec for
> the Reader. A ROReportSpec sent as part of ROSpec in the ADD_ROSPEC
> command overrides the default value for that ROSpec. However, in cases
> where there is no ROReportSpec specified in a ROSpec sent as part of
> ADD_ROSPEC, that particular ROSpec inherits the default ROReportSpec.
> The data field ResetToFactoryDefault informs the Reader to set all
> configurable values to factory defaults before applying the
> remaining parameters.
> </description>
> <Compliance>
> Compliant Reader and Clients SHALL implement this message
> </Compliance>
> <Copyright>
> Copyright 2006, 2007 EPCglobal Inc.
> </Copyright>
> </annotation>
>
>
Perhaps the copyright string could be an attribute of the description.
It's important but when you're reading documentation it's also noise not
directly related to apprehending the actual content. So I think an
attribute might be nicer.
I think compliance string is not primarily documentation and so should
not appear in the documentation string. It is functional, so it should
be an additional attribute of the message or parameter. Leaving this out
was probably just an oversight in the original design of llrpdef.xsd.
compliance="optional|required" or
shall="true|false" or
required="true|false"
something like that. In any event, please don't make it a free-form
documentation string. It wants to be machine processable so that a
conformance test "checker" can be autogenerated from llrpdef.xml.
For the documentation itself, we should specify mixed content for the
description element type in the XSD (may already be set up that way, I
don't recall) and state the markup language to use (so we can proper
bold, underlining, line breaks, possibly figures if necessary). XHTML is
the obvious choice.
Where this becomes important is editing XML instances of llrp.xsd, where
llrp.xsd is regenerated from llrpdef.xml. The text editor should be able
to pop up the documentation as you go. I don't know if all text editors
will support XHTML, but if they don't they are required to ignore it.
-- John.
------------------------------------------------------------------------
-
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems? Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >> http://get.splunk.com/
_______________________________________________
llrp-toolkit-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/llrp-toolkit-devel
-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
llrp-toolkit-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/llrp-toolkit-devel
