Changeset 99514 in vbox for trunk/doc/manual

Timestamp:

Apr 22, 2023 1:59:25 AM (21 months ago)

Author:

vboxsync

Message:

manual: Added the changelog to the (DITA) manual. bugref:10302

Location:

trunk/doc/manual

Files:

• Makefile.kmk (modified) (6 diffs)
• dita-refentry-flat-to-single-topic.sh (modified) (1 diff)
• docbook-changelog-to-manual-dita.sh (copied) (copied from trunk/doc/manual/dita-refentry-flat-to-single-topic.sh ) (6 diffs)
• docbook-changelog-to-manual-dita.xsl (added)
• en_US/dita/UserManual.ditamap (modified) (1 diff)
• en_US/dita/topics/ChangeLog.dita (added)
• en_US/dita/topics/changelog-older.dita (added)

trunk/doc/manual/Makefile.kmk

@@ -731 +731 @@
  #
 
- ## Convert a single refentry file to dita.
  # @param 1    Language
  define def_vbox_generate_vboxmanage_overview
@@ -759 +758 @@
 
  #
- # 3a. UserManual.pdf - Run dost.jar from DITA-OT to produce the PDF version.
+ # 3. Convert the changelog from DocBook to a bunch of DITA topics and corresponding map.
+ #
+
+ ##
+ # @param 1    Language
+ # @note  We don't really need to do this for each language, but whatever.
+ # @note  Outputs a bunch of .dita files for each version too...
+ define def_vbox_convert_changelog_to_dita
+  VBOX_USER_MANUAL_DITA_STAGED_FILES_$1 += $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/changelog-versions.ditamap
+  $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/changelog-versions.ditamap: \
+                $$(VBOX_PATH_MANUAL_SRC)/docbook-changelog-to-manual-dita.sh \
+                $$(VBOX_PATH_MANUAL_SRC)/docbook-changelog-to-manual-dita.xsl \
+                $$(VBOX_XML_CATALOG) \
+                $$(VBOX_XML_CATALOG_DOCBOOK) \
+                $$(VBOX_XML_CATALOG_MANUAL) \
+                | $$$$(dir $$$$@)
+        $$(call MSG_TOOL,xsltproc docbook-changelog-to-manual-dita.xsl,,,$$@)
+        $$(QUIET)$$(RM) -f -- "$$@" "[email protected]"
+        $$(QUIET)$$(ASH) \
+                $$(VBOX_PATH_MANUAL_SRC)/docbook-changelog-to-manual-dita.sh \
+                $$(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml \
+                $$(VBOX_PATH_MANUAL_SRC)/docbook-changelog-to-manual-dita.xsl \
+                $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics \
+                -- \
+                $$(call VBOX_XSLTPROC_WITH_CAT)
+ endef # def_vbox_convert_changelog_to_dita
+ $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(evalcall2 def_vbox_convert_changelog_to_dita,$(lang)))
+
+
+ #
+ # 4a. UserManual.pdf - Run dost.jar from DITA-OT to produce the PDF version.
  #
  # Note! The /tempdir is deleted, recreated, used and deleted again for each
@@ -804 +833 @@
 
  #
- # 3b. UserManual.html - Run dost.jar from DITA-OT to produce the HTML versions.
+ # 4b. UserManual.html - Run dost.jar from DITA-OT to produce the HTML versions.
  #
  # We produce both chunked and singled paged HTML versions of the en_US manual
@@ -912 +941 @@
  if defined(VBOX_WITH_DOCS_QHELP) && !defined(VBOX_ONLY_SDK)
   #
-  # 3c. VirtualBox.qch + VirtualBox.qhc - Qt compressed help and collection file.
+  # 4c. VirtualBox.qch + VirtualBox.qhc - Qt compressed help and collection file.
   #
   # See usermanual.pdf under DITA-OT-xxxxx/doc folder for details.
@@ -941 +970 @@
                 $(VBOX_USER_MANUAL_DITA_STAGED_FILES_$(1)) \
                 $(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$(1))
+        $$(call MSG_L1,dita-ot-qhelp, => $$@)
         $$(QUIET)$$(RM) -Rf -- "$$(@D)" "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita-ot-qhelp/"
         $$(QUIET)$$(MKDIR) -- "$$(@D)"
@@ -980 +1010 @@
                 | $$$$(dir $$$$@)
         $$(call MSG_L1,$$(notdir $$(VBOX_QHELPGENERATOR)) $$<,=> $$@)
-        $$(QUIET)$$(RM) -f $$@
+        $$(QUIET)$$(RM) -f -- "$$@"
    ifdef VBOX_WITH_QT6
         $$(QUIET)$$(REDIRECT) -- $$(VBOX_QHELPGENERATOR) $$<

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

@@ -47 +47 @@
 MY_OUTPUT_DIR="$4"
 if test "$5" != "--"; then
-    echo "syntax error: Expected '--' as the 3rd parameter, got: $3" 1>&2;
+    echo "syntax error: Expected '--' as the 5th parameter, got: $5" 1>&2;
     exit 2;
 fi

trunk/doc/manual/docbook-changelog-to-manual-dita.sh

@@ -2 +2 @@
 # $Id$
 ## @file
-# Helper Script for splitting up a convert manpage into separate topic
-# files (named by @id).
+# Helper script for converting the changelog into a ditamap and a topic
+# file per version.
 #
 
@@ -28 +28 @@
 #
 
+#
+# Globals.
+#
+MY_SED=kmk_sed
 
 #
 # This script is very internal, so we got the following fixed position parameters:
-#   1: The input DITA file (output from docbook-refentry-to-manual-dita.xsl).
-#   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).
+#   1: user_ChangeLogImpl.xml to use as input.
+#   2: docbook-changelog-to-manual-dita.xsl
+#   3: The out directory.
+#   4: '--'
+#   5+: xsltproc invocation (sans output, input and xslt file).
 #
 if test $# -lt 6; then
@@ -43 +46 @@
 fi
 MY_INPUT_FILE="$1"
-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 3rd parameter, got: $3" 1>&2;
+MY_XSLT="$2"
+MY_OUTPUT_DIR="$3"
+if test "$4" != "--"; then
+    echo "syntax error: Expected '--' as the 4th parameter, got: $4" 1>&2;
     exit 2;
 fi
-shift 5
+shift 4
 
 if ! test -f "${MY_INPUT_FILE}"; then
@@ -56 +58 @@
     exit 1;
 fi
-if ! test -f "${MY_XSLT_TOPIC_IDS}"; then
+if ! test -f "${MY_XSLT}"; then
     echo "error: The given dita-refentry-flat-topic-ids.xsl file does not exists or is not a regular file: ${MY_XSLT_TOPIC_IDS}" 1>&2;
-    exit 1;
-fi
-if ! test -f "${MY_XSLT_TO_SINGLE_TOPIC}"; then
-    echo "error: The given dita-refentry-flat-to-single-topic.xsl file does not exists or is not a regular file: ${MY_XSLT_TO_SINGLE_TOPIC}" 1>&2;
     exit 1;
 fi
@@ -74 +72 @@
 #
 # First get the ID list from it.
+# We drop the first line with the <?xml ... ?> stuff.
 #
-MY_TOPIC_IDS=$($* "${MY_XSLT_TOPIC_IDS}" "${MY_INPUT_FILE}")
+MY_TOPIC_IDS=$($* --stringparam g_sMode ids "${MY_XSLT}" "${MY_INPUT_FILE}" | ${MY_SED} -e 1d)
 
 #
@@ -85 +84 @@
         --stringparam g_sMode topic \
         --stringparam g_idTopic "${MY_ID}" \
-        --output "${MY_OUTPUT_DIR}/${MY_ID}.dita" "${MY_XSLT_TO_SINGLE_TOPIC}" "${MY_INPUT_FILE}"
+        --output "${MY_OUTPUT_DIR}/${MY_ID}.dita" "${MY_XSLT}" "${MY_INPUT_FILE}"
 done
+
+#
+# Now for the ditamap file.
+#
+$* --stringparam g_sMode map --output "${MY_OUTPUT_DIR}/changelog-versions.ditamap" "${MY_XSLT}" "${MY_INPUT_FILE}"
 exit 0

trunk/doc/manual/en_US/dita/UserManual.ditamap

@@ -677 +677 @@
    </chapter>
 
-   <!-- Change Log-->
+   <!-- Change Log -->
+   <chapter href="topics/ChangeLog.dita">
+      <!-- This map file and all the topics it is referencing is generated from user_ChangeLogImpl.xml. -->
+      <topicref format="ditamap" href="topics/changelog-versions.ditamap"/>
+      <topicref href="topics/changelog-older.dita"/>
+   </chapter>
 
    <!-- Third Party Licenses-->