Updated VOTable 1.5 Working Draft

[Tom Donaldson]

Hi François and Markus,

Thanks François for the detailed review and Markus for the comments.  Based on this discussion I made the changes below and included them in pull request https://github.com/ivoa-std/VOTable/pull/50.  Please add your review comments to the PR or on this e-mail thread.

- Updated the Appendix B title to say V1.5
- Removed space from xtype="circle" in section 4.7
- Explicitly listed current vocabularies for TIMESYS timescale and refposition
- Removed \parindent=0pt to make paragraph breaks more apparent
- Added reference to architecture figure in section 1.4 to encourage better placement of the figure

In removing \parindent=0pt I noticed that we went from 35 to 32 overfull hboxes. Though I'm not sure that's necessarily an improvement, I didn't notice any new display problems in the draft pdf. This look does seem consistent with a couple other docs I looked at (DataLink and TAP). Please have a look for yourself at the pdf artifact generated for this PR (https://github.com/ivoa-std/VOTable/suites/18051624563/artifacts/1039567030).

Regarding whether some attributes of COOSYS should be mandatory to be consistent with TIMESYS, I've added a comment to issue 23 (https://github.com/ivoa-std/VOTable/issues/23#issuecomment-1803341737), but still think we should maintain backward compatibility until version 2.0.  

Please comment that issue if clarification is needed. If you'd to add something to this version warning that certain attributes may become required, please suggest wording here on this PR.

Thanks,
Tom


> On 11/7/23, 2:00 PM, "apps on behalf of Markus Demleitner" <apps-bounces at ivoa.net <mailto:apps-bounces at ivoa.net> on behalf of msdemlei at ari.uni-heidelberg.de <mailto:msdemlei at ari.uni-heidelberg.de>> wrote:
> 
> Hi François,
>
> On Tue, Nov 07, 2023 at 06:02:38PM +0100, Francois Ochsenbein wrote:
> > * section 3.5 (on TIMESYS): shouldn't the list of allowed timescale
> > values be listed, as are the system COOSYS values? The same remark
> 
> In principle, I'm not overly wild about in-document vocabularies;
> vocabularies are designed to grow (and to have labels and
> descriptions, without which they're not terribly useful). But you're
> right, if we do it in one place, we should do it in the other, too.
> 
> I'll leave it to the editor to decide whether or not to put it
> 
> At the time or writing, this vocabulary includes the terms
> % GENERATED: !vocterms timescale
> % /GENERATED
> 
> near the current line 809 and running make generate. For
> TIMESYS/@refposition, I'd say there current cross reference to COOSYS
> should be enough (or perhaps add "see there for a snapshot of the
> defined values as of the release of this document.
> 
> > applies on the list of refposition, listed for COOSYS, but not for
> > TIMESYS (both share the same list). It looks also strange to me that
> > the system attribute in COOSYS is optional, while the timescale
> > attribute in TIMESYS is required — shouldn't this be harmonized ?
> 
> Yes, it should. The question is how to do that. Making
> COOSYS/@system mandatory will make some VOTables invalid, and we're
> officially not supposed to do that in a minor version.
> 
> I suppose it would be a reasonable and defendable policy if we said
> now that we reserve the right not make it mandatory two minor
> versions down the road or so.
> 
> > And last, for the comfort in reading the document, some additional
> > space between the paragraphs (the \parskip value) would be nice.
> 
> Since VOTable sets
> 
> \parindent=0pt
> 
> (which, frankly, I'd probably drop if I were the editor) you are
> right that discerning paragraphs is not always simple. Hence, having
> a bit of parskip is indeed wise, and I'd totally go for
> 
> \parskip=0.5ex
> 
> -- that's also a lot less invasive than re-introducing the parskip
> (which will probably result in overfull hboxes).
> 
> -- Markus