Minor revision (#520)

Some minor revisions that I found when scrolling through the document.

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
 

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,13 +111,17 @@ 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[]
 
 <<<
 === "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[]