Misc improvements.

Author: dhebbeker

doc/decisions/dr-004.md

@@ -3,7 +3,7 @@
 ## Context
 
 Currently we violate the requirement to use libraries and frameworks only through adapters, as it is required by the objectives of the software architecture (see 
-[relevant section in Software Architecture](<\ref flexible_structure> "relevant section in Software Architecture"):
+[relevant section in Software Architecture](<\ref flexible_structure> "relevant section in Software Architecture")):
 We currently use an implementation of the [ArduinoCore-API][ACA] (ACA) as a hardware abstraction layer (HAL) from outside of the adapters layer.
 More specifically we use an implementation of the ACA from Espressif coined for ESP32s.
 
@@ -26,7 +26,7 @@ Those adapters would reside in the
 
 #### Option 1a)
 
-For an object oriented (OO) variant, defining an interface and inheriting from it, it would require to:
+For an object oriented (OO) variant, defining an interface and inheriting from it would require to:
 
 - define one or several interfaces inside the
   [board adapters package](<\ref board_adapters> "board adapters package")
@@ -70,7 +70,7 @@ Factories are not necessary because this approach does not rely on objects.
 #### Option 1c)
 
 A hybrid approach (OO and free functions) is also possible.
-This would fit well to the [ACA][] as is also consists of classes and free functions.
+This would fit well to the ACA as is also consists of classes and free functions.
 
 The steps required would be a mixture of those of options 1a) and 1b).
 
@@ -81,10 +81,10 @@ Change the current guidelines such that the direct dependency to 3rd party HALs
 
 This approach eliminates the requirement to define 3rd party adapters to the HAL.
 
-In order to be able to test code depending on the [ACA][], the 3rd party interface needs to be stubbed.
-*For vanilla [ACA][], stubbing the proprietary interface can be greatly simplified by using [ArduinoFake][].*
-We use an [implementation of the Arduino Core API (ACA) specific for ESP32s by Espressif](https://github.com/espressif/arduino-esp32/) which extends the [ACA][].
-Following the approach of this option, to directly use [ACA][] and [ArduinoFake][] for testing, we would need to deal with the extensions separately.
+In order to be able to test code depending on the ACA, the 3rd party interface needs to be stubbed.
+*For vanilla ACA, stubbing the proprietary interface can be greatly simplified by using [ArduinoFake][].*
+We use an [implementation of the Arduino Core API (ACA) specific for ESP32s by Espressif](https://github.com/espressif/arduino-esp32/) which extends the ACA.
+Following the approach of this option, to directly use ACA and ArduinoFake for testing, we would need to deal with the extensions separately.
 The following variants of this option, specifies different methods to cope with the extensions.
 
 [ArduinoFake]: https://platformio.org/lib/show/1689/ArduinoFake "ArduinoFake in PlaftormIO's registry"
@@ -93,14 +93,14 @@ The following variants of this option, specifies different methods to cope with
 
 Instead of directly using a modified Arduino interface (for example for a specific `class`), we use an adapter.
 The adapters would be integrated just as for option 1.
-But compared to option 1 this only needs to be done for those smallest indivisible interfaces which are not compatible to the vanilla [ACA][].
+But compared to option 1 this only needs to be done for those smallest indivisible interfaces which are not compatible to the vanilla ACA.
 
 #### Option 2b)
 
 At those places in the source code where extensions are used, we introduce conditionally compiled sections.
-One section uses the modified version of the [ACA][], necessary for the productive code.
+One section uses the modified version of the ACA, necessary for the productive code.
 The alternative section is instead used when compiling for native tests.
-It uses the vanilla [ACA][] which can be simply stubbed using [ArduinoFake][].
+It uses the vanilla ACA which can be simply stubbed using ArduinoFake.
 
 The selection of conditionally compiled sections is done using `constexpr if`, where possible.
 Else the C preprocessor (CPP) is used for conditional inclusion (`#if`, ...).
@@ -175,5 +175,5 @@ And more specifically for testing on native environments, use:
 
 > **Option 2b):** Where the ACA is used it is allowed to add small conditionally compiled sections for tests in order to cope with deviations of the ACA used in productive code from the vanilla ACA.
 
-The latter relaxation is in order to facilitate the use of [ArduinoFake][] to stub the HAL's interface.
+The latter relaxation is in order to facilitate the use of ArduinoFake to stub the HAL's interface.