chiark / gitweb /
man: extend systemd.directives(7) to all manual pages
authorZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Sat, 26 Jan 2013 15:47:16 +0000 (10:47 -0500)
committerZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Sat, 26 Jan 2013 16:36:53 +0000 (11:36 -0500)
New sections are added: PAM options, crypttab options, commandline
options, miscellaneous. The last category will be used for all
untagged <varname> elements.

Commandline options sections is meant to be a developer tool: when
adding an option it is sometimes useful to be able to check if
similarly named options exist elsewhere.

34 files changed:
Makefile.am
make-directive-index.py
man/crypttab.xml
man/journalctl.xml
man/kernel-command-line.xml
man/localectl.xml
man/loginctl.xml
man/pam_systemd.xml
man/runlevel.xml
man/sd_listen_fds.xml
man/sd_notify.xml
man/systemctl.xml
man/systemd-bootchart.xml
man/systemd-cryptsetup-generator.xml
man/systemd-fsck@.service.xml
man/systemd-fstab-generator.xml
man/systemd-journald.service.xml
man/systemd-modules-load.service.xml
man/systemd-quotacheck.service.xml
man/systemd-udevd.service.xml
man/systemd-vconsole-setup.service.xml
man/systemd.automount.xml
man/systemd.exec.xml
man/systemd.kill.xml
man/systemd.mount.xml
man/systemd.path.xml
man/systemd.service.xml
man/systemd.socket.xml
man/systemd.swap.xml
man/systemd.timer.xml
man/systemd.unit.xml
man/systemd.xml
man/timedatectl.xml
man/udev.xml

index f362b53..9c92bff 100644 (file)
@@ -767,31 +767,12 @@ MANPAGES += \
        man/systemd.index.7 \
        man/systemd.directives.7
 
-XML_DIRECTIVE_FILES = \
-       man/systemd.xml \
-       man/systemd.unit.xml \
-       man/systemd.service.xml \
-       man/systemd.socket.xml \
-       man/systemd.mount.xml \
-       man/systemd.automount.xml \
-       man/systemd.swap.xml \
-       man/systemd.target.xml \
-       man/systemd.path.xml \
-       man/systemd.timer.xml \
-       man/systemd.snapshot.xml \
-       man/systemd.exec.xml \
-       man/systemd.kill.xml \
-       man/systemd.device.xml \
-       man/systemd.conf.xml \
-       man/systemd.journal-fields.xml \
-       man/systemd.time.xml \
-       man/bootchart.conf.xml
-
-man/systemd.index.xml: make-man-index.py $(filter-out man/systemd.index.xml,$(XML_FILES))
+NON_INDEX_XML_FILES = $(filter-out man/systemd.index.xml,$(XML_FILES))
+man/systemd.index.xml: make-man-index.py $(NON_INDEX_XML_FILES)
        $(AM_V_at)$(MKDIR_P) $(dir $@)
        $(AM_V_GEN)$(PYTHON) $^ > $@
 
-man/systemd.directives.xml: make-directive-index.py $(XML_DIRECTIVE_FILES)
+man/systemd.directives.xml: make-directive-index.py $(filter-out man/systemd.directives.xml,$(NON_INDEX_XML_FILES))
        $(AM_V_at)$(MKDIR_P) $(dir $@)
        $(AM_V_GEN)$(PYTHON) $^ > $@
 
index 48d830e..29c594c 100755 (executable)
@@ -2,7 +2,7 @@
 #
 #  This file is part of systemd.
 #
-#  Copyright 2012 Zbigniew Jędrzejewski-Szmek
+#  Copyright 2012-2013 Zbigniew Jędrzejewski-Szmek
 #
 #  systemd is free software; you can redistribute it and/or modify it
 #  under the terms of the GNU Lesser General Public License as published by
@@ -20,6 +20,7 @@
 import sys
 import collections
 import xml.etree.ElementTree as tree
+import re
 
 TEMPLATE = '''\
 <refentry id="systemd.directives">
@@ -58,27 +59,19 @@ TEMPLATE = '''\
         </refsect1>
 
         <refsect1>
-                <title>System manager directives</title>
-
-                <para>Directives for configuring the behaviour of the
-                systemd process.</para>
-
-                <variablelist id='systemd-directives' />
-        </refsect1>
-
-        <refsect1>
                 <title>Options on the kernel command line</title>
 
                 <para>Kernel boot options for configuring the behaviour of the
                 systemd process.</para>
 
-                <variablelist id='kernel-commandline-directives' />
+                <variablelist id='kernel-commandline-options' />
         </refsect1>
 
         <refsect1>
                 <title>Environment variables</title>
 
-                <para>Environment variables understood by the systemd process.</para>
+                <para>Environment variables understood by the systemd
+                manager and other programs.</para>
 
                 <variablelist id='environment-variables' />
         </refsect1>
@@ -93,15 +86,40 @@ TEMPLATE = '''\
         </refsect1>
 
         <refsect1>
-                <title>Journal directives</title>
+                <title>Journal fields</title>
 
-                <para>Directives for configuring the behaviour of the
-                journald process.</para>
+                <para>Fields in the journal events with a well known meaning.</para>
 
                 <variablelist id='journal-directives' />
         </refsect1>
 
         <refsect1>
+                <title>PAM configuration directives</title>
+
+                <para>Directives for configuring PAM behaviour.</para>
+
+                <variablelist id='pam-directives' />
+        </refsect1>
+
+        <refsect1>
+                <title>crypttab options</title>
+
+                <para>Options which influence mounted filesystems and
+                encrypted volumes.</para>
+
+                <variablelist id='crypttab-options' />
+        </refsect1>
+
+        <refsect1>
+                <title>System manager directives</title>
+
+                <para>Directives for configuring the behaviour of the
+                systemd process.</para>
+
+                <variablelist id='systemd-directives' />
+        </refsect1>
+
+        <refsect1>
                 <title>bootchart.conf directives</title>
 
                 <para>Directives for configuring the behaviour of the
@@ -111,6 +129,24 @@ TEMPLATE = '''\
         </refsect1>
 
         <refsect1>
+                <title>command-line options</title>
+
+                <para>Command-line options accepted by programs in the
+                systemd suite.</para>
+
+                <variablelist id='options' />
+        </refsect1>
+
+        <refsect1>
+                <title>Miscellaneous options and directives</title>
+
+                <para>Other configuration elements which don't fit in
+                any of the above groups.</para>
+
+                <variablelist id='miscellaneous' />
+        </refsect1>
+
+        <refsect1>
                 <title>Colophon</title>
                 <para id='colophon' />
         </refsect1>
@@ -127,11 +163,16 @@ def _extract_directives(directive_groups, page):
     section = t.find('./refmeta/manvolnum').text
     pagename = t.find('./refmeta/refentrytitle').text
     for variablelist in t.iterfind('.//variablelist'):
-        klass = variablelist.attrib.get('class') or 'unit-directives'
-        stor = directive_groups[klass]
-        for varname in variablelist.iterfind('./varlistentry/term/varname'):
-            text = ''.join(varname.text.partition('=')[:2])
-            stor[text].append((pagename, section))
+        klass = variablelist.attrib.get('class')
+        storvar = directive_groups[klass or 'miscellaneous']
+        storopt = directive_groups['options']
+        # <option>s go in OPTIONS, unless class is specified
+        for xpath, stor in (('./varlistentry/term/varname', storvar),
+                            ('./varlistentry/term/option',
+                             storvar if klass else storopt)):
+            for name in variablelist.iterfind(xpath):
+                text = re.sub(r'([= ]).*', r'\1', name.text).rstrip()
+                stor[text].append((pagename, section))
 
 def _make_section(template, name, directives):
     varlist = template.find(".//*[@id='{}']".format(name))
@@ -142,7 +183,7 @@ def _make_section(template, name, directives):
         para = tree.SubElement(tree.SubElement(entry, 'listitem'), 'para')
 
         b = None
-        for manpage, manvolume in sorted(manpages):
+        for manpage, manvolume in sorted(set(manpages)):
                 if b is not None:
                         b.tail = ', '
                 b = tree.SubElement(para, 'citerefentry')
@@ -181,16 +222,19 @@ def _make_page(template, directive_groups):
 
     return template
 
-def make_page(xml_files):
+def make_page(*xml_files):
     "Extract directives from xml_files and return XML index tree."
     template = tree.fromstring(TEMPLATE)
     names = [vl.get('id') for vl in template.iterfind('.//variablelist')]
     directive_groups = {name:collections.defaultdict(list)
                         for name in names}
     for page in xml_files:
-        _extract_directives(directive_groups, page)
+        try:
+            _extract_directives(directive_groups, page)
+        except Exception:
+            raise ValueError("failed to process " + page)
 
     return _make_page(template, directive_groups)
 
 if __name__ == '__main__':
-    tree.dump(make_page(sys.argv[1:]))
+    tree.dump(make_page(*sys.argv[1:]))
index acc7029..2379fc0 100644 (file)
                 comma-delimited list of options.  The following
                 options are recognized:</para>
 
-                <variablelist>
+                <variablelist class='crypttab-options'>
                         <varlistentry>
                                 <term><varname>cipher=</varname></term>
 
index 959ae1e..d8f8f68 100644 (file)
         <refsect1>
                 <title>Environment</title>
 
-                <variablelist>
+                <variablelist class='environment-variables'>
                         <varlistentry>
                                 <term><varname>$SYSTEMD_PAGER</varname></term>
                                 <listitem><para>Pager to use when
index 154d399..f249798 100644 (file)
@@ -74,7 +74,7 @@
         <refsect1>
                 <title>Core OS Command Line Arguments</title>
 
-                <variablelist>
+                <variablelist class='kernel-commandline-options'>
                         <varlistentry>
                                 <term><varname>systemd.unit=</varname></term>
                                 <term><varname>rd.systemd.unit=</varname></term>
index 73bff98..7563eb5 100644 (file)
         <refsect1>
                 <title>Environment</title>
 
-                <variablelist>
+                <variablelist class='environment-variables'>
                         <varlistentry>
                                 <term><varname>$SYSTEMD_PAGER</varname></term>
                                 <listitem><para>Pager to use when
index 9d082cf..90b6f1e 100644 (file)
         <refsect1>
                 <title>Environment</title>
 
-                <variablelist>
+                <variablelist class='environment-variables'>
                         <varlistentry>
                                 <term><varname>$SYSTEMD_PAGER</varname></term>
                                 <listitem><para>Pager to use when
index 600bfd7..0093a8f 100644 (file)
 
                 <para>The following options are understood:</para>
 
-                <variablelist>
+                <variablelist class='pam-directives'>
                         <varlistentry>
                                 <term><option>kill-session-processes=</option></term>
 
 
                 <para>The following environment variables are set for the processes of the user's session:</para>
 
-                <variablelist>
+                <variablelist class='environment-variables'>
                         <varlistentry>
                                 <term><varname>$XDG_SESSION_ID</varname></term>
 
index 0ad4953..6d9fe85 100644 (file)
@@ -96,7 +96,7 @@
         <refsect1>
                 <title>Environment</title>
 
-                <variablelist>
+                <variablelist class='environment-variables'>
                         <varlistentry>
                                 <term><varname>$RUNLEVEL</varname></term>
 
index b891b6b..9c8fdbc 100644 (file)
         <refsect1>
                 <title>Environment</title>
 
-                <variablelist>
+                <variablelist class='environment-variables'>
                         <varlistentry>
                                 <term><varname>$LISTEN_PID</varname></term>
                                 <term><varname>$LISTEN_FDS</varname></term>
index 75edeea..81f74aa 100644 (file)
         <refsect1>
                 <title>Environment</title>
 
-                <variablelist>
+                <variablelist class='environment-variables'>
                         <varlistentry>
                                 <term><varname>$NOTIFY_SOCKET</varname></term>
 
index 60a0f40..3842645 100644 (file)
         <refsect1>
                 <title>Environment</title>
 
-                <variablelist>
+                <variablelist class='environment-variables'>
                         <varlistentry>
                                 <term><varname>$SYSTEMD_PAGER</varname></term>
                                 <listitem><para>Pager to use when
index 8c4d7cc..0df7c4b 100644 (file)
@@ -65,7 +65,7 @@
 
                 <para>systemd-bootchart can be invoked in several different ways:</para>
 
-                <variablelist class='bootchart-invocation'>
+                <variablelist>
 
                         <varlistentry>
                                 <title>Kernel invocation</title>
index 49d4d55..c5f8d2a 100644 (file)
@@ -72,7 +72,7 @@
                 <para><filename>systemd-cryptsetup-generator</filename> understands
                 the following kernel command line parameters:</para>
 
-                <variablelist>
+                <variablelist class='kernel-commandline-options'>
                         <varlistentry>
                                 <term><varname>luks=</varname></term>
                                 <term><varname>rd.luks=</varname></term>
index 62f6311..4d6464c 100644 (file)
@@ -77,7 +77,7 @@
                 <para><filename>systemd-fsck</filename> understands
                 one kernel command line parameter:</para>
 
-                <variablelist>
+                <variablelist class='kernel-commandline-options'>
                         <varlistentry>
                                 <term><varname>fsck.mode=</varname></term>
 
index b265b6c..4bd25bf 100644 (file)
@@ -81,7 +81,7 @@
                 <para><filename>systemd-fstab-generator</filename> understands
                 the following kernel command line parameters:</para>
 
-                <variablelist>
+                <variablelist class='kernel-commandline-options'>
 
                         <varlistentry>
                                 <term><varname>fstab=</varname></term>
index abc03df..4969ab1 100644 (file)
                 <filename>journald.conf</filename> may be overridden on
                 the kernel command line:</para>
 
-                <variablelist>
+                <variablelist class='kernel-commandline-options'>
                         <varlistentry>
                                 <term><varname>systemd.journald.forward_to_syslog=</varname></term>
                                 <term><varname>systemd.journald.forward_to_kmsg=</varname></term>
index e5f10a7..ea10be2 100644 (file)
@@ -71,7 +71,7 @@
                 <para><filename>systemd-modules-load.service</filename> understands
                 the following kernel command line parameters:</para>
 
-                <variablelist>
+                <variablelist class='kernel-commandline-options'>
 
                         <varlistentry>
                                 <term><varname>modules-load=</varname></term>
index 4d0218b..2ffee91 100644 (file)
@@ -67,7 +67,7 @@
                 <para><filename>systemd-quotacheck</filename> understands
                 one kernel command line parameter:</para>
 
-                <variablelist>
+                <variablelist class='kernel-commandline-options'>
                         <varlistentry>
                                 <term><varname>quotacheck.mode=</varname></term>
 
index 9fc59c1..2b9a29a 100644 (file)
   </refsect1>
 
   <refsect1><title>Environment</title>
-    <variablelist>
+    <variablelist class='environment-variables'>
       <varlistentry>
         <term><varname>$UDEV_LOG=</varname></term>
         <listitem>
  </refsect1>
 
   <refsect1><title>Kernel command line</title>
-    <variablelist>
+    <variablelist class='kernel-commandline-options'>
       <para>Parameters starting with "rd." will be read when
       <command>systemd-udevd</command> is used in an initrd.</para>
       <varlistentry>
index c1ef80d..df1b1a1 100644 (file)
@@ -76,7 +76,7 @@
                 <filename>vconsole.conf</filename> may be overridden on
                 the kernel command line:</para>
 
-                <variablelist>
+                <variablelist class='kernel-commandline-options'>
                         <varlistentry>
                                 <term><varname>vconsole.keymap=</varname></term>
                                 <term><varname>vconsole.keymap.toggle=</varname></term>
index 7575835..f428ddf 100644 (file)
                 specific to the [Automount] section of automount units
                 are the following:</para>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
 
                         <varlistentry>
                                 <term><varname>Where=</varname></term>
index fb74bcc..53094e5 100644 (file)
@@ -82,7 +82,7 @@
         <refsect1>
                 <title>Options</title>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
 
                         <varlistentry>
                                 <term><varname>WorkingDirectory=</varname></term>
index 1bff7b8..5ff8fee 100644 (file)
@@ -82,7 +82,7 @@
         <refsect1>
                 <title>Options</title>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
 
                         <varlistentry>
                                 <term><varname>KillMode=</varname></term>
index f319cf7..022be46 100644 (file)
                 options specific to the [Mount] section of mount
                 units are the following:</para>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
 
                         <varlistentry>
                                 <term><varname>What=</varname></term>
                 for compatibility reasons and should not be used in
                 newly written mount files.</para>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
                         <varlistentry>
                                 <term><varname>FsckPassNo=</varname></term>
 
index a602caa..ccf16df 100644 (file)
                 monitors. The options specific to the [Path] section
                 of path units are the following:</para>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
                         <varlistentry>
                                 <term><varname>PathExists=</varname></term>
                                 <term><varname>PathExistsGlob=</varname></term>
index 891b347..d2feb98 100644 (file)
                 options specific to the <literal>[Service]</literal>
                 section of service units are the following:</para>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
                         <varlistentry>
                                 <term><varname>Type=</varname></term>
 
                 for compatibility reasons and should not be used in
                 newly written service files.</para>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
                         <varlistentry>
                                 <term><varname>SysVStartPriority=</varname></term>
                                 <listitem><para>Set the SysV start
index 7ba8bdc..28730ca 100644 (file)
                 options specific to the [Socket] section of socket
                 units are the following:</para>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
                         <varlistentry>
                                 <term><varname>ListenStream=</varname></term>
                                 <term><varname>ListenDatagram=</varname></term>
index dae9d59..e547e71 100644 (file)
                 options specific to the [Swap] section of swap units
                 are the following:</para>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
 
                         <varlistentry>
                                 <term><varname>What=</varname></term>
index 8682643..2c2ba58 100644 (file)
@@ -97,7 +97,7 @@
                 defines. The options specific to the [Timer] section
                 of timer units are the following:</para>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
                         <varlistentry>
                                 <term><varname>OnActiveSec=</varname></term>
                                 <term><varname>OnBootSec=</varname></term>
index 953a289..dcdfc1e 100644 (file)
                 carries generic information about the unit that is not
                 dependent on the type of unit:</para>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
 
                         <varlistentry>
                                 <term><varname>Description=</varname></term>
                 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                 tool during installation of a unit:</para>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
                         <varlistentry>
                                 <term><varname>Alias=</varname></term>
 
index 962ed56..bae90a5 100644 (file)
         <refsect1>
                 <title>Directories</title>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
                         <varlistentry>
                                 <term>System unit directories</term>
 
                 <filename>/proc/cmdline</filename>
                 instead.</para></footnote>:</para>
 
-                <variablelist class='kernel-commandline-directives'>
+                <variablelist class='kernel-commandline-options'>
                         <varlistentry>
                                 <term><varname>systemd.unit=</varname></term>
                                 <term><varname>rd.systemd.unit=</varname></term>
index 01ca0a7..4f34bb7 100644 (file)
         <refsect1>
                 <title>Environment</title>
 
-                <variablelist>
+                <variablelist class='environment-variables'>
                         <varlistentry>
                                 <term><varname>$SYSTEMD_PAGER</varname></term>
                                 <listitem><para>Pager to use when
index 773635e..415cf8e 100644 (file)
       not only the device that has generated the event. If multiple keys that match
       a parent device are specified in a single rule, all these keys must match at
       one and the same parent device.</para>
-      <variablelist>
+      <variablelist class='udev-directives'>
         <varlistentry>
           <term><option>ACTION</option></term>
           <listitem>
       </variablelist>
 
       <para>The following keys can get values assigned:</para>
-      <variablelist>
+      <variablelist class='udev-directives'>
         <varlistentry>
           <term><option>NAME</option></term>
           <listitem>
           <term><option>OPTIONS</option></term>
           <listitem>
             <para>Rule and device options:</para>
-            <variablelist>
+            <variablelist class='udev-directives'>
               <varlistentry>
                 <term><option>link_priority=<replaceable>value</replaceable></option></term>
                 <listitem>
       is executed, allowing for the use of device properties set by earlier matching
       rules. For all other fields, substitutions are performed while the individual rule is
       being processed. The available substitutions are:</para>
-      <variablelist>
+      <variablelist class='udev-directives'>
         <varlistentry>
           <term><option>$kernel</option>, <option>%k</option></term>
           <listitem>