A landing page and concept guide for cue-vet

[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.

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 landing page and a concept guide for cue vet that (between them), amongst other things, pushes readers towards package-based constraint resolution, not file-based.

Given the non-task-specific nature of this pair of pages, I suggest that the reference hierarchy gains the "landing page", suitable for receiving inbound links from anywhere on the site, which summarises the command and points onwards to relevant documentation - including the more expansive "things you can do with cue vet" concept guide.

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
• write a cue vet landing page for the reference hierarchy
  • https://cuelang.org/docs/reference/command/cue-vet/
• write a cue vet concept guide, explaining the command's ins and outs in detail
  • https://cuelang.org/docs/concept/the-cue-vet-command/

This scheme leaves us with a good template to replicate for 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 #144.