Harmonize sections references titles

As we use a Sphinx extension for all our references to the UEFI
specification, all those references mention the section title after the
section number automatically.
Among our other references written manually, some do mention the section
title (FF-A) and some do not (BBR & Devicetree).

Harmonize all our sections references to mention the referenced section
title after the § sign and the section number.
This has the benefit that references become easier to follow across
revisions when updating the referenced specifications.

Also, document the convention in the README.

Signed-off-by: Vincent Stehlé <vincent.stehle@arm.com>

Author: vstehle

README.rst

@@ -156,6 +156,17 @@ In general, try to keep the text width to at most 80 columns.
 Try to write footnotes contents as close a possible to the places referencing
 them.
 
+When referencing other specifications, use the following format::
+
+  <reference name>_ § <section number> <section title>
+
+For example::
+
+  [DTSPEC]_ § 5 Flattened Devicetree (DTB) Format
+
+As a special case, references to the UEFI specification should use the Sphinx
+extension described below instead.
+
 Sphinx Extensions
 -----------------
 

source/chapter1-about.rst

@@ -155,7 +155,7 @@ It does not define a standardized abstract virtual machine view for a Guest
 Operating System.
 
 This specification is referenced by the Arm Base Boot Requirements
-Specification [ArmBBR]_ § 3.2.
+Specification [ArmBBR]_ § 3.2 EBBR recipe.
 The UEFI requirements found in this document are similar but not identical to
 the requirements found in BBR.
 EBBR provides greater flexibility to support embedded designs which cannot

source/chapter2-uefi.rst

@@ -381,10 +381,11 @@ Devicetree
 
 If firmware provides a Devicetree system description then it must be provided
 in Flattened Devicetree Blob (DTB) format version 17 or higher as described in
-[DTSPEC]_ § 5.
+[DTSPEC]_ § 5 Flattened Devicetree (DTB) Format.
 The DTB Nodes and Properties must be compliant with the requirements listed in
-[DTSPEC]_ § 3 & 4 and with the requirements listed in the following table, which
-take precedence. [#DTSchNote]_
+[DTSPEC]_ § 3 Device Node Requirements & [DTSPEC]_ § 4 Device Bindings, and with
+the requirements listed in the following table, which take precedence.
+[#DTSchNote]_
 
 .. [#DTSchNote] The validity of the DTB and its conformance to [DTSPEC]_ can be
    verified automatically with the tools and schemas in [DTSCHEMA]_.
@@ -396,10 +397,10 @@ take precedence. [#DTSchNote]_
    * - Name
      - Requirement
    * - ``/chosen``
-     - This Node is required. ([DTSPEC]_ § 3.6)
+     - This Node is required. ([DTSPEC]_ § 3.6 /chosen Node)
    * - ``/chosen/stdout-path``
      - This Property is required. It is necessary for console output.
-       ([DTSPEC]_ § 3.6)
+       ([DTSPEC]_ § 3.6 /chosen Node)
 
 The DTB must be contained in memory of type `EfiACPIReclaimMemory`.
 [#ACPIMemNote]_

source/chapter3-secureworld.rst

@@ -52,9 +52,9 @@ version compatible with caller version 1.2. [#FFANote]_
    FF-A v1.2 introduced support for multiple services UUIDs in a partition,
    which eases services discovery, as well as the supporting
    `FFA_MSG_SEND_DIRECT_REQ2` ABI.
-   As per the FF-A specification § 13.2 FFA_VERSION, all callee versions 1.x,
-   with x >= 2, are compatible with caller versions 1.0 to 1.x, which includes
-   caller version 1.2.
+   As per the FF-A specification [FFA]_ § 13.2 FFA_VERSION, all callee versions
+   1.x, with x >= 2, are compatible with caller versions 1.0 to 1.x, which
+   includes caller version 1.2.
 
 RISC-V Multiprocessor Startup Protocol
 ======================================