Re: [oslc-core] Discovery 5.1.3 - I can't quite parse it (also 5.1.1. and 5.1.2 wording/formatting)

[Martin P Pain <martinpain@uk.ibm.com>]

I'm still unsure what "LDPR representations"
means. Should there be a reference/link here?

The questions that come to mind (which
might all become clear once the first is answered):
1. What are "LDPR representations"?
"LDPR" does not appear anywhere else in this document.
2. How would I use them for discovery
details?
3. Exactly what are "discovery
details"? (i.e. what is the scope of this clause?)
4. What is "it" in the second
sentence? (Presumably the discovery details in a LDPR representation, but
it's a little uncertain.)
5. Why is it "also" useful
- presumably the "first" use is discover itself? Does this mean
"Not only is this useful for discovery on HTTP GET and OPTIONS requests,
but also makes the existence of the things being discovered available for
collection into indexes and for querying."?

I don't mean to sound harsh, but it
feels like that item's meaning has been distilled down too much to get
it into 2 short sentences, but has lost the context that gave it meaning.


On reading this again after writing
the above, there are two ways that first sentence could be read:
A. "Servers SHOULD use LDPR representations
- and no other representations - for discovery details."
or
B. "Servers SHOULD use LDPR representations
for discovery details - and for nothing else."
I was previously reading it as (A),
but I now see that (B) makes more sense.... depending on whether my understanding
of "LDPR representations" is correct. (In other words, it's a
clarification of 5.1.2).



Also, while I'm looking at 5.1:
I) 5.1.1: "information
that MAY BE exposed"
Only the "MAY" is formatted, but the "BE" is also capitalised.
"BE" should probably be "be".
II) 5.1.2: "Servers SHOULD minimize
the use of HTTP response headers on various HTTP operations as to not provide
unnecessary additional response content and complexity on server implementations
to provide it." reads as:
"Servers SHOULD minimize the use
of HTTP response headers on various HTTP operations as to not provide unnecessary
... complexity on server implementations to provide it. "
Perhaps:
"Servers SHOULD minimize the use
of HTTP response headers on various HTTP operations as to not provide unnecessary
additional response content. This is also to avoid the complexity on server
implementations that would be needed to provide such additional content.
"


Martin





From:      
 Steve K Speicher <sspeiche@us.ibm.com>
To:      
 Martin P Pain/UK/IBM@IBMGB
Cc:      
 "OASIS OSLC Core
TC Discussion List" <oslc-core@lists.oasis-open.org>
Date:      
 20/02/2015 20:58
Subject:    
   Re: [oslc-core]
Discovery 5.1.3 - I can't quite parse it
Sent by:    
   <oslc-core@lists.oasis-open.org>

---

I've reworked it, let me know if it
is still unclear. 

Thanks, Steve 

> From: Martin P Pain <martinpain@uk.ibm.com>
> To: "OASIS OSLC Core TC Discussion List" <oslc-core@lists.oasis-open.org>
> Date: 02/19/2015 11:15 AM 
> Subject: [oslc-core] Discovery 5.1.3 - I can't quite parse it
> Sent by: <oslc-core@lists.oasis-open.org>
> 
> 
> Discovery: 
> 
> 5.1.3 Servers SHOULD only use of LDPRs representations for discovery
details
> unless there are scenarios where it would be valuable to have that
data 
> readily available for purposes such as query. 
> 
> should this be the following? 
> 
> 5.1.3 Servers SHOULD only use methods defined by LDPR (for example,
the Link
> header in 5.2.2) for discovery details unless there are scenarios
where it 
> would be valuable to have that data readily available for purposes
such as query. 
> 
> or does it mean 
> 
> 5.1.3 Servers SHOULD only use Link headers for discovery details unless
> there are scenarios where it would be valuable to have that data readily
> available for purposes such as query. 
> Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with
number 741598. 
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire
PO6 3AU

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU