search

kdl-org / kdl

the kdl document language specifications
https://kdl.dev
Other
1.09k stars 61 forks source link

The word ‘tag’ is nowhere defined #306

Closed tjol closed 1 year ago

tjol commented 1 year ago

The word ‘tag’ is used in a few documents, including the KQL spec and the JSON-in-KDL spec. From context, it appears to mean ‘type annotation’.

The word ‘tag’ is not used or defined in the README, on kdl.dev, or in the KDL spec. What is worse, the website and README do contain the word ‘tag’ in this example:

tag /*foo=true*/ bar=false

suggesting that ‘tag‘ might be a term for the node name.

zkat commented 1 year ago

this might be worth clarifying, yes.

The answer is, "it's both, right now".

"Tag" for node names comes from "html/xml tags", which are semantically similar to kdl nodes.

Generally, when speaking of type annotations, I refer to them as "type tags", instead of just "tags", though.

larsgw commented 1 year ago

I feel like this might partly be my fault, via #137. I didn't make the JSON-in-KDL spec but that usage might also still have originated from me indirectly, sorry. I don't think I was thinking of html/xml tags, but I may have picked up on it that way. I'll make an update to KQL (I think I'll change everything to "type annotation" and note the change at the top?)

larsgw commented 1 year ago

Actually for at least KQL it's worse than I thought because tag() is actually the syntax, instead of something like type()...

larsgw commented 1 year ago

I made a PR to update the terminology in the JiK & KQL specs, I can make another PR to rename tag() to type() in KQL for v2.

zkat commented 1 year ago

renaming it in KQL sounds good, yes!