tdf#142417: Improve convertfilters.py and add API Names column

This commit involves two parts: 1. Improved the convertfilters.py helper script to make sure the generated convertfilters.xhp file is complete, accurate and containing no duplicated entries, and also add codes to also generate API Names column, as discussed in tdf#142417. Importantly, the code is modified to generate fixed IDs, rather than the previously random IDs or sequential IDs which may make the PO translation strings to show fuzzy when the file is re-generated. 2. This helper script is run and the convertfilters.xhp is updated. 3. The default css is modified to better display the page. There is no need to set overflow=auto for the DisplayArea, otherwise the scrollbar goes to the bottom of that area which is not visible. Also added a css class to display smaller fonts for the table. Change-Id: I8a5c73c9d6a0c0b44fc7db6cb67b140bfeb8b4be Reviewed-on: https://gerrit.libreoffice.org/c/help/+/116405 Tested-by: Jenkins Reviewed-by: Olivier Hallot <olivier.hallot@libreoffice.org>
author: Kevin Suo <suokunlong@126.com> 2021-05-30 20:39:31 +0800
committer: Olivier Hallot <olivier.hallot@libreoffice.org> 2021-05-31 16:45:00 +0200
commit: 226a545d33667a0c9526593a5182ac0a849933e2 (patch)
tree: 82d799d420f02dd4c6fa18c26d2b238ac8298b03 /helpers
parent: 8ca38307bd81fbb37a664dd848fd1fda2c2b4181 (diff)
1 files changed, 151 insertions, 84 deletions
diff --git a/helpers/convertfilters.py b/helpers/convertfilters.py
index 209a78c1dc..dcb25af00a 100644..100755
--- a/helpers/convertfilters.py
+++ b/helpers/convertfilters.py
@@ -6,106 +6,173 @@
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 #
-# Run this in instdir/share/registry/
+# This script is used to generate the convertfilters.xhp file located
+# in helpcontent2/source/text/shared/guide.
+#
+# Run this script followed by the path of instdir/share/registry/
+# i.e.: ./convertfilters.py /path/to/source/core/instdir/share/registry
+# 
 # Requires Python 3.6 or greater.
 
+import os
 import sys
 import random
 import time
 from math import floor
 from lxml import etree
 
+output_file_path = os.path.join(os.path.dirname(sys.argv[0]), "convertfilters.xhp")
+try:
+    registry_dir = sys.argv[1]
+except IndexError:
+    print("Usage: ./convertfilters.py /path/to/source/core/instdir/share/registry")
+    sys.exit(1)
+
+if not os.path.exists(registry_dir):
+    print(f"{registry_dir} does not exist. Make sure you have built the core repo before running this script")
+    sys.exit(1)
+
 modules = ["writer.xcd","calc.xcd","impress.xcd","draw.xcd","math.xcd","base.xcd","graphicfilter.xcd"]
 
-def rdm(prefix):
-    return prefix + "_id" + str(floor(random.random() * 1000) + 1) + str(int(time.time()))
+def gen_id(apiname):
+    '''This function accepts module name and an API Name of the filter, and then generate 
+    a unique ID. API Names are used since they are unique within the page.
+    
+    Do not use random numbers or sequence-count numbers here since it will cause all words to be "fuzzy" in PO files
+    when the xhp file is regenerated.
+    '''
+    apiname = apiname.replace(" ", "_")
+    apiname = apiname.replace("(", "_")
+    apiname = apiname.replace(")", "_")
+    apiname = apiname.replace("/", "_")
+    
+    return apiname
 
-output = ""
-output += f'<?xml version="1.0" encoding="UTF-8"?>\n'
-output += f'<helpdocument version="1.0">\n'
-output += f'<!--\n'
-output += f'    * This file is part of the LibreOffice project.\n    *\n'
-output += f'    * This Source Code Form is subject to the terms of the Mozilla Public\n'
-output += f'    * License, v. 2.0. If a copy of the MPL was not distributed with this\n'
-output += f'    * file, You can obtain one at http://mozilla.org/MPL/2.0/.\n'
-output += f'    *\n'
-output += f'    -->\n'
-output += f'<meta>\n'
-output += f'<topic id="convertfilters" indexer="include" status="PUBLISH">\n'
-output += f'<title id="tit" xml-lang="en-US">File Conversion Filters Tables</title>\n'
-output += f'<filename>/text/shared/guide/convertfilters.xhp</filename>\n'
-output += f'</topic>\n</meta>\n<body>\n'
-output += f'<section id="convertfilters01">\n'
-output += f'<bookmark xml-lang="en-US" branch="index" id="bm_id541554406270299">\n'
-output += f'<bookmark_value>filters;document conversion</bookmark_value>\n'
-output += f'<bookmark_value>document conversion;filters</bookmark_value>\n'
-output += f'<bookmark_value>convert-to;filters</bookmark_value>\n'
-output += f'<bookmark_value>command line document conversion;filters</bookmark_value>\n'
-output += f'<bookmark_value>module file filters</bookmark_value>\n'
-output += f'</bookmark>\n'
-output += f'<h1 id="hd_id771554399002497"><link href="text/shared/guide/convertfilters.xhp" name="conversion filter names">File Conversion Filter Names</link></h1>\n'
-output += f'<paragraph id="par_id581554399002498" role="paragraph" xml-lang="en-US"><variable id="variable name"><ahelp hid=".">Tables with filter names for command line document conversion.</ahelp></variable></paragraph>\n'
-output += f'</section>\n'
-output += f'<paragraph role="paragraph" id="par_id00tablehead"><ahelp hid="." visibility="hidden"><variable visibility="hidden" id="filtername">Filter name</variable><variable visibility="hidden" id="mediatype">Media type</variable><variable visibility="hidden" id="fileextensions">File name extensions</variable></ahelp></paragraph>\n'
+output = '''<?xml version="1.0" encoding="UTF-8"?>
+<helpdocument version="1.0">
+<!--
+    * This file is part of the LibreOffice project.
+    *
+    * This Source Code Form is subject to the terms of the Mozilla Public
+    * License, v. 2.0. If a copy of the MPL was not distributed with this
+    * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+    *
+-->
+<meta>
+    <topic id="convertfilters" indexer="include" status="PUBLISH">
+        <title id="tit" xml-lang="en-US">File Conversion Filters Tables</title>
+        <filename>/text/shared/guide/convertfilters.xhp</filename>
+    </topic>
+</meta>
+<body>
+<section id="convertfilters01">
+    <bookmark xml-lang="en-US" branch="index" id="bm_id541554406270299">
+        <bookmark_value>filters;document conversion</bookmark_value>
+        <bookmark_value>document conversion;filters</bookmark_value>
+        <bookmark_value>convert-to;filters</bookmark_value>
+        <bookmark_value>command line document conversion;filters</bookmark_value>
+        <bookmark_value>module file filters</bookmark_value>
+    </bookmark>
+    <h1 id="hd_id771554399002497">
+        <link href="text/shared/guide/convertfilters.xhp" name="conversion filter names">File Conversion Filter Names</link>
+    </h1>
+    <paragraph id="par_id581554399002498" role="paragraph" xml-lang="en-US">
+        <variable id="variable name">
+            <ahelp hid=".">Tables with filter names for command line document conversion.</ahelp>
+        </variable>
+    </paragraph>
+</section>
+'''
+
+output += '''
+<paragraph role="paragraph" id="par_id00tablehead">
+    <ahelp hid="." visibility="hidden">
+        <variable visibility="hidden" id="filtername">Filter Name</variable>
+        <variable visibility="hidden" id="apiname">API Name</variable>
+        <variable visibility="hidden" id="mediatype">Media Type (Extension)</variable>
+    </ahelp>
+</paragraph>
+'''
 
 for module in modules:
-    tree = etree.parse(module)
+    print("\n-------" + module + "----------")
+    module_path = os.path.join(registry_dir, module)
+    tree = etree.parse(module_path)
     namespaces = tree.getroot().nsmap
-    typenodes = tree.findall('oor:component-data/node[@oor:name="Types"]/node', namespaces)
+    filternodes = tree.findall(
+        'oor:component-data[@oor:name="Filter"]/node',
+        namespaces)[-1]
     filters = []
 
-    for type in typenodes:
-        uiname = str(type.findtext('prop[@oor:name="UIName"]/value', namespaces=namespaces))
-        mediatype = str(type.findtext('prop[@oor:name="MediaType"]/value', namespaces=namespaces))
-        extensions = str(type.findtext('prop[@oor:name="Extensions"]/value', namespaces=namespaces))
-        filters.append([uiname,mediatype,extensions])
+    for filter_node in filternodes:
+        uiname = str(filter_node.findtext('prop[@oor:name="UIName"]/value', namespaces=namespaces))
+        apiname = filter_node.attrib['{' + namespaces['oor'] + '}name']
+        
+        filter_type = str(filter_node.findtext('prop[@oor:name="Type"]/value', namespaces=namespaces))
+        type_node = tree.find(
+            f'oor:component-data[@oor:name="Types"]/node/node[@oor:name="{filter_type}"]',
+            namespaces)
+        try:
+            mediatype = str(type_node.findtext('prop[@oor:name="MediaType"]/value', namespaces=namespaces))
+            extensions = str(type_node.findtext('prop[@oor:name="Extensions"]/value', namespaces=namespaces))
+        except AttributeError:
+            continue
+        
+        filter_data = [uiname, apiname, mediatype, extensions]
+        print(filter_data)
+        filters.append(filter_data)
+    
+    output += f'\
+<section id="filters{module[:-4]}">\n\
+    <bookmark xml-lang="en-US" branch="index" id="bm_000{module[:-4]}">\n\
+        <bookmark_value>command line document conversion; filters for {module[:-4].upper()}</bookmark_value>\n\
+    </bookmark>\n\
+    <h2 id="hd_000{module[:-4]}">Filters for {module[:-4].upper()}</h2>\n\
+    <table id="filternames_tbl_{module[:-4]}">\n\
+        <tablerow>\n\
+            <tablecell>\n\
+                <paragraph role="tablehead" localize="false" id="hd_111{module[:-4]}">\n\
+                    <embedvar href="text/shared/guide/convertfilters.xhp#filtername" markup="ignore"/>\n\
+                </paragraph>\n\
+            </tablecell>\n\
+            <tablecell>\n\
+                <paragraph role="tablehead" localize="false" id="hd_apiname_{module[:-4]}">\n\
+                    <embedvar href="text/shared/guide/convertfilters.xhp#apiname" markup="ignore"/>\n\
+                </paragraph>\n\
+            </tablecell>\n\
+            <tablecell>\n\
+                <paragraph role="tablehead" localize="false" id="hd_222{module[:-4]}">\n\
+                    <embedvar href="text/shared/guide/convertfilters.xhp#mediatype" markup="ignore"/>\n\
+                </paragraph>\n\
+            </tablecell>\n\
+        </tablerow>\n\
+'
+
+    for item in filters:
+        uid = gen_id(item[1])
+        output += f'\
+        <tablerow>\n\
+            <tablecell>\n\
+                <paragraph role="table_font_small paragraph" id="FilterName_{uid}">{item[0]}</paragraph>\n\
+            </tablecell>\n\
+            <tablecell>\n\
+                <paragraph role="table_font_small paragraph" id="APIName_{uid}" localize="false">{item[1]}</paragraph>\n\
+            </tablecell>\n\
+            <tablecell>\n\
+                <paragraph role="table_font_small paragraph" id="MediaType_{uid}" localize="false">{item[2]} ({item[3]})</paragraph>\n\
+            </tablecell>\n\
+        </tablerow>\n'
+    
+    output += f'\
+    </table>\n\
+</section>\n'
 
-    st = sorted(filters, key=lambda x: x[0])
-    output += f'<section id="filters{module[:-4]}">\n'
-    output += f'<bookmark xml-lang="en-US" branch="index" id="bm_000{module[:-4]}">\n'
-    output += f'<bookmark_value>command line document conversion; filters for {module[:-4].upper()}</bookmark_value>\n'
-    output += f'</bookmark>\n'
-    output += f'<h2 id="hd_000{module[:-4]}">Filters for {module[:-4].upper()}</h2>\n'
-    output += f'    <table id="{rdm("tbl")}">\n'
-    output += '        <tablerow>\n'
-    output += '            <tablecell>\n'
-    output += f'                <paragraph role="tablehead" localize="false" id="hd_111{module[:-4]}"><embedvar href="text/shared/guide/convertfilters.xhp#filtername" markup="ignore"/>'
-    output += '</paragraph>\n'
-    output += '            </tablecell>\n'
-    output += '            <tablecell>\n'
-    output += f'                <paragraph role="tablehead" localize="false" id="hd_222{module[:-4]}"><embedvar href="text/shared/guide/convertfilters.xhp#mediatype" markup="ignore"/>'
-    output += '</paragraph>\n'
-    output += '            </tablecell>\n'
-    output += '            <tablecell>\n'
-    output += f'                <paragraph role="tablehead" localize="false" id="hd_333{module[:-4]}"><embedvar href="text/shared/guide/convertfilters.xhp#fileextensions" markup="ignore"/>'
-    output += '</paragraph>\n'
-    output += '            </tablecell>\n'
-    output += '        </tablerow>\n'
-    count = 0
-    for item in st:
-        output += '        <tablerow>\n'
-        output += '            <tablecell>\n'
-        output += f'                <paragraph role="paragraph" id="{"par_" + module[:-4] + str(count)}">'
-        output += f'{item[0]}'
-        count +=1
-        output += '</paragraph>\n'
-        output += '            </tablecell>\n'
-        output += '            <tablecell>\n'
-        output += f'                <paragraph role="paragraph" id="{"par_" + module[:-4] + str(count)}">'
-        output += f'{item[1]}'
-        count +=1
-        output += '</paragraph>\n'
-        output += '            </tablecell>\n'
-        output += '            <tablecell>\n'
-        output += f'                <paragraph role="paragraph" id="{"par_" + module[:-4] + str(count)}" localize="false">'
-        output += f'{item[2]}'
-        count +=1
-        output += '</paragraph>\n'
-        output += '            </tablecell>\n'
-        output += '        </tablerow>\n'
+output += f'\
+</body>\n\
+</helpdocument>'
 
-    output += '    </table>\n'
-    output += '</section>\n'
+with open(output_file_path, "w") as f:
+    f.write(output)
 
-output += f'</body>\n</helpdocument>'
-print(output)
+print(f'\nDone. File saved at: {output_file_path}.')
+print(f'Please move this file into helpcontent2/source/text/shared/guide.')
author	Kevin Suo <suokunlong@126.com>	2021-05-30 20:39:31 +0800
committer	Olivier Hallot <olivier.hallot@libreoffice.org>	2021-05-31 16:45:00 +0200
commit	226a545d33667a0c9526593a5182ac0a849933e2 (patch)
tree	82d799d420f02dd4c6fa18c26d2b238ac8298b03 /helpers
parent	8ca38307bd81fbb37a664dd848fd1fda2c2b4181 (diff)