Add VOUnits syntax summary

[mbtaylor]

A new section is added that can serve as a quick introduction for readers wanting to know how to write VOUnits but not keen to plough through the whole document. This is intended to answer a large majority of people's questions, highlights some important points which are otherwise a bit buried (e.g. what about whitespace, and how to express multiples and powers of units), and provides pointers to other parts of the document that deal with the more subtle issues.

This is intended to address issue #26.

Improvements/adjustments welcome ... also I'm not sure if the placement of this section (sec 1.5, at the end of the Sec 1: Introduction) is optimal, an alternative would be to place it at the head of the (otherwise normative) Section 2.

[mbtaylor]

Thanks @nxg, useful comments. I fixed up the quotes to be consistent with the rest of the document. I have not added discussion here of the binary prefixes on the grounds that it's a rather special interest concern - I count about 1000 out of 220k legal units in the registry using [KMG]ibyte, all of them from VizieR, who probably know what they're doing already.

I reworded the item about unknown base symbols which is one of the subtle points that I sometimes get wrong (quotes around unrecognised base symbols don't make any difference except in case of ambiguity); your clarification at #30 helps. What I don't like about the way it's defined (and probably why I have trouble remembering it) is that consumers can't tell the difference between an inadvertently wrong unit and one that's known to be outside of the list of recognised units; e.g. "solarMass" is probably a typo for "solMass", but parsers/validators can only treat it the same as e.g. "mercuryMass". If quotes were required for unrecognised base units, then you'd write "solarMass" but "'mercuryMass'", and the former would trigger a validation error while the latter wouldn't, so it would be easier to diagnose metadata issues. But I guess it's too late to change that now.

[nxg]

It probably is too late, yes. Part of the motivation (though probably not discussed explicitly) was to make the VOUnits syntax overlap with the FITS-and-friends syntaxes as much as possible, which meant accepting mercuryMass without extra punctuation.

The other thing that the quotes do is turn a recognised symbol into an unrecognised one. Thus mm must always refer to the metre, and can't be a private notation for the magnitude, say (should one be mad enough to want to do that). However m'm' must not be the metre. That's probably also a sufficiently niche concern that it shouldn't be pushed into this crib.

The branch is green to merge. I haven't yet done the merge, though, in order to let Markus add review comments.

[msdemlei]

On Tue, Sep 12, 2023 at 04:38:04AM -0700, Norman Gray wrote:

The branch is green to merge. I haven't yet done the merge, though, in order to let Markus add review comments.

Ah, I'm happy with the changes -- feel free to merge. Thanks all around!

[msdemlei]

On Mon, Sep 11, 2023 at 07:43:03AM -0700, Mark Taylor wrote:

A new section is added that can serve as a quick introduction for readers wanting to know how to write VOUnits but not keen to plough

Thanks a lot, that's very helpful, and I particularly like the references to the normative material.

Content-wise I have nothing to add to Norman's comments, so the only thing I have to say is: What if we promoted this to a section rather than have it at the end of the introduction? It'd be more visible in the ToC, and since it's likely this is the only thing many people will read from the whole document, I think even the, ummm, saliency of the material warrants a promotion.

[nxg]

The only concern I'd have about promoting this to a separate section is that that would result in a significant change to the section numbering between versions 1.0 and 1.1, which might be worth avoiding. I wouldn't hold out against it, though.

[mbtaylor]

I agree it could use more prominence, but I don't know if a whole section would distort the structure of the document a bit. Another possibility would be highlighting the existence of this section early in the Introduction (or Abstract?) where a reader might stumble across it before losing interest. But I'm happy to leave this decision to one of the authors/editors.

[msdemlei]

On Wed, Sep 13, 2023 at 01:11:29AM -0700, Mark Taylor wrote:

I agree it could use more prominence, but I don't know if a whole section would distort the structure of the document a bit. Another possibility would be highlighting the existence of this section early in the Introduction (or Abstract?) where a reader might stumble across it before losing interest. But I'm happy to leave this decision to one of the authors/editors.

I wonder if there are references into VOUnits sections at this point; I doubt it, and if there aren't I'd say having it as a section would be the preferable. But then if Norman has doubts, I'm fine with merging it as is, too. So: it's on Norman, I'm afraid...

[nxg]

Even if there aren't external references into the document, it still feels a bit wrong doing any renumbering in a point-change of a document.

Highlighting the new section sounds like a good idea, though. I'll add something there, after merging this as it currently is.