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.
parent 6b76fa66
......@@ -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) $^ > $@
......
......@@ -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">
......@@ -57,28 +58,20 @@ TEMPLATE = '''\
<variablelist id='unit-directives' />
</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,14 +86,39 @@ 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>
......@@ -110,6 +128,24 @@ TEMPLATE = '''\
<variablelist id='bootchart-directives' />
</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' />
......@@ -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:]))
......@@ -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>
......
......@@ -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
......
......@@ -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>
......
......@@ -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
......
......@@ -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
......
......@@ -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>
......
......@@ -96,7 +96,7 @@
<refsect1>
<title>Environment</title>
<variablelist>
<variablelist class='environment-variables'>
<varlistentry>
<term><varname>$RUNLEVEL</varname></term>
......
......@@ -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>
......
......@@ -254,7 +254,7 @@
<refsect1>
<title>Environment</title>
<variablelist>
<variablelist class='environment-variables'>
<varlistentry>
<term><varname>$NOTIFY_SOCKET</varname></term>
......
......@@ -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
......
......@@ -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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -82,7 +82,7 @@
<refsect1>
<title>Options</title>
<variablelist>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>WorkingDirectory=</varname></term>
......
......@@ -82,7 +82,7 @@
<refsect1>
<title>Options</title>
<variablelist>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>KillMode=</varname></term>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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
......
......@@ -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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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
......
......@@ -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>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment