Improving syntax+documentation

[Clancy508]

Hi all, I'm wondering if there's any work ongoing to tidy up the syntax for ignition and the documentation? At least for Fedora CoreOS I've noticed it's not particularly clear from the published specifications when a subheading requires a leading hyphen, for instance, and in at least one case this is inconsistent between equivalent uses, e.g. for setting file content using content: vs append: (note the hyphen and extra indentation on the append inline - transpilation throws an error without this even though the contents example works perfectly):

- path: /some/file/path
  contents:
    inline: |
      New
      File
      Contents

vs

- path: /some/existing/file
  append:
    - inline: |
        Added File Contents

[jlebon]

Ahh, I guess you posted this here instead of https://github.com/coreos/butane because Discussions is not enabled there? I'm not sure if there's a historical reason for that.

Anyway, agree this can be confusing. The reasoning in this case is that you may want to append multiple things to a file, and merge semantics from different configs can be useful there. Whereas in the contents case, the whole file is being described so naturally only one definition can exist.

[travier]

If you look at the specification, it says contents (object) so this take a single object (i.e. not a list, no dash, single entry) and append (list of objects) so this takes a list of items, each prefixed with a -.