From 643f5469b89de87406e8ec931e6a5666f49c18c3 Mon Sep 17 00:00:00 2001
From: Marno van der Maas <34654485+marnovandermaas@users.noreply.github.com>
Date: Wed, 5 Feb 2025 19:10:27 +0000
Subject: [PATCH] Minor revision (#520)

Some minor revisions that I found when scrolling through the document.
---
 readme.adoc           |  6 +++++-
 src/instructions.adoc | 18 ++++++++++++++++++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/readme.adoc b/readme.adoc
index 32c5e5b7..f0df1e8b 100644
--- a/readme.adoc
+++ b/readme.adoc
@@ -21,9 +21,13 @@ For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUT
 To build the document, you'll need the following tools installed on your system:
 
 * Make
-* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, and asciidoctor-mathematical
 * Docker
+
+If you want to build outside of Docker, you'll need some more tools:
 * Python3
+* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, asciidoctor-mathematical and asciidoctor-sail
+* bytefield-svg
+* wavedrom-cli
 
 === Cloning the Repository
 
diff --git a/src/instructions.adoc b/src/instructions.adoc
index 9c7f8ff7..c501399f 100644
--- a/src/instructions.adoc
+++ b/src/instructions.adoc
@@ -22,6 +22,8 @@ extensions will eventually be listed in a CHERI profile.
 <<<
 === "{cheri_base_ext_name}" and "{cheri_default_ext_name}" Extensions for CHERI
 
+These are the main instructions that are added by CHERI.
+
 include::insns/cmv_32bit.adoc[]
 
 include::insns/modesw_32bit.adoc[]
@@ -71,6 +73,8 @@ include::insns/store_32bit_cap.adoc[]
 <<<
 === RV32I/E and RV64I/E Base Integer Instruction Sets
 
+There are a number of instructions that are already in RISC-V that have modified behavior when CHERI is included.
+
 include::insns/auipc_32bit.adoc[]
 
 include::insns/condbr_32bit.adoc[]
@@ -90,6 +94,8 @@ include::insns/dret.adoc[]
 <<<
 === "A" Standard Extension for Atomic Instructions
 
+Atomic instructions and their interactions with CHERI.
+
 include::insns/amo_32bit.adoc[]
 
 include::insns/amoswap_32bit_cap.adoc[]
@@ -105,6 +111,8 @@ include::insns/store_cond_cap_32bit.adoc[]
 <<<
 === "Zicsr", Control and Status Register (CSR) Instructions
 
+CSR instructions and how they interact with CHERI.
+
 include::insns/csrrw_32bit.adoc[]
 
 include::insns/csrr_32bit.adoc[]
@@ -112,6 +120,8 @@ include::insns/csrr_32bit.adoc[]
 <<<
 === "Zfh", "Zfhmin", "F" and "D" Standard Extension for Floating-Point
 
+Floating point instructions and how CHERI affects them.
+
 include::insns/load_32bit_fp.adoc[]
 
 include::insns/store_32bit_fp.adoc[]
@@ -243,6 +253,8 @@ include::insns/store_16bit_cap_sprel.adoc[]
 <<<
 === "Zicbom", "Zicbop", "Zicboz" Standard Extensions for Base Cache Management Operations
 
+Cache-related instructions and how CHERI affects them.
+
 include::insns/cbo.clean.adoc[]
 
 include::insns/cbo.flush.adoc[]
@@ -260,6 +272,8 @@ include::insns/prefetch.w.adoc[]
 <<<
 === "Zba" Extension for Bit Manipulation Instructions
 
+Bit manipulation instruction reference.
+
 include::insns/adduw_32bit.adoc[]
 
 include::insns/sh123add_32bit.adoc[]
@@ -274,6 +288,8 @@ include::insns/sh4adduw_32bit.adoc[]
 [#Zcb,reftext="Zcb"]
 === "Zcb" Standard Extension For Code-Size Reduction
 
+Code-size reduction instructions and how they interact with CHERI.
+
 include::insns/load_16bit_Zcb.adoc[]
 
 include::insns/store_16bit_Zcb.adoc[]
@@ -368,6 +384,8 @@ include::insns/zcmt_cmjt.adoc[]
 
 === "H" Extension for Hypervisor Support
 
+Hypervisor instructions and the CHERI extensions.
+
 include::insns/hypv-virt-load.adoc[]
 
 include::insns/hypv-virt-load-cap.adoc[]