docs/reference: automate the vendor of the language spec

This change adds the CUE language specification by reusing the
current method of using go-generate to pull in the spec's markdown
source from the github.com/cue-lang/cuelang.org module dependency
version.

It changes the output very slightly, as the preprocessor can't cope with
an HTML comment preceeding the markown front matter - which needs to be
YAML, not TOML.

Instead we drop the prefix that includes the copyright file (per the
previous CL that is covered by the copyright in the root of this repo)
and the leading h1, and then take everything that follows. The h1
heading is taken care of by the frontmatter in alpha.cuelang.org.

This leaves the diff to the original cue-lang/cue spec as:

    ----
    -WARNING: Code generated by genspec. DO NOT EDIT.
    -title: "The CUE Language Specification"
    -authors:
    -- mpvl
    ----
    +<!--
    + Copyright 2018 The CUE Authors
    +
    + Licensed under the Apache License, Version 2.0 (the "License");
    + you may not use this file except in compliance with the License.
    + You may obtain a copy of the License at
    +
    +     http://www.apache.org/licenses/LICENSE-2.0
    +
    + Unless required by applicable law or agreed to in writing, software
    + distributed under the License is distributed on an "AS IS" BASIS,
    + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    + See the License for the specific language governing permissions and
    + limitations under the License.
    +-->
    +
    +# The CUE Language Specification

For cue-lang/docs-and-content#53.
Closes cue-lang/cue#2603.

Change-Id: I4be6880354083a24b088d9b9bf5aec2eafe8174b
Signed-off-by: Jonathan Matthews <[email protected]>
Preview-Path: /docs/reference/specification/
Co-authored-by: Paul Jolly <[email protected]>
Dispatch-Trailer: {"type":"trybot","CL":1167735,"patchset":10,"ref":"refs/changes/35/1167735/10","targetBranch":"alpha"}

content/docs/reference/spec/en.md

@@ -1,4 +1,5 @@
 ---
+WARNING: Code generated by internal/genspec; DO NOT EDIT.
 title: "The CUE Language Specification"
 authors:
 - mpvl

content/docs/reference/spec/generate.go

@@ -0,0 +1,17 @@
+// Copyright 2022 CUE Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package spec
+
+//go:generate go run github.com/cue-lang/cuelang.org/internal/genspec

hugo/content/en/docs/reference/spec/index.md

@@ -1,4 +1,5 @@
 ---
+WARNING: Code generated by internal/genspec; DO NOT EDIT.
 title: "The CUE Language Specification"
 authors:
 - mpvl

internal/genspec/main.go

@@ -41,14 +41,21 @@ func main() {
 	if err != nil {
 		log.Fatal(fmt.Errorf("failed to read %v: %w", srcSpecPath, err))
 	}
+	// Strip the prefix upto and including the h1 heading
+	const h1 = "# The CUE Language Specification\n"
+	_, srcSpec, found := bytes.Cut(srcSpec, []byte(h1))
+	if !found {
+		log.Fatalf("failed to find h1 heading %q", h1)
+	}
 	var out bytes.Buffer
-	fmt.Fprintln(&out, `<!-- Code generated by genspec. DO NOT EDIT. -->
-+++
-title = "Language Specification"
-layout = "spec"
-+++`)
+	fmt.Fprintln(&out, `---
+WARNING: Code generated by internal/genspec; DO NOT EDIT.
+title: "The CUE Language Specification"
+authors:
+- mpvl
+---`)
 	out.Write(srcSpec)
-	dstPath := "spec.md"
+	dstPath := "en.md"
 	if err := os.WriteFile(dstPath, out.Bytes(), 0666); err != nil {
 		log.Fatal(fmt.Errorf("failed to write to %v: %w", dstPath, err))
 	}