diff options
| author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2013-01-26 10:47:16 -0500 |
|---|---|---|
| committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2013-01-26 11:36:53 -0500 |
| commit | ccc9a4f9ffdab069b0b785627c48962fdadf6d46 (patch) | |
| tree | 13d75aea780ceb7bface70b83f49aec62078e0f7 | |
| parent | 6b76fa66199967b4ec71854f717d0b8ee94497c4 (diff) | |
man: extend systemd.directives(7) to all manual pages
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, 112 insertions, 87 deletions
diff --git a/Makefile.am b/Makefile.am index f362b53728..9c92bffc01 100644 --- a/Makefile.am +++ b/Makefile.am @@ -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) $^ > $@ diff --git a/make-directive-index.py b/make-directive-index.py index 48d830e96f..29c594cb75 100755 --- a/make-directive-index.py +++ b/make-directive-index.py @@ -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:])) diff --git a/man/crypttab.xml b/man/crypttab.xml index acc702961d..2379fc0827 100644 --- a/man/crypttab.xml +++ b/man/crypttab.xml @@ -103,7 +103,7 @@ comma-delimited list of options. The following options are recognized:</para> - <variablelist> + <variablelist class='crypttab-options'> <varlistentry> <term><varname>cipher=</varname></term> diff --git a/man/journalctl.xml b/man/journalctl.xml index 959ae1efa2..d8f8f68929 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -518,7 +518,7 @@ <refsect1> <title>Environment</title> - <variablelist> + <variablelist class='environment-variables'> <varlistentry> <term><varname>$SYSTEMD_PAGER</varname></term> <listitem><para>Pager to use when diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index 154d399d5a..f249798171 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -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> diff --git a/man/localectl.xml b/man/localectl.xml index 73bff98938..7563eb513c 100644 --- a/man/localectl.xml +++ b/man/localectl.xml @@ -229,7 +229,7 @@ <refsect1> <title>Environment</title> - <variablelist> + <variablelist class='environment-variables'> <varlistentry> <term><varname>$SYSTEMD_PAGER</varname></term> <listitem><para>Pager to use when diff --git a/man/loginctl.xml b/man/loginctl.xml index 9d082cf915..90b6f1e110 100644 --- a/man/loginctl.xml +++ b/man/loginctl.xml @@ -457,7 +457,7 @@ <refsect1> <title>Environment</title> - <variablelist> + <variablelist class='environment-variables'> <varlistentry> <term><varname>$SYSTEMD_PAGER</varname></term> <listitem><para>Pager to use when diff --git a/man/pam_systemd.xml b/man/pam_systemd.xml index 600bfd71b4..0093a8fb2d 100644 --- a/man/pam_systemd.xml +++ b/man/pam_systemd.xml @@ -118,7 +118,7 @@ <para>The following options are understood:</para> - <variablelist> + <variablelist class='pam-directives'> <varlistentry> <term><option>kill-session-processes=</option></term> @@ -247,7 +247,7 @@ <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> diff --git a/man/runlevel.xml b/man/runlevel.xml index 0ad4953efd..6d9fe85726 100644 --- a/man/runlevel.xml +++ b/man/runlevel.xml @@ -96,7 +96,7 @@ <refsect1> <title>Environment</title> - <variablelist> + <variablelist class='environment-variables'> <varlistentry> <term><varname>$RUNLEVEL</varname></term> diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index b891b6b039..9c8fdbccaf 100644 --- a/man/sd_listen_fds.xml +++ b/man/sd_listen_fds.xml @@ -168,7 +168,7 @@ <refsect1> <title>Environment</title> - <variablelist> + <variablelist class='environment-variables'> <varlistentry> <term><varname>$LISTEN_PID</varname></term> <term><varname>$LISTEN_FDS</varname></term> diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 75edeeadf3..81f74aa843 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -254,7 +254,7 @@ <refsect1> <title>Environment</title> - <variablelist> + <variablelist class='environment-variables'> <varlistentry> <term><varname>$NOTIFY_SOCKET</varname></term> diff --git a/man/systemctl.xml b/man/systemctl.xml index 60a0f401bd..38426454d4 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1296,7 +1296,7 @@ <refsect1> <title>Environment</title> - <variablelist> + <variablelist class='environment-variables'> <varlistentry> <term><varname>$SYSTEMD_PAGER</varname></term> <listitem><para>Pager to use when diff --git a/man/systemd-bootchart.xml b/man/systemd-bootchart.xml index 8c4d7cc1dc..0df7c4bcf4 100644 --- a/man/systemd-bootchart.xml +++ b/man/systemd-bootchart.xml @@ -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> diff --git a/man/systemd-cryptsetup-generator.xml b/man/systemd-cryptsetup-generator.xml index 49d4d5545b..c5f8d2a9d8 100644 --- a/man/systemd-cryptsetup-generator.xml +++ b/man/systemd-cryptsetup-generator.xml @@ -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> diff --git a/man/systemd-fsck@.service.xml b/man/systemd-fsck@.service.xml index 62f63110e1..4d6464c2b8 100644 --- a/man/systemd-fsck@.service.xml +++ b/man/systemd-fsck@.service.xml @@ -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> diff --git a/man/systemd-fstab-generator.xml b/man/systemd-fstab-generator.xml index b265b6c082..4bd25bfa8f 100644 --- a/man/systemd-fstab-generator.xml +++ b/man/systemd-fstab-generator.xml @@ -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> diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml index abc03df5db..4969ab19c3 100644 --- a/man/systemd-journald.service.xml +++ b/man/systemd-journald.service.xml @@ -137,7 +137,7 @@ <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> diff --git a/man/systemd-modules-load.service.xml b/man/systemd-modules-load.service.xml index e5f10a7beb..ea10be2234 100644 --- a/man/systemd-modules-load.service.xml +++ b/man/systemd-modules-load.service.xml @@ -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> diff --git a/man/systemd-quotacheck.service.xml b/man/systemd-quotacheck.service.xml index 4d0218b659..2ffee9158e 100644 --- a/man/systemd-quotacheck.service.xml +++ b/man/systemd-quotacheck.service.xml @@ -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> diff --git a/man/systemd-udevd.service.xml b/man/systemd-udevd.service.xml index 9fc59c1bf1..2b9a29adcd 100644 --- a/man/systemd-udevd.service.xml +++ b/man/systemd-udevd.service.xml @@ -116,7 +116,7 @@ </refsect1> <refsect1><title>Environment</title> - <variablelist> + <variablelist class='environment-variables'> <varlistentry> <term><varname>$UDEV_LOG=</varname></term> <listitem> @@ -127,7 +127,7 @@ </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> diff --git a/man/systemd-vconsole-setup.service.xml b/man/systemd-vconsole-setup.service.xml index c1ef80dae4..df1b1a16b6 100644 --- a/man/systemd-vconsole-setup.service.xml +++ b/man/systemd-vconsole-setup.service.xml @@ -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> diff --git a/man/systemd.automount.xml b/man/systemd.automount.xml index 7575835060..f428ddfe1a 100644 --- a/man/systemd.automount.xml +++ b/man/systemd.automount.xml @@ -123,7 +123,7 @@ specific to the [Automount] section of automount units are the following:</para> - <variablelist> + <variablelist class='unit-directives'> <varlistentry> <term><varname>Where=</varname></term> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index fb74bcc972..53094e587d 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -82,7 +82,7 @@ <refsect1> <title>Options</title> - <variablelist> + <variablelist class='unit-directives'> <varlistentry> <term><varname>WorkingDirectory=</varname></term> diff --git a/man/systemd.kill.xml b/man/systemd.kill.xml index 1bff7b81fa..5ff8feee63 100644 --- a/man/systemd.kill.xml +++ b/man/systemd.kill.xml @@ -82,7 +82,7 @@ <refsect1> <title>Options</title> - <variablelist> + <variablelist class='unit-directives'> <varlistentry> <term><varname>KillMode=</varname></term> diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml index f319cf7ce9..022be4661d 100644 --- a/man/systemd.mount.xml +++ b/man/systemd.mount.xml @@ -182,7 +182,7 @@ options specific to the [Mount] section of mount units are the following:</para> - <variablelist> + <variablelist class='unit-directives'> <varlistentry> <term><varname>What=</varname></term> @@ -276,7 +276,7 @@ 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> diff --git a/man/systemd.path.xml b/man/systemd.path.xml index a602caab13..ccf16df004 100644 --- a/man/systemd.path.xml +++ b/man/systemd.path.xml @@ -108,7 +108,7 @@ 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> diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 891b3474aa..d2feb98247 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -121,7 +121,7 @@ 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> @@ -887,7 +887,7 @@ 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 diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 7ba8bdc85b..28730ca441 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -143,7 +143,7 @@ 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> diff --git a/man/systemd.swap.xml b/man/systemd.swap.xml index dae9d59e7c..e547e71722 100644 --- a/man/systemd.swap.xml +++ b/man/systemd.swap.xml @@ -136,7 +136,7 @@ options specific to the [Swap] section of swap units are the following:</para> - <variablelist> + <variablelist class='unit-directives'> <varlistentry> <term><varname>What=</varname></term> diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml index 8682643349..2c2ba58226 100644 --- a/man/systemd.timer.xml +++ b/man/systemd.timer.xml @@ -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> diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 953a2897ad..dcdfc1e5d6 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -222,7 +222,7 @@ 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> @@ -944,7 +944,7 @@ <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> diff --git a/man/systemd.xml b/man/systemd.xml index 962ed56ffc..bae90a5f09 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -508,7 +508,7 @@ <refsect1> <title>Directories</title> - <variablelist> + <variablelist class='unit-directives'> <varlistentry> <term>System unit directories</term> @@ -987,7 +987,7 @@ <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> diff --git a/man/timedatectl.xml b/man/timedatectl.xml index 01ca0a73d5..4f34bb7b73 100644 --- a/man/timedatectl.xml +++ b/man/timedatectl.xml @@ -221,7 +221,7 @@ <refsect1> <title>Environment</title> - <variablelist> + <variablelist class='environment-variables'> <varlistentry> <term><varname>$SYSTEMD_PAGER</varname></term> <listitem><para>Pager to use when diff --git a/man/udev.xml b/man/udev.xml index 773635ecf7..415cf8e6a9 100644 --- a/man/udev.xml +++ b/man/udev.xml @@ -148,7 +148,7 @@ 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> @@ -322,7 +322,7 @@ </variablelist> <para>The following keys can get values assigned:</para> - <variablelist> + <variablelist class='udev-directives'> <varlistentry> <term><option>NAME</option></term> <listitem> @@ -489,7 +489,7 @@ <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> @@ -546,7 +546,7 @@ 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> |