Mildwonkey/012 docs updated (#20542)

* docs: update plan command documentation. Fixes #19235

* docs: added a missing reserved variable name. Fixes #19159.

* website: add note that resource names cannot start with a number

* website: add some notes to the 0.12 upgrade guide

command/plan.go

@@ -191,7 +191,7 @@ func (c *PlanCommand) Run(args []string) int {
 
 func (c *PlanCommand) Help() string {
 	helpText := `
-Usage: terraform plan [options] [DIR-OR-PLAN]
+Usage: terraform plan [options] [DIR]
 
   Generates an execution plan for Terraform.
 
@@ -200,9 +200,6 @@ Usage: terraform plan [options] [DIR-OR-PLAN]
   a Terraform plan file, and apply can take this plan file to execute
   this plan exactly.
 
-  If a saved plan is passed as an argument, this command will output
-  the saved plan contents. It will not modify the given plan.
-
 Options:
 
   -destroy            If set, a plan will be generated to destroy all resources

website/docs/commands/plan.html.markdown

@@ -25,7 +25,7 @@ for later execution with `terraform apply`, which can be useful when
 
 ## Usage
 
-Usage: `terraform plan [options] [dir-or-plan]`
+Usage: `terraform plan [options] [dir]`
 
 By default, `plan` requires no flags and looks in the current directory
 for the configuration and state file to refresh.

website/docs/configuration/resources.html.md

@@ -46,6 +46,9 @@ for the resource itself. Most arguments in this section depend on the
 resource type, and indeed in this example both `ami` and `instance_type` are
 arguments defined specifically for [the `aws_instance` resource type](/docs/providers/aws/r/instance.html).
 
+-> **Note:** Resource names must start with a letter or underscore, and may
+contain only letters, digits, underscores, and dashes.
+
 ## Resource Types and Arguments
 
 Each resource is associated with a single _resource type_, which determines

website/docs/configuration/variables.html.md

@@ -62,6 +62,8 @@ _except_ the following:
 - `count`
 - `for_each`
 - `lifecycle`
+- `depends_on`
+- `locals`
 
 These names are reserved for meta-arguments in
 [module configuration blocks](./modules.html), and cannot be

website/upgrade-guides/0-12.html.markdown

@@ -237,6 +237,13 @@ into a list. The upgrade tool does not remove or attempt to consolidate
 any existing duplicate arguments, but other commands like `terraform validate`
 will detect and report these after upgrading.
 
+## Terraform Configuration upgrades requiring human intervention 
+There are some known situations that will be detected, but not upgrade, by the
+upgrade tool. Some examples of these situatations include:
+
+* `count` can no longer be used a variable name.
+* `resource` names cannot start with a number, though they can still contain numbers.
+
 ## Working with `count` on resources
 
 The `count` feature allows declaration of multiple instances of a particular