RegTAP 1.1 PR

[Mark Taylor]

Markus/RegTAP authors,

On Wed, 1 Aug 2018, Markus Demleitner wrote:

> I've uploaded a Proposed Recommendation for RegTAP 1.1 to the
> document repository.  Here's the changelog since WD-20171206:

I have read through this (PR-RegTAP-1.1-20180731).  The document
is generally in good shape, but I found a few issues of varying
degrees of triviality.  Some have been inherited from RegTAP 1.0.

Sec 8.1:
   "... where the canonical prefixes are used."
   It might increase readability to add a reference to Section 5 here.

Sec 8.2:
   The text states that the base_role column can assume one of the
   values "contact, publisher, contributor or creator", but the
   tabulated description of this item mentions only "contact, publisher
   and creator".

Sec 8.7:
   The tabulated descriptions of the "ucd" and "std" items say
   "parameter" when they should say "column".

   "The following columns MUST be lowercased during ingestion: 
    ivoid, name, ucd, utype, datatype, type_system."
   - should extended_type be added to this list?

Sec 8.8:
   "mereley" -> "merely"

Sec 8.12:
   "The content of incoming date/@type attributes must be normalized 
    according to the rules laid down in sect. 4.5 before lowercasing."
   - should that read "date/@role"?

Sec 9:
   The documentation of ivo_hasword and ivo_hashlist_has ought
   (like ivo_nocasematch) to make explicit that the return value
   is 0 in the case of no match.

Sec 10.3:
   ivo_hashlist_has arguments are the wrong way round.
   "1=ivo_hashlist_has('infrared', waveband)" should read
   "1=ivo_hashlist_has(waveband, 'infrared')"

Sec 10.12:
   The description tails off in mid-sentence.

Appendix C:
   This appendix looks like it's up for removal, so my comments 
   are pretty ignorable.  However in case it stays: I think the 
   recommended VARCHAR(4) type for interface.query_type is inadequate, 
   since the content is a hash-separated list, so could be, 
   e.g. "get#post" (or "get#post#head"??).

Appendix E.1:
   "inline XSLT utype maker" -> "inline XSLT utype marker"?

Appendix E.2:
   "/capability/interface/securityMethod/@standardID" could use some
   hyphenation hints for the PDF output.


I have one other suggestion on readability: the information from
the "the following columns MUST be lowercased during ingestion"
boilerplate in sections 8.* might be easier to digest if it
appeared as some sort of flag in the tabulated field descriptions
rather than in the text (e.g. marked "string/lc" rather than "string").
Just a thought.


What I haven't done is upgrade Taplint to be RegTAP-1.1 sensitive.
I probably should do that at some point.

Mark

--
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-9288776  http://www.star.bris.ac.uk/~mbt/