docs/reference: rename cli hierarchy to command

This performs two multi-page rename operations in one change (so that
aliases don't have to be left around for pages in the short-lived,
interim state). This is done to create space in the reference namespace
for manually-curated pages about the different cue subcommands, as
described below.

Practically, this change moves all /docs/reference/cli/* pages to
/docs/reference/command/*, continuing with our aim of not referring to
the "CLI", but instead preferring the "cue command".

It then moves all the /docs/reference/command/cue* pages (i.e. the same
set as were renamed above) to /docs/reference/command/cue-help*, and
updates the page's title to reflect the cue-help-based form.

Whilst this second change nominally results in the on-page title and URL
path reflecting the command that's actually demonstrated on the page,
the primary rationale is to provide space in the hierarchy for future
manually-curated pages to live. E.g. /docs/reference/command/cue-export/
will be the location where "cue export"-related links can point towards,
showing the reader a page designed to receive the link, rather than the
current generated cue command help text.

Appropriate aliases are put in place so that inbound requests (for
example) for /docs/reference/cli/cue-export/ will correctly end up at
/docs/reference/command/cue-help-export/. Links across the site are
updated. The distinct (but identical) "cue" and "cue help" pages are
merged, conceptually now being served at "cue help". This is done via
the removal of the bare "cue" page, whose original URL path
(/docs/reference/cli/cue/) is added as an alias to the moved "cue help"
page.

This looks like a lot of changes to review (and it is, numerically), but
it's mainly the result of changes to site.cue and
content/docs/reference/command/commands.cue, followed by a go-generate.
Some light "git grep"/"sed"/etc was also applied, to update the content
of Hugo shortcodes in order to allow the site to build successfully. A
non-exhaustive representative sample of pages is included in preview
links, below, to help the reviewer satisfy themselves as to the
correctness of the renames. Futher confidence may be gained from
clicking from the references index page to the renamed "The cue command"
section, and selecting various subcommands' pages.

Preview-Path: /docs/reference/
Preview-Path: /docs/reference/cli/
Preview-Path: /docs/reference/command/
Preview-Path: /docs/reference/cli/cue-export/
Preview-Path: /docs/reference/command/cue-help-export/
Preview-Path: /docs/reference/cli/cue/
Preview-Path: /docs/reference/cli/cue-help/
Preview-Path: /docs/reference/command/cue-help/
Signed-off-by: Jonathan Matthews <github@hello.jonathanmatthews.com>
Change-Id: I7d7ecb7bcb6a6a1d477002bfe3a31d8104db73e5
Dispatch-Trailer: {"type":"trybot","CL":1196994,"patchset":3,"ref":"refs/changes/94/1196994/3","targetBranch":"master"}

content/_en.html

@@ -177,7 +177,7 @@ <h3 class="icon-teaser__title">Scripting</h3>
                         <p class="link icon-teaser__readmore">
                             <span class="link__text">Learn more</span>
                         </p>
-                        <a class="icon-teaser__link" href="/docs/reference/cli/cue-cmd/" aria-label="Learn more about scripting">
+                        <a class="icon-teaser__link" href="/docs/reference/command/cue-help-cmd/" aria-label="Learn more about scripting">
                             <span>Learn more</span>
                         </a>
                     </div>

content/docs/concept/how-cue-enables-configuration/en.md

@@ -496,7 +496,7 @@ its information to use as data, schema, and policy.
 For more information on workflow commands, and how their ability to
 deterministically combine data from static and dynamic sources can supercharge
 automation, see the
-[`cue commands`]({{< relref "docs/reference/cli/cue-commands" >}})
+[`cue commands`]({{< relref "docs/reference/command/cue-help-commands" >}})
 reference documentation.
 
 ## Abstractions versus direct access

content/docs/concept/how-cue-enables-data-validation/en.md

@@ -469,10 +469,10 @@ cue vet policy.cue schema.proto schema.json data.yml -d '#ExampleType'
 {{{end}}}
 
 The range of formats and encodings that CUE supports is outlined in <!-- TODO: link to a less CLI-y doc -->
-[`cue filetypes`]({{< relref "docs/reference/cli/cue-filetypes" >}}).
+[`cue filetypes`]({{< relref "docs/reference/command/cue-help-filetypes" >}}).
 The `cue` command can also process its standard input stream in any of the
 formats it understands, as described in
-[`cue inputs`]({{< relref "docs/reference/cli/cue-inputs" >}}).
+[`cue inputs`]({{< relref "docs/reference/command/cue-help-inputs" >}}).
 
 ## Future plans
 
@@ -514,7 +514,7 @@ Interested in learning more about CUE? Here's what you could try next:
   - {{< linkto/related/concept "how-cue-works-with-json-schema" >}}
   - {{< linkto/related/concept "how-cue-works-with-protocol-buffers" >}}
   - {{< linkto/related/concept "how-cue-works-with-openapi" >}}
-- {{< linkto/related/reference "cli/cue-filetypes" >}}
+- {{< linkto/related/reference "command/cue-help-filetypes" >}}
   -- how to control which formats the `cue` command processes
-- {{< linkto/related/reference "cli/cue-inputs" >}}
+- {{< linkto/related/reference "command/cue-help-inputs" >}}
   -- how the `cue` command assembles its inputs, including its standard input stream

content/docs/concept/how-cue-works-with-go/en.md

@@ -62,7 +62,7 @@ This generates some CUE packages, placing them alongside our main CUE module:
 tree -d cue.mod/gen/k8s.io
 {{{end}}}
 
-[`cue get go`]({{< relref "docs/reference/cli/cue-get-go" >}})
+[`cue get go`]({{< relref "docs/reference/command/cue-help-get-go" >}})
 also has a `--local` option that generates CUE alongside Go in a main module.
 
 Within *our* main module, we can import and refer to the CUE definitions generated from the Go types:
@@ -351,7 +351,7 @@ CUE features such as data validation, policy enforcement, and more.
 
 ## Related content
 
-- {{< linkto/related/reference "cli/cue-get-go" >}}
+- {{< linkto/related/reference "command/cue-help-get-go" >}}
 - Go API:
     [`cue`](https://pkg.go.dev/cuelang.org/go/cue#section-documentation)
   | [`cue/load`](https://pkg.go.dev/cuelang.org/go/cue/load#section-documentation)

content/docs/concept/how-cue-works-with-json-schema/en.md

@@ -25,9 +25,9 @@ validate data, and to represent them natively in CUE's more succinct and
 expressive form.
 
 In this guide we'll see:
-- [`cue import`]({{< relref "docs/reference/cli/cue-import" >}}) converting a
+- [`cue import`]({{< relref "docs/reference/command/cue-help-import" >}}) converting a
   JSON Schema to CUE,
-- [`cue vet`]({{< relref "docs/reference/cli/cue-vet" >}}) using JSON Schema
+- [`cue vet`]({{< relref "docs/reference/command/cue-help-vet" >}}) using JSON Schema
   constraints directly,
 - and the
   [`encoding/jsonschema`](https://pkg.go.dev/cuelang.org/go/encoding/jsonschema)
@@ -37,7 +37,7 @@ The ability to export CUE constraints as JSON Schema is tracked in {{<issue 929/
 
 ## Using JSON Schema with the `cue` command
 
-The [`cue import`]({{< relref "docs/reference/cli/cue-import" >}}) command can
+The [`cue import`]({{< relref "docs/reference/command/cue-help-import" >}}) command can
 produce CUE from JSON Schema.
 
 Let's start with this JSON Schema:
@@ -148,7 +148,7 @@ and known-bad data (`bad.json`):
 {{{end}}}
 
 The
-[`cue vet`]({{< relref "docs/reference/cli/cue-vet" >}})
+[`cue vet`]({{< relref "docs/reference/command/cue-help-vet" >}})
 command validates our data against the `#Person` constraint:
 
 {{{with script "en" "validate against cue"}}}
@@ -164,7 +164,7 @@ The `cue vet` command can also validate the data using the JSON Schema directly:
 The `cue` command normally recognises JSON Schema's signature fields and treats
 the contents of JSON Schema as data constraints - not just additional data.
 A qualifier can be used to change this behaviour, as outlined in
-[`cue filetypes`]({{< relref "docs/reference/cli/cue-filetypes" >}}):
+[`cue filetypes`]({{< relref "docs/reference/command/cue-help-filetypes" >}}):
 
 {{{with script "en" "use json schema as json"}}}
 #ellipsis 4
@@ -295,8 +295,8 @@ tracked in {{<issue 929/>}}.
 
 ## Related content
 
-- {{< linkto/related/reference "cli/cue-import" >}}
+- {{< linkto/related/reference "command/cue-help-import" >}}
 - The [`encoding/jsonschema`](https://pkg.go.dev/cuelang.org/go/encoding/jsonschema) Go API
-- {{< linkto/related/reference "cli/cue-vet" >}}
-- {{< linkto/related/reference "cli/cue-filetypes" >}}
+- {{< linkto/related/reference "command/cue-help-vet" >}}
+- {{< linkto/related/reference "command/cue-help-filetypes" >}}
 - {{<issue 929>}}Issue #929{{</issue>}} tracks the conversion of CUE to JSON Schema

content/docs/concept/how-cue-works-with-json/en.md

@@ -21,7 +21,7 @@ is its default output format.
 This allows JSON files to be processed by CUE's wide range of data, schema, and
 policy validation capabilities, and to convert input formats to JSON - as
 demonstrated here by
-[`cue export`]({{< relref "docs/reference/cli/cue-export" >}})
+[`cue export`]({{< relref "docs/reference/command/cue-help-export" >}})
 *unifying* all its JSON, YAML, and CUE input files as JSON:
 <!-- TODO: add links for capabilities -->
 <!-- TODO: add link to unification concept guide -->
@@ -68,7 +68,7 @@ using CUE's powerful and compact constraint syntax, it's easy to add
 "pre-flight" checks to existing processes with CUE.
 
 In this example,
-[`cue vet`]({{< relref "docs/reference/cli/cue-vet" >}})
+[`cue vet`]({{< relref "docs/reference/command/cue-help-vet" >}})
 is used to check that a hypothetical system's JSON input files are valid - and
 catches a problematic deployment early in the process:
 
@@ -302,12 +302,12 @@ one very easy way to convert JSON files to CUE is simply to rename them from
 `.json` to `.cue`!
 
 In more complex situations
-[`cue import`]({{< relref "docs/reference/cli/cue-import" >}})
+[`cue import`]({{< relref "docs/reference/command/cue-help-import" >}})
 can create a CUE file for each JSON file it's given, and can even recognise
 embedded YAML and JSON fields, and convert those structures recursively.
 
 Examples of this command being used can be found in the
-[`cue import` CLI reference documentation]({{< relref "docs/reference/cli/cue-import" >}}).
+[`cue import` CLI reference documentation]({{< relref "docs/reference/command/cue-help-import" >}}).
 
 <!-- TODO: refer to a better page than the plain text CLI help text -->
 <!-- TODO: what example could work inline, here? -->

content/docs/concept/how-cue-works-with-openapi/en.md

@@ -28,11 +28,11 @@ natively in CUE’s significantly more concise form.
 
 In this guide, we'll see:
 
-- [`cue def`]({{< relref "docs/reference/cli/cue-def" >}})
+- [`cue def`]({{< relref "docs/reference/command/cue-help-def" >}})
   generating an OpenAPI data schema from a CUE definition,
-- [`cue import`]({{< relref "docs/reference/cli/cue-import" >}})
+- [`cue import`]({{< relref "docs/reference/command/cue-help-import" >}})
   turning the generated OpenAPI back into CUE,
-- [`cue vet`]({{< relref "docs/reference/cli/cue-vet" >}})
+- [`cue vet`]({{< relref "docs/reference/command/cue-help-vet" >}})
   using an OpenAPI data schema directly, to validate some data,
 - and the
   [`encoding/openapi`](https://pkg.go.dev/cuelang.org/go/encoding/openapi)
@@ -66,7 +66,7 @@ $version: "v1.2.3"
 #Kind: "cat" | "dog" | "goldfish"
 {{{end}}}
 
-The [`cue def`]({{< relref "docs/reference/cli/cue-def" >}}) command can
+The [`cue def`]({{< relref "docs/reference/command/cue-help-def" >}}) command can
 express CUE constraints as OpenAPI data schemas, in OpenAPI's
 `components.schemas` namespace - but *only* so long as all the top-level
 constraints are specified using CUE definitions.
@@ -137,7 +137,7 @@ it isn't possible to generate a precise OpenAPI equivalent for *every* CUE const
 CUE does the best conversion it can,
 limited by what OpenAPI's data schemas can represent.
 
-The [`cue import`]({{< relref "docs/reference/cli/cue-import" >}}) command
+The [`cue import`]({{< relref "docs/reference/command/cue-help-import" >}}) command
 can take constraints found in OpenAPI data schemas and express them as CUE.
 Here we take the definition produced by `cue def`, above, and convert it back to CUE:
 
@@ -181,7 +181,7 @@ diff -wu api.pet.cue .api.pet.cue
 rm .api.pet.cue # tidy up
 {{{end}}}
 
-The [`cue vet`]({{< relref "docs/reference/cli/cue-vet" >}}) command can
+The [`cue vet`]({{< relref "docs/reference/command/cue-help-vet" >}}) command can
 directly use constraints from OpenAPI data schemas to validate data.
 
 Let's check the details of a well-known animal,
@@ -283,9 +283,9 @@ are handled by CUE. More complete support is tracked in {{<issue 3133/>}}.
 
 ## Related content
 
-- {{< linkto/related/reference "cli/cue-def" >}}
-- {{< linkto/related/reference "cli/cue-import" >}}
-- {{< linkto/related/reference "cli/cue-vet" >}}
+- {{< linkto/related/reference "command/cue-help-def" >}}
+- {{< linkto/related/reference "command/cue-help-import" >}}
+- {{< linkto/related/reference "command/cue-help-vet" >}}
 - The [`encoding/openapi`](https://pkg.go.dev/cuelang.org/go/encoding/openapi) package
 - {{<issue 3133>}}Issue #3133{{</issue>}} tracks the support of other namespaces defined by
   [the OpenAPI standard](https://github.com/OAI/OpenAPI-Specification/tree/3.0.0)

content/docs/concept/how-cue-works-with-protocol-buffers/en.md

@@ -78,7 +78,7 @@ That's exactly as expected, because CUE's core operation is to automatically
 
 The behaviour of the `cue import` command can be affected by the flags outlined
 in the `proto mode` section of
-[the command's help text]({{< relref "docs/reference/cli/cue-import" >}}).
+[the command's help text]({{< relref "docs/reference/command/cue-help-import" >}}).
 
 ## Using the Go API
 
@@ -141,7 +141,7 @@ If several `.proto` files import each other, and other centralized schema
 definitions, then things can get hairy!
 In these situations, CUE's Go API and the `cue` command have you covered.
 
-Both [`cue import`]({{< relref "docs/reference/cli/cue-import" >}}) and the
+Both [`cue import`]({{< relref "docs/reference/command/cue-help-import" >}}) and the
 [`encoding/protobuf`](https://pkg.go.dev/cuelang.org/go/encoding/protobuf)
 package can be configured to handle custom import paths but, by default, when
 they encounter ...
@@ -183,8 +183,8 @@ CUE.
 
 ## Related content
 
-- {{< linkto/related/reference "cli/cue-import" >}}
-- {{< linkto/related/reference "cli/cue-filetypes" >}}
+- {{< linkto/related/reference "command/cue-help-import" >}}
+- {{< linkto/related/reference "command/cue-help-filetypes" >}}
 - Go API: [`encoding/protobuf`](https://pkg.go.dev/cuelang.org/go/encoding/protobuf)
 - Go API: [`encoding/protobuf/textproto`](https://pkg.go.dev/cuelang.org/go/encoding/protobuf/textproto)
 - Go API: [`encoding/protobuf/jsonpb`](https://pkg.go.dev/cuelang.org/go/encoding/protobuf/jsonpb)

content/docs/concept/how-cue-works-with-yaml/en.md

@@ -18,7 +18,7 @@ those containing multiple documents.
 This allows YAML files to be processed by CUE's wide range of data, schema, and
 policy validation capabilities, and to convert input formats to YAML - as
 demonstrated here by
-[`cue export`]({{< relref "docs/reference/cli/cue-export" >}})
+[`cue export`]({{< relref "docs/reference/command/cue-help-export" >}})
 *unifying* all its YAML, JSON, and CUE input files as YAML:
 <!-- TODO: add links for capabilities -->
 <!-- TODO: add link to unification concept guide -->
@@ -63,7 +63,7 @@ using CUE's powerful and compact constraint syntax, it's easy to add
 "pre-flight" checks to existing processes with CUE.
 
 In this example,
-[`cue vet`]({{< relref "docs/reference/cli/cue-vet" >}})
+[`cue vet`]({{< relref "docs/reference/command/cue-help-vet" >}})
 is used to check that a hypothetical system's YAML input files are valid - and
 catches a problematic deployment early in the process:
 
@@ -294,12 +294,12 @@ discover through the site's search page:
 
 ## Converting YAML files to CUE
 
-[`cue import`]({{< relref "docs/reference/cli/cue-import" >}})
+[`cue import`]({{< relref "docs/reference/command/cue-help-import" >}})
 can create a CUE file for each YAML file it's given, and can even recognise
 embedded YAML and JSON fields, and convert those structures recursively.
 
 Examples of this command being used can be found in the
-[`cue import` CLI reference documentation]({{< relref "docs/reference/cli/cue-import" >}}).
+[`cue import` CLI reference documentation]({{< relref "docs/reference/command/cue-help-import" >}}).
 
 <!-- TODO: refer to a better page than the plain text CLI help text -->
 <!-- TODO: what example could work inline, here? -->

content/docs/howto/combine-multiple-json-files-by-using-file-metadata/en.md

@@ -93,5 +93,5 @@ output: {
 ## Related content
 
 - {{< linkto/related/howto "combine-multiple-yaml-files-by-using-file-metadata" >}}
-- {{< linkto/related/reference "cli/cue-flags" >}}
+- {{< linkto/related/reference "command/cue-help-flags" >}}
   documents the `--with-context` and `-l` flags

content/docs/howto/combine-multiple-json-files-into-a-list/en.md

@@ -91,5 +91,5 @@ contents: [for _name in sortedInputs {
 ## Related content
 
 - {{< linkto/related/howto "combine-multiple-yaml-files-into-a-list" >}}
-- {{< linkto/related/reference "cli/cue-flags" >}}
+- {{< linkto/related/reference "command/cue-help-flags" >}}
   documents the `--with-context` and `-l` flags

content/docs/howto/combine-multiple-yaml-files-by-using-file-metadata/en.md

@@ -79,5 +79,5 @@ c.yaml:
 ## Related content
 
 - {{< linkto/related/howto "combine-multiple-json-files-by-using-file-metadata" >}}
-- {{< linkto/related/reference "cli/cue-flags" >}}
+- {{< linkto/related/reference "command/cue-help-flags" >}}
   documents the `--with-context` and `-l` flags

content/docs/howto/combine-multiple-yaml-files-into-a-list/en.md

@@ -76,5 +76,5 @@ contents:
 ## Related content
 
 - {{< linkto/related/howto "combine-multiple-yaml-files-into-a-list" >}}
-- {{< linkto/related/reference "cli/cue-flags" >}}
+- {{< linkto/related/reference "command/cue-help-flags" >}}
   documents the `--with-context` and `-l` flags

content/docs/howto/conditionally-include-cue-files-using-build-attributes/en.md

@@ -58,5 +58,5 @@ do not need to overlap in any way:** they are entirely unrelated strings.
 
 ## Related content
 
-- {{< linkto/related/reference "cli/cue-injection" >}}
+- {{< linkto/related/reference "command/cue-help-injection" >}}
   -- injecting tags and values into `cue` command invocations

content/docs/howto/fetch-json-data-http/en.md

@@ -53,7 +53,7 @@ CUE version v0.8.2 was released with commit hash 596c99191ad1eb7c39d547e59bc7085
 
 ## Related content
 
-- {{< linkto/related/reference "cli/cue-commands" >}} -- CUE workflow commands
+- {{< linkto/related/reference "command/cue-help-commands" >}} -- CUE workflow commands
 - Go API:
   [`tool/http`](https://pkg.go.dev/cuelang.org/go/pkg/tool/http#section-documentation) --
   make HTTP requests in workflow commands

content/docs/howto/generate-cue-from-local-go/en.md

@@ -176,6 +176,6 @@ Your Go code will probably have known-good and known-bad data for testing your g
 
 ## Related content
 
-- {{< linkto/related/reference "cli/cue-get-go" >}}
+- {{< linkto/related/reference "command/cue-help-get-go" >}}
 - Issue {{< issue 452 >}}#452{{</issue>}}: path resolution issue for files generated by `cue get go`
 - {{< linkto/related/howto "generate-cue-from-go-dependency" >}}

content/docs/howto/log-statistics-from-the-cue-evaluator/en.md

@@ -15,7 +15,7 @@ variable is set to a filename.
 
 The filename is interpreted through the same rules that `cue export` applies to
 its `--outfile` argument, which are explained in
-[`cue filetypes`]({{< relref "docs/reference/cli/cue-filetypes" >}}).
+[`cue filetypes`]({{< relref "docs/reference/command/cue-help-filetypes" >}}).
 Statistics for each evaluation are written into the named file using the file's
 implied data format.
 The file is overwritten on each `cue` invocation, without confirmation.
@@ -33,7 +33,7 @@ cat stats.cue
 
 Specifying the filename `-` causes `cue` to log statistics to its standard error stream as JSON.
 A different format may be selected using a qualifier prefix as outlined in
-[`cue filetypes`]({{< relref "docs/reference/cli/cue-filetypes" >}}).
+[`cue filetypes`]({{< relref "docs/reference/command/cue-help-filetypes" >}}).
 For example: to emit YAML, specify `yaml:-`.
 
 <!-- TODO: what do the emitted stats mean?
@@ -43,4 +43,4 @@ For example: to emit YAML, specify `yaml:-`.
 ## Related content
 
 - {{< issue 2856 >}}Issue #2856{{</issue>}} tracks enhancements to the set of statistics captured by `cue`
-- {{< linkto/related/reference "cli/cue-filetypes" >}}
+- {{< linkto/related/reference "command/cue-help-filetypes" >}}

content/docs/howto/use-your-first-cue-workflow-command/en.md

@@ -10,7 +10,7 @@ tags:
 This guide demonstrates how to define a very simple CUE *workflow command*,
 and how to run it.
 This specific workflow command allows a `-t` flag to
-[inject]({{< relref "docs/reference/cli/cue-injection" >}})
+[inject]({{< relref "docs/reference/command/cue-help-injection" >}})
 a value into the process so that it can be referred to.
 
 {{{with code "en" "cc"}}}
@@ -43,7 +43,7 @@ they are stored in a file with a name ending `_tool.cue`.
 ## Related content
 
 <!-- TODO: link to some central /docs/ page on cue tools -->
-- {{< linkto/related/reference "cli/cue-commands" >}}
+- {{< linkto/related/reference "command/cue-help-commands" >}}
   -- more information about CUE workflow commands
-- {{< linkto/related/reference "cli/cue-injection" >}}
+- {{< linkto/related/reference "command/cue-help-injection" >}}
   -- injecting values into `cue` command invocations

content/docs/howto/walk-schemas-using-go-api/en.md

@@ -188,6 +188,6 @@ generator that takes each CUE definition and produces a matching Go struct type.
 - The [`cue`](https://pkg.go.dev/cuelang.org/go/cue) Go API
 - The [`cue/cuecontext`](https://pkg.go.dev/cuelang.org/go/cue/cuecontext) Go API
 - The [`cue/load`](https://pkg.go.dev/cuelang.org/go/cue/load) Go API
-- {{< linkto/related/reference "cli/cue-mod-init" >}}
-- {{< linkto/related/reference "cli/cue-vet" >}}
+- {{< linkto/related/reference "command/cue-help-mod-init" >}}
+- {{< linkto/related/reference "command/cue-help-vet" >}}
 - {{< linkto/related/tour "types/defs" >}}

content/docs/reference/_en.md

@@ -11,7 +11,7 @@ The source of truth for how the CUE language should behave
 {{< /card >}}
 
 <!-- The trailing "\" on the next line vertically aligns the card's body with the spec card's body -->
-{{< card title="The cue command" label="reference/cli" href="cli/" >}}\
+{{< card title="The cue command" label="reference/command" href="command/" >}}\
 Help texts for the `cue` command and its subcommands
 {{< /card >}}