Subject: RE: documenting OCP parameters

From: "Martin Stecher" <[email-masked]>
Date: Sat, 25 Oct 2003 08:50:17 +0200

> 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];
> 	};
> 

I think, this last option is easiest to understand.

Martin

---

From: Alex Rousskov <[email-masked]>
Date: Sat, 25 Oct 2003 08:58:20 -0600 (MDT)

> I think, this last option is easiest to understand.

Agreed, documented, and pushed to the web site.

Alex.

---

From: "Martin Stecher" <[email-masked]>
Date: Sun, 26 Oct 2003 23:22:07 +0100

Alex,

I am changing parameter definitions to TDM. This is what I have so far:

  am-part: extends atom;
  am-parts: extends list am-part;

  HTTP-Profile: extends Feature with {
  [Aux-Parts: am-parts];
  [Wont-Use-Body: size];
  [Pause-At-Body: size];
  [Content-Encodings: codings];
  };

Is this correct?

In order to define which tokens are defined as the am-part atoms, may I
still write:
  am-part = "request-header"
          / "request-body"
          / "request-trailer"
          / "response-header"
          / "response-body"
          / "response-trailer"
in addition to the above?

And what is codings now?
Is it actually a list of tokens, as we used it so far or a list of
quoted-values?
Or is it just a list of atoms and implementations decide whether bare-values
work here?

Regards
Martin

----- Original Message ----- 
From: "Alex Rousskov" <[email-masked]>
To: "OPES WG" <[email-masked]>
Sent: Saturday, October 25, 2003 3:58 PM
Subject: RE: documenting OCP parameters

> ------------------------------------------------------------
> This mail has been scanned by debian3-smtp
> (WebWasher 4.4.1 Build 688)
> ------------------------------------------------------------
>

---

From: Alex Rousskov <[email-masked]>
Date: Sun, 26 Oct 2003 15:36:27 -0700 (MST)

> I am changing parameter definitions to TDM. This is what I have so far:

Yes.

>   am-parts: extends list am-part;

This looks awkward, does not it? How about:

    am-parts: extends list of am-part;

>   [Content-Encodings: codings];

Yes.

Should we use capital letters for types (Am-Parts rather than
am-part)? I do in OCP Core (e.g., "Feature" not "feature") but can
change to small letters if you prefer.

> in addition to the above?

I would render the above as a list in the text:

	<t>This specification documents the following am-part
	values:</t>

	<list style="hanging">
            <t hangText="request-header:">HTTP request headers
	    including ... as defined in ...</t>
	    ...

	</list>

Or you can use a table (see texttable in P draft).

It is a semantic requirement, and the type can support extensions (or
not, depending on how you document it).

> And what is codings now? Is it actually a list of tokens, as we used
> it so far or a list of quoted-values? Or is it just a list of atoms
> and implementations decide whether bare-values work here?

A list of atoms. Or a list of "coding", where coding extends atom with
some semantic properties.

OCP does not distinguish quoted and unquoted values on a semantical
level.

HTH,

Alex.

---

From: "Martin Stecher" <[email-masked]>
Date: Sun, 26 Oct 2003 23:56:53 +0100

>     am-parts: extends list of am-part;

ok.

> change to small letters if you prefer.

In 3.1 everything is lowercase. In section 9 we have uppercase and in
section 10 we have a mixture (bad that section title and text differ).
I think it looks well, if named parameter's names start with a capital
letter but type names are lowercase; then you know that the lowercase things
will be replaced by s.th. else while the capital words stay.

>     including ... as defined in ...</t>

ok. Thanks.

> some semantic properties.

I will then use:

  content-coding: extends atom;
  content-codings: extends list of content-coding;

  The semantics of content-coding is defined in section 3.5 of <xref
target="RFC2616" />

Thank you
Martin

---

From: Alex Rousskov <[email-masked]>
Date: Sun, 26 Oct 2003 19:41:15 -0700 (MST)

> will be replaced by s.th. else while the capital words stay.

OK. I will try to be consistent with the above when editing Core.

Alex.