Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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 <conor.dooley@microchip.com>
Reviewed-by: Krzysztof Kozlowski <krzk@kernel.org>
Link: https://lore.kernel.org/r/20240918195130.2024205-2-robh@kernel.org
Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
+30
+30
Documentation/devicetree/bindings/writing-schema.rst
+30
Documentation/devicetree/bindings/writing-schema.rst
···
43
43
or device does, standards the device conforms to, and links to datasheets for
44
44
more information.
45
45
46
+
The YAML format has several options for defining the formatting of the text
47
+
block. The options are controlled with indicator characters following the key
48
+
(e.g. "description: \|"). The minimum formatting needed for a block should be
49
+
used. The formatting controls can not only affect whether the YAML can be
50
+
parsed correctly, but are important when the text blocks are rendered to
51
+
another form. The options are as follows.
52
+
53
+
The default without any indicators is flowed, plain scalar style where single
54
+
line breaks and leading whitespace are stripped. Paragraphs are delimited by
55
+
blank lines (i.e. double line break). This style cannot contain ": " in it as
56
+
it will be interpretted as a key. Any " #" sequence will be interpretted as
57
+
a comment. There's other restrictions on characters as well. Most
58
+
restrictions are on what the first character can be.
59
+
60
+
The second style is folded which is indicated by ">" character. In addition
61
+
to maintaining line breaks on double line breaks, the folded style also
62
+
maintains leading whitespace beyond indentation of the first line. The line
63
+
breaks on indented lines are also maintained.
64
+
65
+
The third style is literal which is indicated by "\|" character. The literal
66
+
style maintains all line breaks and whitespace (beyond indentation of the
67
+
first line).
68
+
69
+
The above is not a complete description of YAML text blocks. More details on
70
+
multi-line YAML text blocks can be found online:
71
+
72
+
https://yaml-multiline.info/
73
+
74
+
https://www.yaml.info/learn/quote.html
75
+
46
76
select
47
77
Optional. A json-schema used to match nodes for applying the
48
78
schema. By default, without 'select', nodes are matched against their possible