chiark / gitweb /
build-sys,man: use XML entities to substite strings
authorZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Fri, 29 Mar 2013 18:22:27 +0000 (14:22 -0400)
committerZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Sat, 30 Mar 2013 00:30:21 +0000 (20:30 -0400)
This makes it easier to add substitutions to man pages,
avoiding the separate transformation step.

mkdir -p's are removed from the rule, because xsltproc will
will create directories on it's own.

All in all, two or three forks per man page are avoided,
which should make things marginally faster.

Unfortunately python parsers must too be tweaked to handle
entities. This isn't particularly easy: with lxml a custom
Resolver can be used, but the stdlib etree doesn't support
external entities *at all*. So when running without lxml,
the entities are just removed. Right now it doesn't matter,
since the entities are not indexed anyway. But I intend to
add indexing of filenames in the near future, and then the
index generated without lxml might be missing a few lines.
Oh well.

.gitignore
Makefile.am
make-directive-index.py
make-man-index.py
make-man-rules.py
man/.gitignore
man/systemd.unit.xml
xml_helper.py [new file with mode: 0644]

index c3bb81b1f743babac17b19e12f1a27eaeac0473c..58a5000211d4101d9216eec0d3da41afcde6aaa6 100644 (file)
 *.lo
 *.o
 *.stamp
+*.pyc
+__pycache__/
 *~
 .deps/
 .dirstamp
index d5b319e2cbc6c83524503d5cd4e6332a842c5691..92bd542767cb2fbd7ea25f1eca79ee56820d7663 100644 (file)
@@ -97,6 +97,7 @@ rootbindir=$(rootprefix)/bin
 rootlibexecdir=$(rootprefix)/lib/systemd
 
 CLEANFILES = $(BUILT_SOURCES)
+DISTCLEANFILES =
 EXTRA_DIST =
 BUILT_SOURCES =
 INSTALL_EXEC_HOOKS =
@@ -556,9 +557,10 @@ noinst_DATA += \
 CLEANFILES += \
        man/index.html
 
+XML_GLOB = $(wildcard $(top_srcdir)/man/*.xml)
 NON_INDEX_XML_FILES = $(filter-out man/systemd.index.xml,$(XML_FILES))
+SOURCE_XML_FILES = $(filter-out man/systemd.directives.xml,$(NON_INDEX_XML_FILES))
 
-XML_GLOB = $(wildcard $(top_srcdir)/man/*.xml)
 update-man-list: make-man-rules.py $(XML_GLOB)
        $(AM_V_GEN)$(PYTHON) $^ > $(top_srcdir)/Makefile-man.tmp
        $(AM_V_at)mv $(top_srcdir)/Makefile-man.tmp $(top_srcdir)/Makefile-man.am
@@ -566,11 +568,11 @@ update-man-list: make-man-rules.py $(XML_GLOB)
 
 man/systemd.index.xml: make-man-index.py $(NON_INDEX_XML_FILES)
        $(AM_V_at)$(MKDIR_P) $(dir $@)
-       $(AM_V_GEN)$(PYTHON) $^ > $@
+       $(AM_V_GEN)$(PYTHON) $< $@ $(filter-out $<,$^)
 
-man/systemd.directives.xml: make-directive-index.py $(filter-out man/systemd.directives.xml,$(NON_INDEX_XML_FILES))
+man/systemd.directives.xml: make-directive-index.py $(SOURCE_XML_FILES)
        $(AM_V_at)$(MKDIR_P) $(dir $@)
-       $(AM_V_GEN)$(PYTHON) $^ > $@
+       $(AM_V_GEN)$(PYTHON) $< $@ $(filter-out $<,$^)
 
 EXTRA_DIST += \
        man/systemd.index.xml \
@@ -591,7 +593,8 @@ EXTRA_DIST += \
        $(HTML_ALIAS) \
        $(dist_MANS) \
        make-man-index.py \
-       make-directive-index.py
+       make-directive-index.py \
+       xml_helper.py
 
 # ------------------------------------------------------------------------------
 noinst_LTLIBRARIES += \
@@ -3819,38 +3822,46 @@ CLEANFILES += \
 
 # ------------------------------------------------------------------------------
 if ENABLE_MANPAGES
+man/custom-entities.ent: Makefile
+       $(AM_V_GEN)$(MKDIR_P) $(dir $@)
+       $(AM_V_GEN)(echo '<?xml version="1.0" encoding="utf-8" ?>' && \
+        echo '$(subst '|,<!ENTITY ,$(subst =, ",$(subst |',">,$(substitutions))))') \
+        > $@ # '
+
+DISTCLEANFILES += \
+       man/custom-entities.ent
+
 XSLTPROC_FLAGS = \
        --nonet \
        --stringparam man.output.quietly 1 \
        --stringparam funcsynopsis.style ansi \
        --stringparam man.authors.section.enabled 0 \
        --stringparam man.copyright.section.enabled 0 \
-       --stringparam systemd.version $(VERSION)
+       --stringparam systemd.version $(VERSION) \
+       --path '$(builddir)/man:$(srcdir)/man'
 
 XSLTPROC_PROCESS_MAN = \
-       $(AM_V_XSLT)$(MKDIR_P) $(dir $@) && \
-       $(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) $(srcdir)/man/custom-man.xsl $<
+       $(AM_V_XSLT)$(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) $(srcdir)/man/custom-man.xsl $<
 
 XSLTPROC_PROCESS_HTML = \
-       $(AM_V_XSLT)$(MKDIR_P) $(dir $@) && \
-       $(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) $(srcdir)/man/custom-html.xsl $<
+       $(AM_V_XSLT)$(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) $(srcdir)/man/custom-html.xsl $<
 
-man/%.1: man/%.xml man/custom-man.xsl
+man/%.1: man/%.xml man/custom-man.xsl man/custom-entities.ent
        $(XSLTPROC_PROCESS_MAN)
 
-man/%.3: man/%.xml man/custom-man.xsl
+man/%.3: man/%.xml man/custom-man.xsl man/custom-entities.ent
        $(XSLTPROC_PROCESS_MAN)
 
-man/%.5: man/%.xml man/custom-man.xsl
+man/%.5: man/%.xml man/custom-man.xsl man/custom-entities.ent
        $(XSLTPROC_PROCESS_MAN)
 
-man/%.7: man/%.xml man/custom-man.xsl
+man/%.7: man/%.xml man/custom-man.xsl man/custom-entities.ent
        $(XSLTPROC_PROCESS_MAN)
 
-man/%.8: man/%.xml man/custom-man.xsl
+man/%.8: man/%.xml man/custom-man.xsl man/custom-entities.ent
        $(XSLTPROC_PROCESS_MAN)
 
-man/%.html: man/%.xml man/custom-html.xsl
+man/%.html: man/%.xml man/custom-html.xsl man/custom-entities.ent
        $(XSLTPROC_PROCESS_HTML)
 
 define html-alias
index 039efaa4345001fe4f22fa16c07c3fcc55ae632b..99e7bfaf2856e1500796d7af913ff615d63292e3 100755 (executable)
 
 import sys
 import collections
-try:
-    from lxml import etree as tree
-    PRETTY = dict(pretty_print=True)
-except ImportError:
-    import xml.etree.ElementTree as tree
-    PRETTY = {}
 import re
+from xml_helper import *
 
 TEMPLATE = '''\
 <refentry id="systemd.directives" conditional="HAVE_PYTHON">
@@ -173,7 +168,7 @@ referring to {pages} individual manual pages.
 '''
 
 def _extract_directives(directive_groups, formatting, page):
-    t = tree.parse(page)
+    t = xml_parse(page)
     section = t.find('./refmeta/manvolnum').text
     pagename = t.find('./refmeta/refentrytitle').text
 
@@ -282,4 +277,5 @@ def make_page(*xml_files):
     return _make_page(template, directive_groups, formatting)
 
 if __name__ == '__main__':
-    tree.dump(make_page(*sys.argv[1:]), **PRETTY)
+    with open(sys.argv[1], 'wb') as f:
+        f.write(xml_print(make_page(*sys.argv[2:])))
index d9ab5cc7525f35222de6e0c0f4f7f004b465dfc0..74a47b821a9538d4e8531fc123ac05edb934a170 100755 (executable)
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 import collections
-try:
-    from lxml import etree as tree
-    PRETTY = dict(pretty_print=True)
-except ImportError:
-    import xml.etree.ElementTree as tree
-    PRETTY = {}
 import sys
 import re
+from xml_helper import *
+
 MDASH = ' — ' if sys.version_info.major >= 3 else ' -- '
 
 TEMPLATE = '''\
@@ -72,6 +68,7 @@ SUMMARY = '''\
 COUNTS = '\
 This index contains {count} entries, referring to {pages} individual manual pages.'
 
+
 def check_id(page, t):
     id = t.getroot().get('id')
     if not re.search('/' + id + '[.]', page):
@@ -80,7 +77,7 @@ def check_id(page, t):
 def make_index(pages):
     index = collections.defaultdict(list)
     for p in pages:
-        t = tree.parse(p)
+        t = xml_parse(p)
         check_id(p, t)
         section = t.find('./refmeta/manvolnum').text
         refname = t.find('./refnamediv/refname').text
@@ -123,7 +120,7 @@ def add_summary(template, indexpages):
     para = template.find(".//para[@id='counts']")
     para.text = COUNTS.format(count=count, pages=len(pages))
 
-def make_page(xml_files):
+def make_page(*xml_files):
     template = tree.fromstring(TEMPLATE)
     index = make_index(xml_files)
 
@@ -135,4 +132,5 @@ def make_page(xml_files):
     return template
 
 if __name__ == '__main__':
-    tree.dump(make_page(sys.argv[1:]), **PRETTY)
+    with open(sys.argv[1], 'wb') as f:
+        f.write(xml_print(make_page(*sys.argv[2:])))
index 46a586374f6d34dbd1fba2beef5b3bf127d86ff1..ad601f874f220015b7dad8af72a6df994577cb3c 100644 (file)
@@ -18,9 +18,9 @@
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 from __future__ import print_function
-import xml.etree.ElementTree as tree
 import collections
 import sys
+from xml_helper import *
 
 SECTION = '''\
 MANPAGES += \\
@@ -54,7 +54,7 @@ def man(page, number):
     return 'man/{}.{}'.format(page, number)
 
 def add_rules(rules, name):
-    xml = tree.parse(name)
+    xml = xml_parse(name)
     # print('parsing {}'.format(name), file=sys.stderr)
     conditional = xml.getroot().get('conditional') or ''
     rulegroup = rules[conditional]
index 3798c75f1db3f5aa45abed0084487b4782963f04..bf5eeab938eccf6b69180572ad89f747232bba3a 100644 (file)
@@ -1,4 +1,4 @@
 /systemd.directives.xml
 /systemd.index.xml
 /*.[13578]
-/python-systemd/
+/custom-entities.ent
index 2196e73bb308f5649add04ec20d319b81811cbe0..47c50315ae941e58d5b923da3b8e89a355d37d8c 100644 (file)
@@ -1,6 +1,9 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY % entities SYSTEM "custom-entities.ent" >
+%entities;
+]>
 
 <!--
   This file is part of systemd.
                         <entry>Generated units</entry>
                       </row>
                       <row>
-                        <entry><filename>@SYSTEM_CONFIG_UNIT_PATH@</filename></entry>
+                        <entry><filename>&SYSTEM_CONFIG_UNIT_PATH;</filename></entry>
                         <entry morerows='1'>Local configuration</entry>
                       </row>
                       <row>
                         <entry>Units for local packages</entry>
                       </row>
                       <row>
-                        <entry><filename>@systemunitdir@</filename></entry>
+                        <entry><filename>&systemunitdir;</filename></entry>
                         <entry>Systemd package configuration</entry>
                       </row>
                       <row>
                         <entry>Generated units</entry>
                       </row>
                       <row>
-                        <entry><filename>@USER_CONFIG_UNIT_PATH@</filename></entry>
+                        <entry><filename>&USER_CONFIG_UNIT_PATH;</filename></entry>
                         <entry morerows='1'>Local configuration</entry>
                       </row>
                       <row>
                         <entry><filename>/usr/local/share/systemd/user</filename></entry>
                       </row>
                       <row>
-                        <entry><filename>@userunitdir@</filename></entry>
+                        <entry><filename>&userunitdir;</filename></entry>
                         <entry>Systemd package configuration</entry>
                       </row>
                       <row>
diff --git a/xml_helper.py b/xml_helper.py
new file mode 100644 (file)
index 0000000..a484bea
--- /dev/null
@@ -0,0 +1,40 @@
+#  -*- Mode: python; coding: utf-8; indent-tabs-mode: nil -*- */
+#
+#  This file is part of systemd.
+#
+#  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
+#  the Free Software Foundation; either version 2.1 of the License, or
+#  (at your option) any later version.
+#
+#  systemd is distributed in the hope that it will be useful, but
+#  WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+#  Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+
+try:
+    from lxml import etree as tree
+
+    class CustomResolver(tree.Resolver):
+        def resolve(self, url, id, context):
+            if 'custom-entities.ent' in url:
+                return self.resolve_filename('man/custom-entities.ent', context)
+
+    _parser = tree.XMLParser()
+    _parser.resolvers.add(CustomResolver())
+    xml_parse = lambda page: tree.parse(page, _parser)
+    xml_print = lambda xml: tree.tostring(xml, pretty_print=True)
+except ImportError:
+    import xml.etree.ElementTree as tree
+    import re as _re
+    import io as _io
+
+    def xml_parse(page):
+        s = _re.sub(b'&[a-zA-Z0-9_]+;', b'', open(page, 'rb').read())
+        return tree.parse(_io.BytesIO(s))
+    xml_print = tree.tostring