picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
Makefile.am
View 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) $^ > $@

92
make-directive-index.py
View File

@ -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:]))

2
man/crypttab.xml
View File

@ -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>

2
man/journalctl.xml
View File

@ -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

2
man/kernel-command-line.xml
View 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>

2
man/localectl.xml
View File

@ -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

2
man/loginctl.xml
View File

@ -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

4
man/pam_systemd.xml
View File

@ -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>

2
man/runlevel.xml
View File

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

2
man/sd_listen_fds.xml
View File

@ -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>

2
man/sd_notify.xml
View File

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

2
man/systemctl.xml
View File

@ -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

2
man/systemd-bootchart.xml
View 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>

2
man/systemd-cryptsetup-generator.xml
View 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>

2
man/systemd-fsck@.service.xml
View 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>

2
man/systemd-fstab-generator.xml
View 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>

2
man/systemd-journald.service.xml
View File

@ -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>

2
man/systemd-modules-load.service.xml
View 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>

2
man/systemd-quotacheck.service.xml
View 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>

4
man/systemd-udevd.service.xml
View File

@ -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>

2
man/systemd-vconsole-setup.service.xml
View 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>

2
man/systemd.automount.xml
View File

@ -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>

2
man/systemd.exec.xml
View File

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

2
man/systemd.kill.xml
View File

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

4
man/systemd.mount.xml
View File

@ -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>

2
man/systemd.path.xml
View File

@ -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>

4
man/systemd.service.xml
View File

@ -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

2
man/systemd.socket.xml
View File

@ -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>

2
man/systemd.swap.xml
View File

@ -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>

2
man/systemd.timer.xml
View 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>

4
man/systemd.unit.xml
View File

@ -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>

4
man/systemd.xml
View File

@ -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>

2
man/timedatectl.xml
View File

@ -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

8
man/udev.xml
View File

@ -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>