# $Id: Makefile.kmk 56533 2015-06-18 18:15:51Z vboxsync $ ## @file # Sub-Makefile for the VBox User Manual. # # # Copyright (C) 2006-2015 Oracle Corporation # # This file is part of VirtualBox Open Source Edition (OSE), as # available from http://www.virtualbox.org. This file is free software; # you can redistribute it and/or modify it under the terms of the GNU # General Public License (GPL) as published by the Free Software # Foundation, in version 2 as it comes in the "COPYING" file of the # VirtualBox OSE distribution. VirtualBox OSE is distributed in the # hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. # # # 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 # # -- VirtualBox.chm # # 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. # # -- CHM file: again, pre-process the XML files in PATH_TARGET, then use # xsltproc to create a .HHP file for the Microsoft Help Compiler, then # feed that file to it. # SUB_DEPTH = ../.. include $(KBUILD_PATH)/subheader.kmk # # Globals # # Error out if someone tries to override old globals. ifdef HTMLHELPOPTS $(error HTMLHELPOPTS was renamed to VBOX_HTMLHELP_OPTS!) endif ifdef DOCBOOKPATH $(error DOCBOOKPATH was renamed to VBOX_PATH_DOCBOOK!) endif ifdef DOCBOOKPATH $(error DOCBOOKPATH was renamed to VBOX_PATH_DOCBOOK!) endif ifdef XML_CATALOG $(error XML_CATALOG was renamed to VBOX_XML_CATALOG!) endif ifdef VBOX_XML_CATALOG_DOCBOOK $(error XML_CATALOG_DOCBOOK was renamed to VBOX_XML_CATALOG_DOCBOOK!) endif ifdef VBOXMANAGEPATH $(error VBOXMANAGEPATH was renamed to VBOXMANAGEHELP_PATH!) endif ifdef PDFLATEX_INTERACTION $(error PDFLATEX_INTERACTION was renamed to VBOX_PDFLATEX_INTERACTION!) endif ifdef PDFLATEX $(error PDFLATEX was renamed to VBOX_PDFLATEX_CMD!) endif ifdef HHC $(error HHC was renamed to VBOX_HHC!) endif # Source and output locations. VBOX_PATH_MANUAL_SRC := $(PATH_SUB_CURRENT) VBOX_PATH_MANUAL_OUTBASE := $(PATH_TARGET)/manual # tool locations ifndef VBOX_OSE # use docbook from our tools directory VBOX_PATH_DOCBOOK ?= $(PATH_DEVTOOLS)/common/DocBook/v1.69.1 VBOX_PATH_DOCBOOK_DTD ?= $(PATH_DEVTOOLS)/common/docbook-xml/v4.3 VBOX_XML_CATALOG ?= $(VBOX_PATH_MANUAL_OUTBASE)/catalog VBOX_XML_CATALOG_DOCBOOK ?= $(VBOX_PATH_MANUAL_OUTBASE)/docbook else # use docbook of the build host VBOX_PATH_DOCBOOK ?= http://docbook.sourceforge.net/release/xsl/current/ endif # xsltproc with the catalog trick if applicable. ifdef VBOX_XML_CATALOG VBOX_XSLTPROC_WITH_CAT = $(REDIRECT) -E "XML_CATALOG_FILES=$(VBOX_XML_CATALOG)" -- \ $(VBOX_XSLTPROC) --nonet --xinclude $(VBOX_XSLTPROC_OPTS) VBOX_XMLLINT_WITH_CAT = $(REDIRECT) -E "XML_CATALOG_FILES=$(VBOX_XML_CATALOG)" -- \ $(VBOX_XMLLINT) --nonet --xinclude --noout $(VBOX_XMLLINT_OPTS) else VBOX_XSLTPROC_WITH_CAT = $(VBOX_XSLTPROC) --nonet --xinclude $(VBOX_XSLTPROC_OPTS) VBOX_XMLLINT_WITH_CAT = $(VBOX_XMLLINT) --nonet --xinclude --noout $(VBOX_XMLLINT_OPTS) endif VBOXMANAGEHELP_PATH ?= $(PATH_STAGE_BIN)/VBoxManageHelp$(SUFF_EXE) # VBOX_PDFLATEX_INTERACTION = errorstopmode - Use this when you wants to figure out build failures # without catting the log a million times. VBOX_PDFLATEX_INTERACTION ?= batchmode ifeq ($(KBUILD_HOST),win) ifndef VBOX_PDFLATEX VBOX_PDFLATEX := $(firstword $(rsort $(wildcard $(PATH_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 # Windows HTML Help Workshop compiler (stupid thing always returns an error!) VBOX_HHC = -$(EXEC_X86_WIN32) $(VBOX_PATH_HTML_HELP_WORKSHOP)/hhc.exe # Additional xsltproc options when generating 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. # $(evalcall2 def_vbox_replace_paths_in_xslt) # @param 1 The XSLT source file (relative to Makefile dir). # @param 2 Optional output subdirectory. define def_vbox_replace_paths_in_xslt OTHER_CLEAN += $$(VBOX_PATH_MANUAL_OUTBASE)/$2$(notdir $1) $$(VBOX_PATH_MANUAL_OUTBASE)/$2$(notdir $1): $$(VBOX_PATH_MANUAL_SRC)/$1 | $$$$(dir $$$$@) $$(call MSG_GENERATE,,$$@,$$<) $$(QUIET)$$(SED) \ -e 's|@VBOX_PATH_DOCBOOK@|$$(VBOX_PATH_DOCBOOK)|g' \ -e 's|@VBOX_PATH_MANUAL_SRC@|$$(VBOX_PATH_MANUAL_SRC)|g' \ -e 's|@VBOX_PATH_MANUAL_OUTBASE@|$$(VBOX_PATH_MANUAL_OUTBASE)|g' \ \ -e 's|@CFGPATH@|$$(VBOX_PATH_MANUAL_SRC)|g' \ -e 's|@TARGETPATH@|$$(@D)|g' \ --output "$$(@)" $$< endef ## List of refentry files (manpages). VBOX_MANUAL_XML_REFENTRY_FILES = \ man_VBoxManage-debugvm.xml \ man_VBoxManage-extpack.xml # # Targets # BLDDIRS += $(VBOX_PATH_MANUAL_OUTBASE) if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK)) if defined(VBOX_ONLY_SDK) || defined(VBOX_WITH_DOCS_SDKREF) ## @todo make this an install target, drop the BLDDIRS. OTHERS += \ $(VBOX_PATH_SDK)/docs/SDKRef.pdf BLDDIRS += \ $(VBOX_PATH_SDK)/docs endif ifdef VBOX_WITH_DOCS_CHM VBOX_PATH_BIN_CHM = $(PATH_STAGE_BIN)/VirtualBox.chm else # Do not build chm. VBOX_PATH_BIN_CHM = endif ifndef VBOX_ONLY_SDK VBOX_MANUAL_PACK += \ $(PATH_STAGE_BIN)/UserManual.pdf \ $(VBOX_PATH_BIN_CHM) OTHERS += \ $(PATH_STAGE_BIN)/UserManual.pdf OTHERS.win += \ $(VBOX_PATH_BIN_CHM) OTHERS.linux += \ $(VBOX_PATH_BIN_CHM) ifdef VBOX_WITH_DOCS_TRANSLATIONS OTHERS += \ $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf) ifdef VBOX_WITH_DOCS_CHM OTHERS.win += \ $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm) OTHERS.linux += \ $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm) endif endif endif # !VBOX_ONLY_SDK ifdef VBOX_ONLY_DOCS PACKING += $(PATH_STAGE_BIN)/VBoxDocumentation.zip endif ifdef VBOX_WITH_DOCS_TRANSLATIONS VBOX_MANUAL_LANGUAGES += $(VBOX_MANUAL_ADD_LANGUAGES) endif VBOX_MANUAL_XML_CHANGELOG = \ user_ChangeLogImpl.xml VBOX_MANUAL_XML_FILES = \ UserManual.xml \ user_AdvancedTopics.xml \ user_BasicConcepts.xml \ user_Glossary.xml \ user_Frontends.xml \ user_Installation.xml \ user_GuestAdditions.xml \ user_Introduction.xml \ user_KnownIssues.xml \ user_PrivacyPolicy.xml \ user_Security.xml \ user_Technical.xml \ user_ThirdParty.xml \ user_Troubleshooting.xml \ user_VBoxManage.xml \ user_VirtualBoxAPI.xml \ user_Storage.xml \ user_Networking.xml VBOX_MANUAL_XML_FILES_INCL_CHANGELOG = $(VBOX_MANUAL_XML_FILES) \ user_ChangeLog.xml VBOX_SDKREF_XML_FILES = \ SDKRef.xml # Wildcard the images path for every supported language $(foreach f,$(VBOX_MANUAL_LANGUAGES), \ $(eval VBOX_MANUAL_PNG_FILES_$$(f) := $$(patsubst $$(VBOX_PATH_MANUAL_SRC)/$$(f)/%,%,$$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$$(f)/images/*.png)))) VBOX_MANUAL_TEX_UNICODE_FILES = \ $(wildcard $(VBOX_PATH_MANUAL_SRC)/texfiles/unicode/*) VBOX_MANUAL_LATEX_FILES_TARGET = \ $(addprefix UserManual.,aux log out toc tex) VBOX_SDKREF_LATEX_FILES_TARGET = \ $(addprefix SDKRef.,aux log out toc tex) BLDDIRS += \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/,\ $(VBOX_MANUAL_LANGUAGES) \ $(addsuffix /images, $(VBOX_MANUAL_LANGUAGES)) \ $(addsuffix /html-single, $(VBOX_MANUAL_LANGUAGES)) \ $(addsuffix /html-chunks, $(VBOX_MANUAL_LANGUAGES)) \ $(addsuffix /HTMLHelp, $(VBOX_MANUAL_LANGUAGES)) \ $(addsuffix /HTMLHelp/images, $(VBOX_MANUAL_LANGUAGES)) \ ) ifdef VBOX_WITH_DOCS_CHM VBOX_MANUAL_PACK += \ $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf $(PATH_STAGE_BIN)/VirtualBox_$(f).chm) endif OTHER_CLEAN += \ $(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) \ $(addprefix user_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \ $(patsubst man_%,%.1,$(basename $(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 HTMLHelp/, 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)) ) \ $(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 \ UserManual.pdf \ VirtualBox.chm \ validatemanual.run \ )) \ $(VBOX_PATH_MANUAL_OUTBASE)/$(VBOX_MANUAL_XML_CHANGELOG) \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/overview_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \ $(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml \ $(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_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 # if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK)) # # 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. $(VBOX_XML_CATALOG): $(MAKEFILE_CURRENT) | $$(dir $$@) $(call MSG_L1,Creating catalog $@) $(QUIET)$(RM) -f $@.tmp $@ $(QUIET)$(APPEND) $@.tmp '' $(QUIET)$(APPEND) $@.tmp '' $(QUIET)$(APPEND) $@.tmp '' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp '' $(QUIET)$(MV) -f $@.tmp $@ # Create a docbook catalog file for xsltproc that points to the local docbook files. $(VBOX_XML_CATALOG_DOCBOOK): $(MAKEFILE_CURRENT) | $$(dir $$@) $(call MSG_L1,Creating catalog $@) $(QUIET)$(RM) -f $@.tmp $@ $(QUIET)$(APPEND) $@.tmp '' $(QUIET)$(APPEND) $@.tmp '' $(QUIET)$(APPEND) $@.tmp '' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp ' ' $(QUIET)$(APPEND) $@.tmp '' $(QUIET)$(MV) -f $@.tmp $@ endif if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK)) ########################################################################################## # # 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,//!d' \ -e 's///' \ --output $@ $@.tmp var=`$(SED) -n '/!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/p' $<`; \ test -n "$${var}" \ && $(SED) -e 's///g' \ --append $@ $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml; \ true $(QUIET)$(SED) -e '//,$$!d' \ -e 's///' --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)/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)/user_VBoxManage_CommandsOverview.xml )) # 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)/user_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ $$(addprefix $$(@D)/overview_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ $(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml \ $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \ $(VBOXMANAGEHELP_PATH) | $$(dir $$@) $(call MSG_L1,Pre-processing [2] $(@F) to $@) $(QUIET)$(RM) -f $@ $@.dumpopts $@.screen $(QUIET)$(REDIRECT) -wo $@.dumpopts -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 ':a' \ -e 'N' \ -e '$(DOLLAR)!ba' \ -e 's//\>\;/g' \ -e 's/\n*$(DOLLAR)/<\/screen>/' \ -e 's/^//' \ --output $@.screen $@.dumpopts $(QUIET)$(SED) \ -e '/@VBOX_MANAGE_OUTPUT@/{' -e 'r $@.screen' -e 'd' -e '}' \ \ -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 "$@" \ "$<" $(QUIET)$(RM) -f $@.dumpopts $@.screen ## # Morph man pages into manual sections. # $(evalcall2 def_vbox_refentry_to_user_sect1) # @param 1 The XSLT source file (relative to Makefile dir). # @param 2 Optional output subdirectory. define def_vbox_refentry_to_user_sect1 $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/user_$(2): \ $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2) \ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl \ $$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \ $$(VBOX_VERSION_STAMP) | $$(dir $$@) $$(call MSG_GENERATE,,$$@,$$<) $$(QUIET)$$(RM) -f "$$@" $$(QUIET)$$(VBOX_XSLTPROC_WITH_CAT) --output $$@ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl $$< endef $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \ , $(evalcall2 def_vbox_refentry_to_user_sect1,$(lang),$(file)))) $(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 $@ $< # Generates the VBoxManage command overview include file (shared between # languages) from the refsynopsisdiv section of the man pages. $(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) \ | $$(dir $$@) $(call MSG_GENERATE,,$@,$(filter %.xml,$^)) $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --output "$@" $< $(filter %.xml,$^) $(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml: $(MAKEFILE_CURRENT) | $$(dir $$@) $(call MSG_GENERATE,,$@,) $(QUIET)$(APPEND) -tn "$@" \ '' \ '' \ '' \ $(foreach refentry, $(filter man_VBoxManage%,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \ , ' ') \ '' # 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,//!d' \ -e 's///' \ --output $@ $@.tmp $(QUIET)$(SED) -e 's///g' --append $@ $(VBOX_MANUAL_APIREF_TMP) $(QUIET)$(SED) -e '//,$$!d' \ -e 's///' --append $@ $@.tmp # $(QUIET)$(MV) -f $@.tmp $@ $(QUIET)$(RM) -f -- "$@.tmp" ########################################################################################## # # Shared rules for PDF generation # ########################################################################################## ifndef VBOX_OSE # copy ucs.sty and related files $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/ucs.sty): $(call MSG_L1,Copying unicode support for LaTeX) $(QUIET)$(INSTALL_STAGING) -m0644 -- $(VBOX_MANUAL_TEX_UNICODE_FILES) "$(@D)" endif # 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_pdf local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang) $(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \ $$(out_dir)/%: $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@) $$(call MSG_L1,Copying temporary $$< => $$@) $$(QUIET)$$(INSTALL_STAGING) -m0644 -- '$$<' '$$(@D)' endef $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_cp_images_pdf)) ########################################################################################## # # UserManual.pdf # ########################################################################################## ## @todo INSTALLS target for this! $(PATH_STAGE_BIN)/UserManual.pdf: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.pdf | $$(dir $$@) $(QUIET)$(CP) $< $@ $(call MSG_L1,Fresh LaTeX-generated PDF is now at $@) $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf): \ $(PATH_STAGE_BIN)/UserManual_%.pdf : $(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.pdf $(QUIET)$(CP) $< $@ $(call MSG_L1,Fresh LaTeX-generated PDF is now at $@) $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/UserManual.pdf): \ $(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.pdf : \ $(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.tex \ $(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/%/ucs.sty) \ $(foreach f,$(VBOX_MANUAL_LANGUAGES),\ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_MANUAL_PNG_FILES_$(f)))) | $$(dir $$@) # PDF generation via Latex: generate the .tex file $(call MSG_L1,pdflatex $< (four passes) -> $@) $(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(VBOX_PDFLATEX_CMD) UserManual.tex $(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(VBOX_PDFLATEX_CMD) UserManual.tex $(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(VBOX_PDFLATEX_CMD) UserManual.tex $(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(VBOX_PDFLATEX_CMD) UserManual.tex $(QUIET)$(SED) -ne '/Warning: Hyper reference/p' $(basename $<).log $(QUIET)$(SED) -n \ -e '/Warning: There were \(undefined references\|multiply-defined labels\)/{p; q 1}' \ $(basename $@).log ##@todo restore this when above has been converted to INSTALLS target. $(call MSG_L1,Fresh LaTeX-generated PDF is now at $@) # generate temporary LaTeX source from processed XML $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/UserManual.tex): \ $(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.tex : \ $(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.xml \ $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/%/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \ $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/%/validatemanual.run,) \ $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE_CURRENT) $(call MSG_L1,Generating $@ from DocBook XML) $(QUIET)$(RM) -f $(addprefix $(@D)/,$(VBOX_MANUAL_LATEX_FILES_TARGET)) # generate TeX source from processed docbook and store it in UserManual.tex.tmp; # pass current language to xsltproc in TARGETLANG variable (extract it from the # current directory, should become "de_DE" or the like) $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG $(notdir $(@D)) \ -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 # Useful aliases usermanual UserManual.pdf:: $(PATH_STAGE_BIN)/UserManual.pdf debug-usermanual: $(MAKE) --pretty-command-printing -j1 VBOX_PDFLATEX_INTERACTION=errorstopmode $(PATH_STAGE_BIN)/UserManual.pdf # # Generate rules for validating the UserManual.xml. These are invoked # automatically at build time, but can also be manually invoked via the # 'validatemanual' and 'validatemanual_' aliases. # define def_vbox_validate_xml validatemanual_$(lang):: $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/validatemanual.run $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/validatemanual.run: \ $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/UserManual.xml \ $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/,$$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \ $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(MAKEFILE_CURRENT) | $$$$(dir $$$$@) $$(call MSG_L1,Validating $$<) $$(QUIET)$$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$< $$(QUIET)$$(APPEND) -t "$$@" "done" endef $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_validate_xml)) validatemanual:: $(foreach lang,$(VBOX_MANUAL_LANGUAGES),validatemanual_$(lang)) # # SDKRef.pdf # $(VBOX_PATH_SDK)/docs/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 $$@) # PDF generation via Latex: generate the .tex file $(QUIET)$(MKDIR) -p $(VBOX_PATH_SDK)/docs $(call MSG_L1,pdflatex $< (three passes)) $(QUIET)$(REDIRECT) -C $( $@) $(QUIET)$(RM) -f $@ $(QUIET)$(VBOX_HHC) $(subst /,\\,$<) # 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 $@ $< # Manual formatcfg dependencies. $(foreach lang,$(VBOX_MANUAL_LANGUAGES), $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/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 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: \ $(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.xml \ $(VBOX_PATH_MANUAL_OUTBASE)/%/docbook-htmlhelp-formatcfg.xsl \ $(VBOX_PATH_MANUAL_OUTBASE)/%/titlepage-htmlhelp.xsl \ $(VBOX_PATH_MANUAL_OUTBASE)/%/validatemanual.run \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/%/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \ $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(call MSG_L1,xsltproc $<,=> $@) $(QUIET)$(RM) -f $@ $(QUIET)$(MKDIR) -p $(@D) $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --output $(@D)/ \ --stringparam htmlhelp.chm \ $(subst /,\\,$(@D)/../VirtualBox.chm) \ $(HTMLHELPOPTS) $(@D)/../docbook-htmlhelp-formatcfg.xsl \ $< # 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) $(call MSG_L1,Packing documentation $@) $(QUIET)$(RM) -f $@ $(QUIET)$(REDIRECT) -C $(PATH_STAGE_BIN) -- zip$(HOSTSUFF_EXE) -9 $@ $(notdir $^) endif # VBOX_WITH_DOCS_CHM ########################################################################################## # # UserManual.html # ########################################################################################## # Manual formatcfg dependencies. $(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl: \ $(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl \ $(VBOX_PATH_MANUAL_SRC)/common-html-formatcfg.xsl # intermediate step to do some variable replacement in the XSL configuration $(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl: \ $(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-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 $< $(QUIET)$(MV) -f $@.tmp $@ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl: \ $(VBOX_PATH_MANUAL_SRC)/docbook-html-chunks-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 $< $(QUIET)$(MV) -f $@.tmp $@ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html: \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \ $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatemanual.run,) \ $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \ | $$(dir $$@) $(call MSG_L1,xsltproc $<) $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) \ --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.xml $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html: \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \ $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatemanual.run,) \ $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \ | $$(dir $$@) $(call MSG_L1,xsltproc $<) $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) \ --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html \ --stringparam chunk.section.depth 0 \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.xml $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip: \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html $(call MSG_L1,Packing documentation $@) $(QUIET)$(RM) -f $@ $(QUIET)$(REDIRECT) -C $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ -- zip$(HOSTSUFF_EXE) \ -9 -r $@ html-single html-chunks $(VBOX_MANUAL_PNG_FILES_en_US) html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html html-zip:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip ########################################################################################## # # ChangeLog.html # ########################################################################################## # intermediate step to do some variable replacement in the XSL configuration $(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-changelog-formatcfg.xsl: \ $(VBOX_PATH_MANUAL_SRC)/docbook-changelog-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 $< $(QUIET)$(MV) -f $@.tmp $@ # This XSLT rule depends on $(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml, which is build by the complex rule # $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/user_ChangeLog.xml): ... # much further above. That rule takes en_US/user_ChangeLog.xml and replaces $VIRTUALBOX_CHANGELOG_IMPL # with the actual change log contained in user_ChangeLogImpl.xml $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html: \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-changelog-formatcfg.xsl \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml $(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html \ $(@D)/docbook-changelog-formatcfg.xsl \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml $(call MSG_L1,Fresh ChangeLog.html is now at $@) cl-html: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html endif # if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK)) # # VBoxManage man pages (parts also required by VBoxManage build-in help). # $(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-manpage.xsl,) ## # 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_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \ $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@) $$(call MSG_GENERATE,,$$@,$$<) $$(QUIET)$$(RM) -f "$$@" $$(QUIET)$$(VBOX_XSLTPROC_WITH_CAT) --output $$@ \ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl $$< ifdef VBOX_WITH_XMLLINT $$(QUIET)$$(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_OUTBASE)/docbook-refentry-to-manpage.xsl \ $$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \ $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@) $$(call MSG_GENERATE,,$$@,$$<) $$(QUIET)$$(RM) -f "$$@" $$(QUIET)$$(VBOX_XSLTPROC_WITH_CAT) --output $$@ $$(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-manpage.xsl $$< endef $(foreach lang,$(VBOX_MANUAL_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_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \ ,$$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/$(patsubst man_%,%.1,$(basename $(file))))) # # VBoxManage built-in help. # # Note! Generating the stuff here is a bit annoying, but currently the most # practical way I can come up with. # OTHERS += \ $(VBOX_PATH_MANUAL_OUTBASE)/VBoxManageBuiltInHelp.cpp \ $(VBOX_PATH_MANUAL_OUTBASE)/VBoxManageBuiltInHelp.h OTHER_CLEAN += \ $(VBOX_PATH_MANUAL_OUTBASE)/VBoxManageBuiltInHelp.cpp \ $(VBOX_PATH_MANUAL_OUTBASE)/VBoxManageBuiltInHelp.h help-experiment: \ $(VBOX_PATH_MANUAL_OUTBASE)/VBoxManageBuiltInHelp.cpp \ $(VBOX_PATH_MANUAL_OUTBASE)/VBoxManageBuiltInHelp.h $(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-C-help.xsl,) $(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-H-help.xsl,) $(VBOX_PATH_MANUAL_OUTBASE)/VBoxManageBuiltInHelp.cpp: \ $(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-C-help.xsl \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(filter man_VBoxManage-%,$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE) | $$(dir $$@) $(call MSG_GENERATE,,$@,$<) $(QUIET)$(APPEND) -tn "$@" \ '/* Autogenerated by $<, do not edit! */' \ '' \ '#include ' \ '#include "VBoxManageBuiltInHelp.h"' \ '' $(foreach refentry,$(filter %.xml,$^) \ ,$(NLTAB)$(QUIET)$(REDIRECT) -a+to "$@" -- $(VBOX_XSLTPROC_WITH_CAT) $< $(refentry)) $(QUIET)$(APPEND) -n "$@" \ '' \ 'PCREFENTRY g_apHelpEntries[] = ' \ '{' \ $(foreach refentry,$(filter %.xml,$^) \ , ' &g_$(subst -,_,$(tolower $(patsubst man_%,%,$(notdir $(basename $(refentry)))))), ') \ '};' \ 'const uint32_t g_cHelpEntries = RT_ELEMENTS(g_apHelpEntries);' \ '' $(VBOX_PATH_MANUAL_OUTBASE)/VBoxManageBuiltInHelp.h: \ $(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-H-help.xsl \ $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(filter man_VBoxManage-%,$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE) | $$(dir $$@) $(call MSG_GENERATE,,$@,$<) $(QUIET)$(APPEND) -tn "$@" \ '/* Autogenerated by $<, do not edit! */' \ '' \ '#ifndef ___VBoxManageBuiltInHelp_h___' \ '#define ___VBoxManageBuiltInHelp_h___' \ '' \ '#include ' \ '' \ 'RT_C_DECLS_BEGIN' \ '' \ 'typedef enum HELP_CMD_VBOXMANAGE' \ '{' \ ' HELP_CMD_VBOXMANAGE_INVALID = 0,' $(foreach refentry,$(filter %.xml,$^) \ ,$(NLTAB)$(QUIET)$(REDIRECT) -a+to "$@" -- $(VBOX_XSLTPROC_WITH_CAT) \ --stringparam 'g_sMode' 'cmd' $< $(refentry)) $(QUIET)$(APPEND) -n "$@" \ ' HELP_CMD_VBOXMANAGE_END' \ '} HELP_CMD_VBOXMANAGE;' $(foreach refentry,$(filter %.xml,$^) \ ,$(NLTAB)$(QUIET)$(REDIRECT) -a+to "$@" -- $(VBOX_XSLTPROC_WITH_CAT) \ --stringparam 'g_sMode' 'subcmd' $< $(refentry)) $(QUIET)$(APPEND) -n "$@" \ '' \ 'extern PCREFENTRY g_apHelpEntries[];' \ 'extern const uint32_t g_cHelpEntries;' \ '' \ 'RT_C_DECLS_END' \ '' \ '#endif' \ '' include $(FILE_KBUILD_SUB_FOOTER)