better explanation of the `-m / --multi <dir>` option

[ghostsquad]

This is a request to get more information on the -m / --multi <dir> option of jsonnet.

I first found out about this from the very clever use by coreos/kube-prometheus here:
https://github.com/coreos/kube-prometheus#compiling

---

jsonnet -J vendor -m manifests "${1-example.jsonnet}" | xargs -I{} sh -c 'cat {} | gojsontoyaml > {}.yaml; rm -f {}' -- {}

This script runs the jsonnet code, then reads each key of the generated json and uses that as the file name, and writes the value of that key to that file, and converts each json manifest to yaml.

---

It appears as though, if your file is an object, each key of that object becomes the file names that are both sent to stdout as well as used as the filename that is written. The contents of the file being the value of that key.

I was not able to find any official documentation that actually explained this behavior, and the help from the cmd tool itself was only slightly useful.

Is there anything else to know about how this option works? what happens if you also provide --yaml-stream?

And finally, would it make sense to have addition commandline option & behavior documentation here in the repo? either the top-level README.md or possibly within a docs directory?

[sbarzowski]

I agree that the documentation here is lacking. The easiest and most important improvement would be adding a better explanation in the command-line help. Then we may think of adding some section with the comparison of the commandline output helpers to the website (maybe here https://jsonnet.org/articles/output-formats.html ?).

[ghostsquad]

@sbarzowski I like that idea. Since there's no --format option on the command line, how your code is formatted is largely controlled by your jsonnet code itself. The caveats being --multi, --yaml-stream and --string command line options.

So I think that article could be expanded to explain all the various ways to use the tool (options), write code, and combine the 2 to get a variety of different results.

[sbarzowski]

It appears as though, if your file is an object, each key of that object becomes the file names that are both sent to stdout as well as used as the filename that is written. The contents of the file being the value of that key.

[...]

Is there anything else to know about how this option works? what happens if you also provide --yaml-stream?

I think your description is accurate. It seems that it takes precedence over --yaml-stream (https://github.com/google/go-jsonnet/blob/v0.14.0/cmd/jsonnet/cmd.go#L545). Other than that I don't have anything to add.

The implementation is here btw:
https://github.com/google/go-jsonnet/blob/v0.14.0/interpreter.go#L813
https://github.com/google/go-jsonnet/blob/v0.14.0/cmd/jsonnet/cmd.go#L344