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.

1 files changed, 15 insertions, 1 deletions

diff --git a/man/os-release.xml b/man/os-release.xml
index dd3c39f876..4acd1a9a57 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>