# $Id: Makefile.kmk 99111 2023-03-22 10:18:55Z vboxsync $ ## @file # Sub-Makefile for the VirtualBox User Manual, SDK reference and other manuals. # # # 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 . # # SPDX-License-Identifier: GPL-3.0-only # # # This slightly messy makefile transforms the DocBook XML source for the # user manual into presentation output. We support two targets: # # -- UserManual.pdf, generated by LaTex # # # Both files end up in PATH_STAGE_BIN. # # Both targets indirectly depend on the XML files in this directory; # "indirectly" because we first copy them to PATH_TARGET and hack them # up a bit for variable substitution and such (see below). # The toolchains are roughly like this: # # -- PDF file via Apache FOP: pre-process the XML files in PATH_TARGET, # then create a .FO file (another XML format for "formatted objects") # via xsltproc, then feed the .FO file to Apache FOP to create the PDF. # # -- PDF file via LaTeX: pre-process the XML files in PATH_TARGET, then # run our custom "dblatex" perl script on UserManual.xml, which parses # the XML (using the Perl SAX parsers) and dumps a matching LaTeX file # to UserManual.tex. This is then regularly processed by pdflatex to # generate PDF. # # SUB_DEPTH = ../.. include $(KBUILD_PATH)/subheader.kmk ifndef VBOX_DOC_MANUAL_CONFIG_KMK_INCLUDED include $(PATH_SUB_CURRENT)/Config.kmk endif if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK)) # Whole file. # # Globals # ## Combines the VBOX_MANUAL_LANGUAGES and VBOX_MANUAL_ADD_LANGUAGES lists from # /Config.kmk, as per the VBOX_WITH_DOCS_TRANSLATIONS setting. ifdef VBOX_WITH_DOCS_TRANSLATIONS VBOX_MANUAL_ALL_LANGUAGES := $(VBOX_MANUAL_LANGUAGES) $(VBOX_MANUAL_ADD_LANGUAGES) else VBOX_MANUAL_ALL_LANGUAGES := $(VBOX_MANUAL_LANGUAGES) endif ## The files that should go into VBoxDocumentation.zip (must be immediately under PATH_STAGE_BIN). VBOX_MANUAL_PACK = # Various file lists (mainly needed for OTHER_CLEAN). VBOX_QHELP_OUTPUT_FILES := UserManual.qch UserManual.qhc VBOX_ACCESSIBILITY_XML_FILES := Accessibility.xml VBOX_MANUAL_LATEX_FILES_TARGET := $(addprefix UserManual.,aux log out toc tex) VBOX_SDKREF_LATEX_FILES_TARGET := $(addprefix SDKRef.,aux log out toc tex) VBOX_ACCESSIBILITY_LATEX_FILES_TARGET := $(addprefix Accessibility.,aux log out toc tex) VBOX_MANUAL_TEX_UNICODE_FILES = $(wildcard $(VBOX_PATH_MANUAL_SRC)/texfiles/unicode/*) # Wildcard the images path for every supported language $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES) \ ,$(eval VBOX_MANUAL_PNG_FILES_$$(lang) := $$(patsubst $$(VBOX_PATH_MANUAL_SRC)/$$(lang)/%,%, \ $$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$$(lang)/images/*.png)))) # XML $(foreach lang, $(VBOX_MANUAL_ALL_LANGUAGES), \ $(eval VBOX_MANUAL_XML_FILES_GENERATED_$$(lang) := \ $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/overview_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_man_VBoxHeadless.xml \ $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_man_vboximg-mount.xml \ $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_isomakercmd-man.xml)) # 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 # # PDF LaTeX related globals. # VBOX_PDFLATEX_INTERACTION ?= batchmode # VBOX_PDFLATEX_INTERACTION = errorstopmode - Use this when you wants to figure out build failures # without catting the log a million times. ifeq ($(KBUILD_HOST),win) ifndef VBOX_PDFLATEX VBOX_PDFLATEX := $(firstword $(rsort $(wildcard $(KBUILD_DEVTOOLS)/win.x86/miktex-portable/*/miktex/bin/pdflatex.exe))) ifneq ($(VBOX_PDFLATEX),) VBOX_PDFLATEX_CMD = $(VBOX_PDFLATEX) -halt-on-error -interaction $(VBOX_PDFLATEX_INTERACTION) endif endif ifndef VBOX_PDFLATEX # Tell MiKTeX to automatically download packages if system wide install. VBOX_PDFLATEX := pdflatex VBOX_PDFLATEX_CMD = $(VBOX_PDFLATEX) -halt-on-error -interaction $(VBOX_PDFLATEX_INTERACTION) --enable-installer endif else VBOX_PDFLATEX ?= pdflatex VBOX_PDFLATEX_HALT = $(shell ( $(VBOX_PDFLATEX) -version | head -1 | grep 141592 > /dev/null ) && echo -halt-on-error ) VBOX_PDFLATEX_CMD = pdflatex $(VBOX_PDFLATEX_HALT) -interaction $(VBOX_PDFLATEX_INTERACTION) endif # # DITA-OT related globals. # ## # Copies DITA-OT to $1, runs the dost.jar with /ditadir given and nukes $1 when done. # # Additional options for dost.jar can be specified following the call to VBOX_DITA_RUN_DOST # # @param 1 Temporary+unique DITA-OT path. # @param 2 Additional kmk_redirect options. # @param 3 Parameters for the invoker. # @param 4 Parameters only for 1.8.5. # @param 5 Parameters only for 4.0.2. # VBOX_DITA_RUN_DOST ?= $(REDIRECT) \ -E 'ANT_OPTS=-Xmx512m -Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl' \ -E 'ANT_HOME=$1/tools/ant' \ -E 'DITA_DIR=$1' \ -E 'JAVA_HOME=$(VBOX_JAVA_HOME)' \ -A 'PATH=$(HOST_PATH_SEP)$1/tools/ant/bin' \ -E 'CLASSPATH=$1/lib/dost.jar' \ -A 'CLASSPATH=$(HOST_PATH_SEP)$1/lib' \ -A 'CLASSPATH=$(HOST_PATH_SEP)$1/lib/commons-codec-1.4.jar' \ -A 'CLASSPATH=$(HOST_PATH_SEP)$1/lib/resolver.jar' \ -A 'CLASSPATH=$(HOST_PATH_SEP)$1/lib/icu4j.jar' \ -A 'CLASSPATH=$(HOST_PATH_SEP)$1/lib/xercesImpl.jar' \ -A 'CLASSPATH=$(HOST_PATH_SEP)$1/lib/xml-apis.jar' \ -A 'CLASSPATH=$(HOST_PATH_SEP)$1/lib/saxon/saxon9.jar' \ -A 'CLASSPATH=$(HOST_PATH_SEP)$1/lib/saxon/saxon9-dom.jar' \ $2 \ -- $(ASH) $(VBOX_PATH_MANUAL_SRC)/dita-ot-copy-exec.sh "$(VBOX_DITA_ORIGINAL_PATH)" "$1" \ -- $(VBOX_JAVA) -jar "$1/lib/dost.jar" "/ditadir:$1" $3 $4 # "/outercontrol:fail" ? if 0 # Experiments with dita-ot v4.0.2. Requires java 17. VBOX_JAVA_HOME := C:/Program Files/Java/jdk-17/ VBOX_DITA_ORIGINAL_PATH := D:/Tmp/dita/dita-ot-4.0.2 VBOX_DITA_CLASSPATH = \ $(subst $(SP),;,$(strip \ $(VBOX_DITA_ORIGINAL_PATH)/lib/ant-launcher.jar \ $(VBOX_DITA_ORIGINAL_PATH)/config \ $(VBOX_DITA_ORIGINAL_PATH)/lib \ $(wildcard \ $(VBOX_DITA_ORIGINAL_PATH)/lib/*.jar \ $(VBOX_DITA_ORIGINAL_PATH)/plugins/*/lib/*.jar))) VBOX_DITA_RUN_DOST = $(REDIRECT) \ -E 'ANT_HOME=$(VBOX_DITA_ORIGINAL_PATH)' \ -E 'DITA_DIR=$(VBOX_DITA_ORIGINAL_PATH)' \ -E 'JAVA_HOME=$(VBOX_JAVA_HOME)' \ -E 'CLASSPATH=$(VBOX_DITA_CLASSPATH)' \ $2 \ -- \ $(VBOX_JAVA) \ "-Djava.awt.headless=true" \ "-Dsun.io.useCanonCaches=true" \ "-Dant.home=$(VBOX_DITA_ORIGINAL_PATH)" \ "-Ddita.dir=$(VBOX_DITA_ORIGINAL_PATH)" \ org.apache.tools.ant.launch.Launcher \ -cp "$(VBOX_DITA_CLASSPATH)" \ -buildfile "$(VBOX_DITA_ORIGINAL_PATH)/build.xml" \ -main "org.dita.dost.invoker.Main" \ $(patsubst "/i:%,"--input=%, \ $(patsubst "/transtype:%,"--format=%, \ $(patsubst "/outdir:%,"--output=%, \ $(patsubst "/tempdir:%,"--temp=%, \ $(patsubst "/debug","--debug",$3))))) \ $5 --verbose --debug endif # # Targets # BLDDIRS += $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/, $(VBOX_MANUAL_ALL_LANGUAGES)) ifdef VBOX_ONLY_DOCS PACKING += $(PATH_STAGE_BIN)/VBoxDocumentation.zip endif BLDDIRS += \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/topics \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/topics/images BLDDIRS += \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/, \ $(addsuffix /images, $(VBOX_MANUAL_ALL_LANGUAGES)) \ $(addsuffix /html-single, $(VBOX_MANUAL_ALL_LANGUAGES)) \ $(addsuffix /html-chunks, $(VBOX_MANUAL_ALL_LANGUAGES)) \ $(addsuffix /qhelp, $(VBOX_MANUAL_ALL_LANGUAGES)) \ $(addsuffix /qhelp/images, $(VBOX_MANUAL_ALL_LANGUAGES)) \ $(addsuffix /HTMLHelp, $(VBOX_MANUAL_ALL_LANGUAGES)) \ $(addsuffix /HTMLHelp/images, $(VBOX_MANUAL_ALL_LANGUAGES)) \ ) # Explicit cleaning has some overlap with default cleaning rules, since this # Makefile is using very complex conditionals for selectively creating # specific files, and not everyone remembers to use the same with "kmk clean". OTHER_CLEAN += \ $(VBOX_XML_CATALOG) \ $(VBOX_XML_CATALOG_DOCBOOK) \ $(VBOX_XML_CATALOG_MANUAL) \ $(VBOX_XML_ENTITIES) \ $(foreach lang, $(VBOX_MANUAL_ALL_LANGUAGES) \ ,$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/, \ $(VBOX_XML_XREF_TO_TEXT) \ $(VBOX_XML_XREF_TO_TEXT).cat \ $(addprefix user_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \ $(VBOX_MANUAL_XML_REFENTRY_FILES) \ $(patsubst man_%,%.1,$(basename $(VBOX_MANUAL_XML_REFENTRY_FILES))) \ man_VBoxHeadless.xml \ user_man_VBoxHeadless.xml \ man_vboximg-mount.xml \ user_man_vboximg-mount.xml \ isomakercmd-man.xml \ user_isomakercmd-man.xml \ $(VBOX_MANUAL_LATEX_FILES_TARGET) \ $(VBOX_MANUAL_PNG_FILES_$(lang)) \ $(notdir $(VBOX_MANUAL_TEX_UNICODE_FILES)) \ $(addprefix HTMLHelp/,$(VBOX_MANUAL_PNG_FILES_$(lang))) \ $(addprefix qhelp/, $(VBOX_MANUAL_PNG_FILES_$(lang))) \ html-single/UserManual.html \ $(addprefix qhelp/, UserManual.qhp UserManual.qhcp $(VBOX_QHELP_OUTPUT_FILES)) \ $(addprefix HTMLHelp/, index.html go01.html) \ $(addprefix qhelp/, index.html go01.html) \ $(addprefix html-chunks/, 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 \ html-chunks/re$(n).html \ HTMLHelp/ch$(n).html \ HTMLHelp/re$(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)) \ qhelp/ch$(n).html \ qhelp/re$(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,qhelp/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) \ qhelp/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,qhelp/ap$(n)s$(s).html) ) \ $(foreach n,01 02 03 04 05 \ ,html-chunks/pr$(n).html \ HTMLHelp/pr$(n).html \ $(foreach s,01 02 03 04 05 06 07 08,HTMLHelp/pr$(n)s$(s).html) \ qhelp/pr$(n).html \ $(foreach s,01 02 03 04 05 06 07 08,qhelp/pr$(n)s$(s).html) ) \ HTMLHelp/toc.hhc \ HTMLHelp/htmlhelp.hhp \ qhelp/toc.hhc \ qhelp/htmlhelp.hhp \ UserManual.pdf \ VirtualBox.chm \ $(VBOX_QHELP_OUTPUT_FILES) \ ChangeLog.html \ validatemanual.run \ validateaccessibility.run \ validatesdkref.run \ ) \ ) \ $(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/overview_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \ $(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 \ \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \ $(VBOX_SDKREF_LATEX_FILES_TARGET) \ SDKRef.pdf \ ) \ $(PATH_STAGE_BIN)/sdk/docs/SDKRef.pdf \ \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \ $(VBOX_ACCESSIBILITY_LATEX_FILES_TARGET) \ html-single/Accessibility.html \ Accessibility.pdf \ ) \ $(PATH_STAGE_BIN)/Accessibility.html \ $(PATH_STAGE_BIN)/Accessibility.pdf \ \ $(VBOX_DOC_XIDL_SRC_TMP) \ $(VBOX_MANUAL_APIREF_TMP) ifndef VBOX_ONLY_SDK # # target for installing UserManual.pdf # INSTALLS += VBox-docs-usermanual VBox-docs-usermanual_INST = $(INST_BIN) VBox-docs-usermanual_MODE = a+r,u+w VBox-docs-usermanual_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.pdf VBOX_MANUAL_PACK += $(PATH_STAGE_BIN)/UserManual.pdf ifdef VBOX_WITH_DOCS_TRANSLATIONS # # target for installing translated UserManual_*.pdf # INSTALLS += VBox-docs-usermanual-l10n VBox-docs-usermanual-l10n_INST = $(INST_BIN) VBox-docs-usermanual-l10n_MODE = a+r,u+w VBox-docs-usermanual-l10n_SOURCES = \ $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$(f)/UserManual.pdf=>UserManual_$(f).pdf) VBOX_MANUAL_PACK += $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf) endif ifdef VBOX_WITH_DOCS_HTML # # target for installing the chunked HTML docs # INSTALLS += VBox-docs-usermanual-html VBox-docs-usermanual-html_INST = $(INST_BIN) VBox-docs-usermanual-html_MODE = a+r,u+w VBox-docs-usermanual-html_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip=>UserManual-html.zip VBOX_MANUAL_PACK += $(PATH_STAGE_BIN)/UserManual-html.zip endif ifdef VBOX_WITH_DOCS_QHELP # # Installs the qhelp version of the manual. # INSTALLS += VBox-docs-usermanual-qhelp VBox-docs-usermanual-qhelp_INST = $(INST_BIN) VBox-docs-usermanual-qhelp_MODE = a+r,u+w VBox-docs-usermanual-qhelp_SOURCES = \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qhc \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qch ifdef VBOX_WITH_DOCS_QHELP_PACKING VBOX_MANUAL_PACK += \ $(PATH_STAGE_BIN)/UserManual.qch \ $(PATH_STAGE_BIN)/UserManual.qhc endif endif ifdef VBOX_WITH_DOCS_ACCESSIBILITY # # target for installing Accessibility.pdf # INSTALLS += VBox-docs-accessibility VBox-docs-accessibility_INST = $(INST_BIN) VBox-docs-accessibility_MODE = a+r,u+w VBox-docs-accessibility_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.pdf # # target for installing Accessibility.html # INSTALLS += VBox-docs-accessibility-html VBox-docs-accessibility-html_INST = $(INST_BIN) VBox-docs-accessibility-html_MODE = a+r,u+w VBox-docs-accessibility-html_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html endif endif # !VBOX_ONLY_SDK if defined(VBOX_ONLY_SDK) || defined(VBOX_WITH_DOCS_SDKREF) # # target for installing SDKRef.pdf # INSTALLS += VBox-docs-sdkref VBox-docs-sdkref_INST = $(INST_SDK)docs/ VBox-docs-sdkref_MODE = a+r,u+w VBox-docs-sdkref_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.pdf endif ## # Morph man pages into Docbook manual sections. # $(evalcall2 def_vbox_refentry_to_user_sect1) # # @param 1 Language. # @param 2 the refentry xml base file name. # @param 3 the full refentry xml file path. ## @todo r=bird: This is still Docbook, so unused now? define def_vbox_refentry_to_user_sect1 $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/user_$(2): $(3) \ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl \ $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \ $$(VBOX_XML_ENTITIES) $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@) $$(call MSG_TOOL,xsltproc docbook-refentry-to-manual-sect1.xsl,,$3,$$@) $$(QUIET)$$(RM) -f -- "$$@" $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl $$< endef $(foreach lang, $(VBOX_MANUAL_ALL_LANGUAGES) \ ,$(foreach file, $(VBOX_MANUAL_XML_REFENTRY_FILES) man_VBoxHeadless.xml man_vboximg-mount.xml \ , $(evalcall2 def_vbox_refentry_to_user_sect1,$(lang),$(file),$(VBOX_PATH_MANUAL_SRC)/$(lang)/$(file)))) $(foreach lang, $(VBOX_MANUAL_ALL_LANGUAGES) \ ,$(evalcall2 def_vbox_refentry_to_user_sect1,$(lang),isomakercmd-man.xml,$(PATH_ROOT)/src/VBox/Runtime/common/fs/isomakercmd-man.xml)) # Generates the VBoxManage command overview include file (shared between # languages) from the refsynopsisdiv section of the man pages. ## @todo r=bird: This is still Docbook, so unused now? $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/overview_,$(VBOX_MANUAL_XML_REFENTRY_FILES)): \ $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-overview.xsl \ $$(patsubst overview_%,$$(VBOX_PATH_MANUAL_SRC)/en_US/%,$$(notdir $$@)) \ $(VBOX_XML_CATALOG) \ $(VBOX_XML_CATALOG_DOCBOOK) \ $(VBOX_XML_CATALOG_MANUAL) \ $(VBOX_XML_ENTITIES) | $$(dir $$@) $(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@) $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --output "$@" $< $(filter %.xml,$^) # # Shared rules for LaTeX based PDF generation - Only used for SDK & Accessibility. # ifndef VBOX_OSE # Copy ucs.sty and associated files. ## @todo r=bird: This is ugly since only ucs.sty is listed as output while we're actually copying 177 other files. $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/ucs.sty): | $$(dir $$@) $(call MSG_L1,Copying unicode support for LaTeX) $(QUIET)$(INSTALL_STAGING) -m0644 -- $(VBOX_MANUAL_TEX_UNICODE_FILES) "$(@D)" endif # Copy the PNG files. define def_vbox_cp_images_pdf $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \ $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/% : \ $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@) $$(call MSG_L1,Copying temporary $$< => $$@) $$(QUIET)$$(INSTALL_STAGING) -m0644 -- '$$<' '$$(@D)' endef $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(evalcall2 def_vbox_cp_images_pdf)) ################################################################################################################################# # SDKRef.pdf - xidl => Docbook => LaTeX => PDF # ################################################################################################################################# VBOX_SDKREF_XML_FILES = SDKRef.xml # Replace @a and @c with tags in VirtualBox.xidl. $(VBOX_DOC_XIDL_SRC_TMP): $(VBOX_DOC_XIDL_SRC) $(MAKEFILE_CURRENT) | $$(dir $$@) $(call MSG_L1,Generating $@) $(QUIET)$(SED) \ -e 's|@a \+\(\w\+\)|\1|g' \ -e 's|@c \+\(\w\+\)|\1|g' \ --output $@ $< # Generate SDKRef_apiref.xml as a docbook file excerpt that will be referenced from the SDKRef.xml. $(VBOX_MANUAL_APIREF_TMP): $(VBOX_PATH_MANUAL_SRC)/xidl2docbook.xsl $(VBOX_DOC_XIDL_SRC_TMP) $(call MSG_L1,Generating $@) $(QUIET)$(VBOX_XSLTPROC) $(VBOX_XSLTPROC_OPTS) --xinclude --nonet -o $@ $< $(VBOX_DOC_XIDL_SRC_TMP) # Turn SDKRef.xml into LaTeX. $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex: \ $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_SDKREF_XML_FILES)) \ $(VBOX_MANUAL_APIREF_TMP) \ $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \ $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run,) \ $(VBOX_XML_CATALOG) \ $(VBOX_XML_CATALOG_DOCBOOK) \ $(VBOX_XML_CATALOG_MANUAL) \ $(VBOX_XML_ENTITIES) \ $(MAKEFILE_CURRENT) \ | $$(dir $$@) $(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@) $(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_SDKREF_LATEX_FILES_TARGET)) # generate TeX source from processed docbook and store it in SDKRef.tex.tmp $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG en_US \ -o $@.tmp $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $< # for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word; # the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections $(QUIET)$(SED) \ -e 's|^\\QUOTE{}|\\OQ{}|g' \ -e 's|\(\W\)\\QUOTE{}|\1\\OQ{}|g' \ -e 's|\(\w\)\\QUOTE{}|\1\\CQ{}|g' \ --output $@ $@.tmp $(QUIET)$(RM) -f $@.tmp # Turn SDKRef.tex into a PDF. $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.pdf: \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex \ $(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ucs.sty) \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \ | $$(dir $$@) $(call MSG_L1,pdflatex $< (three passes)) $(QUIET)$(REDIRECT) -C $( LaTeX => PDF # ################################################################################################################################# # Turn Accessibility.xml into LaTeX. $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.tex: \ $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \ $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \ $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run,) \ $(VBOX_XML_CATALOG) \ $(VBOX_XML_CATALOG_DOCBOOK) \ $(VBOX_XML_CATALOG_MANUAL) \ $(VBOX_XML_ENTITIES) \ $(MAKEFILE_CURRENT) \ | $$(dir $$@) $(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@) $(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_ACCESSIBILITY_LATEX_FILES_TARGET)) # generate TeX source from processed docbook and store it in Accessibility.tex.tmp $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG en_US \ -o $@.tmp $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $< # for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word; # the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections $(QUIET)$(SED) \ -e 's|^\\QUOTE{}|\\OQ{}|g' \ -e 's|\(\W\)\\QUOTE{}|\1\\OQ{}|g' \ -e 's|\(\w\)\\QUOTE{}|\1\\CQ{}|g' \ --output $@ $@.tmp $(QUIET)$(RM) -f $@.tmp # Turn Accessibility.tex into a PDF. $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.pdf: \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.tex \ $(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ucs.sty) \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) $(call MSG_L1,pdflatex $< (three passes)) $(QUIET)$(REDIRECT) -C $(/dita/* to the corresponding # VBOX_PATH_MANUAL_OUTBASE location. This is mainly to deal with DITO-OT's # inability to search for topic files in more than one place, so we have to # gather generated and static topic sources + the .ditamap-file(s) in one # place. # # Determin the basic set of files as dictated by the en_US version of the # user manual (relative to $(lang)/dita). We'll use these to supply # incomplete manual translations. # Note! This includes .png as well as .dita and .ditamap files. VBOX_USER_MANUAL_DITA_BASIC_SRC_FILES := \ $(notdir $(wildcard $(VBOX_PATH_MANUAL_SRC)/en_US/dita/*.ditamap)) \ $(addprefix topics/,$(notdir $(wildcard $(VBOX_PATH_MANUAL_SRC)/en_US/dita/topics/*dita))) \ $(addprefix topics/images/,$(notdir $(wildcard $(VBOX_PATH_MANUAL_SRC)/en_US/dita/topics/images/*png))) ## # Produce copying rules for one language and defining the variable # VBOX_USER_MANUAL_DITA_STAGED_FILES_ for use in prerequisite to # anything producing a version of the user manual. # # @param 1 lang define def_vbox_copy_manual_dita_src_files VBOX_USER_MANUAL_DITA_SRC_FILES_$(1) := \ $$(notdir $$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$1/dita/*.ditamap)) \ $$(addprefix topics/,$$(notdir $$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$1/dita/topics/*dita))) \ $$(addprefix topics/images/,$$(notdir $$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$1/dita/topics/images/*png))) VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)_FALLBACK := \ $$(filter-out $$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)), $$(VBOX_USER_MANUAL_DITA_BASIC_SRC_FILES)) VBOX_USER_MANUAL_DITA_STAGED_FILES_$(1) = \ $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/, \ $$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)) \ $$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)_FALLBACK) \ topics/reference.dtd) ifneq ($$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)),) $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/,$$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1))): \ $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/% : \ $$(VBOX_PATH_MANUAL_SRC)/$1/dita/% | $$$$(dir $$$$@) $$(QUIET)$$(INSTALL_STAGING) -m 0644 -- "$$<" "$$(@D)/" endif ifneq ($$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)_FALLBACK),) $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/,$$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)_FALLBACK)): \ $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/% : \ $$(VBOX_PATH_MANUAL_SRC)/en_US/dita/% | $$$$(dir $$$$@) $$(QUIET)$$(INSTALL_STAGING) -m 0644 -- "$$<" "$$(@D)/" endif # Create and empty reference.dtd file as docbook2dita converter mentions it in xml declaration and # xlst parsing complains when it cannot find it. $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/topics/reference.dtd: | $$$$(dir $$$$@) $$(QUIET)$$(TOUCH) -- "$$@" endef $(foreach lang, $(VBOX_MANUAL_ALL_LANGUAGES),$(evalcall2 def_vbox_copy_manual_dita_src_files,$(lang))) # # 2. Convert the manpages from Docbook refentry files to DITA reference files. # # In DITA links needs proper href values, with both file and ID. Since the # source only has IDs, we scan all topics and refentry-files alike and # generate a mapping database before we start converting them. This DB is # then used at the end of each conversion to fix the hrefs. # # Steps taken converting individual Docbook refentry files: # 1. refsect2_to_refsect1.py flattens the refsect1/refsect2 hierarchy, # creating a .xml version next to the final dita file. # 2. docbook2dita.xsl takes that and produces a .dita-file. # 3. mark_external_urls.xsl marks external links in the .dita-file. # 4. add_file_to_id_only_references.py converts ID-only hrefs into # href="filename.dita#ID" using the mapping DB. ## # Do per-language stuff for the refentry -> dita file conversion. # # The variable VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_ is defined # by this define and should be expaneded as a prerequisite for any rule # producing a version of the user manual. # # @param 1 Language. # define def_vbox_refentry_to_dita # Generate a ID to FILE mapping database that def_vbox_refentry_to_dita can apply below. VBOX_USER_MANUAL_ID_MAPPING_FILE_$(1) := $$(VBOX_PATH_MANUAL_OUTBASE)/$1/id-mapping-file.db OTHER_CLEAN += $(VBOX_USER_MANUAL_ID_MAPPING_FILE_$(1)) $$(VBOX_USER_MANUAL_ID_MAPPING_FILE_$(1)) + $$(VBOX_USER_MANUAL_ID_MAPPING_FILE_$(1)).lst: \ $$(VBOX_PATH_MANUAL_SRC)/build_id_to_file_mapping.py \ $$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$1/*.xml) \ $$(filter %.dita,$$(VBOX_USER_MANUAL_DITA_STAGED_FILES_$(1))) \ | $$$$(dir $$$$@) $$(call MSG_L1, $$<) $$(APPEND) -nt "$$@.lst" $$(filter-out %.py,$$^) $$(QUIET)$$(VBOX_BLD_PYTHON) "$$<" --output "$$@" @"$$@.lst" # We must copy over the man_VBoxManage-dhcpserver-dhcpoptions.xml include # file, so that xsltproc can easily find it when running docbook2dita.xsl. $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/topics/man_VBoxManage-dhcpserver-dhcpoptions.xml: \ $$(qfirstfile , $$(qwildcard , $$(VBOX_PATH_MANUAL_SRC)/$(1)/man_VBoxManage-dhcpserver-dhcpoptions.xml) \ $$(VBOX_PATH_MANUAL_SRC)/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xml) | $$$$(dir $$$$@) $$(QUIET)$$(INSTALL_STAGING) -m 0644 -- "$$<" "$$(@D)/" # Accumulated list of conversion output file names to be used as a # prerequisite in rules producing a version of the user manual. VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$1 := \ $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/topics/user_isomakercmd-man.dita # Unlike other refentry docbook files user_isomakercmd-man.xml is located # in the output folder thus a special target for its conversion. Note that # user_isomakercmd-man.xml does not have refsect hierarchy and hrefs to be pre/post # processed. So we skip these steps for this file. $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/topics/user_isomakercmd-man.dita: \ $$(VBOX_DITA_CONVERTER_PATH)/db2dita/docbook2dita.xsl \ $$(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_isomakercmd-man.xml | $$$$(dir $$$$@) $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) \ --maxdepth 6000 \ --output "$$@" \ "$$<" \ $$(VBOX_PATH_MANUAL_OUTBASE)/$1/user_isomakercmd-man.xml endef # def_vbox_refentry_to_dita ## Convert a single refentry file to dita. # @param 1 Language # @param 2 Filename w/o extension. define def_vbox_refentry_file_to_dita VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$1 += $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).dita $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).dita \ + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).xml: \ $$(VBOX_DITA_CONVERTER_PATH)/db2dita/docbook2dita.xsl \ $$(qfirstfile , $$(qwildcard , $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2).xml) $$(VBOX_PATH_MANUAL_SRC)/en_US/$(2).xml) \ $$(VBOX_PATH_MANUAL_SRC)/mark_external_urls.xsl \ $$(VBOX_PATH_MANUAL_SRC)/add_file_to_id_only_references.py \ $$(VBOX_USER_MANUAL_ID_MAPPING_FILE_$1) \ $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/topics/man_VBoxManage-dhcpserver-dhcpoptions.xml \ $$(VBOX_XML_CATALOG) \ $$(VBOX_XML_CATALOG_DOCBOOK) \ $$(VBOX_XML_CATALOG_MANUAL) \ $$(VBOX_XML_ENTITIES) \ $$(VBOX_VERSION_STAMP) \ | $$$$(dir $$$$@) $$(call MSG_TOOL,xsltproc docbook2dita.xsl,,$$(firstword $$(filter %.xml,$$^)),$$@) $$(QUIET)$$(RM) -f "$$@" $$(QUIET)$$(VBOX_BLD_PYTHON) $$(VBOX_PATH_MANUAL_SRC)/refsect2_to_refsect1.py \ -i $$(qfirstfile , $$(qwildcard , $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2).xml) $$(VBOX_PATH_MANUAL_SRC)/en_US/$(2).xml) \ -o "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).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).xml" $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --maxdepth 6000 --output "$$@" \ "$$(VBOX_PATH_MANUAL_SRC)/mark_external_urls.xsl" "$$@" $$(QUIET)$$(VBOX_BLD_PYTHON) $$(VBOX_PATH_MANUAL_SRC)/add_file_to_id_only_references.py \ --mapping-file "$$(VBOX_USER_MANUAL_ID_MAPPING_FILE_$1)" "$$@" endef # def_vbox_refentry_file_to_dita $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES) \ ,$(evalcall2 def_vbox_refentry_to_dita,$(lang)) \ $(foreach file, $(basename $(VBOX_MANUAL_XML_REFENTRY_FILES) man_vboximg-mount man_VBoxHeadless) \ ,$(evalcall2 def_vbox_refentry_file_to_dita,$(lang),$(file)))) # # 3a. 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 # run. So, be careful where you point it. # Note! This crappy utility may fail to find files (or fail to parse the # command line) and still return a successfully (0) exit code. # define def_ditamap_to_pdf $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/UserManual.pdf \ + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/UserManual_pdf.log \ +| $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita.list \ +| $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita.xml.properties: \ $$(VBOX_MANUAL_XML_FILES_COMMON) \ $$(VBOX_MANUAL_XML_FILES_GENERATED_$(lang)) \ $$(VBOX_USER_MANUAL_DITA_STAGED_FILES_$(lang)) \ $$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$(lang)) $$(QUIET)$$(RM) -f -- "$$@" "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/UserManual_pdf.log" $$(QUIET)$$(RM) -Rf -- "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita-ot-pdf/" $$(QUIET)$$(call VBOX_DITA_RUN_DOST,$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita-ot-pdf,, \ "/i:$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/UserManual.ditamap" \ "/transtype:pdf" \ "/filter:$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/htmlhelp.ditaval" \ "/outdir:$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)" \ "/tempdir:$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/temp_pdf", \ ,,"--logfile=$$(@D)/UserManual_pdf.log") ditamap-to-pdf: $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/UserManual.pdf endef $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(evalcall2 def_ditamap_to_pdf,$(lang))) # Useful aliases usermanual UserManual.pdf:: $(PATH_STAGE_BIN)/UserManual.pdf # # 3b. 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 # mainly for uploading to virtualbox.org. The docs build box produces a zip # including these. # ## @todo front page $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html: \ $(VBOX_USER_MANUAL_DITA_STAGED_FILES_en_US) \ $(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_en_US) $(call MSG_L1,Building html chunks $@) $(QUIET)$(RM) -Rf -- "$(@D)" "$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita-ot-html-chunks/" $(QUIET)$(MKDIR) -- "$(@D)" $(QUIET)$(call VBOX_DITA_RUN_DOST,$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita-ot-html-chunks,, \ "/i:$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/UserManual.ditamap" \ "/transtype:xhtml" \ "/filter:$(VBOX_PATH_MANUAL_SRC)/en_US/dita/htmlhelp.ditaval" \ "/outdir:$(@D)" \ "/tempdir:$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/temp_xhtml_chunks" \ ,,"--logfile=$(@D)/UserManual_xhtml.log") html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html # We must modify UserManual.ditamap here, removing all chunk attributes and put # a chunk="to-content" on the root element (bookmap). For clues see: # https://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/chunking.html # https://www.oxygenxml.com/forum/post25114.html?hilit=dita%20xhtml%20chunk#p25114 # We stich the index.html and UserManual-Single.html files together using # SED since we haven't been able to convince DITA-OT to combine them. ## @todo front page $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html: \ $(VBOX_USER_MANUAL_DITA_STAGED_FILES_en_US) \ $(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_en_US) $(call MSG_L1,Building html chunks $@) $(QUIET)$(RM) -f -- "$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/UserManual-Single.ditamap" $(SED) -r -e 's/ chunk=["][^"]+["]//g' -e 's//{p}' \ --output "$@" "$(@D)/UserManual-Single.html" $(APPEND) -n "$@" "" $(SED) -ne '//,/<\/body>/{//d;/<\/body>/d;s/UserManual-Single.html/UserManual.html/g;p}' \ --append "$@" "$(@D)/index.html" $(APPEND) -n "$@" "" $(SED) -ne '//,99999999{//d;s/UserManual-Single.html/UserManual.html/g;p}' \ --append "$@" "$(@D)/UserManual-Single.html" html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip: \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html $(call MSG_L1,Packing documentation $@) $(QUIET)$(RM) -f $@ $(QUIET)$(REDIRECT) -C $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ -- $(VBOX_ZIP) \ -9 -r "$@" \ "html-chunks" \ "html-single" \ -x "html-chunks/dita.list" \ -x "html-chunks/dita.xml.properties" \ -x "html-chunks/UserManual_xhtml.log" \ -x "html-single/dita.list" \ -x "html-single/dita.xml.properties" \ -x "html-single/UserManual-Single_xhtml.log" \ -x "html-single/index.html" \ -x "html-single/UserManual-Single.html" html-zip:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip # # A few things which are shared between htmlhelp and qhelp docs. # TODO: This is Docbook related work. Left here in case we can reuse some of # the ideas from it for DITA-OT. # VBOX_DOCBOOK_HTMLHELP_FORMATCFG = \ $(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl \ $(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl \ $(VBOX_PATH_MANUAL_SRC)/common-html-formatcfg.xsl # Prepare the XSL file for our title page, htmlhelp and qhelp variant. $(VBOX_PATH_MANUAL_OUTBASE)/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 $@ # end old stuff. if defined(VBOX_WITH_DOCS_QHELP) && !defined(VBOX_ONLY_SDK) # # 3c. VirtualBox.qch + VirtualBox.qhc - Qt compressed help and collection file. # # See usermanual.pdf under DITA-OT-xxxxx/doc folder for details. # # Enable Qt and locate the Qt help generator. ifdef VBOX_WITH_QT6 USES += qt6 VBOX_QHELPGENERATOR = $(PATH_TOOL_QT6_LIBEXEC)/qhelpgenerator else USES += qt5 VBOX_QHELPGENERATOR_VERSION_MINOR = $(shell $(REDIRECT) -E QT_QPA_PLATFORM_PLUGIN_PATH=$(PATH_SDK_QT5)/plugins -- $(PATH_TOOL_QT5_BIN)/qhelpgenerator -v 2>/dev/null | $(SED) -ne 's/.*(Qt [1-9][0-9]*\.\([1-9][0-9]*\)\.[1-9][0-9]*).*$$/\1/p') VBOX_QHELPGENERATOR = $(PATH_TOOL_QT5_BIN)/$(if-expr $(VBOX_QHELPGENERATOR_VERSION_MINOR) >= 12,qhelpgenerator,qcollectiongenerator) endif ## Build QHelp version of manual for given language. # @param 1 Language # @param 2 The language specific qhelp output directory. define def_vbox_usermanual_as_qhelp # 1. Generate UserManual.hpp using DITA-OT. # # Setting HHCDIR here so that it fails to locate hcc.exe and always skips the # compilation step that produces the .chm-file, since we don't need it and it # mangles the path so it always fails anyway. ## @todo front page. $(2)/UserManual.hhp: \ $(VBOX_USER_MANUAL_DITA_STAGED_FILES_$(1)) \ $(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$(1)) $$(QUIET)$$(RM) -Rf -- "$$(@D)" "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita-ot-qhelp/" $$(QUIET)$$(MKDIR) -- "$$(@D)" $$(QUIET)$$(call VBOX_DITA_RUN_DOST,$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita-ot-qhelp, -EHHCDIR="$$(@D)", \ "/i:$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/UserManual.ditamap" \ "/transtype:htmlhelp" \ "/filter:$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/htmlhelp.ditaval" \ "/outdir:$(2)" \ "/tempdir:$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/temp_qhelp" \ ,,"--logfile=$(2)/UserManual_htmlhelp.log") ditamap-to-htmlhelp: $(2)/UserManual.hhp # 2. Generate a Qt Help Project file (QHP) using htmlhelp-qthelp.py. $(2)/UserManual.qhp: \ $(2)/UserManual.hhp \ $$(VBOX_PATH_MANUAL_SRC)/htmlhelp-qthelp.py \ | $$$$(dir $$$$@) $$(call MSG_L1,htmlhelp-qthelp.py $$<,=> $$@) $$(QUIET)$$(RM) -f -- "$$@" $$(QUIET)$$(VBOX_BLD_PYTHON) $$(VBOX_PATH_MANUAL_SRC)/htmlhelp-qthelp.py \ -d "$$( $$@) $$(QUIET)$$(RM) -f $$@ ifdef VBOX_WITH_QT6 $$(QUIET)$$(REDIRECT) -- $$(VBOX_QHELPGENERATOR) $$< else $$(QUIET)$$(REDIRECT) -E QT_QPA_PLATFORM_PLUGIN_PATH=$$(PATH_SDK_QT5)/plugins -- $$(VBOX_QHELPGENERATOR) $$< endif $$(call MSG_L1,Fresh QCH is now at $$@) endef # def_vbox_usermanual_as_qhelp $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES) \ ,$(evalcall2 def_vbox_usermanual_as_qhelp,$(lang),$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/qhelp)) qhelp:: $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/, $(VBOX_QHELP_OUTPUT_FILES)) endif # VBOX_WITH_DOCS_QHELP && !VBOX_ONLY_SDK ################################################################################################################################# # Miscellaneous # ################################################################################################################################# # # ChangeLog.html # # This XSLT rule formats en_US/user_ChangeLog.xml (which includes the actual change log # contained in user_ChangeLogImpl.xml) as a standalone HTML file. # $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html: \ $(VBOX_PATH_MANUAL_SRC)/en_US/docbook-changelog-formatcfg.xsl \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml \ $(VBOX_XML_CATALOG) \ $(VBOX_XML_CATALOG_DOCBOOK) \ $(VBOX_XML_CATALOG_MANUAL) \ $(VBOX_XML_ENTITIES) | $$(dir $$@) $(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@) $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --output "$@" "$<" $(filter %.xml,$^) $(call MSG_L1,Fresh ChangeLog.html is now at $@) cl-html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html # # VBoxManage man pages (parts also required by VBoxManage built-in help). # ## # Emits rules for preprocessing refentry sources (applying remarks element), # and for producing the actual man pages. # $(evalcall2 def_vbox_refentry_to_manpage) # @param 1 The language # @param 2 The file name (no path). define def_vbox_refentry_to_manpage $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(2): \ $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2) \ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl \ $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT) \ $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \ $$(VBOX_XML_ENTITIES) $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@) $$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@) $$(QUIET)$$(RM) -f "$$@" $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ \ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl $$< $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@.tmp $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT) $$@ $$(QUIET)$$(MV) -f -- "$$@.tmp" "$$@" if defined(VBOX_HAVE_XMLLINT) $$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$@ endif $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(patsubst man_%,%.1,$(basename $(2))): \ $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(2) \ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage.xsl \ $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \ $$(VBOX_XML_ENTITIES) $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@) $$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@) $$(QUIET)$$(RM) -f "$$@" $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --maxdepth 6000 --output $$@ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage.xsl $$< endef $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \ , $(evalcall2 def_vbox_refentry_to_manpage,$(lang),$(file)))) # Handy aliases. validate-manpages:: $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_REFENTRY_FILES)) man-experiment:: $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \ ,$$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/$(patsubst man_%,%.1,$(basename $(file))))) # # Manually updating the DHCP option list taken from VirtualBox.xidl # dhcpoptions: $(PATH_ROOT)/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xsl \ $(PATH_ROOT)/src/VBox/Main/idl/VirtualBox.xidl $(call VBOX_XSLTPROC) --output "$(PATH_ROOT)/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xml" $^ # # Packing the docs into a zip file (part of the packing pass on the docs build box). # ifneq ($(VBOX_MANUAL_PACK),) $(PATH_STAGE_BIN)/VBoxDocumentation.zip: $(VBOX_MANUAL_PACK) $(call MSG_L1,Packing documentation $@) $(QUIET)$(RM) -f $@ $(QUIET)$(REDIRECT) -C $(PATH_STAGE_BIN) -- $(VBOX_ZIP) -9 $@ $(notdir $^) endif endif # if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK)) include $(FILE_KBUILD_SUB_FOOTER)