add descriptions from spec

[FelixBenning]

Description

This adds some of the descriptions from https://docs.citationstyles.org/en/stable/specification.html#appendix-iv-variables to the JSON Schema

It took me some time to find the spec and it would be nice to have tooltips in vscode by simply using the $schema key in the json.

Type of change

• New feature (non-breaking change which adds functionality)

Checklist

• I have installed the repo pre-commit hook; if not, and I have modified any of the schema files, I have run trang and/or prettier on the files, per CONTRIBUTING
• I have performed a self-review of my own code
• I have included suggested corresponding changes to the documentation (if relevant)

[bdarcus]

Thanks for doing this; we intended to, but just hadn't figured the best approach.

The only obvious question I have is why some properties have "descriptions", some "titles" and others both?

[FelixBenning]

Both are used for tooltips. If I remember correctly (haven't worked with json schemas for some time) vscode displays the title above the description on hover if both are there. And one or the other are displayed if only one of them are there. So in some sense they are equivalent. So I tried to use "title" for short "titley" descriptions like DOI, "Digital Object Identifier". And use "description" for longer descriptions. But there is no system behind it just rule of thumb. Basically took 10-20 min to throw as many descriptions into the file as I could find in that time. It won't be complete either. But I did not want to spend too much time before getting a reaction about it.

[FelixBenning]

Later on I started to split the description into a more punchy title and the remaining description. But not from the start so that is why that only happens sometimes

[FelixBenning]

The order in the documentation is not the same as in the schema, so it was sometimes hard to match the stuff. Ideally you would generate one from the other. Probably the docs from the json schema, since it is easier to read json programmatically

[bdarcus]

Here's from the json schema docs:

The title and description keywords must be strings. A “title” will preferably be short, whereas a “description” will provide a more lengthy explanation about the purpose of the data described by the schema.

On this:

Ideally you would generate one from the other. Probably the docs from the json schema, since it is easier to read json programmatically.

Yes, this is what I was alluding to above on the "best approach."

But it's even more complicated, given the overlap with the csl style schema variables.

[bdarcus]

As I've been using VSCode completion as part of #420 ...

If I remember correctly (haven't worked with json schemas for some time) vscode displays the title above the description on hover if both are there. And one or the other are displayed if only one of them are there.

Not from what I can see. It seems if a description is present, it uses that, even if there's a title.

But I can certainly imagine both being useful; for example, a title could be used to extract human-readable documentation. Or some editors might use both?