Index: /trunk/doc/manual/Makefile.kmk
===================================================================
--- /trunk/doc/manual/Makefile.kmk	(revision 56177)
+++ /trunk/doc/manual/Makefile.kmk	(revision 56178)
@@ -136,4 +136,9 @@
 VBOX_HTMLHELP_OPTS ?=
 
+# SDK related globals.
+VBOX_MANUAL_APIREF_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef_apiref.xml
+VBOX_DOC_XIDL_SRC      = $(PATH_ROOT)/src/VBox/Main/idl/VirtualBox.xidl
+VBOX_DOC_XIDL_SRC_TMP  = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.xidl.tmp
+
 ##
 # Non-pattern-rule approach to editing XSLT files.
@@ -142,5 +147,5 @@
 # @param    2   Optional output subdirectory.
 define def_vbox_replace_paths_in_xslt
-CLEANS += $$(VBOX_PATH_MANUAL_OUTBASE)/$2$(notdir $1)
+OTHER_CLEAN += $$(VBOX_PATH_MANUAL_OUTBASE)/$2$(notdir $1)
 $$(VBOX_PATH_MANUAL_OUTBASE)/$2$(notdir $1): $1 | $$$$(dir $$$$@)
 	$$(call MSG_GENERATE,,$$@,$$<)
@@ -156,9 +161,9 @@
 
 
-##########################################################################################
-#
-#  Main targets
-#
-##########################################################################################
+
+#
+# Targets
+#
+
 BLDDIRS += $(VBOX_PATH_MANUAL_OUTBASE)
 
@@ -269,31 +274,46 @@
 
  OTHER_CLEAN += \
- 	$(foreach f,$(VBOX_MANUAL_LANGUAGES), $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG))) \
- 	$(foreach f,en_US,                    $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_SDKREF_XML_FILES))) \
- 	$(foreach f,$(VBOX_MANUAL_LANGUAGES), $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_MANUAL_LATEX_FILES_TARGET))) \
- 	$(foreach f,en_US,                    $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_SDKREF_LATEX_FILES_TARGET))) \
- 	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/, \
- 		catalog docbook \
- 		UserManual.fo) \
- 	$(foreach f,$(VBOX_MANUAL_LANGUAGES), $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/, \
- 		docbook-htmlhelp-formatcfg.xsl \
+ 	$(VBOX_XML_CATALOG) \
+ 	$(VBOX_XML_CATALOG_DOCBOOK) \
+ 	$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/, \
+ 		$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG) \
+               $(VBOX_MANUAL_XML_REFENTRY_FILES) \
+ 		$(VBOX_MANUAL_LATEX_FILES_TARGET) \
+		$(VBOX_MANUAL_PNG_FILES_$(lang)) \
+ 		$(notdir $(VBOX_MANUAL_TEX_UNICODE_FILES)) \
+		$(addprefix HTMLHelp/,$(VBOX_MANUAL_PNG_FILES_$(lang))) \
+               html-single/UserManual.html \
+               $(addprefix html-chunks/ HTMLHelp/, index.html go01.html) \
+               $(foreach n,01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 \
+			,html-chunks/ch$(n).html \
+			HTMLHelp/ch$(n).html \
+			$(foreach d2,0 1 2 3 4 5 6 7 8 9,$(foreach d1,0 1 2 3 4 5 6 7 8 9,HTMLHelp/ch$(n)s$(d2)$(d1).html)) ) \
+               $(foreach n,a b c \
+			,html-chunks/ap$(n).html \
+			HTMLHelp/ap$(n).html \
+               	$(foreach s,01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20,HTMLHelp/ap$(n)s$(s).html) ) \
+               HTMLHelp/toc.hhc \
+               HTMLHelp/htmlhelp.hhp \
+		docbook-htmlhelp-formatcfg.xsl \
 		docbook-html-one-page-formatcfg.xsl \
 		docbook-html-chunks-formatcfg.xsl \
- 		titlepage-htmlhelp.xsl )) \
- 	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_MANUAL_PNG_FILES_$(f)))) \
- 	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/HTMLHelp/,$(VBOX_MANUAL_PNG_FILES_$(f)))) \
- 	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/UserManual.pdf) \
- 	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/VirtualBox.chm) \
+ 		titlepage-htmlhelp.xsl \
+		UserManual.pdf \
+		VirtualBox.chm \
+		)) \
+ 	$(VBOX_PATH_MANUAL_OUTBASE)/$(VBOX_MANUAL_XML_CHANGELOG) \
  	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf) \
  	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm) \
  	$(PATH_STAGE_BIN)/UserManual.pdf \
  	$(PATH_STAGE_BIN)/VirtualBox.chm \
- 	$(foreach f,en_US,$(VBOX_PATH_MANUAL_OUTBASE)/$f/SDKRef.pdf) \
- 	$(PATH_STAGE_BIN)/sdk/docs/SDKRef.pdf \
- 	$(wildcard $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/HTMLHelp/*.h*)) \
- 	$(foreach f,$(VBOX_MANUAL_LANGUAGES),\
- 		$(patsubst $(VBOX_PATH_MANUAL_SRC)/texfiles/unicode/%,$(VBOX_PATH_MANUAL_OUTBASE)/$f/%, \
- 			$(VBOX_MANUAL_TEX_UNICODE_FILES))) \
- 	$(VBOX_PATH_MANUAL_OUTBASE)/$(VBOX_MANUAL_XML_CHANGELOG)
+       \
+ 	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \
+		$(VBOX_SDKREF_XML_FILES) \
+		$(VBOX_SDKREF_LATEX_FILES_TARGET) \
+		SDKRef.pdf \
+		) \
+	$(VBOX_DOC_XIDL_SRC_TMP) \
+	$(VBOX_MANUAL_APIREF_TMP) \
+ 	$(PATH_STAGE_BIN)/sdk/docs/SDKRef.pdf
 
 endif # VBOX_WITH_DOCS
@@ -301,176 +321,10 @@
 
 
-
-##########################################################################################
-#
-#  Rules: Preprocess DocBook XML files
-#  (preliminary step for both CHM and PDF generation)
-#
-##########################################################################################
-
-#
-# The following rules for $(VBOX_PATH_MANUAL_OUTBASE)/*.xml process the XML files
-# in doc/manual to allow for some magic variable replacements. The PDF and CHM
-# targets do not depend on the XML files in doc/manual, but those in
-# $(VBOX_PATH_MANUAL_OUTBASE) instead, which we copy there from here, after that magic
-# processing.
-#
-# So, before copying, the following steps are performed:
-#
-# -- $VBOX_VERSION_* strings are replaced with the actual current VBox version.
-# -- $VBOX_MANAGE_OUTPUT (in VBoxManage.xml) is replaced with the current
-#    output of the actual VBoxManage program, to save us from having to
-#    update the manual all the time.
-#
-
-# Only one changelog for all languages
-# $(VBOX_PATH_MANUAL_OUTBASE)/$(VBOX_MANUAL_XML_CHANGELOG): $(VBOX_PATH_MANUAL_SRC)/$(VBOX_MANUAL_XML_CHANGELOG) | $$(dir $$@)
-# 	$(QUIET)$(INSTALL) -m 0644 $< $@
-
-# intermediate step to do some variable replacement in the document
-$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(filter-out user_VBoxManage.xml,$(VBOX_MANUAL_XML_FILES)))): \
-		$(VBOX_PATH_MANUAL_OUTBASE)/% : $(VBOX_PATH_MANUAL_SRC)/% $(VBOX_VERSION_STAMP) | $$(dir $$@)
-	$(call MSG_L1,Pre-processing [1] $(@F) to $@)
-	$(QUIET)$(RM) -f $@ $@.tmp
-	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
-	               -e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
-	               -e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
-	               -e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
-	               -e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
-	               -e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
-	               -e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
-	               --output $@.tmp $<
-	$(QUIET)$(MV) -f $@.tmp $@
-
-$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/user_ChangeLog.xml): \
-		$(VBOX_PATH_MANUAL_OUTBASE)/% : \
-		$(VBOX_PATH_MANUAL_SRC)/% $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml | $$(dir $$@)
-	$(call MSG_L1,Pre-processing [3] $(@F) to $@)
-	$(QUIET)$(RM) -f $@ $@.tmp $@.tmp2
-	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
-	               -e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
-	               -e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
-	               -e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
-	               -e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
-	               -e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
-	               -e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
-	               --output $@.tmp $<
-	$(QUIET)$(SED) -e '1,/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/!d' \
-	               -e 's/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->//' \
-	               --output $@ $@.tmp
-	var=`$(SED) -n '/!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/p' $<`; \
-		test -n "$${var}" \
-		&& $(SED) -e 's/<?xml version=\"1.0\" encoding=\"UTF-8\"?>//g' \
-			--append $@ $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml; \
-       	true
-	$(QUIET)$(SED) -e '/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/,$$!d' \
-	               -e 's/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->//' --append $@ $@.tmp
-
-# TODO: figure why the rule below doesn't cause kmk to rebuild the manual when a man page changes!
-$(foreach lang,$(VBOX_MANUAL_LANGUAGES), \
-$(eval $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/user_VBoxManage.xml: $(VBOX_PATH_MANUAL_SRC)/$(lang)/user_VBoxManage.xml \
-	$$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES)))))
-
-# user_VBoxManage.xml currently needs some extra processing to stitch in the VBoxManage usage blob.
-$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/user_VBoxManage.xml): \
-		$(VBOX_PATH_MANUAL_OUTBASE)/% : \
-		$(VBOX_PATH_MANUAL_SRC)/% \
-               $$(addprefix $$(@D)/,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
-		$(VBOX_XML_CATALOG) \
-		$(VBOX_XML_CATALOG_DOCBOOK) \
-		$(VBOXMANAGEHELP_PATH) | $$(dir $$@)
-	$(call MSG_L1,Pre-processing [2] $(@F) to $@)
-	$(QUIET)$(RM) -f $@ $@.tmp $@.tmp2
-	$(QUIET)$(SED) \
-		-e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
-		-e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
-		-e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
-		-e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
-		-e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
-		-e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
-		-e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
-		-e 's|@VBOX_PATH_DOCBOOK@|$(VBOX_PATH_DOCBOOK)|g' \
-		-e 's|@VBOX_PATH_MANUAL_SRC@|$(VBOX_PATH_MANUAL_SRC)|g' \
-		--output $@.tmp $<
-	$(QUIET)$(SED) \
-		-e '1,/\$$VBOX_MANAGE_OUTPUT/!d' \
-	        -e 's/\$$VBOX_MANAGE_OUTPUT.*//' \
-	        --output $@.tmp3 $@.tmp
-	$(QUIET)$(REDIRECT) -wo $@.tmp2 -E 'VBOX_LOG_FLAGS=disabled' -E 'VBOX_LOG_DEST=nofile' \
-		$(if $(eq $(KBUILD_TARGET),darwin), -E 'DYLD_FALLBACK_LIBRARY_PATH=$(dir $(LIB_RUNTIME))') \
-		-- \
-		$(VBOXMANAGEHELP_PATH) --dumpopts
-	$(QUIET)$(SED) -e 's/</\&lt;/g' -e 's/>/\&gt;/g' --append $@.tmp3 $@.tmp2
-	$(QUIET)$(SED) \
-		-e '/\$$VBOX_MANAGE_OUTPUT/,$$!d' \
-		-e 's/.*\$$VBOX_MANAGE_OUTPUT//' \
-		--append $@.tmp3 $@.tmp
-if 0 # Not currently needed.
-	$(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output $@ \
-		$(VBOX_PATH_MANUAL_SRC)/usage-to-docbook-manual.xsl \
-		$@.tmp3
-else
-	$(QUIET)$(CP) $@.tmp3 $@
-endif
-	$(QUIET)$(RM) -f $@.tmp $@.tmp2 $@.tmp3
-
-
-# Morph man pages into manual sections.
-$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/,$(VBOX_MANUAL_XML_REFENTRY_FILES))): \
-		$(VBOX_PATH_MANUAL_OUTBASE)/% : $(VBOX_PATH_MANUAL_SRC)/% \
-		$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl \
-		$(VBOX_VERSION_STAMP) | $$(dir $$@)
-	$(call MSG_GENERATE,,$@,$<)
-	$(QUIET)$(RM) -f $@
-	$(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output $@ \
-		$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl $<
-
-# ????
-VBOX_MANUAL_APIREF_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef_apiref.xml
-VBOX_DOC_XIDL_SRC = $(PATH_ROOT)/src/VBox/Main/idl/VirtualBox.xidl
-VBOX_DOC_XIDL_SRC_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.xidl.tmp
-
-$(VBOX_DOC_XIDL_SRC_TMP): $(VBOX_DOC_XIDL_SRC) $(MAKEFILE_CURRENT) | $$(dir $$@)
-	$(call MSG_L1,Generating $@)
-	$(QUIET)$(SED) -e 's|@a \+\(\w\+\)|<tt>\1</tt>|g' \
-	       -e 's|@c \+\(\w\+\)|<tt>\1</tt>|g' \
-	       --output $@ $<
-
-# generate SDKRef_apiref.xml as a docbook file excerpt that will be referenced from the SDKRef.xml.
-$(VBOX_MANUAL_APIREF_TMP): $(VBOX_DOC_XIDL_SRC_TMP) $(VBOX_PATH_MANUAL_SRC)/xidl2docbook.xsl
-	$(call MSG_L1,Generating $@)
-	$(QUIET)$(VBOX_XSLTPROC) --xinclude -o $@ $(VBOX_PATH_MANUAL_SRC)/xidl2docbook.xsl $(VBOX_DOC_XIDL_SRC_TMP)
-
-$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.xml: \
-		$(VBOX_PATH_MANUAL_SRC)/en_US/SDKRef.xml $(VBOX_MANUAL_APIREF_TMP) \
-		| $$(dir $$@)
-	$(call MSG_L1,Pre-processing [2] $(@F) to $@)
-	$(QUIET)$(RM) -f $@ $@.tmp
-	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
-	               -e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
-	               -e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
-	               -e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
-	               -e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
-	               -e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
-	               -e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
-	               --output $@.tmp $<
-	$(QUIET)$(SED) -e '1,/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->/!d' \
-	               -e 's/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->//' \
-	               --output $@ $@.tmp
-	$(QUIET)$(SED) -e 's/<?xml version=\"1.0\" encoding=\"utf-8\"?>//g' --append $@ $(VBOX_MANUAL_APIREF_TMP)
-	$(QUIET)$(SED) -e '/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->/,$$!d' \
-	               -e 's/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->//' --append $@ $@.tmp
-#	$(QUIET)$(MV) -f $@.tmp $@
-
-
-##########################################################################################
-#
-#  Rules: Create or preprocess files for xsltproc
-#  (preliminary step for both CHM and PDF generation)
-#
-##########################################################################################
-
+#
+# To avoid network I/O for fetching DTDs, we generate catalogs mapping the public
+# entity IDs to local files.  (Obviously, only done when we have local files.)
+#
+ifdef VBOX_XML_CATALOG
 # Create a catalog file for xsltproc that points to docbook catalog.
-ifdef VBOX_XML_CATALOG
 $(VBOX_XML_CATALOG): $(MAKEFILE_CURRENT) | $$(dir $$@)
 	$(call MSG_L1,Creating catalog $@)
@@ -529,21 +383,163 @@
 endif
 
-# intermediate step to do some variable replacement in the XSL configuration
-$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/docbook-htmlhelp-formatcfg.xsl): \
-		$(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl $(MAKEFILE_CURRENT) | $$(dir $$@)
-	$(call MSG_L1,Pre-processing $(@F) to $@)
-	$(QUIET)$(RM) -f $@.tmp $@
-	$(QUIET)$(SED) -e 's|\$$DOCBOOKPATH|$(VBOX_PATH_DOCBOOK)|g' \
-	               -e 's|\$$CFGPATH|$(VBOX_PATH_MANUAL_SRC)|g' \
-	               -e 's|\$$TARGETPATH|$(@D)|g' --output $@.tmp $<
+
+##########################################################################################
+#
+#  Rules: Preprocess DocBook XML files
+#  (preliminary step for both CHM and PDF generation)
+#
+##########################################################################################
+
+#
+# The following rules for $(VBOX_PATH_MANUAL_OUTBASE)/*.xml process the XML files
+# in doc/manual to allow for some magic variable replacements. The PDF and CHM
+# targets do not depend on the XML files in doc/manual, but those in
+# $(VBOX_PATH_MANUAL_OUTBASE) instead, which we copy there from here, after that magic
+# processing.
+#
+# So, before copying, the following steps are performed:
+#
+# -- $VBOX_VERSION_* strings are replaced with the actual current VBox version.
+# -- $VBOX_MANAGE_OUTPUT (in VBoxManage.xml) is replaced with the current
+#    output of the actual VBoxManage program, to save us from having to
+#    update the manual all the time.
+#
+
+# Only one changelog for all languages
+# $(VBOX_PATH_MANUAL_OUTBASE)/$(VBOX_MANUAL_XML_CHANGELOG): $(VBOX_PATH_MANUAL_SRC)/$(VBOX_MANUAL_XML_CHANGELOG) | $$(dir $$@)
+# 	$(QUIET)$(INSTALL) -m 0644 $< $@
+
+# intermediate step to do some variable replacement in the document
+$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(filter-out user_VBoxManage.xml,$(VBOX_MANUAL_XML_FILES)))): \
+		$(VBOX_PATH_MANUAL_OUTBASE)/% : $(VBOX_PATH_MANUAL_SRC)/% $(VBOX_VERSION_STAMP) | $$(dir $$@)
+	$(call MSG_L1,Pre-processing [1] $(@F) to $@)
+	$(QUIET)$(RM) -f $@ $@.tmp
+	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
+	               -e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
+	               -e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
+	               -e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
+	               -e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
+	               -e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
+	               -e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
+	               --output $@.tmp $<
 	$(QUIET)$(MV) -f $@.tmp $@
 
-# Prepare the XSL file for our title page, htmlhelp variant.
-$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/titlepage-htmlhelp.xsl): \
-		$(VBOX_PATH_MANUAL_SRC)/titlepage-htmlhelp.xml $(MAKEFILE_CURRENT) | $$(dir $$@)
-	$(call MSG_L1,xsltproc $<)
-	$(QUIET)$(RM) -f $@.tmp $@
-	$(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet -o $@.tmp $(VBOX_PATH_DOCBOOK)/template/titlepage.xsl $<
-	$(QUIET)$(MV) -f $@.tmp $@
+$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/user_ChangeLog.xml): \
+		$(VBOX_PATH_MANUAL_OUTBASE)/% : \
+		$(VBOX_PATH_MANUAL_SRC)/% $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml | $$(dir $$@)
+	$(call MSG_L1,Pre-processing [3] $(@F) to $@)
+	$(QUIET)$(RM) -f $@ $@.tmp $@.tmp2
+	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
+	               -e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
+	               -e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
+	               -e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
+	               -e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
+	               -e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
+	               -e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
+	               --output $@.tmp $<
+	$(QUIET)$(SED) -e '1,/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/!d' \
+	               -e 's/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->//' \
+	               --output $@ $@.tmp
+	var=`$(SED) -n '/!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/p' $<`; \
+		test -n "$${var}" \
+		&& $(SED) -e 's/<?xml version=\"1.0\" encoding=\"UTF-8\"?>//g' \
+			--append $@ $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml; \
+       	true
+	$(QUIET)$(SED) -e '/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/,$$!d' \
+	               -e 's/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->//' --append $@ $@.tmp
+	$(QUIET)$(RM) -f -- "$@.tmp"
+
+# TODO: figure why the rule below doesn't cause kmk to rebuild the manual when a man page changes!
+$(foreach lang,$(VBOX_MANUAL_LANGUAGES), \
+$(eval $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/user_VBoxManage.xml: $(VBOX_PATH_MANUAL_SRC)/$(lang)/user_VBoxManage.xml \
+	$$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES)))))
+
+# user_VBoxManage.xml currently needs some extra processing to stitch in the VBoxManage usage blob.
+$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/user_VBoxManage.xml): \
+		$(VBOX_PATH_MANUAL_OUTBASE)/% : \
+		$(VBOX_PATH_MANUAL_SRC)/% \
+               $$(addprefix $$(@D)/,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
+		$(VBOX_XML_CATALOG) \
+		$(VBOX_XML_CATALOG_DOCBOOK) \
+		$(VBOXMANAGEHELP_PATH) | $$(dir $$@)
+	$(call MSG_L1,Pre-processing [2] $(@F) to $@)
+	$(QUIET)$(RM) -f $@ $@.tmp $@.tmp2
+	$(QUIET)$(SED) \
+		-e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
+		-e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
+		-e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
+		-e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
+		-e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
+		-e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
+		-e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
+		-e 's|@VBOX_PATH_DOCBOOK@|$(VBOX_PATH_DOCBOOK)|g' \
+		-e 's|@VBOX_PATH_MANUAL_SRC@|$(VBOX_PATH_MANUAL_SRC)|g' \
+		--output $@.tmp $<
+	$(QUIET)$(SED) \
+		-e '1,/\$$VBOX_MANAGE_OUTPUT/!d' \
+	        -e 's/\$$VBOX_MANAGE_OUTPUT.*//' \
+	        --output $@.tmp3 $@.tmp
+	$(QUIET)$(REDIRECT) -wo $@.tmp2 -E 'VBOX_LOG_FLAGS=disabled' -E 'VBOX_LOG_DEST=nofile' \
+		$(if $(eq $(KBUILD_TARGET),darwin), -E 'DYLD_FALLBACK_LIBRARY_PATH=$(dir $(LIB_RUNTIME))') \
+		-- \
+		$(VBOXMANAGEHELP_PATH) --dumpopts
+	$(QUIET)$(SED) -e 's/</\&lt;/g' -e 's/>/\&gt;/g' --append $@.tmp3 $@.tmp2
+	$(QUIET)$(SED) \
+		-e '/\$$VBOX_MANAGE_OUTPUT/,$$!d' \
+		-e 's/.*\$$VBOX_MANAGE_OUTPUT//' \
+		--append $@.tmp3 $@.tmp
+if 0 # Not currently needed.
+	$(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output $@ \
+		$(VBOX_PATH_MANUAL_SRC)/usage-to-docbook-manual.xsl \
+		$@.tmp3
+else
+	$(QUIET)$(CP) $@.tmp3 $@
+endif
+	$(QUIET)$(RM) -f $@.tmp $@.tmp2 $@.tmp3
+
+
+# Morph man pages into manual sections.
+$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/,$(VBOX_MANUAL_XML_REFENTRY_FILES))): \
+		$(VBOX_PATH_MANUAL_OUTBASE)/% : $(VBOX_PATH_MANUAL_SRC)/% \
+		$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl \
+		$(VBOX_VERSION_STAMP) | $$(dir $$@)
+	$(call MSG_GENERATE,,$@,$<)
+	$(QUIET)$(RM) -f $@
+	$(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output $@ \
+		$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl $<
+
+
+$(VBOX_DOC_XIDL_SRC_TMP): $(VBOX_DOC_XIDL_SRC) $(MAKEFILE_CURRENT) | $$(dir $$@)
+	$(call MSG_L1,Generating $@)
+	$(QUIET)$(SED) -e 's|@a \+\(\w\+\)|<tt>\1</tt>|g' \
+	       -e 's|@c \+\(\w\+\)|<tt>\1</tt>|g' \
+	       --output $@ $<
+
+# generate SDKRef_apiref.xml as a docbook file excerpt that will be referenced from the SDKRef.xml.
+$(VBOX_MANUAL_APIREF_TMP): $(VBOX_DOC_XIDL_SRC_TMP) $(VBOX_PATH_MANUAL_SRC)/xidl2docbook.xsl
+	$(call MSG_L1,Generating $@)
+	$(QUIET)$(VBOX_XSLTPROC) --xinclude -o $@ $(VBOX_PATH_MANUAL_SRC)/xidl2docbook.xsl $(VBOX_DOC_XIDL_SRC_TMP)
+
+$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.xml: \
+		$(VBOX_PATH_MANUAL_SRC)/en_US/SDKRef.xml $(VBOX_MANUAL_APIREF_TMP) \
+		| $$(dir $$@)
+	$(call MSG_L1,Pre-processing [2] $(@F) to $@)
+	$(QUIET)$(RM) -f $@ $@.tmp
+	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
+	               -e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
+	               -e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
+	               -e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
+	               -e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
+	               -e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
+	               -e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
+	               --output $@.tmp $<
+	$(QUIET)$(SED) -e '1,/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->/!d' \
+	               -e 's/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->//' \
+	               --output $@ $@.tmp
+	$(QUIET)$(SED) -e 's/<?xml version=\"1.0\" encoding=\"utf-8\"?>//g' --append $@ $(VBOX_MANUAL_APIREF_TMP)
+	$(QUIET)$(SED) -e '/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->/,$$!d' \
+	               -e 's/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->//' --append $@ $@.tmp
+#	$(QUIET)$(MV) -f $@.tmp $@
+	$(QUIET)$(RM) -f -- "$@.tmp"
 
 
@@ -558,5 +554,5 @@
 $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/ucs.sty):
 	$(call MSG_L1,Copying unicode support for LaTeX)
-	$(QUIET)$(CP) $(VBOX_MANUAL_TEX_UNICODE_FILES) $(@D)
+	$(QUIET)$(INSTALL_STAGING) -- $(VBOX_MANUAL_TEX_UNICODE_FILES) "$(@D)"
 endif
 
@@ -568,5 +564,5 @@
 		$$(out_dir)/%: $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@)
 	$$(call MSG_L1,Copying temporary $$< => $$@)
-	$$(QUIET)$$(CP) -f $$< $$@
+	$$(QUIET)$$(INSTALL_STAGING) -- '$$<' '$$(@D)'
 endef
 
@@ -632,10 +628,7 @@
 
 
-##########################################################################################
-#
-#  SDKRef.pdf
-#
-##########################################################################################
-
+#
+# SDKRef.pdf
+#
 $(VBOX_PATH_SDK)/docs/SDKRef.pdf: \
 		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex \
@@ -673,28 +666,23 @@
 
 
-##########################################################################################
-#
-#  VirtualBox.chm
-#
-##########################################################################################
-
-#
-# Main rule for the .chm file (target of OTHERS at the top):
-# We first generate a .hhp help source file from the preprocessed
-# DocBook XML files, as defined above,  then feed that into the
-# Microsoft Help Compiler.
-#
 
 ifdef VBOX_WITH_DOCS_CHM
-$(PATH_STAGE_BIN)/VirtualBox.chm: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.chm
+ #
+ # VirtualBox.chm
+ #
+ # We first generate a .hhp help source file from the preprocessed
+ # DocBook XML files, as defined above, then feed that into the
+ # Microsoft Help Compiler.
+ #
+ $(PATH_STAGE_BIN)/VirtualBox.chm: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.chm
 	$(QUIET)$(CP) $< $@
 	$(call MSG_L1,Fresh CHM is now at $@)
 
-$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm): \
+ $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm): \
 	$(PATH_STAGE_BIN)/VirtualBox_%.chm : $(VBOX_PATH_MANUAL_OUTBASE)/%/VirtualBox.chm
 	$(QUIET)$(CP) $< $@
 	$(call MSG_L1,Fresh CHM is now at $@)
 
-$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/VirtualBox.chm): \
+ $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/VirtualBox.chm): \
 		$(VBOX_PATH_MANUAL_OUTBASE)/%/VirtualBox.chm: \
 		$(VBOX_PATH_MANUAL_OUTBASE)/%/HTMLHelp/htmlhelp.hhp \
@@ -704,5 +692,24 @@
 	$(QUIET)$(VBOX_HHC) $(subst /,\\,$<)
 
-$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/HTMLHelp/htmlhelp.hhp): \
+
+ # intermediate step to do some variable replacement in the XSL configuration
+ $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/docbook-htmlhelp-formatcfg.xsl): \
+		$(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl $(MAKEFILE_CURRENT) | $$(dir $$@)
+	$(call MSG_GENERATE,,$@,$<)
+	$(QUIET)$(RM) -f $@
+	$(QUIET)$(SED) -e 's|\$$DOCBOOKPATH|$(VBOX_PATH_DOCBOOK)|g' \
+	               -e 's|\$$CFGPATH|$(VBOX_PATH_MANUAL_SRC)|g' \
+	               -e 's|\$$TARGETPATH|$(@D)|g' --output $@ $<
+
+ # Prepare the XSL file for our title page, htmlhelp variant.
+ $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/titlepage-htmlhelp.xsl): \
+		$(VBOX_PATH_MANUAL_SRC)/titlepage-htmlhelp.xml $(MAKEFILE_CURRENT) | $$(dir $$@)
+	$(call MSG_L1,xsltproc $<)
+	$(QUIET)$(RM) -f $@.tmp $@
+	$(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet -o $@.tmp $(VBOX_PATH_DOCBOOK)/template/titlepage.xsl $<
+	$(QUIET)$(MV) -f $@.tmp $@
+
+
+ $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/HTMLHelp/htmlhelp.hhp): \
 		$(VBOX_PATH_MANUAL_OUTBASE)/%/HTMLHelp/htmlhelp.hhp: \
 		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/%/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
@@ -719,21 +726,22 @@
 		$<
 
-# copy the PNG files.
-# Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
-define def_vbox_cp_images_html
-local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/HTMLHelp
-$$(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \
+ # copy the PNG files.
+ # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
+ define def_vbox_cp_images_html
+ local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/HTMLHelp
+ $$(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \
 			$$(out_dir)/%: $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@)
 	$$(call MSG_L1,Copying temporary $$< => $$@)
 	$$(QUIET)$$(CP) -f $$< $$@
-endef
-
-$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(eval $(def_vbox_cp_images_html)))
-
-# Packing the docs into a zip file
-$(PATH_STAGE_BIN)/VBoxDocumentation.zip: $(VBOX_MANUAL_PACK)
+ endef
+
+ $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(eval $(def_vbox_cp_images_html)))
+
+ # Packing the docs into a zip file
+ $(PATH_STAGE_BIN)/VBoxDocumentation.zip: $(VBOX_MANUAL_PACK)
 	$(call MSG_L1,Packing documentation $@)
 	$(QUIET)$(RM) -f $@
 	$(QUIET)$(REDIRECT) -C $(PATH_STAGE_BIN) -- zip$(HOSTSUFF_EXE) -9 $@ $(notdir $^)
+
 endif # VBOX_WITH_DOCS_CHM
 
