The YAML format has a couple of different forms for multi-line text
blocks which control allowed characters and handling of line-breaks.
Getting this wrong is a common review issue. Either a literal block is
used when there's no formatting needed or a folded/literal block is
not used when there is formatting to maintain.

Add some descriptions of the different forms to point folks to in
reviews.

Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
---
I have a prototype yamllint addition to check this for us. Not sure
if it will be upstreamable given something that works for us is quite
easier than supporting any possible YAML.

Digging into this more, I had not realized that plain style can support
paragraphs with a blank line nor that folded (">") style maintains
indented lines. That probably means we could use those 2 just about
everywhere. Or maybe it's just easier to say use ">" everywhere (or
everywhere with more than 1 line).
---
 .../devicetree/bindings/writing-schema.rst    | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
index 7e71cdd1d6de..eb8ced400c7e 100644
--- a/Documentation/devicetree/bindings/writing-schema.rst
+++ b/Documentation/devicetree/bindings/writing-schema.rst
@@ -43,6 +43,36 @@ description
   or device does, standards the device conforms to, and links to datasheets for
   more information.
 
+  The YAML format has several options for defining the formatting of the text
+  block. The options are controlled with indicator characters following the key
+  (e.g. "description: \|"). The minimum formatting needed for a block should be
+  used. The formatting controls can not only affect whether the YAML can be
+  parsed correctly, but are important when the text blocks are rendered to
+  another form. The options are as follows.
+
+  The default without any indicators is flowed, plain scalar style where single
+  line breaks and leading whitespace are stripped. Paragraphs are delimited by
+  blank lines (i.e. double line break). This style cannot contain ": " in it as
+  it will be interpretted as a key. Any " #" sequence will be interpretted as
+  a comment. There's other restrictions on characters as well. Most
+  restrictions are on what the first character can be.
+
+  The second style is folded which is indicated by ">" character. In addition
+  to maintaining line breaks on double line breaks, the folded style also
+  maintains leading whitespace beyond indentation of the first line. The line
+  breaks on indented lines are also maintained.
+
+  The third style is literal which is indicated by "\|" character. The literal
+  style maintains all line breaks and whitespace (beyond indentation of the
+  first line).
+
+  The above is not a complete description of YAML text blocks. More details on
+  multi-line YAML text blocks can be found online:
+
+  https://yaml-multiline.info/
+
+  https://www.yaml.info/learn/quote.html
+
 select
   Optional. A json-schema used to match nodes for applying the
   schema. By default, without 'select', nodes are matched against their possible
-- 
2.45.2

On Wed, Sep 18, 2024 at 02:51:30PM -0500, Rob Herring (Arm) wrote:
> The YAML format has a couple of different forms for multi-line text
> blocks which control allowed characters and handling of line-breaks.
> Getting this wrong is a common review issue. Either a literal block is
> used when there's no formatting needed or a folded/literal block is
> not used when there is formatting to maintain.
> 
> Add some descriptions of the different forms to point folks to in
> reviews.
> 
> Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
> ---

Reviewed-by: Krzysztof Kozlowski <krzk@kernel.org>

Best regards,
Krzysztof

On Wed, Sep 18, 2024 at 02:51:30PM -0500, Rob Herring (Arm) wrote:
> The YAML format has a couple of different forms for multi-line text
> blocks which control allowed characters and handling of line-breaks.
> Getting this wrong is a common review issue. Either a literal block is
> used when there's no formatting needed or a folded/literal block is
> not used when there is formatting to maintain.
> 
> Add some descriptions of the different forms to point folks to in
> reviews.

And mentioning the # stuff is good too, keep hitting that with the
commit descriptions in the riscv extension stuff. That said, not as if
people read documentation anyway...

Reviewed-by: Conor Dooley <conor.dooley@microchip.com>