diff --git a/README.md b/README.md
index fa94ddb..bf0412b 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,33 @@
 # rust2rpm
 
-Convert Rust crates to RPM.
+rust2rpm is a tool for automatically generating RPM spec files for Rust crates.
 
-## `.rust2rpm.conf`
+## `rust2rpm.conf`
 
-You can place configuration file which is used as source for additional
-information for spec generation.
+If it is present, a `rust2rpm.conf` configuration file is read
+by rust2rpm to override some aspects of the automatic spec file generation.
 
-Some simple example would be better than many words ;)
+This file can be committed to dist-git to ensure that these settings
+will be applied for future updates of a crate package, as well.
+
+The file follows a slightly modified `ini` syntax. It supports sections for
+default settings (`[DEFAULT]`) and target-specific settings (i.e. `[fedora]`).
+
+These configuration options are available right now:
+
+- `unwanted-features`: features or optional dependencies for which no
+  `+feature` subpackage should be generated (for example, dependencies on Rust
+  compiler internals for crates that are also bundled with Rust itself)
+- `buildrequires`: additional build dependencies that must be installed for the
+  package to build correctly (i.e., `pkgconfig(foo)` for the `foo-sys` crate)
+- `lib.requires`: additional build dependencies that must be installed for the
+  crate to build correctly as a dependency of another crate (usually, this
+  contains the same values as the `buildrequires` option)
+- `lib+foo.requires`: additional build dependencies that must be installed for
+  the crate to build correctly as a dependency of another crate if it has
+  enabled the optional `foo` feature
+- `bin.requires`: additional runtime dependencies of the binary application that
+  is built from this crate
 
 ```ini
 [DEFAULT]
@@ -27,3 +47,10 @@ lib.requires =
 lib+default.requires =
   pkgconfig(bar) >= 2.0.0
 ```
+
+Note that features and optional dependencies that are marked as
+`unwanted-features` must not be dependencies of other Cargo features that are
+not marked "unwanted" as well. Failing to consider transitive dependencies will
+lead to broken dependencies of generated `rust-foo+bar-devel` packages and / or
+errors when generating spec files with rust2rpm.
+
diff --git a/rust2rpm/__main__.py b/rust2rpm/__main__.py
index 2cffd40..87f0a44 100644
--- a/rust2rpm/__main__.py
+++ b/rust2rpm/__main__.py
@@ -498,7 +498,22 @@ def main():
     kwargs["license_files"] = license_files
 
     conf = configparser.ConfigParser(interpolation=configparser.ExtendedInterpolation())
-    conf.read(["_rust2rpm.conf", ".rust2rpm.conf"])
+    confs = conf.read([".rust2rpm.conf", "_rust2rpm.conf", "rust2rpm.conf"])
+
+    # clean up configuration files with deprecated names
+    if len(confs) > 1:
+        print("WARNING: More than one *rust2rpm.conf file is present in this directory.")
+        print("         Ensure that there is only one, and that it has the correct contents.")
+        sys.exit(1)
+
+    if ".rust2rpm.conf" in confs and "rust2rpm.conf" not in confs:
+        os.rename(".rust2rpm.conf", "rust2rpm.conf")
+        print("Renamed deprecated, hidden .rust2rpm.conf file to rust2rpm.conf.")
+
+    if "_rust2rpm.conf" in confs and "rust2rpm.conf" not in confs:
+        os.rename("_rust2rpm.conf", "rust2rpm.conf")
+        print("Renamed deprecated _rust2rpm.conf file to rust2rpm.conf.")
+
     if args.target not in conf:
         conf.add_section(args.target)