feat: improve YAML recipes

examples/ChefYAMLRecipes.md

@@ -38,6 +38,8 @@ For example:
 
 ```
 resources:
+- name: package[apache2]
+
 - type: "directory"
   name: "/var/www/html" # string
   mode: 755 # integer
@@ -49,52 +51,103 @@ resources:
 Will yield:
 
 ```
+package "apache2"
+
 directory "/var/www/html" do
   mode 755
   recursive true
   action ["create"]
 end
 ```
 
+YAML recipe is ERB template, like other tepmlates in Chef, so you can use all its features:
+
+```
+resources:
+<%- if node['platform_family'] == 'debian' %>
+- name: package[apache2]
+<%- else %>
+- name: package[httpd]
+<%- end %>
+
+<%- value = "Chef rocks!" %>
+- name: file[/etc/someconfig]
+  content: |
+    # Generated by Chef cookbook <%= cookbook_name %>
+    option = <%= value %>
+```
+
 ### Guards
 
-Some common resource functionality is also supported, provided that the value of a property can be expressed as one of the 4 primitive types (string, integer, boolean, array). That means it is possible to use `only_if` or `not_if` guards as long as they shell-out to bash or powershell and not passed a Ruby block.
+Some common resource functionality is also supported, provided that the value of a property can be expressed as one of the 4 primitive types (string, integer, boolean, array). That means it is possible to use `only_if` or `not_if` guards as long as they shell-out to bash or powershell.
 
 ```
-# works
 resources:
 - type: "directory"
   name: "/var/www/html"
   only_if: "which apache2"
+```
+
+You can use ERB ruby blocks, but only if they're returning boolean value
 
-# doesn't work
+```
 resources:
 - type: "directory"
   name: "/var/www/html"
-  only_if: "{ ::File.exist?('/usr/sbin/apache2') }"
+  only_if: "<%= ::File.exist?('/usr/sbin/apache2') %>"
+```
+
+Last string will produce following Ruby code if file exist:
+
+```
+  only_if "true"
+```
+
+Which is proper BASH command.
+
+### notifies/subscribes
+
+You can use `notifies/subscribes` for your resources:
+
+```
+- name: package[nginx]
+- name: service[nginx]
+  subscribes: 
+    - restart
+    - package[nginx]
+    - delayed
+  action:
+    - enable
+    - start
+- name: file[/etc/nginx/conf.d/vhost.conf]
+  notifies:
+    - reload
+    - service[nginx]
+    - delayed
 ```
 
 ## Knife yaml convert
 
 Along with YAML recipes, Chef 16 added a knife command for converting YAML recipes to the Ruby DSL equivalent. This is helpful when debugging issues with a YAML recipe or for when you need to start using more advanced features that are not available in the YAML recipe format.
 
+Converting of YAML files with ERB not supported yet.
+
 ```
 $ knife yaml convert recipes/apache2.yml
 Converted 'recipes/apache2.yml' to 'recipes/apache2.rb'
 ```
 
 ## What is not currently supported?
 
-Since YAML recipes are currently intended for users who are not familiar with Ruby, any of the functionality that relies on Ruby values is not available.
+Since YAML recipes are currently intended for users who are not familiar with Ruby, some functionality that relies on Ruby values is not available.
 
 Some notable things not supported:
 
-- Using node attributes
+- Including recipes with `include_recipe`, `load_recipe`
 - Resources with properties that accept a block, hash or a set of method parameters
   - For example the `ruby_script` resource is not supported because you must supply the `block` parameter
 - Common resource properties that accept a block, hash or a set of method parameters
-  - `notifies` and `subscribes`
   - arguments to guards and `guard_interpreter`
-  - guards that use ruby
+  - guards that use ruby (directly, see above)
   - `lazy`
   - windows file security