From ee6fd6a50922d2b27c97084e1c3f9872d495c273 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Mon, 28 Feb 2022 09:47:28 +0100
Subject: [PATCH] man: recommend built-in platform.freedesktop_os_release() in
 our page

Python gained support for reading os-release, let's advertise it a bit more.
Our open-coded example is still useful, but let's not suggest it as the
default implementation.

I added quotes around the printed string because it looks a bit better
this way.
---
 man/check-os-release-simple.py | 12 ++++++++++++
 man/check-os-release.py        |  2 +-
 man/os-release.xml             | 16 +++++++++++++++-
 3 files changed, 28 insertions(+), 2 deletions(-)
 create mode 100644 man/check-os-release-simple.py

diff --git a/man/check-os-release-simple.py b/man/check-os-release-simple.py
new file mode 100644
index 00000000000..738b1fd8605
--- /dev/null
+++ b/man/check-os-release-simple.py
@@ -0,0 +1,12 @@
+#!/usr/bin/python
+# SPDX-License-Identifier: CC0-1.0
+
+import platform
+os_release = platform.freedesktop_os_release()
+
+pretty_name = os_release.get('PRETTY_NAME', 'Linux')
+print(f'Running on {pretty_name!r}')
+
+if 'fedora' in [os_release.get('ID', 'linux'),
+                *os_release.get('ID_LIKE', '').split()]:
+    print('Looks like Fedora!')
diff --git a/man/check-os-release.py b/man/check-os-release.py
index dbac79fd700..91a5494b4a1 100644
--- a/man/check-os-release.py
+++ b/man/check-os-release.py
@@ -29,7 +29,7 @@ def read_os_release():
 os_release = dict(read_os_release())
 
 pretty_name = os_release.get('PRETTY_NAME', 'Linux')
-print(f'Running on {pretty_name}')
+print(f'Running on {pretty_name!r}')
 
 if 'debian' in [os_release.get('ID', 'linux'),
                 *os_release.get('ID_LIKE', '').split()]:
diff --git a/man/os-release.xml b/man/os-release.xml
index dd3c39f8762..4acd1a9a575 100644
--- a/man/os-release.xml
+++ b/man/os-release.xml
@@ -502,9 +502,23 @@ VERSION_ID=32</programlisting>
 
     <example>
       <title>Reading <filename>os-release</filename> in
-      <citerefentry><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry></title>
+      <citerefentry><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (versions &gt;= 3.10)</title>
+
+      <programlisting><xi:include href="check-os-release-simple.py" parse="text" /></programlisting>
+
+      <para>See docs for <ulink url="https://docs.python.org/3/library/platform.html#platform.freedesktop_os_release">
+      <function>platform.freedesktop_os_release</function></ulink> for more details.
+      </para>
+    </example>
+
+    <example>
+      <title>Reading <filename>os-release</filename> in
+      <citerefentry><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (any version)</title>
 
       <programlisting><xi:include href="check-os-release.py" parse="text" /></programlisting>
+
+      <para>Note that the above version that uses the built-in implementation is preferred
+      in most cases, and the open-coded version here is provided for reference.</para>
     </example>
 
   </refsect1>