man: keyfile: improve explanation of the format and routes properties

https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1722

man/nm-settings-keyfile.xsl

@@ -54,22 +54,31 @@
       <refsect1 id='file_format'><title>File Format</title>
         <para>
           The <emphasis>keyfile</emphasis> config format is a simple .ini-style
-          format. It consists of sections (groups) of key-value pairs. Each section
-          corresponds to a setting name as described in the settings specification
-          (<citerefentry><refentrytitle>nm-settings-nmcli</refentrytitle>
-          <manvolnum>5</manvolnum></citerefentry>). Each configuration key/value
-          pair in the section is one of the properties listed in the settings
-          specification. The majority of properties of the specification is written
-          in the same format into the <emphasis>keyfile</emphasis> too. However
-          some values are inconvenient for people to use. These are stored in the
-          files in more readable ways. These properties are described below.
-          An example could be IP addresses that are not written as integer arrays,
-          but more reasonably as "1.2.3.4/12 1.2.3.254".
+          format. It consists of sections (groups) of key-value pairs.
           More information of the generic key file format can be found at
           <ulink url="https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html#glib-Key-value-file-parser.description">
           GLib key file format</ulink> (Lines beginning with a '#' are comments,
           lists are separated by character <literal>;</literal> etc.).
         </para>
+        <para>
+          Each section corresponds to a setting name as described in the settings
+          specification (<citerefentry><refentrytitle>nm-settings-nmcli</refentrytitle>
+          <manvolnum>5</manvolnum></citerefentry>). Each key/value pair in a
+          section is one of the properties from the specification.
+        </para>
+        <para>
+          The majority of properties are written in the same format as the
+          specification into the <emphasis>keyfile</emphasis>. However, some
+          values are inconvenient for people to use so they are stored in the
+          <emphasis>keyfile</emphasis> in more readable ways. These properties
+          that differ from the specification are described below.
+          An example could be IP addresses that are not written as integer arrays,
+          but more reasonably as "1.2.3.4/12 1.2.3.254".
+          Also, some lists of complex values (addresses, routes, routing-rules),
+          instead of using a semicolon separated list, use one key-value pair
+          per list element, with the key being the singular of the property name
+          followed by the numeric index (i.e address1, address2, ...).
+        </para>
         <para>
           Users can create or modify the <emphasis>keyfile</emphasis> connection files
           manually, even if that is not the recommended way of managing the profiles.

src/libnm-core-impl/nm-setting-ip4-config.c

@@ -703,6 +703,15 @@ nm_setting_ip4_config_class_init(NMSettingIP4ConfigClass *klass)
      *   route2=7.7.0.0/16
      * ---end---
      */
+    /* ---keyfile---
+     * property: routes (attributes)
+     * variable: route1_options, route2_options, ...
+     * format: key=val[,key=val...]
+     * description: Attributes defined for the routes, if any. The supported
+     *   attributes are explained in ipv4.routes entry in `man nm-settings-nmcli`.
+     * example: route1_options=mtu=1000,onlink=true
+     * ---end---
+     */
     /* ---ifcfg-rh---
      * property: routes
      * variable: ADDRESS1, NETMASK1, GATEWAY1, METRIC1, OPTIONS1, ...
@@ -711,6 +720,16 @@ nm_setting_ip4_config_class_init(NMSettingIP4ConfigClass *klass)
      * ---end---
      */
 
+    /* ---keyfile---
+     * property: routing-rules
+     * variable: routing-rule1, routing-rule2, ...
+     * format: routing rule string
+     * description: Routing rules as defined with `ip rule add`, but with mandatory
+     *    fixed priority.
+     * example: routing-rule1=priority 5 from 192.167.4.0/24 table 45
+     * ---end---
+     */
+
     /* ---ifcfg-rh---
      * property: ignore-auto-routes
      * variable: PEERROUTES(+)

src/libnm-core-impl/nm-setting-ip6-config.c

@@ -714,6 +714,15 @@ nm_setting_ip6_config_class_init(NMSettingIP6ConfigClass *klass)
      * example: route1=2001:4860:4860::/64,2620:52:0:2219:222:68ff:fe11:5403
      * ---end---
      */
+    /* ---keyfile---
+     * property: routes (attributes)
+     * variable: route1_options, route2_options, ...
+     * format: key=val[,key=val...]
+     * description: Attributes defined for the routes, if any. The supported
+     *   attributes are explained in ipv6.routes entry in `man nm-settings-nmcli`.
+     * example: route1_options=mtu=1000,onlink=true
+     * ---end---
+     */
     /* ---ifcfg-rh---
      * property: routes
      * variable: (none)
@@ -722,6 +731,16 @@ nm_setting_ip6_config_class_init(NMSettingIP6ConfigClass *klass)
      * ---end---
      */
 
+    /* ---keyfile---
+     * property: routing-rules
+     * variable: routing-rule1, routing-rule2, ...
+     * format: routing rule string
+     * description: Routing rules as defined with `ip rule add`, but with mandatory
+     *    fixed priority.
+     * example: routing-rule1=priority 5 from 2001:4860:4860::/64 table 45
+     * ---end---
+     */
+
     /* ---ifcfg-rh---
      * property: ignore-auto-routes
      * variable: IPV6_PEERROUTES(+)