Merge branch 'kh/doc-refs-migrate-limitations' into jch

The known limitations of the ref format migration in 'git refs' have
been moved to be displayed as a caution admonition directly under the
description of the 'migrate' subcommand, improving visibility.  A
reference to 'git-maintenance' has also been corrected to use the
'linkgit' macro.

* kh/doc-refs-migrate-limitations:
  doc: refs: linkgit to git-maintenance(1)
  doc: refs: put ref migration warning under the command

Documentation/git-refs.adoc

@@ -35,6 +35,21 @@ COMMANDS
 
 `migrate`::
 	Migrate ref store between different formats.
++
+[CAUTION]
+--
+The ref format migration has several known limitations in its current form:
+
+* It is not possible to migrate repositories that have worktrees.
+
+* There is no way to block concurrent writes to the repository during an
+  ongoing migration. Concurrent writes can lead to an inconsistent migrated
+  state. Users are expected to block writes on a higher level. If your
+  repository is registered for scheduled maintenance, it is recommended to
+  unregister it first with linkgit:git-maintenance[1].
+
+These limitations may eventually be lifted.
+--
 
 `verify`::
 	Verify reference database consistency.
@@ -130,21 +145,6 @@ The following options are specific to commands which write references:
 	Operate on <ref> itself rather than the reference it points to via a
 	symbolic ref.
 
-KNOWN LIMITATIONS
------------------
-
-The ref format migration has several known limitations in its current form:
-
-* It is not possible to migrate repositories that have worktrees.
-
-* There is no way to block concurrent writes to the repository during an
-  ongoing migration. Concurrent writes can lead to an inconsistent migrated
-  state. Users are expected to block writes on a higher level. If your
-  repository is registered for scheduled maintenance, it is recommended to
-  unregister it first with git-maintenance(1).
-
-These limitations may eventually be lifted.
-
 GIT
 ---
 Part of the linkgit:git[1] suite