search

ivoa-std / DataLink

DataLink standard (DAL)
3 stars 6 forks source link

Improve Section 5 #59

Closed mbtaylor closed 2 years ago

mbtaylor commented 2 years ago

Section 5 ('New “datalink” content-type for the LINK element in VOTable') (which originated in #30, new in DataLink 1.1) is kind of a mess.

I don't see why it belongs in DataLink; wouldn't the same thing apply to any content-type one wants to assert for the output of URLs in a VOTable?

If we do want to keep it in this document, I think it needs some improvement:

Bonnarel commented 2 years ago

Section 5 ('New “datalink” content-type for the LINK element in VOTable') (which originated in #30, new in DataLink 1.1) is kind of a mess.

I don't see why it belongs in DataLink; wouldn't the same thing apply to any content-type one wants to assert for the output of URLs in a VOTable? A real issue as been raised by people willing to use DataLink outside the ObsCore or DAL discovery services context as soon as 2017

If we do want to keep it in this document, I think it needs some improvement:

* putting it in its own top-level section with a chatty title seems to disrupt the flow of the document; could it be put somewhere else, e.g. Section 2?

OK. I think 3.1 is more adapted

* it mentions a "LINKS" element; I think that should read "LINK"

Sure

  • reword "content type defined in section for 3.1"

Sure

  • "see Appendix for details" - what Appendix?

This appendix was moved to an implementation note which is stalled since two years. We can remove it.

  • the example should be written with more care to help readers understand what's going on; replace "bla" and "bla bla bla" with text that gives a clue about the semantics

OK

  • the example overflows page bounds in the PDF

OK

I'm preparing a PR along these lines