Changeset 105189 in vbox for trunk/doc/manual

Timestamp:

Jul 8, 2024 2:00:44 PM (7 months ago)

Author:

vboxsync

Message:

Docs: bugref:10705. Add ZIP containing generated DITA files for the DocBook refentry files. Improve cleaning.

Location:

trunk/doc/manual

Files:

• Makefile.kmk (modified) (8 diffs)
• dita-refentry-flat-to-single-topic.sh (modified) (4 diffs)

trunk/doc/manual/Makefile.kmk

@@ -259 +259 @@
         $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/overview_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \
         $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf) \
+        $(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_en_US) \
+        $(addsuffix .kmk,$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_en_US)) \
+        $(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES2_en_US) \
+        $(VBOX_PATH_MANUAL_OUTBASE)/en_US/RefEntryDITA.zip \
+        $(PATH_STAGE_BIN)/RefEntryDITA.zip \
+        $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip \
+        $(PATH_STAGE_BIN)/UserManual-html.zip \
         $(PATH_STAGE_BIN)/UserManual.pdf \
+        $(PATH_STAGE_BIN)/VBoxDocumentation.zip \
         \
         $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \
@@ -327 +335 @@
         $(PATH_STAGE_BIN)/UserManual.qhc
    endif
+  endif
+
+  ifdef VBOX_WITH_DOCS_USERMANUAL_REFENTRY_DITA
+   #
+   # target for installing the chunked HTML docs
+   #
+   INSTALLS += VBox-docs-usermanual-refentry-dita
+   VBox-docs-usermanual-refentry-dita_INST = $(INST_BIN)
+   VBox-docs-usermanual-refentry-dita_MODE = a+r,u+w
+   VBox-docs-usermanual-refentry-dita_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/RefEntryDITA.zip
+   VBOX_MANUAL_PACK += $(PATH_STAGE_BIN)/RefEntryDITA.zip
   endif
 
@@ -608 +627 @@
  #
  # The variable VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_<lang> is defined
- # by this define and should be expaneded as a prerequisite for any rule
+ # by this define and should be expanded as a prerequisite for any rule
  # producing a version of the user manual.
  #
@@ -636 +655 @@
  # @param 2    Filename w/o extension.
  # @param 3    Alternative fallback filename (for isomakercmd-man.xml).
- # @note This produces more files that listed in the output, but we currently let kmk be ignorant of that.
+ # @note This produces more files than listed in the output, but we currently let kmk be ignorant of that.
  define def_vbox_refentry_file_to_dita
   VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$1 += $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).ditamap
   $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).ditamap \
+  + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).ditamap.kmk \
   + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).dita \
   + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).xml: \
@@ -665 +685 @@
                 $$(qfirstfile , $$(qwildcard , $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2).xml) $(3) $$(VBOX_PATH_MANUAL_SRC)/en_US/$(2).xml)
         $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) \
-                --stringparam "g_fReplaceHypens" "true" \
+                --stringparam "g_fReplaceHyphens" "true" \
                 --output "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).dita" \
                 $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-dita.xsl \
@@ -672 +692 @@
                 --mapping-file "$$(VBOX_USER_MANUAL_ID_MAPPING_FILE_$1)" \
                 "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).dita"
-        $$(QUIET)$$(ASH) -x \
+        $$(QUIET)$$(ASH) \
                 "$$(VBOX_PATH_MANUAL_SRC)/dita-refentry-flat-to-single-topic.sh" \
                 "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).dita" \
                 "$$(VBOX_PATH_MANUAL_SRC)/dita-refentry-flat-topic-ids.xsl" \
                 "$$(VBOX_PATH_MANUAL_SRC)/dita-refentry-flat-to-single-topic.xsl" \
+                "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).ditamap.kmk" \
+                "VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES2_$(1)" \
                 "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics" \
                 -- $$(subst $$(REDIRECT),$$(REDIRECT_EXT),$$(call VBOX_XSLTPROC_WITH_CAT)) $(VBOX_XSLTPROC_WORKAROUND) \
@@ -695 +717 @@
         $(evalcall2 def_vbox_refentry_file_to_dita,$(lang),user_isomakercmd-man, \
                 $(PATH_ROOT)/src/VBox/Runtime/common/fs/isomakercmd-man.xml))
+
+ include $(VBOX_PATH_MANUAL_OUTBASE)/refentry.kmk
+
+ $(VBOX_PATH_MANUAL_OUTBASE)/refentry.kmk: \
+        $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES) \
+        ,$(VBOX_PATH_MANUAL_OUTBASE)/refentry_$(lang).kmk)
+        $(QUIET)$(RM) -f -- "$@"
+        $(APPEND) -tn "$@" '# refentry.kmk'
+        $(APPEND) -n "$@" $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),'include $(VBOX_PATH_MANUAL_OUTBASE)/refentry_$(lang).kmk')
+        $(APPEND) -n "$@" '# done'
+
+ ## Include file for all language specific refentry files.
+ # @param 1    Language
+ define def_vbox_refentry_lang_kmk
+  $$(VBOX_PATH_MANUAL_OUTBASE)/refentry_$(1).kmk: \
+        $$(addsuffix .kmk,$$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$(1)))
+        $$(QUIET)$$(RM) -f -- "$$@"
+        $$(APPEND) -tn "$$@" '# refentry_$(1).kmk'
+        $$(APPEND) -n "$$@" $$(addprefix 'include ,$$(addsuffix .kmk',$$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$(1))))
+        $$(APPEND) -n "$$@" '# done'
+
+ endef # def_vbox_refentry_lang_kmk
+
+ $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES) \
+        ,$(evalcall2 def_vbox_refentry_lang_kmk,$(lang)))
 
  # Run conversion testcase.
@@ -709 +756 @@
                 $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-dita.xsl \
                 "$(VBOX_PATH_MANUAL_OUTBASE)/testcase-refentry1.xml"
+
+ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/RefEntryDITA.zip: \
+                $(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_en_US)
+        $(call MSG_L1,Packing documentation $@)
+        $(QUIET)$(RM) -f $@
+        $(QUIET)$(REDIRECT) -C $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ -- $(VBOX_ZIP) \
+                -9 -r "$@" \
+                $(patsubst $(VBOX_PATH_MANUAL_OUTBASE)/en_US/%,%,$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_en_US)) \
+                $(patsubst $(VBOX_PATH_MANUAL_OUTBASE)/en_US/%,%,$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES2_en_US))
+
+ refentry-dita-zip:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/RefEntryDITA.zip
 
  #

trunk/doc/manual/dita-refentry-flat-to-single-topic.sh

@@ -34 +34 @@
 #   2: dita-refentry-flat-topic-ids.xsl
 #   3: dita-refentry-flat-to-single-topic.xsl
-#   4: The out directory.
-#   5: '--'
-#   6+: xsltproc invocation (sans output, input and xslt file).
+#   4: The refentry.kmk file where the DITA file list will be appended.
+#   5: Variable name to update in refentry.kmk.
+#   6: The out directory.
+#   7: '--'
+#   8+: xsltproc invocation (sans output, input and xslt file).
 #
-if test $# -lt 6; then
+if test $# -lt 8; then
     echo "syntax error: too few arguments" 1>&2;
     exit 2;
@@ -45 +47 @@
 MY_XSLT_TOPIC_IDS="$2"
 MY_XSLT_TO_SINGLE_TOPIC="$3"
-MY_OUTPUT_DIR="$4"
-if test "$5" != "--"; then
-    echo "syntax error: Expected '--' as the 5th parameter, got: $5" 1>&2;
+MY_GENERATED_KMK="$4"
+MY_GENERATED_KMK_VARIABLE="$5"
+MY_OUTPUT_DIR="$6"
+if test "$7" != "--"; then
+    echo "syntax error: Expected '--' as the 7th parameter, got: $7" 1>&2;
     exit 2;
 fi
-shift 5
+shift 7
 
 if ! test -f "${MY_INPUT_FILE}"; then
@@ -77 +81 @@
 MY_TOPIC_IDS=$($* "${MY_XSLT_TOPIC_IDS}" "${MY_INPUT_FILE}")
 
+echo "${MY_GENERATED_KMK_VARIABLE} += \\" > "${MY_GENERATED_KMK}"
+
 #
 # Extract each topic.
@@ -86 +92 @@
         --stringparam g_idTopic "${MY_ID}" \
         --output "${MY_OUTPUT_DIR}/${MY_ID}.dita" "${MY_XSLT_TO_SINGLE_TOPIC}" "${MY_INPUT_FILE}"
+    echo "    ${MY_OUTPUT_DIR}/${MY_ID}.dita \\" >> "${MY_GENERATED_KMK}"
+
 done
+echo "" >> "${MY_GENERATED_KMK}"
 exit 0