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`

1 files changed, 8 insertions, 1 deletions

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