cue-lang / docs-and-content

A place to discuss, plan, and track documentation on cuelang.org
5 stars 1 forks source link

docs/concept: how the `cue` command combines its inputs #144

Open jpluscplusm opened 1 month ago

jpluscplusm commented 1 month ago

As mentioned in https://github.com/cue-lang/docs-and-content/issues/125#issuecomment-2071421324, we need a single page that shows off the ways that different cue subcommands accept and combine the inputs they're handed at the command line.

This page could start by demonstrating the common behaviours shared by cue vet/export/def/eval (what about import?), and then show any behaviours unique to specific commands (e.g. cue vet file.cue file1.json file2.json doesn't unify the 2 JSON inputs).

We should consider demonstrating each of these scenarios with at least one of the subcommands listed above, and with every subcommand for which the invocation has some special meaning:

jpluscplusm commented 1 month ago

This is related to #87, but that issue tracks a concept guide with a slightly wider scope. That guide can probably refer to this guide, but it shouldn't (IMHO) shy away from duplication which benefits the reader (because they can have a single narrative path through the topic, on the page) despite potentially increasing our burden as authors & maintainers.