diff --git a/doc/topics/troubleshooting/index.rst b/doc/topics/troubleshooting/index.rst index 73789364c3..6cc14530b4 100644 --- a/doc/topics/troubleshooting/index.rst +++ b/doc/topics/troubleshooting/index.rst @@ -118,3 +118,11 @@ Or with the following salt state: sysctl: - present - value: 4096 87380 16777216 + + +Common YAML Gotchas +=================== + +An extensive list of +:doc:`yaml idiosyncrasies` +has been compiled. diff --git a/doc/topics/troubleshooting/yaml_idiosyncrasies.rst b/doc/topics/troubleshooting/yaml_idiosyncrasies.rst index 4bf71164ba..f430ded6fc 100644 --- a/doc/topics/troubleshooting/yaml_idiosyncrasies.rst +++ b/doc/topics/troubleshooting/yaml_idiosyncrasies.rst @@ -2,35 +2,35 @@ YAML Idiosyncrasies =================== -One of Salt's strength, the use of existing serialization systems for +One of Salt's strengths, the use of existing serialization systems for representing sls data, can also backfire. YAML is a general purpose system and there are a number of things that would seem to make sense in an sls -file that cause YAML issues. It is wise to be aware of these issues, while +file that cause YAML issues. It is wise to be aware of these issues. While reports or running into them are generally rare they can still crop up at unexpected times. Spaces vs Tabs ============== -Yaml uses spaces, period, do not use tabs in your sls files! If strange +Yaml uses spaces, period. Do not use tabs in your sls files! If strange errors are coming up in rendering sls files, make sure to check that -no tabs have crept in! +no tabs have crept in! In vi / vim, you can check with ``:se spell``. Indentation =========== -The suggested syntax for Yaml files is to use 2 spaces for indentation, -but Yaml will follow whatever indentation system that the individual file -uses. Generally 2 space indentation works very well for sls files given -the fact that the represented data is uniform and not deeply nested. +The suggested syntax for YAML files is to use 2 spaces for indentation, +but YAML will follow whatever indentation system that the individual file +uses. Indentation of two spaces works very well for sls files given the +fact that the data is uniform and not deeply nested. -Nested Dicts (key-value) +Nested Dicts (key=value) ------------------------ When dicts are more deeply nested they no longer follow the same indentation logic. This is rarely something that comes up in Salt, since deeply nested options like these are discouraged when making state modules, but some do -exist. A good example is the context and default options in the file.managed -state: +exist. A good example is the context and default options in the +:doc:`file.managed` state: .. code-block:: yaml @@ -50,7 +50,7 @@ state: Notice that the spacing used is 2 spaces, and that when defining the context and defaults options there is a 4 space indent. If only a 2 space indent is -used then the information will not be correctly loaded. If using double spacing +used then the information will not be loaded correctly. If using double spacing is not desirable, then a deeply nested dict can be declared with curly braces: .. code-block:: yaml @@ -89,7 +89,7 @@ This is best explained when setting the mode for a file: - mode: 644 Salt manages this well, since the mode is passed as 644, but if the mode is -zero padded as 0644, then it is read by Yaml as an integer and evaluated as +zero padded as 0644, then it is read by YAML as an integer and evaluated as a hexadecimal value, 0644 becomes 420. Therefore, if the file mode is preceded by a 0 then it needs to be passed as a string: