chiark / gitweb /
bus: remove KDBUS_MAKE_ACCESS_WORLD, remove (n_payload > 2) check
[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 import re
23 from xml_helper import *
24
25 TEMPLATE = '''\
26 <refentry id="systemd.directives" conditional="HAVE_PYTHON">
27
28         <refentryinfo>
29                 <title>systemd.directives</title>
30                 <productname>systemd</productname>
31
32                 <authorgroup>
33                         <author>
34                                 <contrib>Developer</contrib>
35                                 <firstname>Zbigniew</firstname>
36                                 <surname>JÄ™drzejewski-Szmek</surname>
37                                 <email>zbyszek@in.waw.pl</email>
38                         </author>
39                 </authorgroup>
40         </refentryinfo>
41
42         <refmeta>
43                 <refentrytitle>systemd.directives</refentrytitle>
44                 <manvolnum>7</manvolnum>
45         </refmeta>
46
47         <refnamediv>
48                 <refname>systemd.directives</refname>
49                 <refpurpose>Index of configuration directives</refpurpose>
50         </refnamediv>
51
52         <refsect1>
53                 <title>Unit directives</title>
54
55                 <para>Directives for configuring units, used in unit
56                 files.</para>
57
58                 <variablelist id='unit-directives' />
59         </refsect1>
60
61         <refsect1>
62                 <title>Options on the kernel command line</title>
63
64                 <para>Kernel boot options for configuring the behaviour of the
65                 systemd process.</para>
66
67                 <variablelist id='kernel-commandline-options' />
68         </refsect1>
69
70         <refsect1>
71                 <title>Environment variables</title>
72
73                 <para>Environment variables understood by the systemd
74                 manager and other programs.</para>
75
76                 <variablelist id='environment-variables' />
77         </refsect1>
78
79         <refsect1>
80                 <title>UDEV directives</title>
81
82                 <para>Directives for configuring systemd units through the
83                 udev database.</para>
84
85                 <variablelist id='udev-directives' />
86         </refsect1>
87
88         <refsect1>
89                 <title>Journal fields</title>
90
91                 <para>Fields in the journal events with a well known meaning.</para>
92
93                 <variablelist id='journal-directives' />
94         </refsect1>
95
96         <refsect1>
97                 <title>PAM configuration directives</title>
98
99                 <para>Directives for configuring PAM behaviour.</para>
100
101                 <variablelist id='pam-directives' />
102         </refsect1>
103
104         <refsect1>
105                 <title>crypttab options</title>
106
107                 <para>Options which influence mounted filesystems and
108                 encrypted volumes.</para>
109
110                 <variablelist id='crypttab-options' />
111         </refsect1>
112
113         <refsect1>
114                 <title>System manager directives</title>
115
116                 <para>Directives for configuring the behaviour of the
117                 systemd process.</para>
118
119                 <variablelist id='systemd-directives' />
120         </refsect1>
121
122         <refsect1>
123                 <title>bootchart.conf directives</title>
124
125                 <para>Directives for configuring the behaviour of the
126                 systemd-bootchart process.</para>
127
128                 <variablelist id='bootchart-directives' />
129         </refsect1>
130
131         <refsect1>
132                 <title>command-line options</title>
133
134                 <para>Command-line options accepted by programs in the
135                 systemd suite.</para>
136
137                 <variablelist id='options' />
138         </refsect1>
139
140         <refsect1>
141                 <title>Miscellaneous options and directives</title>
142
143                 <para>Other configuration elements which don't fit in
144                 any of the above groups.</para>
145
146                 <variablelist id='miscellaneous' />
147         </refsect1>
148
149         <refsect1>
150                 <title>Files and directories</title>
151
152                 <para>Paths and file names referred to in the
153                 documentation.</para>
154
155                 <variablelist id='filenames' />
156         </refsect1>
157
158         <refsect1>
159                 <title>Colophon</title>
160                 <para id='colophon' />
161         </refsect1>
162 </refentry>
163 '''
164
165 COLOPHON = '''\
166 This index contains {count} entries in {sections} sections,
167 referring to {pages} individual manual pages.
168 '''
169
170 def _extract_directives(directive_groups, formatting, page):
171     t = xml_parse(page)
172     section = t.find('./refmeta/manvolnum').text
173     pagename = t.find('./refmeta/refentrytitle').text
174
175     storopt = directive_groups['options']
176     for variablelist in t.iterfind('.//variablelist'):
177         klass = variablelist.attrib.get('class')
178         storvar = directive_groups[klass or 'miscellaneous']
179         # <option>s go in OPTIONS, unless class is specified
180         for xpath, stor in (('./varlistentry/term/varname', storvar),
181                             ('./varlistentry/term/option',
182                              storvar if klass else storopt)):
183             for name in variablelist.iterfind(xpath):
184                 text = re.sub(r'([= ]).*', r'\1', name.text).rstrip()
185                 stor[text].append((pagename, section))
186                 if text not in formatting:
187                     # use element as formatted display
188                     if name.text[-1] in '= ':
189                         name.clear()
190                     else:
191                         name.tail = ''
192                     name.text = text
193                     formatting[text] = name
194
195     storfile = directive_groups['filenames']
196     for xpath, absolute_only in (('.//refsynopsisdiv//filename', False),
197                                  ('.//refsynopsisdiv//command', False),
198                                  ('.//filename', True)):
199         for name in t.iterfind(xpath):
200             if absolute_only and not (name.text and name.text.startswith('/')):
201                 continue
202             if name.attrib.get('noindex'):
203                 continue
204             name.tail = ''
205             if name.text:
206                 if name.text.endswith('*'):
207                     name.text = name.text[:-1]
208                 if not name.text.startswith('.'):
209                     text = name.text.partition(' ')[0]
210                     if text != name.text:
211                         name.clear()
212                         name.text = text
213                     if text.endswith('/'):
214                         text = text[:-1]
215                     storfile[text].append((pagename, section))
216                     if text not in formatting:
217                         # use element as formatted display
218                         formatting[text] = name
219             else:
220                 text = ' '.join(name.itertext())
221                 storfile[text].append((pagename, section))
222                 formatting[text] = name
223
224 def _make_section(template, name, directives, formatting):
225     varlist = template.find(".//*[@id='{}']".format(name))
226     for varname, manpages in sorted(directives.items()):
227         entry = tree.SubElement(varlist, 'varlistentry')
228         term = tree.SubElement(entry, 'term')
229         term.append(formatting[varname])
230
231         para = tree.SubElement(tree.SubElement(entry, 'listitem'), 'para')
232
233         b = None
234         for manpage, manvolume in sorted(set(manpages)):
235                 if b is not None:
236                         b.tail = ', '
237                 b = tree.SubElement(para, 'citerefentry')
238                 c = tree.SubElement(b, 'refentrytitle')
239                 c.text = manpage
240                 d = tree.SubElement(b, 'manvolnum')
241                 d.text = manvolume
242         entry.tail = '\n\n'
243
244 def _make_colophon(template, groups):
245     count = 0
246     pages = set()
247     for group in groups:
248         count += len(group)
249         for pagelist in group.values():
250             pages |= set(pagelist)
251
252     para = template.find(".//para[@id='colophon']")
253     para.text = COLOPHON.format(count=count,
254                                 sections=len(groups),
255                                 pages=len(pages))
256
257 def _make_page(template, directive_groups, formatting):
258     """Create an XML tree from directive_groups.
259
260     directive_groups = {
261        'class': {'variable': [('manpage', 'manvolume'), ...],
262                  'variable2': ...},
263        ...
264     }
265     """
266     for name, directives in directive_groups.items():
267             _make_section(template, name, directives, formatting)
268
269     _make_colophon(template, directive_groups.values())
270
271     return template
272
273 def make_page(*xml_files):
274     "Extract directives from xml_files and return XML index tree."
275     template = tree.fromstring(TEMPLATE)
276     names = [vl.get('id') for vl in template.iterfind('.//variablelist')]
277     directive_groups = {name:collections.defaultdict(list)
278                         for name in names}
279     formatting = {}
280     for page in xml_files:
281         try:
282             _extract_directives(directive_groups, formatting, page)
283         except Exception:
284             raise ValueError("failed to process " + page)
285
286     return _make_page(template, directive_groups, formatting)
287
288 if __name__ == '__main__':
289     with open(sys.argv[1], 'wb') as f:
290         f.write(xml_print(make_page(*sys.argv[2:])))