From 1d31c6fc86c09a2ed08e71a6bfae74bb1d7b116b Mon Sep 17 00:00:00 2001 From: "Rob Herring (Arm)" Date: Wed, 18 Sep 2024 14:51:30 -0500 Subject: [PATCH] dt-bindings: writing-schema: Add details on YAML text blocks 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. Reviewed-by: Conor Dooley Reviewed-by: Krzysztof Kozlowski Link: https://lore.kernel.org/r/20240918195130.2024205-2-robh@kernel.org Signed-off-by: Rob Herring (Arm) --- .../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