Add basic support for tagging text in the spec

This adds three things:

1. Custom CSS to add a subtle dotted underline on hover to any element with an ID starting with `manual__`.
2. An example tag `manual__x0_is_zero`, tagging the text that specifies that x0 is hardwired to 0.
3. A way of extracting the text of the tags into JSON.

This just adds a single tag as an exmaple, but the intention is that such tags would be added throughout the spec, allowing coverage, test plans, tests, documentation, etc. to all link to specific parts of the spec.

Author: Timmmm

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "docs-resources"]
 	path = docs-resources
-	url = https://github.com/riscv/docs-resources
+	url = https://github.com/Timmmm/docs-resources

Makefile

@@ -93,12 +93,16 @@ BUILD_DIR := build
 DOCS_PDF := $(addprefix $(BUILD_DIR)/, $(addsuffix .pdf, $(DOCS)))
 DOCS_HTML := $(addprefix $(BUILD_DIR)/, $(addsuffix .html, $(DOCS)))
 DOCS_EPUB := $(addprefix $(BUILD_DIR)/, $(addsuffix .epub, $(DOCS)))
+DOCS_TAGS := $(addprefix $(BUILD_DIR)/, $(addsuffix .tags.json, $(DOCS)))
 
 ENV := LANG=C.utf8
 XTRA_ADOC_OPTS :=
+
 ASCIIDOCTOR_PDF := $(ENV) asciidoctor-pdf
 ASCIIDOCTOR_HTML := $(ENV) asciidoctor
 ASCIIDOCTOR_EPUB := $(ENV) asciidoctor-epub3
+ASCIIDOCTOR_TAGS := $(ENV) asciidoctor --backend tags --require=./docs-resources/converters/tags.rb
+
 OPTIONS := --trace \
            -a compress \
            -a mathematical-format=svg \
@@ -107,6 +111,8 @@ OPTIONS := --trace \
            $(WATERMARK_OPT) \
            -a revnumber='$(DATE)' \
            -a revremark='$(RELEASE_DESCRIPTION)' \
+           -a docinfo=shared \
+           -a tags-prefix=manual__ \
            $(XTRA_ADOC_OPTS) \
            -D build \
            --failure-level=ERROR
@@ -116,7 +122,7 @@ REQUIRES := --require=asciidoctor-bibtex \
             --require=asciidoctor-mathematical \
             --require=asciidoctor-sail
 
-.PHONY: all build clean build-container build-no-container build-docs build-pdf build-html build-epub submodule-check
+.PHONY: all build clean build-container build-no-container build-docs build-pdf build-html build-epub build-tags submodule-check
 
 all: build
 
@@ -132,6 +138,7 @@ build-docs: $(DOCS_PDF) $(DOCS_HTML) $(DOCS_EPUB)
 build-pdf: $(DOCS_PDF)
 build-html: $(DOCS_HTML)
 build-epub: $(DOCS_EPUB)
+build-tags: $(DOCS_TAGS)
 
 ALL_SRCS := $(shell git ls-files $(SRC_DIR))
 
@@ -150,6 +157,11 @@ $(BUILD_DIR)/%.epub: $(SRC_DIR)/%.adoc $(ALL_SRCS)
 	$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_EPUB) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE)
 	$(WORKDIR_TEARDOWN)
 
+$(BUILD_DIR)/%.tags.json: $(SRC_DIR)/%.adoc $(ALL_SRCS) docs-resources/converters/tags.rb
+	$(WORKDIR_SETUP)
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_TAGS) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE)
+	$(WORKDIR_TEARDOWN)
+
 build: submodule-check
 	@echo "Checking if Docker is available..."
 	@if command -v docker >/dev/null 2>&1 ; then \

docs-resources

@@ -0,0 +1,21 @@
+<style>
+/*
+Any ID starting with 'manual__' is a snippet of specification text
+that has been specifically tagged to allow referencing it robustly,
+for use cases such as:
+
+* Linking coverage, tests plans, tests, assertions etc. to parts of
+  the spec that they cover.
+* Detecting when parts of the spec change. You can extract these
+  snippets via Asciidoc's docbook output and parsing the XML.
+* Linking documentation (e.g. the implementation defined parameter list)
+  to the spec.
+
+This adds a subtle decoration to make it easier to find tagged text.
+*/
+[id^="manual_"]:hover {
+    text-decoration: underline;
+    text-decoration-style: dotted;
+    text-decoration-color: gray;
+}
+</style>

src/docinfo.html

@@ -40,7 +40,8 @@ Most of the commentary for RV32I also applies to the RV64I base.
 
 <<gprs>> shows the unprivileged state for the base
 integer ISA. For RV32I, the 32 `x` registers are each 32 bits wide,
-i.e., `XLEN=32`. Register `x0` is hardwired with all bits equal to 0.
+i.e., `XLEN=32`.
+[#manual__x0_is_zero]#Register `x0` is hardwired with all bits equal to 0.#
 General purpose registers `x1-x31` hold values that various
 instructions interpret as a collection of Boolean values, or as two's
 complement signed binary integers or unsigned binary integers.