mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2024-11-21 19:46:16 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

dt-bindings: writing-schema: Add details on YAML text blocks

Browse Source 
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>
This commit is contained in:
Rob Herring (Arm) 2024-09-18 14:51:30 -05:00
parent 29bf3116cf
commit 1d31c6fc86
1 changed files with 30 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
Documentation/devicetree/bindings/writing-schema.rst
View File

@ -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