Re: [PRD] Issues to resolve before publication (section 1)

Christian de Sainte Marie wrote:
> Gary,
>
> I answer your comments in separate emails, trying to separate the 
> concerns; this email is about section 1.
>
> Summary: questions #1 and #2 (in my "issues" email [1]) seem to 
> resolve to "should the informal introduction of example rules in the 
> introduction be plain english or shall we rather use some sort of 
> intuitive rule-like structure?
It should be similar in style to UCR - plain English followed by the PS
>
> [1] http://lists.w3.org/Archives/Public/public-rif-wg/2008Jun/0191.html
>
> Detailled comments below.
>
> Gary Hallmark wrote:
>>>
>>> #1. Section 1.1: Introduction. I propose that we keep that section 
>>> as it
>>> is in the current version, except for typos and blatantly bad english. 
>>
>> I still object to this section because it introduces 2 presentation 
>> syntaxes but one is never fully defined.
>> This document needs to be split into a specification and a tutorial, 
>> but we can do that after FPWD.
>
> Do we agree that the document should be self-standing?
The document should be structured like BLD --

1. An overview (I like having an example, but I note that BLD does not 
have one (yet)).  Note that a document can have a forward reference from 
an example using PS in the overview to a following section that fully 
defines it.

2. Presentation Syntax
  2.5 EBNF of PS

3. Semantics

4. XML Serialization

etc.

I have no idea why we need more than one example in the introduction, 
and would not include "wish list" features like user-defined externals 
for which we are lacking a robust solution at the moment.

> If yes, do you really think that we can just start with an unfamiliar 
> and as yet unspecified syntax for the inroductory examples?
Yes, that is what UCR does (and I urge the BLD editors to consider 
adding a simple example to the BLD overview)
>
> The "informal" syntax is not meant as a PS and it is not meant to be 
> specified: it is meant to give an intuitive and informal sense of the 
> example rules and of their structure as far as PRD is concerned, where 
> just writing them in plain english might be heavy and difficult to 
> read/parse.
Then use a simpler example.  It doesn't seem to be heavy for UCR.
>
> This being said: would you prefer plain english instead of an informal 
> rule-like presentation, for example 1.1 and the running example?
Yes.
>
>>> I
>>> added an editor's note about the presentation syntax and will open the
>>> corresponding issue. (Gary, could you check that I got the PS right in
>>> example 1.2, please?)
>>
>> PRD does not support logic functions so your example won't work.  I 
>> changed it.
>
> Yes, I forgot the "external" around the function "CurrentYerCumul", 
> and the IRI (it was meant to be an application-specific function).
I think we should avoid this in an introductory example, because I have 
doubts that we can or should define
user-defined externals (and isn't this a DTB issue anyway?)
>
> But your transcription is ok with me.
>
> Just for the sake of clarification: if we considered only the RIF 
> document as part of which that rule would be interchanged, "Gold" 
> coudl as well be a local name, right?
It could be _Gold in the PS
>
>>> #2. Section 1.3: Running example. I propose that we keep it as in the
>>> current version. I added a paragraph at the end of the section to 
>>> clarify
>>> some of the assumptions (per [4]):
>>
>> In your new informal PS, the repeated use of the term "which" is 
>> awkward (but then, so is the notion of a second PS)
>
> I removed the whiches (but if we agree on plain english, the informal 
> rule-like form will go away anyway).
+1 for plain English
>
> Christian
>

Received on Monday, 30 June 2008 18:34:46 UTC