blob: fb2b0b7c6fde6c8e4bfeb21f600fbb0f77547467 [file] [log] [blame]
Jörg Thalheim3e67e5c2017-05-01 02:26:56 +02001#!/usr/bin/env python3
Zbigniew Jędrzejewski-Szmeke7098b62012-11-13 18:39:18 +01002# -*- Mode: python; coding: utf-8; indent-tabs-mode: nil -*- */
Zbigniew Jędrzejewski-Szmek35df7442017-11-18 17:32:46 +01003# SPDX-License-Identifier: LGPL-2.1+
Zbigniew Jędrzejewski-Szmeke7098b62012-11-13 18:39:18 +01004#
5# This file is part of systemd.
6#
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -05007# Copyright 2012-2013 Zbigniew Jędrzejewski-Szmek
Zbigniew Jędrzejewski-Szmeke7098b62012-11-13 18:39:18 +01008#
9# systemd is free software; you can redistribute it and/or modify it
10# under the terms of the GNU Lesser General Public License as published by
11# the Free Software Foundation; either version 2.1 of the License, or
12# (at your option) any later version.
13#
14# systemd is distributed in the hope that it will be useful, but
15# WITHOUT ANY WARRANTY; without even the implied warranty of
16# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17# Lesser General Public License for more details.
18#
19# You should have received a copy of the GNU Lesser General Public License
20# along with systemd; If not, see <http://www.gnu.org/licenses/>.
21
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +020022import sys
23import collections
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -050024import re
Zbigniew Jędrzejewski-Szmek1c6c3ef2017-07-02 20:26:32 -040025from xml_helper import xml_parse, xml_print, tree
Zbigniew Jędrzejewski-Szmek827f70e2013-05-29 22:31:20 -040026from copy import deepcopy
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +020027
28TEMPLATE = '''\
Zbigniew Jędrzejewski-Szmek56ba3c72013-02-02 22:47:47 -050029<refentry id="systemd.directives" conditional="HAVE_PYTHON">
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +020030
31 <refentryinfo>
32 <title>systemd.directives</title>
33 <productname>systemd</productname>
34
35 <authorgroup>
36 <author>
37 <contrib>Developer</contrib>
38 <firstname>Zbigniew</firstname>
39 <surname>Jędrzejewski-Szmek</surname>
40 <email>zbyszek@in.waw.pl</email>
41 </author>
42 </authorgroup>
43 </refentryinfo>
44
45 <refmeta>
46 <refentrytitle>systemd.directives</refentrytitle>
Zbigniew Jędrzejewski-Szmek9cc2c8b2013-01-14 22:08:33 -050047 <manvolnum>7</manvolnum>
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +020048 </refmeta>
49
50 <refnamediv>
51 <refname>systemd.directives</refname>
52 <refpurpose>Index of configuration directives</refpurpose>
53 </refnamediv>
54
55 <refsect1>
56 <title>Unit directives</title>
57
58 <para>Directives for configuring units, used in unit
59 files.</para>
60
61 <variablelist id='unit-directives' />
62 </refsect1>
Zbigniew Jędrzejewski-Szmeke1abd3e2012-09-16 11:11:34 +020063
64 <refsect1>
Zbigniew Jędrzejewski-Szmek08177c82013-01-14 21:58:22 -050065 <title>Options on the kernel command line</title>
66
67 <para>Kernel boot options for configuring the behaviour of the
68 systemd process.</para>
69
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -050070 <variablelist id='kernel-commandline-options' />
Zbigniew Jędrzejewski-Szmek08177c82013-01-14 21:58:22 -050071 </refsect1>
72
73 <refsect1>
74 <title>Environment variables</title>
75
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -050076 <para>Environment variables understood by the systemd
77 manager and other programs.</para>
Zbigniew Jędrzejewski-Szmek08177c82013-01-14 21:58:22 -050078
79 <variablelist id='environment-variables' />
80 </refsect1>
81
82 <refsect1>
Zbigniew Jędrzejewski-Szmeke1abd3e2012-09-16 11:11:34 +020083 <title>UDEV directives</title>
84
85 <para>Directives for configuring systemd units through the
86 udev database.</para>
87
88 <variablelist id='udev-directives' />
89 </refsect1>
Zbigniew Jędrzejewski-Szmekf6c2e282012-08-10 19:35:43 +020090
91 <refsect1>
Tom Gundersen1f068072013-11-10 19:33:18 +010092 <title>Network directives</title>
93
94 <para>Directives for configuring network links through the
Tom Gundersen46b09252013-11-10 20:52:53 +010095 net-setup-link udev builtin and networks through
96 systemd-networkd.</para>
Tom Gundersen1f068072013-11-10 19:33:18 +010097
98 <variablelist id='network-directives' />
99 </refsect1>
100
101 <refsect1>
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500102 <title>Journal fields</title>
Zbigniew Jędrzejewski-Szmekf6c2e282012-08-10 19:35:43 +0200103
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500104 <para>Fields in the journal events with a well known meaning.</para>
Zbigniew Jędrzejewski-Szmekf6c2e282012-08-10 19:35:43 +0200105
106 <variablelist id='journal-directives' />
107 </refsect1>
Zbigniew Jędrzejewski-Szmek4a431c92013-01-14 20:18:36 -0500108
109 <refsect1>
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500110 <title>PAM configuration directives</title>
111
112 <para>Directives for configuring PAM behaviour.</para>
113
114 <variablelist id='pam-directives' />
115 </refsect1>
116
117 <refsect1>
Zbigniew Jędrzejewski-Szmek63b03c02014-06-30 09:27:16 -0400118 <title><filename>/etc/crypttab</filename> and
119 <filename>/etc/fstab</filename> options</title>
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500120
121 <para>Options which influence mounted filesystems and
122 encrypted volumes.</para>
123
Zbigniew Jędrzejewski-Szmek63b03c02014-06-30 09:27:16 -0400124 <variablelist id='fstab-options' />
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500125 </refsect1>
126
127 <refsect1>
128 <title>System manager directives</title>
129
130 <para>Directives for configuring the behaviour of the
131 systemd process.</para>
132
133 <variablelist id='systemd-directives' />
134 </refsect1>
135
136 <refsect1>
Lennart Poettering81c7dd82014-11-06 20:06:30 +0100137 <title>command line options</title>
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500138
139 <para>Command-line options accepted by programs in the
140 systemd suite.</para>
141
142 <variablelist id='options' />
143 </refsect1>
144
145 <refsect1>
Zbigniew Jędrzejewski-Szmek785a51e2013-06-26 19:48:19 -0400146 <title>Constants</title>
147
148 <para>Various constant used and/or defined by systemd.</para>
149
150 <variablelist id='constants' />
151 </refsect1>
152
153 <refsect1>
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500154 <title>Miscellaneous options and directives</title>
155
156 <para>Other configuration elements which don't fit in
157 any of the above groups.</para>
158
159 <variablelist id='miscellaneous' />
160 </refsect1>
161
162 <refsect1>
Zbigniew Jędrzejewski-Szmeka4e0b942013-02-13 21:51:31 -0500163 <title>Files and directories</title>
164
165 <para>Paths and file names referred to in the
166 documentation.</para>
167
168 <variablelist id='filenames' />
169 </refsect1>
170
171 <refsect1>
Zbigniew Jędrzejewski-Szmek0acfdd62013-01-14 21:34:19 -0500172 <title>Colophon</title>
173 <para id='colophon' />
174 </refsect1>
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200175</refentry>
176'''
177
Zbigniew Jędrzejewski-Szmek0acfdd62013-01-14 21:34:19 -0500178COLOPHON = '''\
179This index contains {count} entries in {sections} sections,
180referring to {pages} individual manual pages.
181'''
182
Zbigniew Jędrzejewski-Szmekd970bd62013-01-26 11:27:35 -0500183def _extract_directives(directive_groups, formatting, page):
Zbigniew Jędrzejewski-Szmek1a13e312013-03-29 14:22:27 -0400184 t = xml_parse(page)
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200185 section = t.find('./refmeta/manvolnum').text
186 pagename = t.find('./refmeta/refentrytitle').text
Zbigniew Jędrzejewski-Szmeka4e0b942013-02-13 21:51:31 -0500187
188 storopt = directive_groups['options']
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200189 for variablelist in t.iterfind('.//variablelist'):
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500190 klass = variablelist.attrib.get('class')
191 storvar = directive_groups[klass or 'miscellaneous']
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500192 # <option>s go in OPTIONS, unless class is specified
193 for xpath, stor in (('./varlistentry/term/varname', storvar),
194 ('./varlistentry/term/option',
195 storvar if klass else storopt)):
196 for name in variablelist.iterfind(xpath):
197 text = re.sub(r'([= ]).*', r'\1', name.text).rstrip()
198 stor[text].append((pagename, section))
Zbigniew Jędrzejewski-Szmekd970bd62013-01-26 11:27:35 -0500199 if text not in formatting:
200 # use element as formatted display
Zbigniew Jędrzejewski-Szmek699ad6c2013-02-27 21:31:02 -0500201 if name.text[-1] in '= ':
202 name.clear()
203 else:
204 name.tail = ''
Zbigniew Jędrzejewski-Szmekd970bd62013-01-26 11:27:35 -0500205 name.text = text
206 formatting[text] = name
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200207
Zbigniew Jędrzejewski-Szmeka4e0b942013-02-13 21:51:31 -0500208 storfile = directive_groups['filenames']
Zbigniew Jędrzejewski-Szmek845c5322013-05-03 00:55:20 -0400209 for xpath, absolute_only in (('.//refsynopsisdiv//filename', False),
210 ('.//refsynopsisdiv//command', False),
211 ('.//filename', True)):
Zbigniew Jędrzejewski-Szmeka4e0b942013-02-13 21:51:31 -0500212 for name in t.iterfind(xpath):
Zbigniew Jędrzejewski-Szmek845c5322013-05-03 00:55:20 -0400213 if absolute_only and not (name.text and name.text.startswith('/')):
214 continue
215 if name.attrib.get('noindex'):
216 continue
Zbigniew Jędrzejewski-Szmeka4e0b942013-02-13 21:51:31 -0500217 name.tail = ''
218 if name.text:
Zbigniew Jędrzejewski-Szmek845c5322013-05-03 00:55:20 -0400219 if name.text.endswith('*'):
220 name.text = name.text[:-1]
Zbigniew Jędrzejewski-Szmeka4e0b942013-02-13 21:51:31 -0500221 if not name.text.startswith('.'):
222 text = name.text.partition(' ')[0]
223 if text != name.text:
224 name.clear()
225 name.text = text
Zbigniew Jędrzejewski-Szmek845c5322013-05-03 00:55:20 -0400226 if text.endswith('/'):
227 text = text[:-1]
Zbigniew Jędrzejewski-Szmeka4e0b942013-02-13 21:51:31 -0500228 storfile[text].append((pagename, section))
229 if text not in formatting:
230 # use element as formatted display
231 formatting[text] = name
232 else:
233 text = ' '.join(name.itertext())
234 storfile[text].append((pagename, section))
235 formatting[text] = name
236
Zbigniew Jędrzejewski-Szmek785a51e2013-06-26 19:48:19 -0400237 storfile = directive_groups['constants']
238 for name in t.iterfind('.//constant'):
239 if name.attrib.get('noindex'):
240 continue
241 name.tail = ''
242 if name.text.startswith('('): # a cast, strip it
243 name.text = name.text.partition(' ')[2]
244 storfile[name.text].append((pagename, section))
245 formatting[name.text] = name
246
Zbigniew Jędrzejewski-Szmekd970bd62013-01-26 11:27:35 -0500247def _make_section(template, name, directives, formatting):
Zbigniew Jędrzejewski-Szmekeeb019b2013-01-14 21:02:49 -0500248 varlist = template.find(".//*[@id='{}']".format(name))
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200249 for varname, manpages in sorted(directives.items()):
250 entry = tree.SubElement(varlist, 'varlistentry')
Zbigniew Jędrzejewski-Szmekd970bd62013-01-26 11:27:35 -0500251 term = tree.SubElement(entry, 'term')
Zbigniew Jędrzejewski-Szmek827f70e2013-05-29 22:31:20 -0400252 display = deepcopy(formatting[varname])
253 term.append(display)
Zbigniew Jędrzejewski-Szmekd970bd62013-01-26 11:27:35 -0500254
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200255 para = tree.SubElement(tree.SubElement(entry, 'listitem'), 'para')
256
257 b = None
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500258 for manpage, manvolume in sorted(set(manpages)):
Zbigniew Jędrzejewski-Szmek827f70e2013-05-29 22:31:20 -0400259 if b is not None:
260 b.tail = ', '
261 b = tree.SubElement(para, 'citerefentry')
262 c = tree.SubElement(b, 'refentrytitle')
263 c.text = manpage
Zbigniew Jędrzejewski-Szmek958caa52015-11-22 23:43:36 -0500264 c.attrib['target'] = varname
Zbigniew Jędrzejewski-Szmek827f70e2013-05-29 22:31:20 -0400265 d = tree.SubElement(b, 'manvolnum')
266 d.text = manvolume
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200267 entry.tail = '\n\n'
268
Zbigniew Jędrzejewski-Szmek0acfdd62013-01-14 21:34:19 -0500269def _make_colophon(template, groups):
270 count = 0
271 pages = set()
272 for group in groups:
273 count += len(group)
274 for pagelist in group.values():
275 pages |= set(pagelist)
276
277 para = template.find(".//para[@id='colophon']")
278 para.text = COLOPHON.format(count=count,
279 sections=len(groups),
280 pages=len(pages))
281
Zbigniew Jędrzejewski-Szmekd970bd62013-01-26 11:27:35 -0500282def _make_page(template, directive_groups, formatting):
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200283 """Create an XML tree from directive_groups.
284
285 directive_groups = {
286 'class': {'variable': [('manpage', 'manvolume'), ...],
287 'variable2': ...},
288 ...
289 }
290 """
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200291 for name, directives in directive_groups.items():
Zbigniew Jędrzejewski-Szmek827f70e2013-05-29 22:31:20 -0400292 _make_section(template, name, directives, formatting)
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200293
Zbigniew Jędrzejewski-Szmek0acfdd62013-01-14 21:34:19 -0500294 _make_colophon(template, directive_groups.values())
295
Zbigniew Jędrzejewski-Szmekeeb019b2013-01-14 21:02:49 -0500296 return template
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200297
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500298def make_page(*xml_files):
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200299 "Extract directives from xml_files and return XML index tree."
Zbigniew Jędrzejewski-Szmekeeb019b2013-01-14 21:02:49 -0500300 template = tree.fromstring(TEMPLATE)
301 names = [vl.get('id') for vl in template.iterfind('.//variablelist')]
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200302 directive_groups = {name:collections.defaultdict(list)
Zbigniew Jędrzejewski-Szmekeeb019b2013-01-14 21:02:49 -0500303 for name in names}
Zbigniew Jędrzejewski-Szmekd970bd62013-01-26 11:27:35 -0500304 formatting = {}
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200305 for page in xml_files:
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500306 try:
Zbigniew Jędrzejewski-Szmekd970bd62013-01-26 11:27:35 -0500307 _extract_directives(directive_groups, formatting, page)
Zbigniew Jędrzejewski-Szmekccc9a4f2013-01-26 10:47:16 -0500308 except Exception:
309 raise ValueError("failed to process " + page)
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200310
Zbigniew Jędrzejewski-Szmekd970bd62013-01-26 11:27:35 -0500311 return _make_page(template, directive_groups, formatting)
Zbigniew Jędrzejewski-Szmekd9cfd692012-08-09 18:08:14 +0200312
313if __name__ == '__main__':
Zbigniew Jędrzejewski-Szmek1a13e312013-03-29 14:22:27 -0400314 with open(sys.argv[1], 'wb') as f:
315 f.write(xml_print(make_page(*sys.argv[2:])))