From e839ebe5511028f6032ae53ebb43601c1f4624be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Thu, 20 May 2021 19:47:55 +0200
Subject: [PATCH] man: add an example how to correctly read os-release in shell

This is not entirely obvious.

The logic of how to interpret the fields applies in any language, so drop the
pointless mention of C or shell.
---
 man/check-os-release.sh | 10 ++++++++++
 man/os-release.xml      | 21 ++++++++++++++++-----
 2 files changed, 26 insertions(+), 5 deletions(-)
 create mode 100644 man/check-os-release.sh

diff --git a/man/check-os-release.sh b/man/check-os-release.sh
new file mode 100644
index 00000000000..2a1a0579283
--- /dev/null
+++ b/man/check-os-release.sh
@@ -0,0 +1,10 @@
+#!/bin/sh -eu
+
+test -e /etc/os-release && os_release='/etc/os-release' || os_release='/usr/lib/os-release'
+. "${os_release}"
+
+echo "Running on ${PRETTY_NAME:-Linux}"
+
+if [ "${ID:-linux}" = "debian" ] || [ "${ID_LIKE:-}" = "debian" ]; then
+    echo "Looks like Debian!"
+fi
diff --git a/man/os-release.xml b/man/os-release.xml
index a5b2437632c..36e5bed62e3 100644
--- a/man/os-release.xml
+++ b/man/os-release.xml
@@ -3,7 +3,7 @@
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 
-<refentry id="os-release">
+<refentry id="os-release" xmlns:xi="http://www.w3.org/2001/XInclude">
   <refentryinfo>
     <title>os-release</title>
     <productname>systemd</productname>
@@ -363,8 +363,8 @@
     <refsect2>
       <title>Notes</title>
 
-      <para>If you are reading this file from C code or a shell script to determine the OS or a specific
-      version of it, use the <varname>ID</varname> and <varname>VERSION_ID</varname> fields, possibly with
+      <para>If you are using this file to determine the OS or a specific version of it, use the
+      <varname>ID</varname> and <varname>VERSION_ID</varname> fields, possibly with
       <varname>ID_LIKE</varname> as fallback for <varname>ID</varname>. When looking for an OS identification
       string for presentation to the user use the <varname>PRETTY_NAME</varname> field.</para>
 
@@ -387,9 +387,12 @@
   </refsect1>
 
   <refsect1>
-    <title>Example</title>
+    <title>Examples</title>
 
-    <programlisting>NAME=Fedora
+    <example>
+      <title><filename>os-release</filename> file for Fedora Workstation</title>
+
+      <programlisting>NAME=Fedora
 VERSION="32 (Workstation Edition)"
 ID=fedora
 VERSION_ID=32
@@ -408,6 +411,14 @@ REDHAT_SUPPORT_PRODUCT_VERSION=32
 PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
 VARIANT="Workstation Edition"
 VARIANT_ID=workstation</programlisting>
+    </example>
+
+    <example>
+      <title>Reading <filename>os-release</filename> in
+      <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry></title>
+
+      <programlisting><xi:include href="check-os-release.sh" parse="text" /></programlisting>
+    </example>
   </refsect1>
 
   <refsect1>