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     for name in t.iterfind(".//literal[@class='specifiers']"):
  99         storfile[name.text].append((pagename, section))
 100         formatting[name.text] = name
 101
 102 def _make_section(template, name, directives, formatting):
 103     varlist = template.find(".//*[@id='{}']".format(name))
 104     for varname, manpages in sorted(directives.items()):
 105         entry = tree.SubElement(varlist, 'varlistentry')
 106         term = tree.SubElement(entry, 'term')
 107         display = deepcopy(formatting[varname])
 108         term.append(display)
 109
 110         para = tree.SubElement(tree.SubElement(entry, 'listitem'), 'para')
 111
 112         b = None
 113         for manpage, manvolume in sorted(set(manpages)):
 114             if b is not None:
 115                 b.tail = ', '
 116             b = tree.SubElement(para, 'citerefentry')
 117             c = tree.SubElement(b, 'refentrytitle')
 118             c.text = manpage
 119             c.attrib['target'] = varname
 120             d = tree.SubElement(b, 'manvolnum')
 121             d.text = manvolume
 122         entry.tail = '\n\n'
 123
 124 def _make_colophon(template, groups):
 125     count = 0
 126     pages = set()
 127     for group in groups:
 128         count += len(group)
 129         for pagelist in group.values():
 130             pages |= set(pagelist)
 131
 132     para = template.find(".//para[@id='colophon']")
 133     para.text = COLOPHON.format(count=count,
 134                                 sections=len(groups),
 135                                 pages=len(pages))
 136
 137 def _make_page(template, directive_groups, formatting):
 138     """Create an XML tree from directive_groups.
 139
 140     directive_groups = {
 141        'class': {'variable': [('manpage', 'manvolume'), ...],
 142                  'variable2': ...},
 143        ...
 144     }
 145     """
 146     for name, directives in directive_groups.items():
 147         _make_section(template, name, directives, formatting)
 148
 149     _make_colophon(template, directive_groups.values())
 150
 151     return template
 152
 153 def make_page(template_path, xml_files):
 154     "Extract directives from xml_files and return XML index tree."
 155     template = xml_parse(template_path)
 156     names = [vl.get('id') for vl in template.iterfind('.//variablelist')]
 157     directive_groups = {name:collections.defaultdict(list)
 158                         for name in names}
 159     formatting = {}
 160     for page in xml_files:
 161         try:
 162             _extract_directives(directive_groups, formatting, page)
 163         except Exception:
 164             raise ValueError("failed to process " + page)
 165
 166     return _make_page(template, directive_groups, formatting)
 167
 168 if __name__ == '__main__':
 169     with open(sys.argv[1], 'wb') as f:
 170         template_path = sys.argv[2]
 171         xml_files = sys.argv[3:]
 172         xml = make_page(template_path, xml_files)
 173         f.write(xml_print(xml))