Add validation for xref fallback text (#3210)

* Fix xref fallback syntax

Signed-off-by: Petar Andric <slate@null.net>

* Add xref fallback validation

Signed-off-by: Petar Andric <slate@null.net>

---------

Signed-off-by: Petar Andric <slate@null.net>

Author: slate5

Makefile

@@ -144,7 +144,7 @@ REQUIRES := --require=asciidoctor-bibtex \
             --require=asciidoctor-sail
 
 .PHONY: all build clean build-container build-no-container build-docs build-pdf build-html build-epub build-tags docker-pull-latest submodule-check
-.PHONY: build-norm-rules build-norm-rules-json build-norm-rules-html check-tags update-ref
+.PHONY: build-norm-rules build-norm-rules-json build-norm-rules-html check-tags update-ref check-xref-fallbacks
 
 all: build
 
@@ -156,10 +156,12 @@ ifeq ("$(wildcard docs-resources/global-config.adoc)","")
 endif
 
 build-pdf: $(DOCS_PDF)
-build-html: $(DOCS_HTML)
+build-html: $(DOCS_HTML) check-xref-fallbacks
 build-epub: $(DOCS_EPUB)
 build-tags: $(DOCS_NORM_TAGS)
 check-xrefs: $(addprefix $(BUILD_DIR)/, $(addsuffix .check-xrefs, $(DOCS)))
+check-xref-fallbacks: $(DOCS_HTML)
+	@python3 ./scripts/check_xref_fallbacks.py $(DOCS_HTML)
 check-tags:
 	@bash ./scripts/check-tag-changes.sh
 
@@ -232,6 +234,7 @@ $(NORM_RULES_HTML): $(DOCS_NORM_TAGS) $(NORM_RULE_DEF_FILES) $(CREATE_NORM_RULE_
 $(BUILD_DIR)/%.check-xrefs: $(SRC_DIR)/%.adoc $(ALL_SRCS)
 	$(WORKDIR_SETUP)
 	$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_HTML) -v $(OPTIONS) $(REQUIRES) $< 2>&1 | grep 'possible invalid reference' && exit 1 || [ $$? -eq 0 ] $(DOCKER_QUOTE)
+	@[ ! -f $@.workdir/$(BUILD_DIR)/$(notdir $*).html ] && exit 0 || python3 scripts/check_xref_fallbacks.py $@.workdir/$(BUILD_DIR)/$(notdir $*).html
 
 # Update docker image to latest
 docker-pull-latest:

scripts/check_xref_fallbacks.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Check rendered HTML for cross-reference fallback text (e.g., <a href="#ref">[ref]</a>)."""
+
+import sys
+from html.parser import HTMLParser
+from pathlib import Path
+
+
+class LinkTextParser(HTMLParser):
+    """Extract href/text pairs from anchor elements."""
+
+    def __init__(self):
+        """Initialize parser."""
+        super().__init__()
+        self.in_a = False
+        self.href = None
+        self.text_parts = []
+        self.links = []
+
+    def handle_starttag(self, tag, attrs):
+        """Start collecting text when entering an anchor."""
+        if tag == "a":
+            self.in_a = True
+            self.href = dict(attrs).get("href", "")
+            self.text_parts = []
+
+    def handle_data(self, data):
+        """Collect visible text while inside an anchor."""
+        if self.in_a:
+            self.text_parts.append(data)
+
+    def handle_endtag(self, tag):
+        """Store the completed link when leaving an anchor."""
+        if tag == "a" and self.in_a:
+            text = "".join(self.text_parts).strip()
+            self.links.append((self.href, text))
+            self.in_a = False
+            self.href = None
+            self.text_parts = []
+
+
+def is_fallback(text):
+    """Return True when link text is fully wrapped in brackets."""
+    return bool(text) and text.startswith("[") and text.endswith("]")
+
+
+def main():
+    """Main execution."""
+    if len(sys.argv) < 2:
+        print("usage: check_xref_fallbacks.py <html-files>", file=sys.stderr)
+        sys.exit(22)
+
+    found_fallback = False
+
+    for filename in sys.argv[1:]:
+        path = Path(filename)
+        html = path.read_text(encoding="utf-8", errors="replace")
+
+        parser = LinkTextParser()
+        parser.feed(html)
+
+        bad = []
+        for href, text in parser.links:
+            if href.startswith("#") and is_fallback(text):
+                bad.append((href[1:], text))
+
+        if bad:
+            found_fallback = True
+            print(f"Fallback xrefs found in {path.name}:")
+            for href, text in bad:
+                print(f"  {href} -> {text}")
+
+    if found_fallback:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

src/unpriv/mm-explanatory.adoc

@@ -1707,7 +1707,7 @@ are redundant with other PPO rules under RVTSO assumptions
 
 Other general notes:
 
-[[sec:silent-stores]]
+[[silent-stores]]
 * Silent stores (i.e., stores that write the same value that already
 exists at a memory location) behave like any other store from a memory
 model point of view. Likewise, AMOs which do not actually change the

src/unpriv/zaamo.adoc

@@ -49,7 +49,7 @@ implementation can guarantee the AMO eventually completes. More complex
 implementations might also implement AMOs at memory controllers, and can
 optimize away fetching the original value when the destination is `x0`.
 Implementations that detect silent stores may reduce write traffic for
-AMOs when they do not change the value in memory (see <<sec:silent-stores>>).
+AMOs when they do not change the value in memory (see <<silent-stores, silent stores>>).
 
 The set of AMOs was chosen to support the C11/C++11 atomic memory
 operations efficiently, and also to support parallel reductions in