`cue vet` primer

[jpluscplusm]

In https://cuelang.org/cl/1193603 I attempted to quickly address https://cuelang.slack.com/archives/CLT4FD7KP/p1711532252834579, which was caused by a user not being aware that cue vet can resolve constraints from packages, not just individual files.

However, if we accept https://cuelang.org/cl/1193603 then we'll also need to expand the help text for other commands. cue help inputs already exists, but it

Whilst we work out the best approach for the built-in cue help texts in this space, on cuelang.org we should publish a primer on cue vet that, amongst other things, pushes readers towards package-based constraint resolution, not file-based.

Given the non-task-specific nature of this primer, I suggest it's best placed inside the reference hierarchy, and should be written with that location in mind.

I propose we:

• remove the cli component of the cue command's URLs, by moving the contents of the https://cuelang.org/docs/reference/cli/ hierarchy to https://cuelang.org/docs/reference/command/
  • resulting in https://cuelang.org/docs/reference/command/cue-export/ (we'll leave redirection aliases behind)
  • IIRC we can't go one level deeper (.../command/cue/export/) as our left hand nav doesn't cope with the nested pages
• migrate all https://cuelang.org/docs/reference/command/cue-/ pages to https://cuelang.org/docs/reference/command/cue-help-/ (i.e. with an added -help-) to better reflect the actual underlying command whose output they demonstrate
• place the cue vet primer at https://cuelang.org/docs/reference/command/cue-vet/

This scheme leaves us with a good setup in which to place reference-level primers/etc on other cue subcommands in the future - and other top-level commands like cuepls, as well, if so desired.

[myitcv]

but it

Looks like this sentence was left unfinished.

As I mentioned offline.

If we do it for vet, we need to do it for all commands (otherwise we end up saying "and take a look at vet to see how to do X"). cue help inputs is the canonical reference. I'm minded to think we need better examples on cuelang.org that are richer than the cue help text. Perhaps a single page with examples, using different commands to drive the point home, of the various permutations of inputs. Rather than trying to create a table test of permutations for each command in each help text or a documentation page specific to each command. And then link to this helpful page from cue help inputs and the related content of any page that mentions cue vet, cue export etc.

[jpluscplusm]

but it

Looks like this sentence was left unfinished.

I'm not sure what I was going to say, there. I'm going to update this issue to track being the cue vet reference page that I believe we need, regardless of any changes we make to cue help vet/inputs/etc.

As I mentioned offline.

If we do it for vet, we need to do it for all commands (otherwise we end up saying "and take a look at vet to see how to do X"). cue help inputs is the canonical reference. I'm minded to think we need better examples on cuelang.org that are richer than the cue help text. Perhaps a single page with examples, using different commands to drive the point home, of the various permutations of inputs. Rather than trying to create a table test of permutations for each command in each help text or a documentation page specific to each command. And then link to this helpful page from cue help inputs and the related content of any page that mentions cue vet, cue export etc.

I've tracked this in https://github.com/cue-lang/docs-and-content/issues/144.