1 files changed, 281 insertions, 0 deletions
diff --git a/doc/manual/htmlhelp-qthelp.py b/doc/manual/htmlhelp-qthelp.py
new file mode 100755
index 00000000..dd0405b8
--- /dev/null
+++ b/doc/manual/htmlhelp-qthelp.py
@@ -0,0 +1,281 @@
+#!/usr/bin/python3
+
+# $Id: htmlhelp-qthelp.py $
+## @file
+# A python script to create a .qhp file out of a given htmlhelp
+# folder. Lots of things about the said folder is assumed. Please
+# see the code and inlined comments.
+
+import sys, getopt
+import os.path
+import re
+import codecs
+import logging
+
+if sys.version_info >= (3, 0):
+    from html.parser import HTMLParser
+else:
+    from HTMLParser import HTMLParser
+
+
+__copyright__ = \
+"""
+Copyright (C) 2006-2023 Oracle and/or its affiliates.
+
+This file is part of VirtualBox base platform packages, as
+available from https://www.virtualbox.org.
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation, in version 3 of the
+License.
+
+This program 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
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, see <https://www.gnu.org/licenses>.
+
+SPDX-License-Identifier: GPL-3.0-only
+"""
+
+# number of opened and not yet closed section tags of toc section
+open_section_tags = 0
+
+html_files = []
+
+# use html_parser stuff to collect <a name tags
+def create_keywords_section(folder):
+    keywords_section_lines = ['<keywords>']
+    for html_file_name in html_files:
+        full_html_path = os.path.join(folder, html_file_name)
+        file_content = codecs.open(full_html_path, encoding='iso-8859-1').read()
+
+        class html_parser(HTMLParser):
+          def __init__(self):
+            HTMLParser.__init__(self)
+            self.a_tag=[]
+          def handle_starttag(self, tag, attributes):
+            if tag != 'div' and tag != 'a':
+              return
+            if tag == 'a':
+              for a in attributes:
+                if a[0] == 'name':
+                  self.a_tag.append(a[1])
+
+        parser = html_parser()
+        parser.feed(file_content)
+        for k in parser.a_tag:
+            line = '<keyword name="' + k + '" id="' + k + '" ref="' + html_file_name + '#' + k + '"/>'
+            keywords_section_lines.append(line);
+    keywords_section_lines.append('</keywords>')
+    return keywords_section_lines
+
+# find the png files under /images folder and create a part of the
+# qhelp project file with <file> tags
+def create_image_list(folder):
+    image_folder_name = 'images'
+    image_files_list = []
+    # Look for 'images' sub folder
+    subdirs = [x[0] for x in os.walk(folder)]
+    full_folder_path = os.path.join(folder, image_folder_name)
+    if full_folder_path not in subdirs:
+        logging.error('Image subfolder "%s" is not found under "%s".', image_folder_name, folder)
+        return image_files_list;
+    png_files = []
+    for f in os.listdir(full_folder_path):
+        png_files.append(image_folder_name + '/' + f)
+        image_files_list.append('<file>images/' + f + '</file>')
+    return image_files_list
+
+# open htmlhelp.hhp files and read the list of html files from there
+def create_html_list(folder):
+    global html_files
+    file_name = 'htmlhelp.hhp'
+    html_file_lines = []
+    if not file_name in os.listdir(folder):
+        logging.error('Could not find the file "%s" in "%s"', file_name, folder)
+        return html_file_lines
+    full_path = os.path.join(folder, 'htmlhelp.hhp')
+    file = codecs.open(full_path, encoding='iso-8859-1')
+
+    lines = file.readlines()
+    file.close()
+    # first search for the [FILES] marker then collect .html lines
+    marker_found = 0
+    for line in lines:
+        if '[FILES]' in line:
+            marker_found = 1
+            continue
+        if marker_found == 0:
+            continue
+        if '.html' in line:
+            html_file_lines.append('<file>' + line.strip('\n') + '</file>')
+            html_files.append(line.strip('\n'))
+    return html_file_lines
+
+
+def create_files_section(folder):
+    files_section_lines = ['<files>']
+    files_section_lines += create_image_list(folder)
+    files_section_lines += create_html_list(folder)
+    files_section_lines.append('</files>')
+    return files_section_lines
+
+def parse_param_tag(line):
+    label = 'value="'
+    start = line.find(label);
+    if start == -1:
+        return ''
+    start +=  len(label)
+    end = line.find('"', start)
+    if end == -1:
+        return '';
+    return line[start:end]
+
+# look at next two lines. they are supposed to look like the following
+#      <param name="Name" value="Oracle VM VirtualBox">
+#      <param name="Local" value="index.html">
+# parse out value fields and return
+# title="Oracle VM VirtualBox" ref="index.html
+def parse_object_tag(lines, index):
+    result=''
+    if index + 2 > len(lines):
+        logging.warning('Not enough tags after this one "%s"',lines[index])
+        return result
+    if not re.match(r'^\s*<param', lines[index + 1], re.IGNORECASE) or \
+       not re.match(r'^\s*<param', lines[index + 2], re.IGNORECASE):
+        logging.warning('Skipping the line "%s" since next two tags are supposed to be param tags',  lines[index])
+        return result
+    title = parse_param_tag(lines[index + 1])
+    ref = parse_param_tag(lines[index + 2])
+    global open_section_tags
+    if title and ref:
+        open_section_tags += 1
+        result = '<section title="' + title + '" ref="' + ref + '">'
+    else:
+        logging.warning('Title or ref part is empty for the tag "%s"', lines[index])
+    return result
+
+# parse any string other than staring with <OBJECT
+# decide if <session tag should be closed
+def parse_non_object_tag(lines, index):
+    if index + 1 > len(lines):
+        return ''
+    global open_section_tags
+    if open_section_tags <= 0:
+        return ''
+    # replace </OBJECT with </section only if the next tag is not <UL
+    if re.match(r'^\s*</OBJECT', lines[index], re.IGNORECASE):
+        if not re.match(r'^\s*<UL', lines[index + 1], re.IGNORECASE):
+            open_section_tags -= 1
+            return '</section>'
+    elif re.match(r'^\s*</UL', lines[index], re.IGNORECASE):
+        open_section_tags -= 1
+        return '</section>'
+    return ''
+
+def parse_line(lines, index):
+    result=''
+
+    # if the line starts with <OBJECT
+    if re.match(r'^\s*<OBJECT', lines[index], re.IGNORECASE):
+        result = parse_object_tag(lines, index)
+    else:
+        result = parse_non_object_tag(lines, index)
+    return result
+
+# parse toc.hhc file. assuming all the relevant information
+# is stored in tags and attributes. whatever is outside of
+# <... > pairs is filtered out. we also assume < ..> are not nested
+# and each < matches to a >
+def create_toc(folder):
+    toc_file = 'toc.hhc'
+    content = [x[2] for x in os.walk(folder)]
+    if toc_file not in content[0]:
+        logging.error('Could not find toc file "%s" under "%s"', toc_file, folder)
+        return
+    full_path = os.path.join(folder, toc_file)
+    file = codecs.open(full_path, encoding='iso-8859-1')
+    content = file.read()
+    file.close()
+    # convert the file string into a list of tags there by eliminating whatever
+    # char reside outside of tags.
+    char_pos = 0
+    tag_list = []
+    while char_pos < len(content):
+        start = content.find('<', char_pos)
+        if start == -1:
+            break
+        end = content.find('>', start)
+        if end == -1 or end >= len(content) - 1:
+            break
+        char_pos = end
+        tag_list.append(content[start:end +1])
+
+    # # insert new line chars. to make sure each line includes at most one tag
+    # content = re.sub(r'>.*?<', r'>\n<', content)
+    # lines = content.split('\n')
+    toc_string_list = ['<toc>']
+    index = 0
+    for tag in tag_list:
+        str = parse_line(tag_list, index)
+        if str:
+            toc_string_list.append(str)
+        index += 1
+    toc_string_list.append('</toc>')
+    toc_string = '\n'.join(toc_string_list)
+
+    return toc_string_list
+
+def usage(arg):
+    print('htmlhelp-qthelp.py -d <helphtmlfolder> -o <outputfilename>')
+    sys.exit()
+
+def main(argv):
+    helphtmlfolder = ''
+    output_filename = ''
+    try:
+        opts, args = getopt.getopt(sys.argv[1:],"hd:o:")
+    except getopt.GetoptError as err:
+        print(err)
+        usage(2)
+    for opt, arg in opts:
+        if opt == '-h':
+            usage(0)
+        elif opt in ("-d"):
+            helphtmlfolder = arg
+        elif opt in ("-o"):
+             output_filename = arg
+
+    # check supplied helphtml folder argument
+    if not helphtmlfolder:
+        logging.error('No helphtml folder is provided. Exiting')
+        usage(2)
+    if not os.path.exists(helphtmlfolder):
+        logging.error('folder "%s" does not exist. Exiting', helphtmlfolder)
+        usage(2)
+    helphtmlfolder = os.path.normpath(helphtmlfolder)
+
+    # check supplied output file name
+    if not output_filename:
+        logging.error('No filename for output is given. Exiting')
+        usage(2)
+
+    out_xml_lines = ['<?xml version="1.0" encoding="UTF-8"?>', \
+                     '<QtHelpProject version="1.0">' , \
+                     '<namespace>org.virtualbox</namespace>', \
+                     '<virtualFolder>doc</virtualFolder>', \
+                     '<filterSection>']
+    out_xml_lines += create_toc(helphtmlfolder) + create_files_section(helphtmlfolder)
+    out_xml_lines += create_keywords_section(helphtmlfolder)
+    out_xml_lines += ['</filterSection>', '</QtHelpProject>']
+
+    out_file = open(output_filename, 'wb')
+    out_file.write('\n'.join(out_xml_lines).encode('utf8'))
+    out_file.close()
+
+if __name__ == '__main__':
+    main(sys.argv[1:])