- <filename>os-release</filename> is a
- newline-separated list of environment-like
- shell-compatible variable assignments. It is possible
- to source the configuration from shell scripts,
- however, beyond mere variable assignments no shell
- features are supported, allowing applications to read
- the file without implementing a shell compatible
- execution engine.</para>
+ <filename>os-release</filename> is a newline-separated
+ list of environment-like shell-compatible variable
+ assignments. It is possible to source the
+ configuration from shell scripts, however, beyond mere
+ variable assignments no shell features are supported
+ (this means variable expansion is explicitly not
+ supported), allowing applications to read the file
+ without implementing a shell compatible execution
+ engine. Variable assignment values should be enclosed
+ in double or single quotes if they include spaces,
+ semicolons or other special characters outside of A-Z,
+ a-z, 0-9. All strings should be in UTF-8 format, and
+ non-printable characters should not be used. If double
+ or single quotes or backslashes are to be used within
+ variable assignments they should be escaped with
+ backslashes, following shell style. It is not
+ supported to concatenate multiple individually quoted
+ strings. Lines beginning with "#" shall be ignored as
+ comments.</para>