Changeset 98893 in vbox for trunk/doc

Timestamp:

Mar 9, 2023 12:25:18 PM (2 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

156227

Message:

Docs: bugref:10302. Using a python script to flatten out refsect1/refsect2 hierarchy.

Location:

trunk/doc/manual

Files:

• Makefile.kmk (modified) (1 diff)
• refsect2_to_refsect1.py (copied) (copied from trunk/doc/manual/correct_references.py ) (2 diffs)

trunk/doc/manual/Makefile.kmk

@@ -859 +859 @@
 
         $$(QUIET)$$(RM) -f "$$@"
-        $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --maxdepth 6000 --output $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2) $(VBOX_PATH_MANUAL_SRC)/refsect2_replace.xsl $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2)
+        $$(QUIET)$$(VBOX_BLD_PYTHON) $$(VBOX_PATH_MANUAL_SRC)/refsect2_to_refsect1.py -i $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2) -o $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2)
         $$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@)
         $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --maxdepth 6000 --output $$@ $$(VBOX_DITA_CONVERTER_PATH)/db2dita/docbook2dita.xsl $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2)

trunk/doc/manual/refsect2_to_refsect1.py

@@ -38 +38 @@
 """
 
-"""
-key is the id, value is the name of the containing file.
-"""
-xref_dictionary = {}
+def replaceRefsect2(file_content):
+    new_content = []
+    """
+        * Add a refsect1 before the first refsect2,
+        * convert refsect2 to refsect1,
+        * remove the </refsect1> which comes after a </refsect2>
+    """
+    first_refsect2 = False
+    # remove lines that consist of new line only
+    file_content = [line for line in file_content if line != "\n"]
+    new_content.append(file_content[0])
+    for current, next in  zip(file_content, file_content[1:]):
 
-""""
-    =================================================================
-    Cross reference utility functions to add file name to target name.
-    =================================================================
-"""
-# Search for hrefs and return a tuple where 0th element is target and 1st element is its index in @p line
-def extractHrefTarget(line, start = 0):
-    target = ""
-    pointer0 = line.find("href=\"", start)
-    if pointer0 == -1:
-        return (target, -1)
-    pointer0 += len("href=\"")
-    pointer1 = line.find("\"", pointer0)
-    if pointer1 == -1:
-        return (target, -1)
-    return (line[pointer0:pointer1], pointer0)
+        if "<refsect2" in next:
+            if not first_refsect2:
+                first_refsect2 = True
+                new_content.append("</refsect1>")
+                new_content.append("\n")
+            new_content.append(next.replace("<refsect2", "<refsect1"))
+        elif "</refsect2>" in next:
+            new_content.append("</refsect1>")
+            new_content.append("\n")
+        elif not ("</refsect1>" in next and "</refsect2>" in current):
+            new_content.append(next)
+    return new_content
 
-# Return list of href targets contained in @p line
-def extractHrefList(line):
-    targets = []
-    index = 0
-    while index < len(line):
-        ttarget = extractHrefTarget(line, index)
-        index = ttarget[1]
-        if index == -1:
-            break
-        targets.append(ttarget[0])
-    return targets
-
-def correctHrefTargets(file_content):
-    for idx, line in enumerate(file_content):
-        if "href" in line:
-            targets = extractHrefList(line)
-            newline = line
-            for target in targets:
-                if target in xref_dictionary and os.path.basename != xref_dictionary[target]:
-                    old = "\"" + target + "\""
-                    new = "\"" + xref_dictionary[target] + "#" + target + "\""
-                    newline = newline.replace(old, new)
-            file_content[idx] = newline
-
-def createXrefIdDictionary(ditafolder):
-    xref_dictionary.clear()
-    dita_files = glob.glob(ditafolder + "/*.dita")
-    for file in dita_files:
-        file_content = open(file, 'r', encoding="utf-8")
-        for line in file_content:
-            if "reference" in line or "topic" in line or "section" in line:
-                start = line.find("id=\"")
-                if start != -1:
-                    start += len("id=\"")
-                    end = line.find("\"", start)
-                    if end != -1:
-                        id = line[start:end]
-                        if len(id) > 0:
-                            if id not in xref_dictionary:
-                                xref_dictionary[id] = os.path.basename(file)
-                            else:
-                                logging.warning('Non unique topic/section id %s in file %s. This is already found in %s'
-                                    % (id, os.path.basename(file), os.path.basename(xref_dictionary[id])))
 
 def usage(arg):
-    print('correct_references.py -d <ditafolder>')
+    print('refsect2_to_refsect1.py -i <input_file> -o <output_file>')
     sys.exit(arg)
 
 def main():
-    ditafolder = ''
+    input_file = ''
+    output_file = ''
     try:
-        opts, args = getopt.getopt(sys.argv[1:],"hd:")
+        opts, args = getopt.getopt(sys.argv[1:],"hi:o:")
     except getopt.GetoptError as err:
         print(err)
@@ -118 +80 @@
         if opt == '-h':
             usage(0)
-        elif opt in ("-d"):
-            ditafolder = arg
+        elif opt in ("-i"):
+            input_file = arg
+        elif opt in ("-o"):
+            output_file = arg
 
-    if not ditafolder:
-        logging.error('No folder is provided. Exiting')
+    if not input_file:
+        logging.error('No input file is provided. Exiting')
         usage(2)
-    createXrefIdDictionary(ditafolder)
+    if not output_file:
+        logging.error('No output file is provided. Exiting')
+        usage(2)
 
-    vboxmanage_dita_files = glob.glob(ditafolder + "/man_V*dita")
-    for file in vboxmanage_dita_files:
-        file_handle = open(file, 'r', encoding="utf-8")
-        file_content = file_handle.readlines()
-        correctHrefTargets(file_content)
-        file_handle.close()
-        file_handle = open(file, 'w', encoding="utf-8")
-        file_handle.write("".join(file_content))
-        file_handle.close()
+    file_handle = open(input_file, 'r', encoding="utf-8")
+    file_content = file_handle.readlines()
+    new_file_content = replaceRefsect2(file_content)
+    file_handle.close()
+    file_handle = open(output_file , 'w', encoding="utf-8")
+    file_handle.write("".join(new_file_content))
+    file_handle.close()
 
 if __name__ == "__main__":