cmd/cue: expand the embed help section

Lifting text and examples from the proposal document,
but in shorter format for the sake of a quick summary
as well as dropping some details which don't matter to users.

Fixes #3268.

Signed-off-by: Daniel Martí <[email protected]>
Change-Id: I8b90923dd43b5c706b9f8cf9dd0bd82513c1ad1d
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1199411
Reviewed-by: Matthew Sackman <[email protected]>
Unity-Result: CUE porcuepine <[email protected]>
TryBot-Result: CUEcueckoo <[email protected]>

cmd/cue/cmd/help.go

@@ -198,8 +198,34 @@ var embedHelp = &cobra.Command{
 	Use:   "embed",
 	Short: "file embedding",
 	Long: `
-The @embed directive can be used to load files of any type as part of CUE
-evaluation.
+The @embed attribute can be used to load files as part of CUE evaluation.
+Embedding must be enabled by a file-level @extern(embed) attribute.
+
+Embed a single file as follows, which must exist when evaluating:
+
+	@extern(embed)
+
+	package foo
+
+	a: _ @embed(file=foo.json)
+
+Embed many files of the same type with a glob pattern,
+which inserts one field per file matched:
+
+	b: _ @embed(glob=images/*.*, type=binary)
+	b: [string]: bytes
+
+Note that "**" glob patterns are not supported at this time.
+
+If the file extension in "file" or "glob" does not imply a file type,
+it must be specified with the "type" encoding as shown above.
+See the "filetypes" help topic for more.
+
+Files containing multiple documents cannot be embedded directly.
+For NDJSON or multi-document YAML files, embed as type=text
+and use APIs like yaml.Extract to decode as a list.
+
+Note that embedding cue files is not supported at this time.
 
 Note: support for embed is experimental, and is enabled via
 CUE_EXPERIMENT=embed.