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.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2013-01-26 10:47:16 -05:00
parent 6b76fa6619
commit ccc9a4f9ff
34 changed files with 112 additions and 87 deletions

View File

@ -767,31 +767,12 @@ MANPAGES += \
man/systemd.index.7 \ man/systemd.index.7 \
man/systemd.directives.7 man/systemd.directives.7
XML_DIRECTIVE_FILES = \ NON_INDEX_XML_FILES = $(filter-out man/systemd.index.xml,$(XML_FILES))
man/systemd.xml \ man/systemd.index.xml: make-man-index.py $(NON_INDEX_XML_FILES)
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))
$(AM_V_at)$(MKDIR_P) $(dir $@) $(AM_V_at)$(MKDIR_P) $(dir $@)
$(AM_V_GEN)$(PYTHON) $^ > $@ $(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_at)$(MKDIR_P) $(dir $@)
$(AM_V_GEN)$(PYTHON) $^ > $@ $(AM_V_GEN)$(PYTHON) $^ > $@

View File

@ -2,7 +2,7 @@
# #
# This file is part of systemd. # 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 # 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 # under the terms of the GNU Lesser General Public License as published by
@ -20,6 +20,7 @@
import sys import sys
import collections import collections
import xml.etree.ElementTree as tree import xml.etree.ElementTree as tree
import re
TEMPLATE = '''\ TEMPLATE = '''\
<refentry id="systemd.directives"> <refentry id="systemd.directives">
@ -57,28 +58,20 @@ TEMPLATE = '''\
<variablelist id='unit-directives' /> <variablelist id='unit-directives' />
</refsect1> </refsect1>
<refsect1>
<title>System manager directives</title>
<para>Directives for configuring the behaviour of the
systemd process.</para>
<variablelist id='systemd-directives' />
</refsect1>
<refsect1> <refsect1>
<title>Options on the kernel command line</title> <title>Options on the kernel command line</title>
<para>Kernel boot options for configuring the behaviour of the <para>Kernel boot options for configuring the behaviour of the
systemd process.</para> systemd process.</para>
<variablelist id='kernel-commandline-directives' /> <variablelist id='kernel-commandline-options' />
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Environment variables</title> <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' /> <variablelist id='environment-variables' />
</refsect1> </refsect1>
@ -93,14 +86,39 @@ TEMPLATE = '''\
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Journal directives</title> <title>Journal fields</title>
<para>Directives for configuring the behaviour of the <para>Fields in the journal events with a well known meaning.</para>
journald process.</para>
<variablelist id='journal-directives' /> <variablelist id='journal-directives' />
</refsect1> </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> <refsect1>
<title>bootchart.conf directives</title> <title>bootchart.conf directives</title>
@ -110,6 +128,24 @@ TEMPLATE = '''\
<variablelist id='bootchart-directives' /> <variablelist id='bootchart-directives' />
</refsect1> </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> <refsect1>
<title>Colophon</title> <title>Colophon</title>
<para id='colophon' /> <para id='colophon' />
@ -127,11 +163,16 @@ def _extract_directives(directive_groups, page):
section = t.find('./refmeta/manvolnum').text section = t.find('./refmeta/manvolnum').text
pagename = t.find('./refmeta/refentrytitle').text pagename = t.find('./refmeta/refentrytitle').text
for variablelist in t.iterfind('.//variablelist'): for variablelist in t.iterfind('.//variablelist'):
klass = variablelist.attrib.get('class') or 'unit-directives' klass = variablelist.attrib.get('class')
stor = directive_groups[klass] storvar = directive_groups[klass or 'miscellaneous']
for varname in variablelist.iterfind('./varlistentry/term/varname'): storopt = directive_groups['options']
text = ''.join(varname.text.partition('=')[:2]) # <option>s go in OPTIONS, unless class is specified
stor[text].append((pagename, section)) 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): def _make_section(template, name, directives):
varlist = template.find(".//*[@id='{}']".format(name)) varlist = template.find(".//*[@id='{}']".format(name))
@ -142,7 +183,7 @@ def _make_section(template, name, directives):
para = tree.SubElement(tree.SubElement(entry, 'listitem'), 'para') para = tree.SubElement(tree.SubElement(entry, 'listitem'), 'para')
b = None b = None
for manpage, manvolume in sorted(manpages): for manpage, manvolume in sorted(set(manpages)):
if b is not None: if b is not None:
b.tail = ', ' b.tail = ', '
b = tree.SubElement(para, 'citerefentry') b = tree.SubElement(para, 'citerefentry')
@ -181,16 +222,19 @@ def _make_page(template, directive_groups):
return template return template
def make_page(xml_files): def make_page(*xml_files):
"Extract directives from xml_files and return XML index tree." "Extract directives from xml_files and return XML index tree."
template = tree.fromstring(TEMPLATE) template = tree.fromstring(TEMPLATE)
names = [vl.get('id') for vl in template.iterfind('.//variablelist')] names = [vl.get('id') for vl in template.iterfind('.//variablelist')]
directive_groups = {name:collections.defaultdict(list) directive_groups = {name:collections.defaultdict(list)
for name in names} for name in names}
for page in xml_files: 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) return _make_page(template, directive_groups)
if __name__ == '__main__': if __name__ == '__main__':
tree.dump(make_page(sys.argv[1:])) tree.dump(make_page(*sys.argv[1:]))

View File

@ -103,7 +103,7 @@
comma-delimited list of options. The following comma-delimited list of options. The following
options are recognized:</para> options are recognized:</para>
<variablelist> <variablelist class='crypttab-options'>
<varlistentry> <varlistentry>
<term><varname>cipher=</varname></term> <term><varname>cipher=</varname></term>

View File

@ -518,7 +518,7 @@
<refsect1> <refsect1>
<title>Environment</title> <title>Environment</title>
<variablelist> <variablelist class='environment-variables'>
<varlistentry> <varlistentry>
<term><varname>$SYSTEMD_PAGER</varname></term> <term><varname>$SYSTEMD_PAGER</varname></term>
<listitem><para>Pager to use when <listitem><para>Pager to use when

View File

@ -74,7 +74,7 @@
<refsect1> <refsect1>
<title>Core OS Command Line Arguments</title> <title>Core OS Command Line Arguments</title>
<variablelist> <variablelist class='kernel-commandline-options'>
<varlistentry> <varlistentry>
<term><varname>systemd.unit=</varname></term> <term><varname>systemd.unit=</varname></term>
<term><varname>rd.systemd.unit=</varname></term> <term><varname>rd.systemd.unit=</varname></term>

View File

@ -229,7 +229,7 @@
<refsect1> <refsect1>
<title>Environment</title> <title>Environment</title>
<variablelist> <variablelist class='environment-variables'>
<varlistentry> <varlistentry>
<term><varname>$SYSTEMD_PAGER</varname></term> <term><varname>$SYSTEMD_PAGER</varname></term>
<listitem><para>Pager to use when <listitem><para>Pager to use when

View File

@ -457,7 +457,7 @@
<refsect1> <refsect1>
<title>Environment</title> <title>Environment</title>
<variablelist> <variablelist class='environment-variables'>
<varlistentry> <varlistentry>
<term><varname>$SYSTEMD_PAGER</varname></term> <term><varname>$SYSTEMD_PAGER</varname></term>
<listitem><para>Pager to use when <listitem><para>Pager to use when

View File

@ -118,7 +118,7 @@
<para>The following options are understood:</para> <para>The following options are understood:</para>
<variablelist> <variablelist class='pam-directives'>
<varlistentry> <varlistentry>
<term><option>kill-session-processes=</option></term> <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> <para>The following environment variables are set for the processes of the user's session:</para>
<variablelist> <variablelist class='environment-variables'>
<varlistentry> <varlistentry>
<term><varname>$XDG_SESSION_ID</varname></term> <term><varname>$XDG_SESSION_ID</varname></term>

View File

@ -96,7 +96,7 @@
<refsect1> <refsect1>
<title>Environment</title> <title>Environment</title>
<variablelist> <variablelist class='environment-variables'>
<varlistentry> <varlistentry>
<term><varname>$RUNLEVEL</varname></term> <term><varname>$RUNLEVEL</varname></term>

View File

@ -168,7 +168,7 @@
<refsect1> <refsect1>
<title>Environment</title> <title>Environment</title>
<variablelist> <variablelist class='environment-variables'>
<varlistentry> <varlistentry>
<term><varname>$LISTEN_PID</varname></term> <term><varname>$LISTEN_PID</varname></term>
<term><varname>$LISTEN_FDS</varname></term> <term><varname>$LISTEN_FDS</varname></term>

View File

@ -254,7 +254,7 @@
<refsect1> <refsect1>
<title>Environment</title> <title>Environment</title>
<variablelist> <variablelist class='environment-variables'>
<varlistentry> <varlistentry>
<term><varname>$NOTIFY_SOCKET</varname></term> <term><varname>$NOTIFY_SOCKET</varname></term>

View File

@ -1296,7 +1296,7 @@
<refsect1> <refsect1>
<title>Environment</title> <title>Environment</title>
<variablelist> <variablelist class='environment-variables'>
<varlistentry> <varlistentry>
<term><varname>$SYSTEMD_PAGER</varname></term> <term><varname>$SYSTEMD_PAGER</varname></term>
<listitem><para>Pager to use when <listitem><para>Pager to use when

View File

@ -65,7 +65,7 @@
<para>systemd-bootchart can be invoked in several different ways:</para> <para>systemd-bootchart can be invoked in several different ways:</para>
<variablelist class='bootchart-invocation'> <variablelist>
<varlistentry> <varlistentry>
<title>Kernel invocation</title> <title>Kernel invocation</title>

View File

@ -72,7 +72,7 @@
<para><filename>systemd-cryptsetup-generator</filename> understands <para><filename>systemd-cryptsetup-generator</filename> understands
the following kernel command line parameters:</para> the following kernel command line parameters:</para>
<variablelist> <variablelist class='kernel-commandline-options'>
<varlistentry> <varlistentry>
<term><varname>luks=</varname></term> <term><varname>luks=</varname></term>
<term><varname>rd.luks=</varname></term> <term><varname>rd.luks=</varname></term>

View File

@ -77,7 +77,7 @@
<para><filename>systemd-fsck</filename> understands <para><filename>systemd-fsck</filename> understands
one kernel command line parameter:</para> one kernel command line parameter:</para>
<variablelist> <variablelist class='kernel-commandline-options'>
<varlistentry> <varlistentry>
<term><varname>fsck.mode=</varname></term> <term><varname>fsck.mode=</varname></term>

View File

@ -81,7 +81,7 @@
<para><filename>systemd-fstab-generator</filename> understands <para><filename>systemd-fstab-generator</filename> understands
the following kernel command line parameters:</para> the following kernel command line parameters:</para>
<variablelist> <variablelist class='kernel-commandline-options'>
<varlistentry> <varlistentry>
<term><varname>fstab=</varname></term> <term><varname>fstab=</varname></term>

View File

@ -137,7 +137,7 @@
<filename>journald.conf</filename> may be overridden on <filename>journald.conf</filename> may be overridden on
the kernel command line:</para> the kernel command line:</para>
<variablelist> <variablelist class='kernel-commandline-options'>
<varlistentry> <varlistentry>
<term><varname>systemd.journald.forward_to_syslog=</varname></term> <term><varname>systemd.journald.forward_to_syslog=</varname></term>
<term><varname>systemd.journald.forward_to_kmsg=</varname></term> <term><varname>systemd.journald.forward_to_kmsg=</varname></term>

View File

@ -71,7 +71,7 @@
<para><filename>systemd-modules-load.service</filename> understands <para><filename>systemd-modules-load.service</filename> understands
the following kernel command line parameters:</para> the following kernel command line parameters:</para>
<variablelist> <variablelist class='kernel-commandline-options'>
<varlistentry> <varlistentry>
<term><varname>modules-load=</varname></term> <term><varname>modules-load=</varname></term>

View File

@ -67,7 +67,7 @@
<para><filename>systemd-quotacheck</filename> understands <para><filename>systemd-quotacheck</filename> understands
one kernel command line parameter:</para> one kernel command line parameter:</para>
<variablelist> <variablelist class='kernel-commandline-options'>
<varlistentry> <varlistentry>
<term><varname>quotacheck.mode=</varname></term> <term><varname>quotacheck.mode=</varname></term>

View File

@ -116,7 +116,7 @@
</refsect1> </refsect1>
<refsect1><title>Environment</title> <refsect1><title>Environment</title>
<variablelist> <variablelist class='environment-variables'>
<varlistentry> <varlistentry>
<term><varname>$UDEV_LOG=</varname></term> <term><varname>$UDEV_LOG=</varname></term>
<listitem> <listitem>
@ -127,7 +127,7 @@
</refsect1> </refsect1>
<refsect1><title>Kernel command line</title> <refsect1><title>Kernel command line</title>
<variablelist> <variablelist class='kernel-commandline-options'>
<para>Parameters starting with "rd." will be read when <para>Parameters starting with "rd." will be read when
<command>systemd-udevd</command> is used in an initrd.</para> <command>systemd-udevd</command> is used in an initrd.</para>
<varlistentry> <varlistentry>

View File

@ -76,7 +76,7 @@
<filename>vconsole.conf</filename> may be overridden on <filename>vconsole.conf</filename> may be overridden on
the kernel command line:</para> the kernel command line:</para>
<variablelist> <variablelist class='kernel-commandline-options'>
<varlistentry> <varlistentry>
<term><varname>vconsole.keymap=</varname></term> <term><varname>vconsole.keymap=</varname></term>
<term><varname>vconsole.keymap.toggle=</varname></term> <term><varname>vconsole.keymap.toggle=</varname></term>

View File

@ -123,7 +123,7 @@
specific to the [Automount] section of automount units specific to the [Automount] section of automount units
are the following:</para> are the following:</para>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>Where=</varname></term> <term><varname>Where=</varname></term>

View File

@ -82,7 +82,7 @@
<refsect1> <refsect1>
<title>Options</title> <title>Options</title>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>WorkingDirectory=</varname></term> <term><varname>WorkingDirectory=</varname></term>

View File

@ -82,7 +82,7 @@
<refsect1> <refsect1>
<title>Options</title> <title>Options</title>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>KillMode=</varname></term> <term><varname>KillMode=</varname></term>

View File

@ -182,7 +182,7 @@
options specific to the [Mount] section of mount options specific to the [Mount] section of mount
units are the following:</para> units are the following:</para>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>What=</varname></term> <term><varname>What=</varname></term>
@ -276,7 +276,7 @@
for compatibility reasons and should not be used in for compatibility reasons and should not be used in
newly written mount files.</para> newly written mount files.</para>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>FsckPassNo=</varname></term> <term><varname>FsckPassNo=</varname></term>

View File

@ -108,7 +108,7 @@
monitors. The options specific to the [Path] section monitors. The options specific to the [Path] section
of path units are the following:</para> of path units are the following:</para>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>PathExists=</varname></term> <term><varname>PathExists=</varname></term>
<term><varname>PathExistsGlob=</varname></term> <term><varname>PathExistsGlob=</varname></term>

View File

@ -121,7 +121,7 @@
options specific to the <literal>[Service]</literal> options specific to the <literal>[Service]</literal>
section of service units are the following:</para> section of service units are the following:</para>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>Type=</varname></term> <term><varname>Type=</varname></term>
@ -887,7 +887,7 @@
for compatibility reasons and should not be used in for compatibility reasons and should not be used in
newly written service files.</para> newly written service files.</para>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>SysVStartPriority=</varname></term> <term><varname>SysVStartPriority=</varname></term>
<listitem><para>Set the SysV start <listitem><para>Set the SysV start

View File

@ -143,7 +143,7 @@
options specific to the [Socket] section of socket options specific to the [Socket] section of socket
units are the following:</para> units are the following:</para>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>ListenStream=</varname></term> <term><varname>ListenStream=</varname></term>
<term><varname>ListenDatagram=</varname></term> <term><varname>ListenDatagram=</varname></term>

View File

@ -136,7 +136,7 @@
options specific to the [Swap] section of swap units options specific to the [Swap] section of swap units
are the following:</para> are the following:</para>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>What=</varname></term> <term><varname>What=</varname></term>

View File

@ -97,7 +97,7 @@
defines. The options specific to the [Timer] section defines. The options specific to the [Timer] section
of timer units are the following:</para> of timer units are the following:</para>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>OnActiveSec=</varname></term> <term><varname>OnActiveSec=</varname></term>
<term><varname>OnBootSec=</varname></term> <term><varname>OnBootSec=</varname></term>

View File

@ -222,7 +222,7 @@
carries generic information about the unit that is not carries generic information about the unit that is not
dependent on the type of unit:</para> dependent on the type of unit:</para>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>Description=</varname></term> <term><varname>Description=</varname></term>
@ -944,7 +944,7 @@
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
tool during installation of a unit:</para> tool during installation of a unit:</para>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term><varname>Alias=</varname></term> <term><varname>Alias=</varname></term>

View File

@ -508,7 +508,7 @@
<refsect1> <refsect1>
<title>Directories</title> <title>Directories</title>
<variablelist> <variablelist class='unit-directives'>
<varlistentry> <varlistentry>
<term>System unit directories</term> <term>System unit directories</term>
@ -987,7 +987,7 @@
<filename>/proc/cmdline</filename> <filename>/proc/cmdline</filename>
instead.</para></footnote>:</para> instead.</para></footnote>:</para>
<variablelist class='kernel-commandline-directives'> <variablelist class='kernel-commandline-options'>
<varlistentry> <varlistentry>
<term><varname>systemd.unit=</varname></term> <term><varname>systemd.unit=</varname></term>
<term><varname>rd.systemd.unit=</varname></term> <term><varname>rd.systemd.unit=</varname></term>

View File

@ -221,7 +221,7 @@
<refsect1> <refsect1>
<title>Environment</title> <title>Environment</title>
<variablelist> <variablelist class='environment-variables'>
<varlistentry> <varlistentry>
<term><varname>$SYSTEMD_PAGER</varname></term> <term><varname>$SYSTEMD_PAGER</varname></term>
<listitem><para>Pager to use when <listitem><para>Pager to use when

View File

@ -148,7 +148,7 @@
not only the device that has generated the event. If multiple keys that match 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 a parent device are specified in a single rule, all these keys must match at
one and the same parent device.</para> one and the same parent device.</para>
<variablelist> <variablelist class='udev-directives'>
<varlistentry> <varlistentry>
<term><option>ACTION</option></term> <term><option>ACTION</option></term>
<listitem> <listitem>
@ -322,7 +322,7 @@
</variablelist> </variablelist>
<para>The following keys can get values assigned:</para> <para>The following keys can get values assigned:</para>
<variablelist> <variablelist class='udev-directives'>
<varlistentry> <varlistentry>
<term><option>NAME</option></term> <term><option>NAME</option></term>
<listitem> <listitem>
@ -489,7 +489,7 @@
<term><option>OPTIONS</option></term> <term><option>OPTIONS</option></term>
<listitem> <listitem>
<para>Rule and device options:</para> <para>Rule and device options:</para>
<variablelist> <variablelist class='udev-directives'>
<varlistentry> <varlistentry>
<term><option>link_priority=<replaceable>value</replaceable></option></term> <term><option>link_priority=<replaceable>value</replaceable></option></term>
<listitem> <listitem>
@ -546,7 +546,7 @@
is executed, allowing for the use of device properties set by earlier matching 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 rules. For all other fields, substitutions are performed while the individual rule is
being processed. The available substitutions are:</para> being processed. The available substitutions are:</para>
<variablelist> <variablelist class='udev-directives'>
<varlistentry> <varlistentry>
<term><option>$kernel</option>, <option>%k</option></term> <term><option>$kernel</option>, <option>%k</option></term>
<listitem> <listitem>