Fix some warnings in users_guide (incl #16640)

- short underline
- :ghc-flag:, not :ghc-flags:
- :since: have to be separate
- newline before code block
- workaround anchor generation so

    - pragma:SPECIALISE
    - pragma:SPECIALIZE-INLINE
    - pragma:SPECIALIZE-inline

  are different anchors, not all the same `pragma:SPECIALIZE`

3 files changed, 11 insertions, 3 deletions

diff --git a/docs/users_guide/8.10.1-notes.rst b/docs/users_guide/8.10.1-notes.rst
index f14271294c..40241746a8 100644
--- a/docs/users_guide/8.10.1-notes.rst
+++ b/docs/users_guide/8.10.1-notes.rst
@@ -1,7 +1,7 @@
 .. _release-8-10-1:
 
 Release notes for version 8.10.1
-===============================
+================================
 
 The significant changes to the various parts of the compiler are listed in the
 following sections.
@@ -116,7 +116,7 @@ Template Haskell
 - The ``Lift`` typeclass is now levity-polymorphic and has a ``liftTyped``
   method. Previously disallowed instances for unboxed tuples, unboxed sums, an
   primitive unboxed types have also been added. Finally, the code generated by
-  :ghc-flags:`-XDeriveLift` has been simplified to take advantage of expression
+  :ghc-flag:`-XDeriveLift` has been simplified to take advantage of expression
   quotations.
 
 ``ghc-prim`` library
diff --git a/docs/users_guide/conf.py b/docs/users_guide/conf.py
index e48992d405..c3d5a3590c 100644
--- a/docs/users_guide/conf.py
+++ b/docs/users_guide/conf.py
@@ -147,7 +147,14 @@ def parse_ghci_cmd(env, sig, signode):
     return name
 
 def parse_pragma(env, sig, signode):
-    idx = sig.split(' ')[0]
+    parts = sig.split(' ')
+    idx = parts[0]
+
+    # To avoid re-using the same HTTP anchor #pragma-SPECIALIZE in multiple
+    # places, we disambiguate the anchor by adding the second word after it (if
+    # one exists).
+    if idx == "SPECIALIZE" and 1 in parts and parts[1].isalpha():
+        idx += "-" + parts[1]
     name = '{-# ' + sig + ' #-}'
     signode += addnodes.desc_name(name, name)
     return idx
diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index b1baa308c5..fdc3b2cafa 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -10433,6 +10433,7 @@ function that can *never* be called, such as this one: ::
 
 Sometimes :extension:`AllowAmbiguousTypes` does not mix well with :extension:`RankNTypes`.
 For example: ::
+
       foo :: forall r. (forall i. (KnownNat i) => r) -> r
       foo f = f @1