improve documentation about backends

I noticed that, using just the man pages, there is no real description
of what backends are, or what ones are available. Except for some
examples.

Added a git-annex-backends man page, that is just a stub, but at least
describes what they basically are, and tells how to find the supported
ons, and links to the backends web page.

Sponsored-by: Brett Eisenberg on Patreon

6 files changed, 44 insertions, 14 deletions

diff --git a/doc/backends.mdwn b/doc/backends.mdwn
index 29b1820311..32267d17dd 100644
--- a/doc/backends.mdwn
+++ b/doc/backends.mdwn
@@ -1,10 +1,8 @@
-When a file is annexed, a [[key|internals/key_format]] is generated from
-its content and/or filesystem metadata. The file checked into git symlinks
-to the key. This key can later be used to retrieve the file's content (its
-value).
-
-Multiple key-value backends are supported, and a single repository
-can use different ones for different files. 
+The "backend" in git-annex specifies how a key is generated from a file's
+content and/or filesystem metadata. Most backends are different kinds of
+hashes. A single repository can use different backends for different files.
+The [[key|internals/key_format]] includes the backend that is used for that
+key.
 
 ## configuring which backend to use
 
@@ -47,7 +45,8 @@ in `.gitattributes`:
   platforms.
 * `BLAKE2S160`, `BLAKE2S224`, `BLAKE2S256`
   `BLAKE2S160E`, `BLAKE2S224E`, `BLAKE2S256E`
-  -- Fast [Blake2 hash](https://blake2.net/) variants optimised for 32 bit
+  -- Fas:w
+  t [Blake2 hash](https://blake2.net/) variants optimised for 32 bit
   platforms.
 * `BLAKE2BP512`, `BLAKE2BP512E`
   -- Fast [Blake2 hash](https://blake2.net/) variants optimised for
@@ -74,7 +73,7 @@ content of an annexed file remains unchanged.
   URL; for long URLs, part of the URL may be represented by a checksum.
   The URL key may contain `&` characters; be sure to quote the key if
   passing it to a shell script.  The URL-backend key is distinct from URLs/URIs
-  that may be attached to a key (from any backend) indicating the key's location
+  that may be attached to a key (using any backend) indicating the key's location
   on the web or in one of [[special_remotes]].
 * `GIT` -- This is used internally by git-annex when exporting trees
   containing files stored in git, rather than git-annex. It represents a
@@ -110,5 +109,3 @@ for [[security_reasons|security/CVE-2018-10857_and_CVE-2018-10859]].
 Note that the various 512 and 384 length hashes result in long paths,
 which are known to not work on Windows. If interoperability on Windows is a
 concern, avoid those.
-
-See also: [[git-annex-examinekey]]
diff --git a/doc/git-annex-backends.mdwn b/doc/git-annex-backends.mdwn
new file mode 100644
index 0000000000..86205eaebc
--- /dev/null
+++ b/doc/git-annex-backends.mdwn
@@ -0,0 +1,24 @@
+# NAME
+
+git-annex-backends - key/value backends for git-annex
+
+# DESCRIPTION
+
+The "backend" in git-annex controls how a key is generated from a file's
+content and/or filesystem metadata. Most backends are different kinds of
+hashes. A single repository can use different backends for different files.
+
+For a list of available backends, see `git-annex version`. For more
+details, see <https://git-annex.branchable.com/backends/>
+
+# SEE ALSO
+
+[[git-annex]](1)
+
+# AUTHOR
+
+Joey Hess <id@joeyh.name>
+
+<http://git-annex.branchable.com/>
+
+Warning: Automatically converted into a man page by mdwn2man. Edit with care.
diff --git a/doc/git-annex-migrate.mdwn b/doc/git-annex-migrate.mdwn
index b05991930d..18e9f2c89e 100644
--- a/doc/git-annex-migrate.mdwn
+++ b/doc/git-annex-migrate.mdwn
@@ -57,6 +57,8 @@ it's best to run migrate in all of them.
 
 [[git-annex-upgrade]](1)
 
+[[git-annex-backend]](1)
+
 # AUTHOR
 
 Joey Hess <id@joeyh.name>
diff --git a/doc/git-annex-preferred-content.mdwn b/doc/git-annex-preferred-content.mdwn
index 5972ab7f3a..f28385dc40 100644
--- a/doc/git-annex-preferred-content.mdwn
+++ b/doc/git-annex-preferred-content.mdwn
@@ -99,11 +99,13 @@ elsewhere to allow removing it).
   Like lackingcopies, but does not look at .gitattributes annex.numcopies
   settings. This makes it significantly faster.
 
-* `inbackend=name`
+* `inbackend=backendname`
 
   Matches only files whose content is stored using the specified key-value
   backend.
 
+  See [[git-annex-backends]](1) for information about available backends.
+
 * `securehash`
 
   Matches only files whose content is hashed using a cryptographically
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 5a8d7af943..5eca6600c8 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -792,7 +792,8 @@ repository, using [[git-annex-config]]. See its man page for a list.)
 * `annex.backend`
 
   Name of the default key-value backend to use when adding new files
-  to the repository.
+  to the repository. See [[git-annex-backends]](1) for information about
+  available backends.
 
   This is overridden by annex annex.backend configuration in the
   .gitattributes files, and by the --backend option.
@@ -1908,7 +1909,9 @@ Remotes are configured using these settings in `.git/config`.
 The key-value backend used when adding a new file to the annex can be
 configured on a per-file-type basis via `.gitattributes` files. In the file,
 the `annex.backend` attribute can be set to the name of the backend to
-use. For example, this here's how to use the WORM backend by default,
+use. (See [[git-annex-backends]](1) for information about
+available backends.)
+For example, this here's how to use the WORM backend by default,
 but the SHA256E backend for ogg files:
 
 	* annex.backend=WORM
diff --git a/git-annex.cabal b/git-annex.cabal
index e3234ec4d7..bea054e907 100644
--- a/git-annex.cabal
+++ b/git-annex.cabal
@@ -46,6 +46,7 @@ Extra-Source-Files:
   doc/git-annex-addurl.mdwn
   doc/git-annex-adjust.mdwn
   doc/git-annex-assistant.mdwn
+  doc/git-annex-backends.mdwn
   doc/git-annex-calckey.mdwn
   doc/git-annex-checkpresentkey.mdwn
   doc/git-annex-config.mdwn
@@ -109,6 +110,7 @@ Extra-Source-Files:
   doc/git-annex-renameremote.mdwn
   doc/git-annex-repair.mdwn
   doc/git-annex-required.mdwn
+  doc/git-annex-restage.mdwn
   doc/git-annex-resolvemerge.mdwn
   doc/git-annex-rmurl.mdwn
   doc/git-annex-schedule.mdwn