diff options
Diffstat (limited to 'make-directive-index.py')
| -rwxr-xr-x | make-directive-index.py | 215 |
1 files changed, 178 insertions, 37 deletions
diff --git a/make-directive-index.py b/make-directive-index.py index eaf7019a2b..396947b303 100755 --- a/make-directive-index.py +++ b/make-directive-index.py @@ -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 @@ -19,10 +19,11 @@ import sys import collections -import xml.etree.ElementTree as tree +import re +from xml_helper import * TEMPLATE = '''\ -<refentry id="systemd.directives"> +<refentry id="systemd.directives" conditional="HAVE_PYTHON"> <refentryinfo> <title>systemd.directives</title> @@ -40,7 +41,7 @@ TEMPLATE = '''\ <refmeta> <refentrytitle>systemd.directives</refentrytitle> - <manvolnum>5</manvolnum> + <manvolnum>7</manvolnum> </refmeta> <refnamediv> @@ -58,12 +59,21 @@ TEMPLATE = '''\ </refsect1> <refsect1> - <title>System manager directives</title> + <title>Options on the kernel command line</title> - <para>Directives for configuring the behaviour of the + <para>Kernel boot options for configuring the behaviour of the systemd process.</para> - <variablelist id='systemd-directives' /> + <variablelist id='kernel-commandline-options' /> + </refsect1> + + <refsect1> + <title>Environment variables</title> + + <para>Environment variables understood by the systemd + manager and other programs.</para> + + <variablelist id='environment-variables' /> </refsect1> <refsect1> @@ -76,37 +86,152 @@ 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> + + <para>Directives for configuring the behaviour of the + systemd-bootchart process.</para> + + <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>Files and directories</title> + + <para>Paths and file names referred to in the + documentation.</para> + + <variablelist id='filenames' /> + </refsect1> + + <refsect1> + <title>Colophon</title> + <para id='colophon' /> + </refsect1> </refentry> ''' -def _extract_directives(directive_groups, page): - t = tree.parse(page) +COLOPHON = '''\ +This index contains {count} entries in {sections} sections, +referring to {pages} individual manual pages. +''' + +def _extract_directives(directive_groups, formatting, page): + t = xml_parse(page) section = t.find('./refmeta/manvolnum').text pagename = t.find('./refmeta/refentrytitle').text + + storopt = directive_groups['options'] 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)) - -def _make_section(refentry, name, directives): - varlist = refentry.find(".//*[@id='{}']".format(name)) + klass = variablelist.attrib.get('class') + storvar = directive_groups[klass or 'miscellaneous'] + # <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)) + if text not in formatting: + # use element as formatted display + if name.text[-1] in '= ': + name.clear() + else: + name.tail = '' + name.text = text + formatting[text] = name + + storfile = directive_groups['filenames'] + for xpath, absolute_only in (('.//refsynopsisdiv//filename', False), + ('.//refsynopsisdiv//command', False), + ('.//filename', True)): + for name in t.iterfind(xpath): + if absolute_only and not (name.text and name.text.startswith('/')): + continue + if name.attrib.get('noindex'): + continue + name.tail = '' + if name.text: + if name.text.endswith('*'): + name.text = name.text[:-1] + if not name.text.startswith('.'): + text = name.text.partition(' ')[0] + if text != name.text: + name.clear() + name.text = text + if text.endswith('/'): + text = text[:-1] + storfile[text].append((pagename, section)) + if text not in formatting: + # use element as formatted display + formatting[text] = name + else: + text = ' '.join(name.itertext()) + storfile[text].append((pagename, section)) + formatting[text] = name + +def _make_section(template, name, directives, formatting): + varlist = template.find(".//*[@id='{}']".format(name)) for varname, manpages in sorted(directives.items()): entry = tree.SubElement(varlist, 'varlistentry') - a = tree.SubElement(tree.SubElement(entry, 'term'), 'varname') - a.text = varname + term = tree.SubElement(entry, 'term') + term.append(formatting[varname]) + 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') @@ -116,7 +241,20 @@ def _make_section(refentry, name, directives): d.text = manvolume entry.tail = '\n\n' -def _make_page(directive_groups): +def _make_colophon(template, groups): + count = 0 + pages = set() + for group in groups: + count += len(group) + for pagelist in group.values(): + pages |= set(pagelist) + + para = template.find(".//para[@id='colophon']") + para.text = COLOPHON.format(count=count, + sections=len(groups), + pages=len(pages)) + +def _make_page(template, directive_groups, formatting): """Create an XML tree from directive_groups. directive_groups = { @@ -125,25 +263,28 @@ def _make_page(directive_groups): ... } """ - refentry = tree.fromstring(TEMPLATE) - for name, directives in directive_groups.items(): - _make_section(refentry, name, directives) + _make_section(template, name, directives, formatting) + + _make_colophon(template, directive_groups.values()) - return refentry + 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 ['unit-directives', - 'udev-directives', - 'systemd-directives', - 'journal-directives', - ]} + for name in names} + formatting = {} for page in xml_files: - _extract_directives(directive_groups, page) + try: + _extract_directives(directive_groups, formatting, page) + except Exception: + raise ValueError("failed to process " + page) - return _make_page(directive_groups) + return _make_page(template, directive_groups, formatting) if __name__ == '__main__': - tree.dump(make_page(sys.argv[1:])) + with open(sys.argv[1], 'wb') as f: + f.write(xml_print(make_page(*sys.argv[2:]))) |