[skip changelog] Fully document library layouts in specification (#1458)

Arduino library authors may chose from multiple structures, each of which have different implications for the compilation
of the library source files. The specification explains this in a somewhat simplistic manner as "1.5 format" and
"1.0 format". That is sufficient for most, but does not provide a complete picture. Feedback indicated that more advanced
users were left wanting complete documentation, which is provided here.

The subject is not well suited for description via prose, so a chart and table are employed instead.

The chart is defined in the DOT graph description language.

Author: per1234

docs/img/library-layout.dot

@@ -0,0 +1,39 @@
+// See: https://www.graphviz.org/documentation/
+digraph {
+  // This generates library-layout.png using the following command:
+  // dot -Tsvg -olibrary-layout.svg library-layout.dot
+  graph [
+    splines=line
+  ]
+  node [
+    shape=box
+  ]
+
+  subgraph {
+    // This subgraph provides the labels on left margin
+    node [
+      margin="0.0,0.0"
+      shape=none
+      width=0.0
+    ]
+    "Metadata:" -> "Format:" -> "Structure:" -> "Layout:" [style=invis]
+  }
+
+  subgraph cluster1 {
+    peripheries=0
+    "library.properties" [height=1.0 margin="0.0,0.0" shape=diamond width=0.0]
+    "library.properties" -> "1.5" [label="yes"]
+    "library.properties" -> "1.0" [label="no"]
+    subgraph cluster2 {
+      peripheries=0
+      rank=same
+      "1.5"
+      "1.0"
+    }
+    "1.5" -> "src/"
+    "src/" [shape=diamond]
+    "src/" -> "recursive" [label=" yes"]
+    "src/" -> "flat" [label="no"]
+    "1.0" -> "flat"
+  }
+}

docs/img/library-layout.svg

@@ -163,6 +163,15 @@ only needs to run on Arduino IDE 1.5.x+, we recommend placing all source code in
 recursive compilation of nested source folders, its code must be in the src/ folder (since Arduino IDE 1.0.x doesn’t
 support recursive compilation, backwards compatibility wouldn’t be possible anyway).
 
+##### Library layout
+
+![Library layout](img/library-layout.svg)
+
+| Layout        | root compiled | `src` compiled | `utility` compiled |
+| ------------- | ------------- | -------------- | ------------------ |
+| **recursive** | no            | recursively    | no                 |
+| **flat**      | yes           | no             | yes                |
+
 #### Precompiled binaries
 
 The `precompiled` field of [library.properties](#libraryproperties-file-format) enables support for the use of