man: add specifiers section to directives index

keszybz · keszybz · commit 0d525a3e9366 · 2020-05-07T14:59:24.000+02:00
The hack with getparent().txt is not very pretty, but the whole
thing seems to work well enough. It is useful to figure out whihc
specifiers are supported where.
diff --git a/man/directives-template.xml b/man/directives-template.xml
@@ -135,6 +135,14 @@
     <variablelist id='miscellaneous' />
   </refsect1>
 
+  <refsect1>
+    <title>Specifiers</title>
+
+    <para>Short strings which are substituted in configuration directives.</para>
+
+    <variablelist id='specifiers' />
+  </refsect1>
+
   <refsect1>
     <title>Files and directories</title>
 
diff --git a/man/systemd.dnssd.xml b/man/systemd.dnssd.xml
@@ -75,7 +75,7 @@
             <para>An instance name of the network service as defined in the section 4.1.1 of <ulink
             url="https://tools.ietf.org/html/rfc6763">RFC 6763</ulink>, e.g. <literal>webserver</literal>.</para>
             <para>The option supports simple specifier expansion. The following expansions are understood:</para>
-            <table>
+            <table class='specifiers'>
               <title>Specifiers available</title>
               <tgroup cols='3' align='left' colsep='1' rowsep='1'>
                 <colspec colname="spec" />
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
@@ -1695,7 +1695,7 @@
     and resolvable for the setting to be valid. The following
     specifiers are understood:</para>
 
-    <table>
+    <table class='specifiers'>
       <title>Specifiers available in unit files</title>
       <tgroup cols='3' align='left' colsep='1' rowsep='1'>
         <colspec colname="spec" />
@@ -1710,7 +1710,8 @@
         </thead>
         <tbody>
           <row>
-            <!-- We do not use the common definition from standard-specifiers.xml here since it includes a reference onto our own man page, which would make the rendered version self-referential. -->
+            <!-- We do not use the common definition from standard-specifiers.xml here since it includes a
+                 reference onto our own man page, which would make the rendered version self-referential. -->
             <entry><literal>%a</literal></entry>
             <entry>Architecture</entry>
             <entry>A short string identifying the architecture of the local system. A string such as <constant>x86</constant>, <constant>x86-64</constant> or <constant>arm64</constant>. See the architectures defined for <varname>ConditionArchitecture=</varname> above for a full list.</entry>
@@ -1740,7 +1741,8 @@
 Note that this setting is <emphasis>not</emphasis> influenced by the <varname>User=</varname> setting configurable in the [Service] section of the service unit.</entry>
           </row>
           <row>
-            <!-- We do not use the common definition from standard-specifiers.xml here since we want a slightly more verbose explanation here, referring to the reload cycle. -->
+            <!-- We do not use the common definition from standard-specifiers.xml here since we want a
+                 slightly more verbose explanation here, referring to the reload cycle. -->
             <entry><literal>%H</literal></entry>
             <entry>Host name</entry>
             <entry>The hostname of the running system at the point in time the unit configuration is loaded.</entry>
diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml
@@ -237,7 +237,7 @@ r     -        500-900
     <para>Specifiers can be used in the "Name", "ID", "GECOS", "Home directory", and "Shell" fields.
     An unknown or unresolvable specifier is treated as invalid configuration.
     The following expansions are understood:</para>
-      <table>
+      <table class='specifiers'>
         <title>Specifiers available</title>
         <tgroup cols='3' align='left' colsep='1' rowsep='1'>
           <colspec colname="spec" />
diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml
@@ -618,7 +618,7 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
     <para>Specifiers can be used in the "path" and "argument" fields.
     An unknown or unresolvable specifier is treated as invalid configuration.
     The following expansions are understood:</para>
-      <table>
+      <table class='specifiers'>
         <title>Specifiers available</title>
         <tgroup cols='3' align='left' colsep='1' rowsep='1'>
           <colspec colname="spec" />
diff --git a/tools/make-directive-index.py b/tools/make-directive-index.py
@@ -87,6 +87,15 @@ def _extract_directives(directive_groups, formatting, page):
         storfile[name.text].append((pagename, section))
         formatting[name.text] = name
 
+    storfile = directive_groups['specifiers']
+    for name in t.iterfind(".//table[@class='specifiers']//entry/literal"):
+        if name.text[0] != '%' or name.getparent().text is not None:
+            continue
+        if name.attrib.get('index') == 'false':
+            continue
+        storfile[name.text].append((pagename, section))
+        formatting[name.text] = name
+
 def _make_section(template, name, directives, formatting):
     varlist = template.find(".//*[@id='{}']".format(name))
     for varname, manpages in sorted(directives.items()):
