Subject: documenting OCP parameters

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

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?

Thanks,

Alex.