chiark / gitweb /
bus: enforce limits on all client influenced data objects
[elogind.git] / make-directive-index.py
1 #  -*- Mode: python; coding: utf-8; indent-tabs-mode: nil -*- */
2 #
3 #  This file is part of systemd.
4 #
5 #  Copyright 2012-2013 Zbigniew JÄ™drzejewski-Szmek
6 #
7 #  systemd is free software; you can redistribute it and/or modify it
8 #  under the terms of the GNU Lesser General Public License as published by
9 #  the Free Software Foundation; either version 2.1 of the License, or
10 #  (at your option) any later version.
11 #
12 #  systemd is distributed in the hope that it will be useful, but
13 #  WITHOUT ANY WARRANTY; without even the implied warranty of
14 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 #  Lesser General Public License for more details.
16 #
17 #  You should have received a copy of the GNU Lesser General Public License
18 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
19
20 import sys
21 import collections
22 try:
23     from lxml import etree as tree
24     PRETTY = dict(pretty_print=True)
25 except ImportError:
26     import xml.etree.ElementTree as tree
27     PRETTY = {}
28 import re
29
30 TEMPLATE = '''\
31 <refentry id="systemd.directives" conditional="HAVE_PYTHON">
32
33         <refentryinfo>
34                 <title>systemd.directives</title>
35                 <productname>systemd</productname>
36
37                 <authorgroup>
38                         <author>
39                                 <contrib>Developer</contrib>
40                                 <firstname>Zbigniew</firstname>
41                                 <surname>JÄ™drzejewski-Szmek</surname>
42                                 <email>zbyszek@in.waw.pl</email>
43                         </author>
44                 </authorgroup>
45         </refentryinfo>
46
47         <refmeta>
48                 <refentrytitle>systemd.directives</refentrytitle>
49                 <manvolnum>7</manvolnum>
50         </refmeta>
51
52         <refnamediv>
53                 <refname>systemd.directives</refname>
54                 <refpurpose>Index of configuration directives</refpurpose>
55         </refnamediv>
56
57         <refsect1>
58                 <title>Unit directives</title>
59
60                 <para>Directives for configuring units, used in unit
61                 files.</para>
62
63                 <variablelist id='unit-directives' />
64         </refsect1>
65
66         <refsect1>
67                 <title>Options on the kernel command line</title>
68
69                 <para>Kernel boot options for configuring the behaviour of the
70                 systemd process.</para>
71
72                 <variablelist id='kernel-commandline-options' />
73         </refsect1>
74
75         <refsect1>
76                 <title>Environment variables</title>
77
78                 <para>Environment variables understood by the systemd
79                 manager and other programs.</para>
80
81                 <variablelist id='environment-variables' />
82         </refsect1>
83
84         <refsect1>
85                 <title>UDEV directives</title>
86
87                 <para>Directives for configuring systemd units through the
88                 udev database.</para>
89
90                 <variablelist id='udev-directives' />
91         </refsect1>
92
93         <refsect1>
94                 <title>Journal fields</title>
95
96                 <para>Fields in the journal events with a well known meaning.</para>
97
98                 <variablelist id='journal-directives' />
99         </refsect1>
100
101         <refsect1>
102                 <title>PAM configuration directives</title>
103
104                 <para>Directives for configuring PAM behaviour.</para>
105
106                 <variablelist id='pam-directives' />
107         </refsect1>
108
109         <refsect1>
110                 <title>crypttab options</title>
111
112                 <para>Options which influence mounted filesystems and
113                 encrypted volumes.</para>
114
115                 <variablelist id='crypttab-options' />
116         </refsect1>
117
118         <refsect1>
119                 <title>System manager directives</title>
120
121                 <para>Directives for configuring the behaviour of the
122                 systemd process.</para>
123
124                 <variablelist id='systemd-directives' />
125         </refsect1>
126
127         <refsect1>
128                 <title>bootchart.conf directives</title>
129
130                 <para>Directives for configuring the behaviour of the
131                 systemd-bootchart process.</para>
132
133                 <variablelist id='bootchart-directives' />
134         </refsect1>
135
136         <refsect1>
137                 <title>command-line options</title>
138
139                 <para>Command-line options accepted by programs in the
140                 systemd suite.</para>
141
142                 <variablelist id='options' />
143         </refsect1>
144
145         <refsect1>
146                 <title>Miscellaneous options and directives</title>
147
148                 <para>Other configuration elements which don't fit in
149                 any of the above groups.</para>
150
151                 <variablelist id='miscellaneous' />
152         </refsect1>
153
154         <refsect1>
155                 <title>Files and directories</title>
156
157                 <para>Paths and file names referred to in the
158                 documentation.</para>
159
160                 <variablelist id='filenames' />
161         </refsect1>
162
163         <refsect1>
164                 <title>Colophon</title>
165                 <para id='colophon' />
166         </refsect1>
167 </refentry>
168 '''
169
170 COLOPHON = '''\
171 This index contains {count} entries in {sections} sections,
172 referring to {pages} individual manual pages.
173 '''
174
175 def _extract_directives(directive_groups, formatting, page):
176     t = tree.parse(page)
177     section = t.find('./refmeta/manvolnum').text
178     pagename = t.find('./refmeta/refentrytitle').text
179
180     storopt = directive_groups['options']
181     for variablelist in t.iterfind('.//variablelist'):
182         klass = variablelist.attrib.get('class')
183         storvar = directive_groups[klass or 'miscellaneous']
184         # <option>s go in OPTIONS, unless class is specified
185         for xpath, stor in (('./varlistentry/term/varname', storvar),
186                             ('./varlistentry/term/option',
187                              storvar if klass else storopt)):
188             for name in variablelist.iterfind(xpath):
189                 text = re.sub(r'([= ]).*', r'\1', name.text).rstrip()
190                 stor[text].append((pagename, section))
191                 if text not in formatting:
192                     # use element as formatted display
193                     if name.text[-1] in '= ':
194                         name.clear()
195                     else:
196                         name.tail = ''
197                     name.text = text
198                     formatting[text] = name
199
200     storfile = directive_groups['filenames']
201     for xpath in ('.//refsynopsisdiv//filename',
202                   './/refsynopsisdiv//command'):
203         for name in t.iterfind(xpath):
204             name.tail = ''
205             if name.text:
206                 if not name.text.startswith('.'):
207                     text = name.text.partition(' ')[0]
208                     if text != name.text:
209                         name.clear()
210                         name.text = text
211                     storfile[text].append((pagename, section))
212                     if text not in formatting:
213                         # use element as formatted display
214                         formatting[text] = name
215             else:
216                 text = ' '.join(name.itertext())
217                 storfile[text].append((pagename, section))
218                 formatting[text] = name
219
220 def _make_section(template, name, directives, formatting):
221     varlist = template.find(".//*[@id='{}']".format(name))
222     for varname, manpages in sorted(directives.items()):
223         entry = tree.SubElement(varlist, 'varlistentry')
224         term = tree.SubElement(entry, 'term')
225         term.append(formatting[varname])
226
227         para = tree.SubElement(tree.SubElement(entry, 'listitem'), 'para')
228
229         b = None
230         for manpage, manvolume in sorted(set(manpages)):
231                 if b is not None:
232                         b.tail = ', '
233                 b = tree.SubElement(para, 'citerefentry')
234                 c = tree.SubElement(b, 'refentrytitle')
235                 c.text = manpage
236                 d = tree.SubElement(b, 'manvolnum')
237                 d.text = manvolume
238         entry.tail = '\n\n'
239
240 def _make_colophon(template, groups):
241     count = 0
242     pages = set()
243     for group in groups:
244         count += len(group)
245         for pagelist in group.values():
246             pages |= set(pagelist)
247
248     para = template.find(".//para[@id='colophon']")
249     para.text = COLOPHON.format(count=count,
250                                 sections=len(groups),
251                                 pages=len(pages))
252
253 def _make_page(template, directive_groups, formatting):
254     """Create an XML tree from directive_groups.
255
256     directive_groups = {
257        'class': {'variable': [('manpage', 'manvolume'), ...],
258                  'variable2': ...},
259        ...
260     }
261     """
262     for name, directives in directive_groups.items():
263             _make_section(template, name, directives, formatting)
264
265     _make_colophon(template, directive_groups.values())
266
267     return template
268
269 def make_page(*xml_files):
270     "Extract directives from xml_files and return XML index tree."
271     template = tree.fromstring(TEMPLATE)
272     names = [vl.get('id') for vl in template.iterfind('.//variablelist')]
273     directive_groups = {name:collections.defaultdict(list)
274                         for name in names}
275     formatting = {}
276     for page in xml_files:
277         try:
278             _extract_directives(directive_groups, formatting, page)
279         except Exception:
280             raise ValueError("failed to process " + page)
281
282     return _make_page(template, directive_groups, formatting)
283
284 if __name__ == '__main__':
285     tree.dump(make_page(*sys.argv[1:]), **PRETTY)