tools/make-man-index.py

   1 #!/usr/bin/env python3
   2 #  -*- Mode: python; coding: utf-8; indent-tabs-mode: nil -*- */
   3 # SPDX-License-Identifier: LGPL-2.1+
   4 #
   5 #  This file is part of systemd.
   6 #
   7 #  Copyright 2012 Lennart Poettering
   8 #  Copyright 2013 Zbigniew Jędrzejewski-Szmek
   9 #
  10 #  systemd is free software; you can redistribute it and/or modify it
  11 #  under the terms of the GNU Lesser General Public License as published by
  12 #  the Free Software Foundation; either version 2.1 of the License, or
  13 #  (at your option) any later version.
  14 #
  15 #  systemd is distributed in the hope that it will be useful, but
  16 #  WITHOUT ANY WARRANTY; without even the implied warranty of
  17 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18 #  Lesser General Public License for more details.
  19 #
  20 #  You should have received a copy of the GNU Lesser General Public License
  21 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22
  23 import collections
  24 import sys
  25 import re
  26 from xml_helper import xml_parse, xml_print, tree
  27
  28 MDASH = ' — ' if sys.version_info.major >= 3 else ' -- '
  29
  30 TEMPLATE = '''\
  31 <refentry id="systemd.index" conditional="HAVE_PYTHON">
  32
  33   <refentryinfo>
  34     <title>systemd.index</title>
  35     <productname>systemd</productname>
  36
  37     <authorgroup>
  38       <author>
  39         <contrib>Developer</contrib>
  40         <firstname>Lennart</firstname>
  41         <surname>Poettering</surname>
  42         <email>lennart@poettering.net</email>
  43       </author>
  44     </authorgroup>
  45   </refentryinfo>
  46
  47   <refmeta>
  48     <refentrytitle>systemd.index</refentrytitle>
  49     <manvolnum>7</manvolnum>
  50   </refmeta>
  51
  52   <refnamediv>
  53     <refname>systemd.index</refname>
  54     <refpurpose>List all manpages from the systemd project</refpurpose>
  55   </refnamediv>
  56 </refentry>
  57 '''
  58
  59 SUMMARY = '''\
  60   <refsect1>
  61     <title>See Also</title>
  62     <para>
  63       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  64     </para>
  65
  66     <para id='counts' />
  67   </refsect1>
  68 '''
  69
  70 COUNTS = '\
  71 This index contains {count} entries, referring to {pages} individual manual pages.'
  72
  73
  74 def check_id(page, t):
  75     id = t.getroot().get('id')
  76     if not re.search('/' + id + '[.]', page):
  77         raise ValueError("id='{}' is not the same as page name '{}'".format(id, page))
  78
  79 def make_index(pages):
  80     index = collections.defaultdict(list)
  81     for p in pages:
  82         t = xml_parse(p)
  83         check_id(p, t)
  84         section = t.find('./refmeta/manvolnum').text
  85         refname = t.find('./refnamediv/refname').text
  86         purpose = ' '.join(t.find('./refnamediv/refpurpose').text.split())
  87         for f in t.findall('./refnamediv/refname'):
  88             infos = (f.text, section, purpose, refname)
  89             index[f.text[0].upper()].append(infos)
  90     return index
  91
  92 def add_letter(template, letter, pages):
  93     refsect1 = tree.SubElement(template, 'refsect1')
  94     title = tree.SubElement(refsect1, 'title')
  95     title.text = letter
  96     para = tree.SubElement(refsect1, 'para')
  97     for info in sorted(pages, key=lambda info: str.lower(info[0])):
  98         refname, section, purpose, realname = info
  99
 100         b = tree.SubElement(para, 'citerefentry')
 101         c = tree.SubElement(b, 'refentrytitle')
 102         c.text = refname
 103         d = tree.SubElement(b, 'manvolnum')
 104         d.text = section
 105
 106         b.tail = MDASH + purpose # + ' (' + p + ')'
 107
 108         tree.SubElement(para, 'sbr')
 109
 110 def add_summary(template, indexpages):
 111     count = 0
 112     pages = set()
 113     for group in indexpages:
 114         count += len(group)
 115         for info in group:
 116             refname, section, purpose, realname = info
 117             pages.add((realname, section))
 118
 119     refsect1 = tree.fromstring(SUMMARY)
 120     template.append(refsect1)
 121
 122     para = template.find(".//para[@id='counts']")
 123     para.text = COUNTS.format(count=count, pages=len(pages))
 124
 125 def make_page(*xml_files):
 126     template = tree.fromstring(TEMPLATE)
 127     index = make_index(xml_files)
 128
 129     for letter in sorted(index):
 130         add_letter(template, letter, index[letter])
 131
 132     add_summary(template, index.values())
 133
 134     return template
 135
 136 if __name__ == '__main__':
 137     with open(sys.argv[1], 'wb') as f:
 138         f.write(xml_print(make_page(*sys.argv[2:])))