README.md: Config reference: packages and subdirs

Reported-by: Mark Wooding <mdw@distorted.org.uk>
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/README.md b/README.md
index 1550719719b68ff927c7e6c02ca08a5df522531f..6e557027dc89b80074e25a5907fd04245931247a 100644 (file)
--- a/README.md
+++ b/README.md
@@ -76,19 +76,12 @@ Telling nailing-cargo how to massage `Cargo.toml`
 To find the subdirectories, and the packages, it looks for `subdirs`
 and `packages` in `Cargo.nail`.
 
-`subdirs` can be a (usually multi-line) string containing a list of
-subdirectory names one per line.  (`#`-comments are supported.)  Or it
-can be a list of strings (`subdirs = ['myproject','mylibrary']`).  In
-each of these directories `Cargo.toml` will be massaged, and
-the package there will be used for other massaged `Cargo.toml`s
-
-For more complex cases: `packages` is a mapping from package names to
-strings or dictionaries (e.g. in `Cargo.nail`, write something like:
-`[packages.mylibrary]` `subdir='mylibrary-test'` or `[packages]`
-`mylibrary='mylibrary-test'`).  These override the locations for the
-specified packages (so you can, for example, have multiple trees with
-the same package in).  These subdirectories are also added to the list
-of places where `Cargo.toml` should be massaged.
+For straightforward use, write `subdirs` as a multi-line string
+containing a list of subdirectory names one per line.  In each of
+these directories `Cargo.toml` will be massaged, and the package there
+will be used for other massaged `Cargo.toml`s.
+
+See "Configuration", below, for the full reference.
 
 Out-of-tree builds
 ==================
@@ -257,8 +250,44 @@ nailing-cargo reads these configuration files:
 Settings in later-mentioned files override ones in earlier-mentioned
 files.
 
-Note that unlike everything else, `packages` and `subdirs` are read
-only from `Cargo.nail` (see "Limitations and bugs", below).
+Source directories and packages (toplevel)
+------------------------------------------
+
+Note that unlike everything else, these keys `packages` and `subdirs`
+are read only from `Cargo.nail` (see "Limitations and bugs", below).
+
+These keys specify a combination of (i) a mapping from package name to
+source subdirectory (ii) a set of subdirectories whose `Cargo.toml`
+must be massaged.
+
+  * `packages`: a map keyed by package name, giving the subdirectory
+    for each one.
+
+    This causes each mentioned subdirectory's `Cargo.toml` to be
+    massaged, and records that subdirectory as the source for that
+    package.  (nailing-cargo will check that subdirectory actually
+    contains the indicated package.)
+
+    Each value can be just the subdirectory name (eg `[packages]`
+    `mylibrary='mylibrary-test'`) or itself a map with the key `subdir`
+    (eg `[packages.mylibrary]` `subdir='mylibrary-test'`).
+
+  * `subdirs`: a list of subdirectory names to process.
+
+    Each subdirectory's `Cargo.toml` will be massaged; also, the
+    subdirectory will be examined to see what package it contains and
+    it will be used as the source for that package, unless that
+    package appears in an entry in `packages`, or an earlier entry in
+    `subdirs`.
+
+    This can be a list of strings (eg `subdirs =
+    ['myproject','mylibrary']`).  Or it can be single multi-line
+    string containing one subdirectory name per line; in that
+    case, `#`-comments are supported and tabs and spaces are ignored
+    (See "Most basic example usage" above.)
+
+In each case the subdirectory should usually be a relative pathname;
+it is relative to the directory containing `Cargo.nail`.
 
 `[alt_cargolock]`: Alternative `Cargo.lock` filename
 ----------------------------------------------------