Subject: RE: documenting OCP parameters

From: "Martin Stecher" <[email-masked]>
Date: Fri, 24 Oct 2003 23:34:11 +0200

Hi Alex,

> 
> 
> HTTP Adaptations draft raised a concern that the only way to document
> a new OCP parameter is to describe it using low-level syntax BNF.
> 
> Using BNFs for declarations is bad because it covers/hides the
> important information in syntax sugar and makes the reader think that
> a parameter may have some syntax features not already documented in
> the OCP Core. Moreover, if extension authors are not very careful,
> they could accidently introduce new syntax features which is a bad
> idea (unless explicitly negotiated first). Finally, since all BNFs
> look similar, using BNF makes OCP parameters look like HTTP headers
> (that have to be defined using BNF because there is nothing else
> available for HTTP) and vice versa, which is not that good since HTTP
> syntax is actually different from OCP syntax.
> 
> If there are no objections, I am going to add a section to OCP that
> will describe a very simple/basic way to document any parameter
> without using a syntax BNF. The same interface will be used in OCP
> Core, of course. Here is a sketch/template of possible choices
> 
> 	<name> : atom;
> 	<name> : list< <item> >;
> 	<name> : structure {
> 			<member> [<member>];       // anonymous
> 			<member-name>: <member>;   // required named
> 			[<member-name>: <member>]; // optional
> 		 };
> 
> This is similar to C/C++ typedefs but uses more-intuitive Pascal-like
> declaration syntax (new type name first, followed by the definition).
> The declaration would be accompanied by semantic rules, of course.
> Note that we already use something like the above for OCP messages
> (defining an entire message using BNF would be tedious).
> 
> Here are a few usage examples from OCP Core:
> 
> 	Uri: atom;
> 
> 	Service: structure {
> 			Uri;
> 	         };
> 
> 	Services: list<Service>;
> 
> And from the HTTP draft:
> 
> 	Am-Part: atom;
> 	Am-Parts: list<Am-Part>;
> 
> 	Http-Profile: structure {
> 			 Uri;
> 			[Aux-Parts: Am-Parts];
> 			[Skip-Parts: Am-Parts];
> 	              };
> 
> And here is how NO message can be declared using the above
> declarations and current message declaration syntax:
> 
> 	name:
> 		NO
> 	anonymous parameters:
> 		Services
> 	named parameters:
> 		[sg-id: Uni]
> 	payload:
> 		undefined
> 
> 
> Any objections or better ideas?
> 

Please add this to the core. I agree that such way of documentation will help.

Could you even improve the Service declaration a little?

Some way that allows to show that there are optional named parameters (none defined by core).
So, that it will allow the HTTP draft to define that
	Http-Profile: Service
and that Aux-Parts is a named parameter of that structure.

Your proposed solution has the disadvantage that NO has Services parameter, defined as a list of Service and in HTTP there is no mapping from HTTP-Profile to Service and no hint that NO anonymous parameter is being changed from Services to Http-Profiles.

Regards
Martin

---

From: Alex Rousskov <[email-masked]>
Date: Fri, 24 Oct 2003 16:16:09 -0600 (MDT)

> Your proposed solution has the disadvantage that NO has Services
> parameter, defined as a list of Service and in HTTP there is no
> mapping from HTTP-Profile to Service and no hint that NO anonymous
> parameter is being changed from Services to Http-Profiles.

Yes, I noticed that problem too. In addition to what you mention
above, it is bad that Http-Profile has to re-list Uri as a member.

Note that documenting with BNF does not solve it since NO message
definition still has Services. The only thing I could come up with is
inheritance-like approach, which I hesitated to propose as a starting
point. For example, in HTTP you would write:

	Profile: structure <Service> {
	             [Aux-Parts: Am-Parts];
	             [Skip-Parts: Am-Parts];
	};

Would that be clear enough? Or would you prefer:

	Profile: structure Service with {
		[Aux-Parts: Am-Parts];
		[Skip-Parts: Am-Parts];
	};

or

	Profile: extends Service with {
		[Aux-Parts: Am-Parts];
		[Skip-Parts: Am-Parts];
	};

Note that since there is only one way to merge anonymous parameters
and the order of named parameters is not important, the "inheritance"
is simply appending new params to old ones. No multiple inheritance is
supported.

Note that you can only extend structures, not atoms or lists.

Which one would you prefer? Any better ideas?

Alex.