[drmaa-wg] DRMAA C Binding Spec v0.9.7

[Peter Troeger]

I read through the spec and found some minor issues. In general the
document looks very detailed and structured, maybe a little bit too
structured. Personally I would try to decrease the number of headings
;-) ...

I see a general unclarity with the use of the RFC-2119 keywords. I am
not sure whether the C-binding document is basically intended for DRMAA
library implementors or DRMAA library users. In the obvious first case,
the following keyword should be written in lower-case, since they do not
address requirements for a library implementor:

section 5.3.1, first "MUST"
section 5.3.1, first "SHOULD"
section 5.3.1, first "RECOMMENDED"
section 5.3.2, first "SHOULD"
section 5.4.5, "MUST"
section 5.6.3, "MAY"

In my opinion, the following keywords should also be written lower-case:

section 4 "MAY" (no requirement expressed)
section 4 "COULD"  (this is not a RFC-2119 keyword)

Some more minor stuff:

Section 4 has a misspelling ("tranlate").
In section 5.1.1, the word "Four" must be replaced with "Five".
I would add some of the original DRMAA text in section 5.4.9.4. in order
to explain the semantics of a job name.
In section 5.4.10.[3-6], the word "where" appears twice.
The sections 5.6.3 and 5.6.4 have some wrong fixed-width font on my machine.

Finally I have a problem that may arise from my lack of C knowledge.
Section 5.1.1 defines that the drmaa_*_s struct definitions shall not be
available in the DRMAA header file. If I am the developer of a DRMAA
application and use drmaa.h and libdrmaa.so only, how can my compiler
get to know the structure definitions ? Should I use another header
file, which contains the structure definitions ?

Regards,
Peter.

Daniel Templeton schrieb:

> As promised, I have incorporated the changes from the trackers, as per 
> my last email.  PLEASE, PLEASE, *PLEASE* read through this document. 
> Especially keep an eye out for usage of SHALL's, etc.
>
> Of particular interest are sections 4, 5.1.1, 5.1.5.27, 5.2.1-5.2.6, 
> 5.6, and 7.
>
> Please help make this document as clean as possible.  Unless there are 
> objections, there's a good chance this document will become the 
> official version 1.0 on Friday.
>
> Thanks,
> Daniel