docs/reference: present pre-release cue-fix help text

This bumps the on-page version of the cue-fix help text to the site's
pre-release, in order to make the --exp flag visible when linked from
pages that mention language experiments. A custom info block tells the
reader that this flag requires a pre-release (but not the command
itself).

The hideIntroduction flag is renamed to genIntroduction (with an
inverted meaning), to avoid any confusion that might otherwise come from
its use alongside a custom "introduction" field.

Preview-Path: /docs/reference/command/cue-help-fix/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: Id46a6e6ebe9c0a01b3955eca93c68b868582c91b
Reviewed-on: https://cue.gerrithub.io/c/cue-lang/cuelang.org/+/1225082
Reviewed-by: Paul Jolly <[email protected]>
TryBot-Result: CUEcueckoo <[email protected]>

Author: jpluscplusm

content/docs/reference/command/commands.cue

@@ -20,24 +20,24 @@ _cuePathBase: {
 	// TODO: use site.cue's canonical data for these values (from the keys of
 	// versions["cue"]) when a solution to the panic captured at
 	// https://cuelang.org/cl/1209140 is available.
-	cueVersion!:       "latest" | "tip" | "prerelease"
-	experimental!:     bool
-	introduction!:     string
-	hideIntroduction!: bool
+	cueVersion!:      "latest" | "tip" | "prerelease"
+	experimental!:    bool
+	introduction!:    string
+	genIntroduction!: bool
 	tagSet!: [string]: true // true is chosen over top purely to produce concrete data.
 	tagList!: [...]
 	relatedCommands!: [...string]
 }
 
 cue: [SubCommand=string]: #CueCommand & {
-	_dirSuffix:       strings.Replace(SubCommand, " ", "-", -1)
-	dir:              *"cue-help-\(_dirSuffix)" | _
-	execCmd:          *"cue help \(SubCommand)" | _
-	title:            *"cue help \(SubCommand)" | _
-	cueVersion:       *"latest" | _
-	experimental:     *false | _
-	introduction:     *"" | _
-	hideIntroduction: *false | _
+	_dirSuffix:      strings.Replace(SubCommand, " ", "-", -1)
+	dir:             *"cue-help-\(_dirSuffix)" | _
+	execCmd:         *"cue help \(SubCommand)" | _
+	title:           *"cue help \(SubCommand)" | _
+	cueVersion:      *"latest" | _
+	experimental:    *false | _
+	introduction:    *"" | _
+	genIntroduction: *true | _
 	tagSet: *{} | _
 	tagList: [for tag, _ in tagSet {tag}]
 	relatedCommands: *[] | _
@@ -67,20 +67,31 @@ cue: {
 		cueVersion: "prerelease"
 		// Consider uncommenting this line, instead of removing this command's
 		// customisation entirely.
-		//hideIntroduction: true
+		//genIntroduction: false
+	}
+
+	fix: {
+		cueVersion:      "prerelease"
+		genIntroduction: false
+		introduction: """
+			{{<info>}}
+			The `--exp` flag is only available in a recent CUE
+			[pre-release]({{<relref"docs/introduction/installation#download-an-official-cue-binary">}}).
+			{{</info>}}
+			"""
 	}
 }
 
 // Introduce experimental and unreleased commands.
 cue: [_]: {
-	experimental:     _
-	cueVersion:       _
-	hideIntroduction: _
+	experimental:    _
+	cueVersion:      _
+	genIntroduction: _
 	let tip = (cueVersion == "tip")
 	let prerelease = (cueVersion == "prerelease")
 	let unreleased = tip || prerelease
 
-	if !hideIntroduction && (experimental || unreleased) {
+	if genIntroduction && (experimental || unreleased) {
 		introduction: strings.Join([
 			"{{<info>}}",
 			if tip {"This command is not yet available in the latest CUE release."},

content/docs/reference/command/cue-help-fix/en.md

@@ -6,9 +6,12 @@ tags:
 - cue command
 ---
 {{{with _script_ "en" "HIDDEN: access required CUE version"}}}
-export PATH=/cues/$CUELANG_CUE_LATEST:$PATH
+export PATH=/cues/$CUELANG_CUE_PRERELEASE:$PATH
 {{{end}}}
-
+{{<info>}}
+The `--exp` flag is only available in a recent CUE
+[pre-release]({{<relref"docs/introduction/installation#download-an-official-cue-binary">}}).
+{{</info>}}
 {{{with script "en" "cue cli help text"}}}
 cue help fix
 {{{end}}}

content/docs/reference/command/cue-help-fix/gen_cache.cue

@@ -8,11 +8,11 @@ package site
 						page: {
 							cache: {
 								multi_step: {
-									hash:       "1CAKPEHL6VR50EPJ0FIAMBG44SO2B0LTSMT0BARDHFOAFC4KF980===="
-									scriptHash: "EAN3P2JQ3V6QSU6V62E80MQMHOEE0B7JE4513535222V3DLB6VEG===="
+									hash:       "776459IJO5M7C45APUNTGDPC6J2PK6RJ2C4VDB0I4AL42O3FEIOG===="
+									scriptHash: "HU2032H2F80QL7EUHCPGTA81DI8EBK53KKJH0UHUN9B3R87QRE7G===="
 									steps: [{
 										doc:      ""
-										cmd:      "export PATH=/cues/v0.14.2:$PATH"
+										cmd:      "export PATH=/cues/v0.15.0-alpha.3:$PATH"
 										exitCode: 0
 										output:   ""
 									}, {
@@ -26,11 +26,34 @@ package site
 
 												Without any packages, fix applies to all files within a module.
 
+
+												Experiments
+
+												CUE experiments are features that are not yet part of the stable language but
+												are being tested for future inclusion. Some of these may introduce backwards
+												incompatible changes for which there is a cue fix. The --exp flag is used to
+												change a file or package to use the new, experimental semantics. Experiments
+												are enabled on a per-file basis.
+
+												For example, to enable the "explicitopen" experiment for all files in a package,
+												you would run:
+
+												\tcue fix . --exp=explicitopen
+
+												For this to succeed, your current language version must support the experiment.
+												If an experiment has not yet been accepted for the current version, an
+												@experiment attribute is added in each affected file to mark the transition as
+												complete.
+
+												The special value --exp=all enables all experimental features that apply to the
+												current version.
+
 												Usage:
 												  cue fix [packages] [flags]
 
 												Flags:
-												  -f, --force   rewrite even when there are errors
+												      --exp strings   list of experiments to port
+												  -f, --force         rewrite even when there are errors
 
 												Global Flags:
 												  -E, --all-errors   print all available errors

hugo/content/en/docs/reference/command/cue-help-fix/index.md

@@ -5,6 +5,10 @@ weight: 1000
 tags:
 - cue command
 ---
+{{<info>}}
+The `--exp` flag is only available in a recent CUE
+[pre-release]({{<relref"docs/introduction/installation#download-an-official-cue-binary">}}).
+{{</info>}}
 ````text { title="TERMINAL" type="terminal" codeToCopy="Y3VlIGhlbHAgZml4" }
 $ cue help fix
 Fix finds CUE programs that use old syntax and old APIs and rewrites them to use newer ones.
@@ -13,11 +17,34 @@ to your program.
 
 Without any packages, fix applies to all files within a module.
 
+
+Experiments
+
+CUE experiments are features that are not yet part of the stable language but
+are being tested for future inclusion. Some of these may introduce backwards
+incompatible changes for which there is a cue fix. The --exp flag is used to
+change a file or package to use the new, experimental semantics. Experiments
+are enabled on a per-file basis.
+
+For example, to enable the "explicitopen" experiment for all files in a package,
+you would run:
+
+	cue fix . --exp=explicitopen
+
+For this to succeed, your current language version must support the experiment.
+If an experiment has not yet been accepted for the current version, an
+@experiment attribute is added in each affected file to mark the transition as
+complete.
+
+The special value --exp=all enables all experimental features that apply to the
+current version.
+
 Usage:
   cue fix [packages] [flags]
 
 Flags:
-  -f, --force   rewrite even when there are errors
+      --exp strings   list of experiments to port
+  -f, --force         rewrite even when there are errors
 
 Global Flags:
   -E, --all-errors   print all available errors