Standardize the way numbered record names are documented

Some records are named after a fixed number of dimensions or items, and
therefore can be collectively documented. To collapse its name while
keeping the information of where the instance number goes, we use square
brackets with the variable N. However, the way the ranges are specified
is inconsistent, and how the user should interpret the brackets
substitution is undocumented. Moreover, we use the variable N for this
context, but there are also PVs with references to such variable name as
well, making it even more confusing for a newcomer.

Change that by standardizing on using angle brackets to specify the
instance number, making consistently documented in the entry
description. To avoid confusion with variables names, use K instead of
N, and provide an example for each record of an expanded record name, in
order to make sure that readers will correctly drop the brackets
characters.

Because NDPluginGather substitutes its instance number based on the
environment variable, properly annotate it as such. In this case, the
range is user-defined, and it is already documented in the description.

Author: henriquesimoes

docs/ADCore/NDArray.rst

@@ -465,13 +465,14 @@ loading ADBase.template.
   * - N.A.
     - N.A
     - r/o
-    - Size of each array dimension, extracted from the $(P)$(R)Dimensions and $(P)$(R)Dimensions_RBV
+    - Size of each array dimension K in [0..9], extracted from the $(P)$(R)Dimensions and $(P)$(R)Dimensions_RBV
       waveform records. Note that these are both longin record, i.e. readonly values using
       subarray records. In the future longout records may be added to write to the individual
       values in $(P)$(R)Dimensions.
     - N.A.
-    - $(P)$(R)ArraySize[N] N=0-9
-      , (P)$(R)ArraySize[N]_RBV
+    - $(P)$(R)ArraySize<K>, $(P)$(R)ArraySize<K>_RBV
+
+      E.g. $(P)$(R)ArraySize0_RBV
     - longin, longin
   * - NDArraySizeX
     - asynInt32

docs/ADCore/NDFileHDF5.rst

@@ -751,9 +751,11 @@ Parameters and Records
     - longout, longin
   * - asynInt32
     - r/w
-    - Size of the N'th extra dimension, for N in [3..9]
-    - HDF5_extraDimSize[N]
-    - $(P)$(R)ExtraDimSize[N], $(P)$(R)ExtraDimSize[N]_RBV
+    - Size of the K'th extra dimension, for K in [3..9]
+    - HDF5_extraDimSize<K>
+    - $(P)$(R)ExtraDimSize<K>, $(P)$(R)ExtraDimSize<K>_RBV
+
+      E.g. $(P)$(R)ExtraDimSize3_RBV
     - longout, longin
   * -
     -
@@ -784,9 +786,11 @@ Parameters and Records
     - stringout, stringin
   * - asynOctet
     - r/w
-    - Specify the NDAttribute name for the N'th index, for N in [3..9]
-    - HDF5_posNameDim[N]
-    - $(P)$(R)PosNameDim[N], $(P)$(R)PosNameDim[N]_RBV
+    - Specify the NDAttribute name for the K'th index, for K in [3..9]
+    - HDF5_posNameDim<K>
+    - $(P)$(R)PosNameDim<K>, $(P)$(R)PosNameDim<K>_RBV
+
+      E.g. $(P)$(R)PosNameDim5
     - stringout, stringin
   * -
     -
@@ -797,7 +801,7 @@ Parameters and Records
     - HDF5_posIndexDimN
     - $(P)$(R)PosIndexDimN, $(P)$(R)PosIndexDimN_RBV
     - stringout, stringin
-  * - asynOctet
+  * - asynOcte9
     - r/w
     - Specify the NDAttribute index for the X dimension
     - HDF5_posIndexDimX
@@ -811,9 +815,11 @@ Parameters and Records
     - stringout, stringin
   * - asynOctet
     - r/w
-    - Specify the NDAttribute index for the N'th dimension, for N in [3..9]
-    - HDF5_posIndexDim[N]
-    - $(P)$(R)PosIndexDim[N], $(P)$(R)PosIndexDim[N]_RBV
+    - Specify the NDAttribute index for the K'th dimension, for K in [3..9]
+    - HDF5_posIndexDim<K>
+    - $(P)$(R)PosIndexDim<K>, $(P)$(R)PosIndexDim<K>_RBV
+
+      E.g. $(P)$(R)PosIndexDim9_RBV
     - stringout, stringin
   * -
     -

docs/ADCore/NDPluginGather.rst

@@ -73,7 +73,7 @@ split into 2 lines, but these are just a single name, for example
       There can be more than one such input port. The maximum is number is specified in
       the NDGatherConfigure command in the startup script.
     - NDARRAY_PORT
-    - $(P)$(R)NDArrayPort_[N], (P)$(R)NDArrayPort_[N]_RBV
+    - $(P)$(R)NDArrayPort_$(N), (P)$(R)NDArrayPort_$(N)_RBV
     - stringout, stringin
   * - NDPluginDriver |br|
       ArrayAddr
@@ -84,7 +84,7 @@ split into 2 lines, but these are just a single name, for example
       in the NDArray driver. There can be more than one such input port. The maximum is
       number is specified in the NDGatherConfigure command in the startup script.
     - NDARRAY_ADDR
-    - $(P)$(R)NDArrayAddress_[N], $(P)$(R)NDArrayAddress_[N]_RBV
+    - $(P)$(R)NDArrayAddress_$(N), $(P)$(R)NDArrayAddress_$(N)_RBV
     - longout, longin
 
 Configuration