Zbigniew Jędrzejewski-Szmek | e7098b6 | 2012-11-13 18:39:18 +0100 | [diff] [blame] | 1 | # -*- Mode: python; coding: utf-8; indent-tabs-mode: nil -*- */ |
| 2 | # |
| 3 | # This file is part of systemd. |
| 4 | # |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 5 | # Copyright 2012-2013 Zbigniew Jędrzejewski-Szmek |
Zbigniew Jędrzejewski-Szmek | e7098b6 | 2012-11-13 18:39:18 +0100 | [diff] [blame] | 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 | |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 20 | import sys |
| 21 | import collections |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 22 | import re |
Zbigniew Jędrzejewski-Szmek | 1a13e31 | 2013-03-29 14:22:27 -0400 | [diff] [blame] | 23 | from xml_helper import * |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 24 | |
| 25 | TEMPLATE = '''\ |
Zbigniew Jędrzejewski-Szmek | 56ba3c7 | 2013-02-02 22:47:47 -0500 | [diff] [blame] | 26 | <refentry id="systemd.directives" conditional="HAVE_PYTHON"> |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 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> |
Zbigniew Jędrzejewski-Szmek | 9cc2c8b | 2013-01-14 22:08:33 -0500 | [diff] [blame] | 44 | <manvolnum>7</manvolnum> |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 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> |
Zbigniew Jędrzejewski-Szmek | e1abd3e | 2012-09-16 11:11:34 +0200 | [diff] [blame] | 60 | |
| 61 | <refsect1> |
Zbigniew Jędrzejewski-Szmek | 08177c8 | 2013-01-14 21:58:22 -0500 | [diff] [blame] | 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 | |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 67 | <variablelist id='kernel-commandline-options' /> |
Zbigniew Jędrzejewski-Szmek | 08177c8 | 2013-01-14 21:58:22 -0500 | [diff] [blame] | 68 | </refsect1> |
| 69 | |
| 70 | <refsect1> |
| 71 | <title>Environment variables</title> |
| 72 | |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 73 | <para>Environment variables understood by the systemd |
| 74 | manager and other programs.</para> |
Zbigniew Jędrzejewski-Szmek | 08177c8 | 2013-01-14 21:58:22 -0500 | [diff] [blame] | 75 | |
| 76 | <variablelist id='environment-variables' /> |
| 77 | </refsect1> |
| 78 | |
| 79 | <refsect1> |
Zbigniew Jędrzejewski-Szmek | e1abd3e | 2012-09-16 11:11:34 +0200 | [diff] [blame] | 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> |
Zbigniew Jędrzejewski-Szmek | f6c2e28 | 2012-08-10 19:35:43 +0200 | [diff] [blame] | 87 | |
| 88 | <refsect1> |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 89 | <title>Journal fields</title> |
Zbigniew Jędrzejewski-Szmek | f6c2e28 | 2012-08-10 19:35:43 +0200 | [diff] [blame] | 90 | |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 91 | <para>Fields in the journal events with a well known meaning.</para> |
Zbigniew Jędrzejewski-Szmek | f6c2e28 | 2012-08-10 19:35:43 +0200 | [diff] [blame] | 92 | |
| 93 | <variablelist id='journal-directives' /> |
| 94 | </refsect1> |
Zbigniew Jędrzejewski-Szmek | 4a431c9 | 2013-01-14 20:18:36 -0500 | [diff] [blame] | 95 | |
| 96 | <refsect1> |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 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> |
Zbigniew Jędrzejewski-Szmek | 4a431c9 | 2013-01-14 20:18:36 -0500 | [diff] [blame] | 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> |
Zbigniew Jędrzejewski-Szmek | 0acfdd6 | 2013-01-14 21:34:19 -0500 | [diff] [blame] | 130 | |
| 131 | <refsect1> |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 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> |
Zbigniew Jędrzejewski-Szmek | a4e0b94 | 2013-02-13 21:51:31 -0500 | [diff] [blame] | 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> |
Zbigniew Jędrzejewski-Szmek | 0acfdd6 | 2013-01-14 21:34:19 -0500 | [diff] [blame] | 159 | <title>Colophon</title> |
| 160 | <para id='colophon' /> |
| 161 | </refsect1> |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 162 | </refentry> |
| 163 | ''' |
| 164 | |
Zbigniew Jędrzejewski-Szmek | 0acfdd6 | 2013-01-14 21:34:19 -0500 | [diff] [blame] | 165 | COLOPHON = '''\ |
| 166 | This index contains {count} entries in {sections} sections, |
| 167 | referring to {pages} individual manual pages. |
| 168 | ''' |
| 169 | |
Zbigniew Jędrzejewski-Szmek | d970bd6 | 2013-01-26 11:27:35 -0500 | [diff] [blame] | 170 | def _extract_directives(directive_groups, formatting, page): |
Zbigniew Jędrzejewski-Szmek | 1a13e31 | 2013-03-29 14:22:27 -0400 | [diff] [blame] | 171 | t = xml_parse(page) |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 172 | section = t.find('./refmeta/manvolnum').text |
| 173 | pagename = t.find('./refmeta/refentrytitle').text |
Zbigniew Jędrzejewski-Szmek | a4e0b94 | 2013-02-13 21:51:31 -0500 | [diff] [blame] | 174 | |
| 175 | storopt = directive_groups['options'] |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 176 | for variablelist in t.iterfind('.//variablelist'): |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 177 | klass = variablelist.attrib.get('class') |
| 178 | storvar = directive_groups[klass or 'miscellaneous'] |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 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)) |
Zbigniew Jędrzejewski-Szmek | d970bd6 | 2013-01-26 11:27:35 -0500 | [diff] [blame] | 186 | if text not in formatting: |
| 187 | # use element as formatted display |
Zbigniew Jędrzejewski-Szmek | 699ad6c | 2013-02-27 21:31:02 -0500 | [diff] [blame] | 188 | if name.text[-1] in '= ': |
| 189 | name.clear() |
| 190 | else: |
| 191 | name.tail = '' |
Zbigniew Jędrzejewski-Szmek | d970bd6 | 2013-01-26 11:27:35 -0500 | [diff] [blame] | 192 | name.text = text |
| 193 | formatting[text] = name |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 194 | |
Zbigniew Jędrzejewski-Szmek | a4e0b94 | 2013-02-13 21:51:31 -0500 | [diff] [blame] | 195 | storfile = directive_groups['filenames'] |
| 196 | for xpath in ('.//refsynopsisdiv//filename', |
| 197 | './/refsynopsisdiv//command'): |
| 198 | for name in t.iterfind(xpath): |
| 199 | name.tail = '' |
| 200 | if name.text: |
| 201 | if not name.text.startswith('.'): |
| 202 | text = name.text.partition(' ')[0] |
| 203 | if text != name.text: |
| 204 | name.clear() |
| 205 | name.text = text |
| 206 | storfile[text].append((pagename, section)) |
| 207 | if text not in formatting: |
| 208 | # use element as formatted display |
| 209 | formatting[text] = name |
| 210 | else: |
| 211 | text = ' '.join(name.itertext()) |
| 212 | storfile[text].append((pagename, section)) |
| 213 | formatting[text] = name |
| 214 | |
Zbigniew Jędrzejewski-Szmek | d970bd6 | 2013-01-26 11:27:35 -0500 | [diff] [blame] | 215 | def _make_section(template, name, directives, formatting): |
Zbigniew Jędrzejewski-Szmek | eeb019b | 2013-01-14 21:02:49 -0500 | [diff] [blame] | 216 | varlist = template.find(".//*[@id='{}']".format(name)) |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 217 | for varname, manpages in sorted(directives.items()): |
| 218 | entry = tree.SubElement(varlist, 'varlistentry') |
Zbigniew Jędrzejewski-Szmek | d970bd6 | 2013-01-26 11:27:35 -0500 | [diff] [blame] | 219 | term = tree.SubElement(entry, 'term') |
| 220 | term.append(formatting[varname]) |
| 221 | |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 222 | para = tree.SubElement(tree.SubElement(entry, 'listitem'), 'para') |
| 223 | |
| 224 | b = None |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 225 | for manpage, manvolume in sorted(set(manpages)): |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 226 | if b is not None: |
| 227 | b.tail = ', ' |
| 228 | b = tree.SubElement(para, 'citerefentry') |
| 229 | c = tree.SubElement(b, 'refentrytitle') |
| 230 | c.text = manpage |
| 231 | d = tree.SubElement(b, 'manvolnum') |
| 232 | d.text = manvolume |
| 233 | entry.tail = '\n\n' |
| 234 | |
Zbigniew Jędrzejewski-Szmek | 0acfdd6 | 2013-01-14 21:34:19 -0500 | [diff] [blame] | 235 | def _make_colophon(template, groups): |
| 236 | count = 0 |
| 237 | pages = set() |
| 238 | for group in groups: |
| 239 | count += len(group) |
| 240 | for pagelist in group.values(): |
| 241 | pages |= set(pagelist) |
| 242 | |
| 243 | para = template.find(".//para[@id='colophon']") |
| 244 | para.text = COLOPHON.format(count=count, |
| 245 | sections=len(groups), |
| 246 | pages=len(pages)) |
| 247 | |
Zbigniew Jędrzejewski-Szmek | d970bd6 | 2013-01-26 11:27:35 -0500 | [diff] [blame] | 248 | def _make_page(template, directive_groups, formatting): |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 249 | """Create an XML tree from directive_groups. |
| 250 | |
| 251 | directive_groups = { |
| 252 | 'class': {'variable': [('manpage', 'manvolume'), ...], |
| 253 | 'variable2': ...}, |
| 254 | ... |
| 255 | } |
| 256 | """ |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 257 | for name, directives in directive_groups.items(): |
Zbigniew Jędrzejewski-Szmek | d970bd6 | 2013-01-26 11:27:35 -0500 | [diff] [blame] | 258 | _make_section(template, name, directives, formatting) |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 259 | |
Zbigniew Jędrzejewski-Szmek | 0acfdd6 | 2013-01-14 21:34:19 -0500 | [diff] [blame] | 260 | _make_colophon(template, directive_groups.values()) |
| 261 | |
Zbigniew Jędrzejewski-Szmek | eeb019b | 2013-01-14 21:02:49 -0500 | [diff] [blame] | 262 | return template |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 263 | |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 264 | def make_page(*xml_files): |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 265 | "Extract directives from xml_files and return XML index tree." |
Zbigniew Jędrzejewski-Szmek | eeb019b | 2013-01-14 21:02:49 -0500 | [diff] [blame] | 266 | template = tree.fromstring(TEMPLATE) |
| 267 | names = [vl.get('id') for vl in template.iterfind('.//variablelist')] |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 268 | directive_groups = {name:collections.defaultdict(list) |
Zbigniew Jędrzejewski-Szmek | eeb019b | 2013-01-14 21:02:49 -0500 | [diff] [blame] | 269 | for name in names} |
Zbigniew Jędrzejewski-Szmek | d970bd6 | 2013-01-26 11:27:35 -0500 | [diff] [blame] | 270 | formatting = {} |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 271 | for page in xml_files: |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 272 | try: |
Zbigniew Jędrzejewski-Szmek | d970bd6 | 2013-01-26 11:27:35 -0500 | [diff] [blame] | 273 | _extract_directives(directive_groups, formatting, page) |
Zbigniew Jędrzejewski-Szmek | ccc9a4f | 2013-01-26 10:47:16 -0500 | [diff] [blame] | 274 | except Exception: |
| 275 | raise ValueError("failed to process " + page) |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 276 | |
Zbigniew Jędrzejewski-Szmek | d970bd6 | 2013-01-26 11:27:35 -0500 | [diff] [blame] | 277 | return _make_page(template, directive_groups, formatting) |
Zbigniew Jędrzejewski-Szmek | d9cfd69 | 2012-08-09 18:08:14 +0200 | [diff] [blame] | 278 | |
| 279 | if __name__ == '__main__': |
Zbigniew Jędrzejewski-Szmek | 1a13e31 | 2013-03-29 14:22:27 -0400 | [diff] [blame] | 280 | with open(sys.argv[1], 'wb') as f: |
| 281 | f.write(xml_print(make_page(*sys.argv[2:]))) |