docs: clarify usage of version files

I found the current discussion around version files somewhat
confusing.

When you're reading the usage guide, the second point is telling you
to make a version file; strongly implying you should.  But in reality,
you most likely do not need to bother with keeping a specific version
file.  Explain more clearly about the implications of this.

Under this is a section on using `python -m setuptools_scm --help`
which seems like an orphan from the "as a cli" section; move it down
there.

The runtime section starts by telling you what is strongly discouraged
without explaination why.  Make it clearer by giving the first example
as the most supported thing, which is using standard importlib; then
briefly discuss the version file from above, explaining what's in it
for a standard Python template, then the strongly discouraged direct
import method.

In the config doc, update to discuss `importlib` for consistency.

Correct some capitalization and other minor formatting bits while
we're here.

docs/config.md

@@ -21,7 +21,7 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
 `version_file: Path | PathLike[str] | None = None`
 :   A path to a file that gets replaced with a file containing the current
     version. It is ideal for creating a ``_version.py`` file within the
-    package, typically used to avoid using `pkg_resources.get_distribution`
+    package, typically used to avoid using `importlib.metadata`
     (which adds some overhead).
 
     !!! warning ""

docs/index.md

@@ -12,9 +12,9 @@ or [configuring Git archive][git-archive-docs].
 
 [git-archive-docs]: usage.md#builtin-mechanisms-for-obtaining-version-numbers
 
-## basic usage
+## Basic usage
 
-### with setuptools
+### With setuptools
 
 Note: `setuptools_scm>=8` intentionally doesn't depend on setuptools to ease non-setuptools usage.
 Please ensure a recent version of setuptools (>=64) is installed.
@@ -37,7 +37,7 @@ dynamic = ["version"]
 ```
 
 
-### with hatch
+### With hatch
 
 [Hatch-vcs](https://github.com/ofek/hatch-vcs) integrates with setuptools_scm
 but provides its own configuration options,

docs/usage.md

@@ -1,6 +1,6 @@
 # Usage
 
-## at build time
+## At build time
 
 The preferred way to configure `setuptools_scm` is to author
 settings in the `tool.setuptools_scm` section of `pyproject.toml`.
@@ -25,7 +25,9 @@ that support PEP 518 ([pip](https://pypi.org/project/pip) and
 [pep517](https://pypi.org/project/pep517/)).
 Tools that still invoke `setup.py` must ensure build requirements are installed
 
-### version files
+### Version files
+
+Version files can be created with the ``version_file`` directive.
 
 ```toml title="pyproject.toml"
 ...
@@ -34,15 +36,13 @@ version_file = "pkg/_version.py"
 ```
 Where ``pkg`` is the name of your package.
 
+Unless the small overhead of introspecting the version at runtime via
+`importlib.metadata` is a concern or you need a version file in an
+alternative format such as plain-text (see ``version_file_template``)
+you most likely do _not_ need to write a separate version file; see
+the runtime discussion below for more details.
 
-```commandline
-$ python -m setuptools_scm
-
-# To explore other options, try:
-$ python -m setuptools_scm --help
-```
-
-## as cli tool
+## As cli tool
 
 If you need to confirm which version string is being generated
 or debug the configuration, you can install
@@ -65,46 +65,32 @@ $ python -m setuptools_scm ls # output trimmed for brevity
 ...
 ```
 
-!!! note "committed files only"
+!!! note "Committed files only"
 
     currently only committed files are listed, this might change in the future
 
 !!! warning "sdists/archives don't provide file lists"
 
-    currently there is no builtin mechanism
-    to safely transfer the file lists to sdists or obtaining them from archives
-    coordination for setuptools and hatch is ongoing
+    Currently there is no builtin mechanism
+    to safely transfer the file lists to sdists or obtaining them from archives.
+    Coordination for setuptools and hatch is ongoing.
 
-## at runtime (strongly discouraged)
-
-the most simple **looking** way to use `setuptools_scm` at runtime is:
-
-```python
-from setuptools_scm import get_version
-version = get_version()
-```
+To explore other options, try
 
-
-In order to use `setuptools_scm` from code that is one directory deeper
-than the project's root, you can use:
-
-```python
-from setuptools_scm import get_version
-version = get_version(root='..', relative_to=__file__)
+```commandline
+$ python -m setuptools_scm --help
 ```
 
+## At runtime
 
-## Python package metadata
-
-
+### Python Metadata
 
-
-### version at runtime
-
-If you have opted not to hardcode the version number inside the package,
-you can retrieve it at runtime from [PEP-0566](https://www.python.org/dev/peps/pep-0566/) metadata using
+The standard method to retrieve the version number at runtime is via
+[PEP-0566](https://www.python.org/dev/peps/pep-0566/) metadata using
 ``importlib.metadata`` from the standard library (added in Python 3.8)
-or the [`importlib_metadata`](https://pypi.org/project/importlib-metadata/) backport:
+or the
+[`importlib_metadata`](https://pypi.org/project/importlib-metadata/)
+backport for earlier versions:
 
 ```python title="package_name/__init__.py"
 from importlib.metadata import version, PackageNotFoundError
@@ -116,6 +102,40 @@ except PackageNotFoundError:
     pass
 ```
 
+### Via your version file
+
+If you have opted to create a Python version file via the standard
+template, you can import that file, where you will have a ``version``
+string and a ``version_tuple`` tuple with elements corresponding to
+the version tags.
+
+```python title="Using package_name/_version.py"
+import package_name._version as v
+
+print(v.version)
+print(v.version_tuple)
+```
+
+### Via setuptools_scm (strongly discouraged)
+
+While the most simple **looking** way to use `setuptools_scm` at
+runtime is:
+
+```python
+from setuptools_scm import get_version
+version = get_version()
+```
+
+it is strongly discouraged to call directly into `setuptools_scm` over
+the standard Python `importlib.metadata`.
+
+In order to use `setuptools_scm` from code that is one directory deeper
+than the project's root, you can use:
+
+```python
+from setuptools_scm import get_version
+version = get_version(root='..', relative_to=__file__)
+```
 
 ### Usage from Sphinx
 
@@ -132,7 +152,7 @@ the working directory for good reasons and using the installed metadata
 prevents using needless volatile data there.
 
 
-## with Docker/Podman
+### With Docker/Podman
 
 
 In some situations, Docker may not copy the `.git`  into the container when