sandbox/manpage-writer/multiple_definition_list_terms.py

   1 #!/usr/bin/env python3
   2 # :Copyright: © 2023 Günter Milde.
   3
   4 #             Released without warranty under the terms of the
   5 #             GNU General Public License (v. 2 or later)
   6
   7 # :License: Released under the terms of the `2-Clause BSD license`_, in short:
   8 #
   9 #    Copying and distribution of this file, with or without modification,
  10 #    are permitted in any medium without royalty provided the copyright
  11 #    notice and this notice are preserved.
  12 #    This file is offered as-is, without any warranty.
  13 #
  14 # .. _2-Clause BSD license: https://opensource.org/licenses/BSD-2-Clause
  15 #
  16 # Test definition list items with extra terms  with Docutils writers
  17 # =================================================================
  18
  19 # `Feature-Request #60`__ asks for the legitimation of definition list
  20 # items with more than one term for two reasons:
  21 #
  22 # * it is legal and supported in HTML,
  23 # * the custom directive `"glossary"`_ may generate definition list items
  24 #   with multiple terms.
  25 #
  26 # __ https://sourceforge.net/p/docutils/feature-requests/60/
  27 # __ https://www.sphinx-doc.org/en/master/
  28 #            usage/restructuredtext/directives.html#glossary
  29 #
  30 # In Docutils <= 0.20, there is no rST syntax construct that can generate a
  31 # definition list item with more than one term.
  32 #
  33 # To allow testing and improving writer support, this skript generates a
  34 # document tree programatically and exports it with the writers defined in
  35 # Docutils to temporary files.
  36
  37 import difflib
  38 import os.path
  39
  40 from docutils.core import publish_doctree, publish_from_doctree
  41 from docutils.nodes import term, classifier
  42
  43 sample = """\
  44 term 1
  45   definition 1
  46 term 2a
  47   definition 2
  48 term 3a : classifier 3a : classifier 3aa
  49   definition 3
  50 """
  51 expected = """\
  52 <document source="<string>">
  53     <definition_list>
  54         <definition_list_item>
  55             <term>
  56                 term 1
  57             <definition>
  58                 <paragraph>
  59                     definition 1
  60         <definition_list_item>
  61             <term>
  62                 term 2a
  63             <term>
  64                 term 2b
  65             <definition>
  66                 <paragraph>
  67                     definition 2
  68         <definition_list_item>
  69             <term>
  70                 term 3a
  71             <classifier>
  72                 classifier 3a
  73             <classifier>
  74                 classifier 3aa
  75             <term>
  76                 term 3b
  77             <classifier>
  78                 classifier 3b
  79             <definition>
  80                 <paragraph>
  81                     definition 3
  82 """
  83
  84 settings = {'_disable_config': True,
  85             'datestamp': False,
  86             'generator': False,
  87             'embed_stylesheet': False,
  88             'indents': True,  # XML writer
  89             'use_latex_citations': True,
  90             'legacy_column_widths': False,
  91             }
  92
  93
  94 doctree = publish_doctree(sample, settings_overrides=settings)
  95
  96 # print(doctree)
  97
  98 # Insert extra <term> node:
  99 # print(doctree[0][1].children)
 100 doctree[0][1].insert(1, term('test', 'term 2b'))
 101 # Insert extra <term> and <classifier> nodes:
 102 # print(doctree[0][2].children)
 103 doctree[0][2].insert(3, term('test', 'term 3b'))
 104 doctree[0][2].insert(4, classifier('test', 'classifier 3b'))
 105
 106 output = publish_from_doctree(doctree, writer_name='pseudoxml',
 107                               settings_overrides=settings)
 108 assert output.decode() == expected
 109
 110
 111 extensions = {'html': 'html',
 112               'html4': 'html',
 113               'html5': 'html',
 114               'latex': 'tex',
 115               'xetex': 'tex',
 116               'manpage': 'man',
 117               'odt': 'odt',
 118               'xml': 'xml',
 119               'pseudoxml': 'txt',
 120               }
 121
 122 for format in extensions.keys():
 123     output = publish_from_doctree(doctree, writer_name=format,
 124                                   settings_overrides=settings)
 125
 126     filename = f'termtest-{format}.{extensions[format]}'
 127     outf = f'output/{filename}'
 128     with open(outf, 'bw') as outfile:
 129         outfile.write(output)
 130         print(f'output written to {outf}')
 131     expf = f'expected/{filename}'
 132     if os.path.exists(expf):
 133         d = difflib.unified_diff(open(expf).readlines(),
 134                                  open(outf).readlines(),
 135                                  fromfile=expf, tofile=outf)
 136         print("".join(list(d)))
 137
 138
 139 # output = publish_from_doctree(doctree, writer_name='odf')
 140 # with open('/tmp/termtest.troff', 'bw') as outfile:
 141 #     outfile.write(output)