Open jpluscplusm opened 6 months ago
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.
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 atvet
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 thecue 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 fromcue help inputs
and the related content of any page that mentionscue vet
,cue export
etc.
I've tracked this in https://github.com/cue-lang/docs-and-content/issues/144.
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-inWe should publish acue help
texts in this space, on cuelang.orgprimerlanding page and a concept guide forcue 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:
cli
component of thecue
command's URLs, by moving the contents of the https://cuelang.org/docs/reference/cli/ hierarchy to https://cuelang.org/docs/reference/command/-help-
) to better reflect the actual underlying command whose output they demonstratecue vet
landing page for the reference hierarchycue vet
concept guide, explaining the command's ins and outs in detailThis scheme leaves us with a good template to replicate for other
cue
subcommands in the future - and other top-level commands likecuepls
, as well, if so desired.