tools/make-directive-index.py

   1 #!/usr/bin/env python3
   2 # SPDX-License-Identifier: LGPL-2.1+
   3
   4 import sys
   5 import collections
   6 import re
   7 from xml_helper import xml_parse, xml_print, tree
   8 from copy import deepcopy
   9
  10 COLOPHON = '''\
  11 This index contains {count} entries in {sections} sections,
  12 referring to {pages} individual manual pages.
  13 '''
  14
  15 def _extract_directives(directive_groups, formatting, page):
  16     t = xml_parse(page)
  17     section = t.find('./refmeta/manvolnum').text
  18     pagename = t.find('./refmeta/refentrytitle').text
  19
  20     storopt = directive_groups['options']
  21     for variablelist in t.iterfind('.//variablelist'):
  22         klass = variablelist.attrib.get('class')
  23         searchpath = variablelist.attrib.get('xpath','./varlistentry/term/varname')
  24         storvar = directive_groups[klass or 'miscellaneous']
  25         # <option>s go in OPTIONS, unless class is specified
  26         for xpath, stor in ((searchpath, storvar),
  27                             ('./varlistentry/term/option',
  28                              storvar if klass else storopt)):
  29             for name in variablelist.iterfind(xpath):
  30                 text = re.sub(r'([= ]).*', r'\1', name.text).rstrip()
  31                 if text.startswith('-'):
  32                     # for options, merge options with and without mandatory arg
  33                     text = text.partition('=')[0]
  34                 stor[text].append((pagename, section))
  35                 if text not in formatting:
  36                     # use element as formatted display
  37                     if name.text[-1] in "= '":
  38                         name.clear()
  39                     else:
  40                         name.tail = ''
  41                     name.text = text
  42                     formatting[text] = name
  43         extra = variablelist.attrib.get('extra-ref')
  44         if extra:
  45             stor[extra].append((pagename, section))
  46             if extra not in formatting:
  47                 elt = tree.Element("varname")
  48                 elt.text= extra
  49                 formatting[extra] = elt
  50
  51     storfile = directive_groups['filenames']
  52     for xpath, absolute_only in (('.//refsynopsisdiv//filename', False),
  53                                  ('.//refsynopsisdiv//command', False),
  54                                  ('.//filename', True)):
  55         for name in t.iterfind(xpath):
  56             if absolute_only and not (name.text and name.text.startswith('/')):
  57                 continue
  58             if name.attrib.get('index') == 'false':
  59                 continue
  60             name.tail = ''
  61             if name.text:
  62                 if name.text.endswith('*'):
  63                     name.text = name.text[:-1]
  64                 if not name.text.startswith('.'):
  65                     text = name.text.partition(' ')[0]
  66                     if text != name.text:
  67                         name.clear()
  68                         name.text = text
  69                     if text.endswith('/'):
  70                         text = text[:-1]
  71                     storfile[text].append((pagename, section))
  72                     if text not in formatting:
  73                         # use element as formatted display
  74                         formatting[text] = name
  75             else:
  76                 text = ' '.join(name.itertext())
  77                 storfile[text].append((pagename, section))
  78                 formatting[text] = name
  79
  80     storfile = directive_groups['constants']
  81     for name in t.iterfind('.//constant'):
  82         if name.attrib.get('index') == 'false':
  83             continue
  84         name.tail = ''
  85         if name.text.startswith('('): # a cast, strip it
  86             name.text = name.text.partition(' ')[2]
  87         storfile[name.text].append((pagename, section))
  88         formatting[name.text] = name
  89
  90     storfile = directive_groups['specifiers']
  91     for name in t.iterfind(".//table[@class='specifiers']//entry/literal"):
  92         if name.text[0] != '%' or name.getparent().text is not None:
  93             continue
  94         if name.attrib.get('index') == 'false':
  95             continue
  96         storfile[name.text].append((pagename, section))
  97         formatting[name.text] = name
  98
  99 def _make_section(template, name, directives, formatting):
 100     varlist = template.find(".//*[@id='{}']".format(name))
 101     for varname, manpages in sorted(directives.items()):
 102         entry = tree.SubElement(varlist, 'varlistentry')
 103         term = tree.SubElement(entry, 'term')
 104         display = deepcopy(formatting[varname])
 105         term.append(display)
 106
 107         para = tree.SubElement(tree.SubElement(entry, 'listitem'), 'para')
 108
 109         b = None
 110         for manpage, manvolume in sorted(set(manpages)):
 111             if b is not None:
 112                 b.tail = ', '
 113             b = tree.SubElement(para, 'citerefentry')
 114             c = tree.SubElement(b, 'refentrytitle')
 115             c.text = manpage
 116             c.attrib['target'] = varname
 117             d = tree.SubElement(b, 'manvolnum')
 118             d.text = manvolume
 119         entry.tail = '\n\n'
 120
 121 def _make_colophon(template, groups):
 122     count = 0
 123     pages = set()
 124     for group in groups:
 125         count += len(group)
 126         for pagelist in group.values():
 127             pages |= set(pagelist)
 128
 129     para = template.find(".//para[@id='colophon']")
 130     para.text = COLOPHON.format(count=count,
 131                                 sections=len(groups),
 132                                 pages=len(pages))
 133
 134 def _make_page(template, directive_groups, formatting):
 135     """Create an XML tree from directive_groups.
 136
 137     directive_groups = {
 138        'class': {'variable': [('manpage', 'manvolume'), ...],
 139                  'variable2': ...},
 140        ...
 141     }
 142     """
 143     for name, directives in directive_groups.items():
 144         _make_section(template, name, directives, formatting)
 145
 146     _make_colophon(template, directive_groups.values())
 147
 148     return template
 149
 150 def make_page(template_path, xml_files):
 151     "Extract directives from xml_files and return XML index tree."
 152     template = xml_parse(template_path)
 153     names = [vl.get('id') for vl in template.iterfind('.//variablelist')]
 154     directive_groups = {name:collections.defaultdict(list)
 155                         for name in names}
 156     formatting = {}
 157     for page in xml_files:
 158         try:
 159             _extract_directives(directive_groups, formatting, page)
 160         except Exception:
 161             raise ValueError("failed to process " + page)
 162
 163     return _make_page(template, directive_groups, formatting)
 164
 165 if __name__ == '__main__':
 166     with open(sys.argv[1], 'wb') as f:
 167         template_path = sys.argv[2]
 168         xml_files = sys.argv[3:]
 169         xml = make_page(template_path, xml_files)
 170         f.write(xml_print(xml))