* 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
This commit is a wide-ranging set of edits to the pages under
/docs/configuration. Among other things, it
- Separates style conventions out into their own page.
- Separates type constraints and conversion info into their own page.
- Conflates similar complex types a little more freely, since the distinction is
only relevant when restricting inputs for a reusable module or resource.
- Clarifies several concepts that confused me during edits.
This adopts a more guide-like writing style, similar to what prior commits
have done to some other subsections of this section.
Since we already have a whole top-level section devoted to modules, there
is no need for full coverage of all of their features here. Instead, this
section focuses on an an initial introduction to what modules are and
the basics of their usage within the Terraform language. We then link
to the main modules section for the full details.
We've historically been somewhat inconsistent in how we refer to the
type of object defined by "variable" blocks in configuration. Parts of
our documentation refer to them as "input variables" or just "variables",
while our implementation refers to them as "user variables".
Since Terraform Registry is now also referring to these as "Inputs", here
we standardize on "Input Variable" as the fully-qualified name for this
concept, with "variable" being a shorthand for this where context is
obvious. Outside of this context, anything that can be referred to in
an interpolation expression is generically known as a "variable", with
Input Variables being just one kind, specified by the "var." prefix.
While this terminology shift is not critical yet, it will become more
important as we start to document the new version of the configuration
language so we can use the generic meaning of "variable" there.
The modules mechanism has changed quite a bit for version 0.11 and so
although simple usage remains broadly compatible there are some
significant changes in the behavior of more complex modules.
Since large parts of this were rewritten anyway, I also took the
opportunity to do some copy-editing to make the prose on this page more
consistent with our usual editorial voice and to wrap the long
lines.
Justin Weissig