From dbaa48ff5b67339366e262b4b663a107bf3a6f8d Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <mitchell.hashimoto@gmail.com>
Date: Wed, 8 Jan 2014 10:42:37 -0800
Subject: [PATCH] website/docs: tips & tricks for vfile [GH-2788]

---
 website/docs/source/layouts/layout.erb        |  7 +--
 website/docs/source/stylesheets/_sidebar.less |  4 ++
 .../docs/source/v2/vagrantfile/tips.html.md   | 49 +++++++++++++++++++
 3 files changed, 57 insertions(+), 3 deletions(-)
 create mode 100644 website/docs/source/v2/vagrantfile/tips.html.md

diff --git a/website/docs/source/layouts/layout.erb b/website/docs/source/layouts/layout.erb
index 1d05c5b79..c7f3f5675 100644
--- a/website/docs/source/layouts/layout.erb
+++ b/website/docs/source/layouts/layout.erb
@@ -128,9 +128,10 @@
 								<ul class="sub unstyled">
 									<li<%= sidebar_current("vagrantfile-version") %>><a href="/v2/vagrantfile/version.html">Configuration Version</a></li>
 									<li<%= sidebar_current("vagrantfile-vagrantversion") %>><a href="/v2/vagrantfile/vagrant_version.html">Minimum Vagrant Version</a></li>
-									<li<%= sidebar_current("vagrantfile-machine") %>><a href="/v2/vagrantfile/machine_settings.html">Machine Settings</a></li>
-									<li<%= sidebar_current("vagrantfile-ssh") %>><a href="/v2/vagrantfile/ssh_settings.html">SSH Settings</a></li>
-									<li<%= sidebar_current("vagrantfile-vagrant") %>><a href="/v2/vagrantfile/vagrant_settings.html">Vagrant Settings</a></li>
+									<li<%= sidebar_current("vagrantfile-tips") %>><a href="/v2/vagrantfile/tips.html">Tips & Tricks</a></li>
+									<li<%= sidebar_current("vagrantfile-machine") %>><a href="/v2/vagrantfile/machine_settings.html" class="nocap">config.vm</a></li>
+									<li<%= sidebar_current("vagrantfile-ssh") %>><a href="/v2/vagrantfile/ssh_settings.html" class="nocap">config.ssh</a></li>
+									<li<%= sidebar_current("vagrantfile-vagrant") %>><a href="/v2/vagrantfile/vagrant_settings.html" class="nocap">config.vagrant</a></li>
 								</ul>
 								<% end %>
 
diff --git a/website/docs/source/stylesheets/_sidebar.less b/website/docs/source/stylesheets/_sidebar.less
index 62531fe48..aad2bda3d 100644
--- a/website/docs/source/stylesheets/_sidebar.less
+++ b/website/docs/source/stylesheets/_sidebar.less
@@ -119,6 +119,10 @@
                 padding: 12px 0;
                 border-top: 1px solid fade(@white, 20%);
 
+                a.nocap {
+                    text-transform: none;
+                }
+
                 &:first-child {
                     border-top: none;
                 }
diff --git a/website/docs/source/v2/vagrantfile/tips.html.md b/website/docs/source/v2/vagrantfile/tips.html.md
new file mode 100644
index 000000000..4e65870ef
--- /dev/null
+++ b/website/docs/source/v2/vagrantfile/tips.html.md
@@ -0,0 +1,49 @@
+---
+page_title: "Tips & Tricks - Vagrantfile"
+sidebar_current: "vagrantfile-tips"
+---
+
+# Tips & Tricks
+
+The Vagrantfile is a very flexible configuration format. Since it is just
+Ruby, there is a lot you can do with it. However, in that same vein, since
+it is Ruby, there are a lot of ways you can shoot yourself in the foot. When
+using some of the tips and tricks on this page, please take care to use them
+correctly.
+
+## Loop Over VM Definitions
+
+If you want to apply a slightly different configuration to many
+multi-machine machines, you can use a loop to do this. For example, if
+you wanted to create three machines:
+
+<pre class="prettyprint">
+(1..3).each do |i|
+  config.vm.define "slave-#{i}" do |slave|
+    slave.vm.provision "shell",
+      inline: "echo hello from slave #{i}"
+  end
+end
+</pre>
+
+<strong>Warning:</strong> The inner portion of multi-machine definitions
+and provider overrides are lazy-loaded. This can cause issues if you change
+the value of a variable used within the configs. For example, the loop below
+<em>does not work</em>:
+
+<pre class="prettyprint">
+# THIS DOES NOT WORK!
+for i in 1..3 do
+  config.vm.define "slave-#{i}" do |slave|
+    slave.vm.provision "shell",
+      inline: "echo hello from slave #{i}"
+  end
+end
+</pre>
+
+The "for i in  ..." construct in Ruby actually modifies the value of `i`
+for each iteration, rather than making a copy. Therefore, when you run this,
+every slave will actually provision with the same text.
+
+This is an easy mistake to make, and Vagrant can't really protect against it,
+so the best we can do is mention it here.