Automatically add ratified text to instructions in manual

arch/manual_version/isa/20240411/isa_20240411.yaml

@@ -19,6 +19,8 @@ volumes:
         organization:
           name: SiFive, Inc.
           url: https://www.sifive.com/
+    srcdir: src
+    main: riscv-unprivileged.adoc
     chapters:
       - src/colophon.adoc
       - src/intro.adoc
@@ -175,6 +177,8 @@ volumes:
         organization:
           name: SiFive, Inc.
           url: https://www.sifive.com/
+    srcdir: src
+    main: riscv-privileged.adoc
     chapters:
       - src/priv-preface.adoc
       - src/priv-intro.adoc

backends/manual/tasks.rake

@@ -189,11 +189,15 @@ rule %r{#{MANUAL_GEN_DIR}/.*/.*/antora/modules/insts/pages/.*.adoc} => [
   ($root / "backends" / "manual" / "templates" / "instruction.adoc.erb").to_s
 ] do |t|
   inst_name = File.basename(t.name, ".adoc")
+  manual_version_name = t.name.sub("/antora/modules/insts/pages/#{inst_name}.adoc", "").split("/").last
 
   cfg_arch = cfg_arch_for("_")
   inst = cfg_arch.instruction(inst_name)
   raise "Can't find instruction '#{inst_name}'" if inst.nil?
 
+  manual_version = cfg_arch.manual_version(manual_version_name)
+  raise "Can't find manual version '#{manual_version_name}'" if manual_version.nil?
+
   inst_template_path = $root / "backends" / "manual" / "templates" / "instruction.adoc.erb"
   erb = ERB.new(inst_template_path.read, trim_mode: "-")
   erb.filename = inst_template_path.to_s

backends/manual/templates/instruction.adoc.erb

@@ -64,13 +64,45 @@ RV64::
 
 == Synopsis
 
+[NOTE]
+The following Synopsis is _community-driven_, and has not been ratified by https://riscv.org[RISC-V International].
+You may suggest a correction or improvement by submitting a Pull Request of the https://github.com/riscv-software-src/riscv-unified-db/blob/main/arch/inst/<%= parts = inst.__source.split("/"); parts[parts.rindex("inst")..].join("/") %>[source file].
+
 <%- if inst.data_independent_timing? -%>
 [IMPORTANT]
 This instruction must have data-independent timing when extension `Zkt` is enabled.
 <%- end -%>
 
 <%= inst.description %>
 
+== Ratified text
+
+<%-
+def get_section(block)
+  if block.context == :section
+    block
+  else
+    raise "?" if block.parent.nil?
+
+    get_section(block.parent)
+  end
+end
+-%>
+
+<%- manual_version.volumes.each do |volume| -%>
+<%- adoc_blocks = volume.find_normative_adoc_for(inst) -%>
+<%- unless adoc_blocks.empty? -%>
+The <%= inst.name %> instruction appears in <%= adoc_blocks.size %> <%= adoc_blocks.size == 1 ? 'paragraph' : 'paragraphs' %> of *<%= volume.title %>*:
+
+<%- adoc_blocks.each do |block| -%>
+<%- section = get_section(block) -%>
+.Section <%= section.sectnum %>, <%= section.title %>
+<%= block.source %>
+
+<%- end -%>
+<%- end -%>
+<%- end -%>
+
 == Access
 [cols="^,^,^,^,^"]
 |===

backends/manual/templates/playbook.yml.erb

@@ -5,9 +5,13 @@ site:
 content:
   sources:
   - url: <%= $root %>
+    worktrees: true
+    branches: [<%= `git rev-parse --abbrev-ref HEAD | tr -d '\n'` %>]
     start_path: gen/manual/<%= manual.name %>/top/<%= output_hash %>/antora/landing
   <%- manual.versions.each do |version| -%>
   - url: <%= $root %>
+    worktrees: true
+    branches: [<%= `git rev-parse --abbrev-ref HEAD | tr -d '\n'` %>]
     start_path: gen/manual/<%= manual.name %>/<%= version.name %>/antora
   <%- end -%>
 antora:

bin/setup

@@ -204,14 +204,15 @@ else
     exit 1
 fi
 
-if [ ! -f $ROOT/.git/hooks/pre-commit ]; then
-  cat << HOOK > $ROOT/.git/hooks/pre-commit
+GIT_REPO_ROOT=`git rev-parse --path-format=absolute --git-common-dir | tr -d '\n'`
+if [ ! -f $GIT_REPO_ROOT/hooks/pre-commit ]; then
+  cat << HOOK > $GIT_REPO_ROOT/hooks/pre-commit
 #!/usr/bin/env bash
 # File generated by pre-commit: https://pre-commit.com
 # ID: 138fd403232d2ddd5efb44317e38bf03
 
 # start templated
-INSTALL_PYTHON=$ROOT/bin/python
+INSTALL_PYTHON=$(realpath ./bin/python)
 ARGS=(hook-impl --config=.pre-commit-config.yaml --hook-type=pre-commit)
 # end templated
 
@@ -227,5 +228,5 @@ else
     exit 1
 fi
 HOOK
-  chmod +x $ROOT/.git/hooks/pre-commit
+  chmod +x $GIT_REPO_ROOT/hooks/pre-commit
 fi

lib/arch_obj_models/manual.rb

@@ -68,6 +68,36 @@ def initialize(data, version)
     @version = version
   end
 
+  def adoc
+    return @adoc unless @adoc.nil?
+
+    srcdir = "#{@repo_path}/#{@data["srcdir"]}"
+    @adoc = Asciidoctor.load_file("#{srcdir}/#{@data["main"]}", base_dir: srcdir, sourcemap: true, parse: true, catalog_assets: true, safe: Asciidoctor::SafeMode::UNSAFE)
+  end
+
+  # @return [Array<Asciidoctor::AbstractBlock>] Blocks that mention obj
+  def find_normative_adoc_for(obj)
+    keyword =
+      if (obj.is_a?(Instruction))
+        obj.name.upcase
+      else
+        raise "TODO: #{obj.class.name}"
+      end
+
+    regex = %r{(^|[ /,])#{keyword}([ ,/.]|$)}
+
+    def is_note?(block)
+      if block.context == :admonition
+        true
+      else
+        block.parent.nil? ? false : is_note?(block.parent)
+      end
+    end
+
+    blocks = adoc.find_by context: :paragraph
+    blocks.reject { |block| !block.methods.include?(:source) || block.source.index(regex).nil? || is_note?(block) }
+  end
+
   def chapters
     return @chapters unless @chapters.nil?