doc: style edits and fixes to guides (#25461)

* doc: style edits and fixes to guides

Edited the nRF Connect platform docs and the building guide for style.
Fixed several linking issues.

Signed-off-by: Grzegorz Ferenc <Grzegorz.Ferenc@nordicsemi.no>

* Restyled by prettier-markdown

---------

Signed-off-by: Grzegorz Ferenc <Grzegorz.Ferenc@nordicsemi.no>
Co-authored-by: Restyled.io <commits@restyled.io>

Author: 2 people

docs/guides/BUILDING.md

@@ -1,8 +1,21 @@
 # Access Control Guide
 
-All Interaction Model operations (read attribute, write attribute, invoke
-command, read event) are governed by access control, and will be denied (status
-0x7E Access Denied) if sufficient privilege for the operation is not obtained.
+All Interaction Model operations in Matter must be verified by the the Access
+Control mechanism.
+
+Whenever a client device and a server device want to interact with one another
+by reading (or subscribing) attributes or events, writing attributes, or
+invoking commands, the Access Control mechanism must verify that the client has
+sufficient privileges to perform the operation on the server device.
+
+If no sufficient privilege is obtained, the operation cannot take place and it
+is denied (status `0x7E Access Denied`).
+
+This guide describes how the Access Control mechanism works and how it is
+implemented, and provides examples of Access Control Lists (ACLs) for different
+use cases.
+
+<hr>
 
 ## Overview
 
@@ -24,82 +37,89 @@ node. It is these ACLs that govern which Interaction Model operations are
 allowed or denied on that server node, for subjects on the fabric, via CASE and
 group messaging.
 
-## ACLs
+<hr>
 
-ACLs are fabric-scoped data structures with the following fields:
+## Access Control Lists
 
--   Privilege
--   AuthMode
--   Subjects
--   Targets
+Access Control Lists (ACLs) are fabric-scoped data structures with the following
+fields:
 
-### Privilege
+-   `Privilege`
+-   `AuthMode`
+-   `Subjects`
+-   `Targets`
 
-Privileges are:
+### Privilege field
+
+The `Privilege` can be of the following types:
 
 -   View
 -   Operate
 -   Manage
 -   Administer
 
-An additional `ProxyView` privilege is not yet supported in the Matter SDK.
+> **Note:** An additional `ProxyView` privilege is not yet supported in the
+> Matter SDK.
 
 By default, the `View` privilege is required to read attributes or events, and
 the `Operate` privilege is required to write attributes or invoke commands.
 
-However, clusters may require stricter privileges for certain operations on
-certain endpoints. For example, the Access Control Cluster requires the
-`Administer` privilege for all its operations.
+Clusters may also require stricter privileges for certain operations on certain
+endpoints. For example, the Access Control Cluster requires the `Administer`
+privilege for all its operations.
 
 If applicable, the ACL grants the privilege, and all less strict privileges
 subsumed by it. Therefore an ACL for `Manage` privilege will work for operations
 which require `Operate` or `View` privilege (but not `Administer` privilege).
 
-### AuthMode
+### AuthMode field
 
-Authentication modes are:
+The `AuthMode`, that is authentication modes, can be as follow:
 
 -   CASE
 -   Group
 
 The ACL applies only to subjects using that authentication mode.
 
-### Subjects
+### Subjects field
 
-Subjects is a list containing zero, one, or more subject identifiers, which are:
+The `Subjects` field is a list containing zero, one, or more subject
+identifiers, which are:
 
--   Node ID for CASE auth mode
--   Group ID for Group auth mode
+-   Node ID for CASE `AuthMode`
+-   Group ID for Group `AuthMode`
 
 A CASE subject may be a CAT, which has its own tag and version mechanism.
 
 The ACL applies only to the listed subjects; if no subjects are listed, the ACL
 applies to any subjects using the authentication mode.
 
-### Targets
+### Targets field
 
-Targets is a list containing zero, one, or more structured entries with fields:
+The `Targets` field is a list containing zero, one, or more structured entries
+with fields:
 
 -   Cluster
 -   Endpoint
 -   DeviceType
 
 All fields are nullable, but at least one must be present, and the endpoint and
 device type fields are mutually exclusive (only one of those two may be
-present).
-
-If cluster is present, the ACL is targeted to just that cluster.
-
-If endpoint is present, the ACL is targeted to just that endpoint.
+present):
 
-If device type is present, the ACL is targeted to just endpoints which contain
-that device type (as reported by the Descriptor Cluster).
+-   If cluster is present, the ACL is targeted to just that cluster.
+-   If endpoint is present, the ACL is targeted to just that endpoint.
+-   If device type is present, the ACL is targeted to just endpoints which
+    contain that device type (as reported by the Descriptor Cluster).
 
-Specifying device type in targets is not yet supported in the Matter SDK.
+> **Note:** Specifying device type in targets is not yet supported in the Matter
+> SDK.
 
 The ACL applies only to the listed targets; if no targets are listed, the ACL
 applies to any targets on the server node.
 
+<hr>
+
 ## Limitations and Restrictions
 
 The Matter Specification states that a Matter implementation must support at
@@ -120,8 +140,12 @@ can be configured globally in `CHIPConfig.h` or per-app in
 -   CHIP_CONFIG_EXAMPLE_ACCESS_CONTROL_MAX_SUBJECTS_PER_ENTRY
 -   CHIP_CONFIG_EXAMPLE_ACCESS_CONTROL_MAX_TARGETS_PER_ENTRY
 
+<hr>
+
 ## Case Studies
 
+This section provides use case examples for different ACL scenarios.
+
 ### Single Administrator
 
 A single controller commissions a server node, providing its own CASE node ID
@@ -174,17 +198,22 @@ Members of groups 123 and 456 are granted `Operate` privilege for the on/off
 cluster on any endpoint, any cluster on endpoint 1, and the level control
 cluster on endpoint 2.
 
-## Managing ACLs Using Chip-Tool
+<hr>
+
+## Managing ACLs using CHIP-Tool
 
 ### Usage
 
+The following sections describe the requirements for managing ACLs using the
+CHIP-Tool.
+
 #### Entire List
 
 The Access Control Cluster's `ACL` attribute is a list.
 
-Currently, list operations for single entries (append, update, delete) are not
-yet supported in the Matter SDK, so the entire list must be written to the
-attribute to change any ACL.
+> **Note:** Currently, list operations for single entries (append, update,
+> delete) are not yet supported in the Matter SDK, so the entire list must be
+> written to the attribute to change any ACL.
 
 The write operation may employ multiple messages, making it unreliable. In any
 case, ACLs are updated as they are processed, and take effect immediately.
@@ -215,38 +244,45 @@ When reading ACLs, the proper fabric index is shown.
 
 The tool requires numerical values for enums and identifiers.
 
-The privileges are:
+-   Privilege values:
 
--   View: 1
--   Operate: 3
--   Manage: 4
--   Administer: 5
+    -   View: 1
+    -   Operate: 3
+    -   Manage: 4
+    -   Administer: 5
 
-The authentication modes are:
+-   AuthMode values:
 
--   CASE: 2
--   Group: 3
+    -   CASE: 2
+    -   Group: 3
 
-Some typical clusters:
+-   Values for some typical clusters:
 
--   On/Off: 6
--   Level Control: 8
--   Descriptor: 29
--   Binding: 30
--   Access Control: 31
--   Basic: 40
+    -   On/Off: 6
+    -   Level Control: 8
+    -   Descriptor: 29
+    -   Binding: 30
+    -   Access Control: 31
+    -   Basic: 40
 
 ### Examples
 
-#### Automatically Installed ACL
+This section provides examples of commands and ACL output for different
+operations with the CHIP-Tool.
 
-After commissioning with chip-tool, assuming `CaseAdminNode` is 112233, the
-automatically installed ACL is:
+#### Verification of the Automatically Installed ACL
+
+During commissioning with the CHIP-Tool, an ACL that assigns Administer rights
+to the commissioner is automatically installed on the commissionee. This can be
+verified using the following command:
 
 ```
 out/debug/standalone/chip-tool accesscontrol read acl 1 0
 ```
 
+Assuming the `CaseAdminNode` value is `112233`, the ACL command output for this
+case is the following:
+
 ```
 Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000 DataVersion: 2578401031
   ACL: 1 entries
@@ -262,10 +298,15 @@ Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000 DataVersion: 2578401031
 
 #### Installing a CASE ACL
 
+The following command example requests the installation of a CASE ACL through a
+write interaction:
+
 ```
 out/debug/standalone/chip-tool accesscontrol write acl '[{"fabricIndex": 0, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 0, "privilege": 1, "authMode": 2, "subjects": [4444, 5555, 6666], "targets": null}]' 1 0
 ```
 
+The resulting ACL command output for this case can look like the following one:
+
 ```
 Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000 DataVersion: 2578401034
   ACL: 2 entries
@@ -291,10 +332,15 @@ Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000 DataVersion: 2578401034
 
 #### Installing a Group ACL
 
+The following command example requests the installation of a Group ACL through a
+write interaction:
+
 ```
 out/debug/standalone/chip-tool accesscontrol write acl '[{"fabricIndex": 0, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 0, "privilege": 1, "authMode": 2, "subjects": [4444, 5555, 6666], "targets": null}, {"fabricIndex": 0, "privilege": 3, "authMode": 3, "subjects": [123, 456], "targets": [{"cluster": 6, "endpoint": null, "deviceType": null}, {"cluster": null, "endpoint": 1, "deviceType": null}, {"cluster": 8, "endpoint": 2, "deviceType": null}]}]' 1 0
 ```
 
+The resulting ACL command output for this case can look like the following one:
+
 ```
 Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000DataVersion: 2578401041
   ACL: 3 entries
@@ -342,22 +388,28 @@ Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000DataVersion: 2578401041
      }
 ```
 
-## Managing ACLs Using Chip-Repl
+<hr>
+
+## Managing ACLs Using Chip-repl
 
 ### Usage
 
+This section provides examples of commands and ACL output for different
+operations with the CHIP-repl.
+
 #### Entire List
 
-See the important notes in the chip-tool section, as they also apply to
-chip-repl.
+See the important notes in the
+[Managing ACLs using CHIP-Tool](#managing-acls-using-chip-tool) section, as they
+also apply to the CHIP-repl.
 
 ### Null Fields
 
 Null fields may be omitted.
 
-OK: `Target(cluster=6, endpoint=Null, deviceType=Null)`
-
-Also OK: `Target(cluster=6)`
+This means that the following entry is acceptable:
+`Target(cluster=6, endpoint=Null, deviceType=Null)`. Just as the following one:
+`Target(cluster=6)`.
 
 The above assumes Target and Null are defined at global scope, which is not
 normally the case.
@@ -366,15 +418,15 @@ normally the case.
 
 The `ACL` attribute is fabric-scoped, so each ACL has a fabric index.
 
-The REPL ignores it when performing the actual write. Because null fields can be
-omitted, simply do not provide it when writing ACLs.
+The CHIP-repl ignores it when performing the actual write. Because null fields
+can be omitted, simply do not provide it when writing ACLs.
 
 When reading ACLs, the proper fabric index is shown.
 
 #### Enums and Identifiers
 
-The REPL accepts numerical values for enums and identifiers, but it also accepts
-strongly typed values:
+The CHIP-repl accepts numerical values for enums and identifiers, but it also
+accepts strongly typed values:
 
 The privileges are:
 
@@ -399,6 +451,9 @@ Some typical clusters:
 
 ### Examples
 
+This section provides examples of commands and ACL output for different
+operations with the CHIP-repl.
+
 #### Automatically Installed ACL
 
 After commissioning with chip-repl, assuming `CaseAdminNode` is 1, the