VirtualBox

source: vbox/trunk/doc/manual/Makefile.kmk@ 87649

Last change on this file since 87649 was 87649, checked in by vboxsync, 4 years ago

doc/manual: bugref:9831. Drag in the Qt5 stuff if needed.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 41.0 KB
Line 
1# $Id: Makefile.kmk 87649 2021-02-08 23:10:27Z vboxsync $
2## @file
3# Sub-Makefile for the VirtualBox User Manual, SDK reference and other manuals.
4#
5
6#
7# Copyright (C) 2006-2020 Oracle Corporation
8#
9# This file is part of VirtualBox Open Source Edition (OSE), as
10# available from http://www.virtualbox.org. This file is free software;
11# you can redistribute it and/or modify it under the terms of the GNU
12# General Public License (GPL) as published by the Free Software
13# Foundation, in version 2 as it comes in the "COPYING" file of the
14# VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15# hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16#
17
18#
19# This slightly messy makefile transforms the DocBook XML source for the
20# user manual into presentation output. We support two targets:
21#
22# -- UserManual.pdf, generated by LaTex
23#
24# -- VirtualBox.chm
25#
26# Both files end up in PATH_STAGE_BIN.
27#
28# Both targets indirectly depend on the XML files in this directory;
29# "indirectly" because we first copy them to PATH_TARGET and hack them
30# up a bit for variable substitution and such (see below).
31# The toolchains are roughly like this:
32#
33# -- PDF file via Apache FOP: pre-process the XML files in PATH_TARGET,
34# then create a .FO file (another XML format for "formatted objects")
35# via xsltproc, then feed the .FO file to Apache FOP to create the PDF.
36#
37# -- PDF file via LaTeX: pre-process the XML files in PATH_TARGET, then
38# run our custom "dblatex" perl script on UserManual.xml, which parses
39# the XML (using the Perl SAX parsers) and dumps a matching LaTeX file
40# to UserManual.tex. This is then regularly processed by pdflatex to
41# generate PDF.
42#
43# -- CHM file: again, pre-process the XML files in PATH_TARGET, then use
44# xsltproc to create a .HHP file for the Microsoft Help Compiler, then
45# feed that file to it.
46#
47
48SUB_DEPTH = ../..
49include $(KBUILD_PATH)/subheader.kmk
50
51ifndef VBOX_DOC_MANUAL_CONFIG_KMK_INCLUDED
52 include $(PATH_SUB_CURRENT)/Config.kmk
53endif
54
55
56#
57# Globals
58#
59
60# Error out if someone tries to override old globals.
61ifdef HTMLHELPOPTS
62 $(error HTMLHELPOPTS was renamed to VBOX_HTMLHELP_OPTS!)
63endif
64ifdef DOCBOOKPATH
65 $(error DOCBOOKPATH was renamed to VBOX_PATH_DOCBOOK!)
66endif
67ifdef DOCBOOKPATH
68 $(error DOCBOOKPATH was renamed to VBOX_PATH_DOCBOOK!)
69endif
70ifdef XML_CATALOG
71 $(error XML_CATALOG was renamed to VBOX_XML_CATALOG!)
72endif
73ifdef XML_CATALOG_DOCBOOK
74 $(error XML_CATALOG_DOCBOOK was renamed to VBOX_XML_CATALOG_DOCBOOK!)
75endif
76ifdef VBOXMANAGEPATH
77 $(error VBOXMANAGEPATH was renamed to VBOXMANAGEHELP_PATH!)
78endif
79ifdef PDFLATEX_INTERACTION
80 $(error PDFLATEX_INTERACTION was renamed to VBOX_PDFLATEX_INTERACTION!)
81endif
82ifdef PDFLATEX
83 $(error PDFLATEX was renamed to VBOX_PDFLATEX_CMD!)
84endif
85ifdef HHC
86 $(error HHC was renamed to VBOX_HHC!)
87endif
88
89VBOX_QHCP_FILES = \
90 UserManual.qhcp
91
92VBOX_QHELP_OUTPUT_FILES = \
93 UserManual.qch \
94 UserManual.qhc
95
96VBOXMANAGEHELP_PATH ?= $(PATH_STAGE_BIN)/VBoxManageHelp$(SUFF_EXE)
97
98 # VBOX_PDFLATEX_INTERACTION = errorstopmode - Use this when you wants to figure out build failures
99 # without catting the log a million times.
100VBOX_PDFLATEX_INTERACTION ?= batchmode
101ifeq ($(KBUILD_HOST),win)
102 ifndef VBOX_PDFLATEX
103 VBOX_PDFLATEX := $(firstword $(rsort $(wildcard $(KBUILD_DEVTOOLS)/win.x86/miktex-portable/*/miktex/bin/pdflatex.exe)))
104 ifneq ($(VBOX_PDFLATEX),)
105 VBOX_PDFLATEX_CMD = $(VBOX_PDFLATEX) -halt-on-error -interaction $(VBOX_PDFLATEX_INTERACTION)
106 endif
107 endif
108 ifndef VBOX_PDFLATEX
109 # Tell MiKTeX to automatically download packages if system wide install.
110 VBOX_PDFLATEX := pdflatex
111 VBOX_PDFLATEX_CMD = $(VBOX_PDFLATEX) -halt-on-error -interaction $(VBOX_PDFLATEX_INTERACTION) --enable-installer
112 endif
113else
114 VBOX_PDFLATEX ?= pdflatex
115 VBOX_PDFLATEX_HALT = $(shell ( $(VBOX_PDFLATEX) -version | head -1 | grep 141592 > /dev/null ) && echo -halt-on-error )
116 VBOX_PDFLATEX_CMD = pdflatex $(VBOX_PDFLATEX_HALT) -interaction $(VBOX_PDFLATEX_INTERACTION)
117endif
118
119# Windows HTML Help Workshop compiler (stupid thing always returns an error!)
120VBOX_HHC = -$(EXEC_X86_WIN32) $(VBOX_PATH_HTML_HELP_WORKSHOP)/hhc.exe
121
122
123# Additional xsltproc options when generating
124VBOX_HTMLHELP_OPTS ?=
125
126# SDK related globals.
127VBOX_MANUAL_APIREF_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef_apiref.xml
128VBOX_DOC_XIDL_SRC = $(PATH_ROOT)/src/VBox/Main/idl/VirtualBox.xidl
129VBOX_DOC_XIDL_SRC_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.xidl.tmp
130
131
132#
133# Targets
134#
135
136BLDDIRS += $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/, $(VBOX_MANUAL_LANGUAGES))
137
138if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK))
139 if defined(VBOX_ONLY_SDK) || defined(VBOX_WITH_DOCS_SDKREF)
140 INSTALLS += VBox-docs-sdkref
141 endif
142
143 ifdef VBOX_WITH_DOCS_HTML
144 INSTALLS += VBox-docs-usermanual-html
145 VBOX_PATH_BIN_HTML = $(PATH_STAGE_BIN)/UserManual-html.zip
146 else # Do not build html.
147 VBOX_PATH_BIN_HTML =
148 endif
149
150 ifdef VBOX_WITH_DOCS_CHM
151 INSTALLS += VBox-docs-usermanual-chm
152 VBOX_PATH_BIN_CHM = $(PATH_STAGE_BIN)/VirtualBox.chm
153 else # Do not build chm.
154 VBOX_PATH_BIN_CHM =
155 endif
156
157 ifdef VBOX_WITH_DOCS_QHELP
158 USES += qt5
159 INSTALLS += VBox-docs-usermanual-qhc
160 INSTALLS += VBox-docs-usermanual-qch
161 VBOX_PATH_BIN_QHELP = $(PATH_STAGE_BIN)/UserManual.qch
162 VBOX_PATH_BIN_QHELP += $(PATH_STAGE_BIN)/UserManual.qhc
163 else # Do not install qhelp.
164 VBOX_PATH_BIN_QHELP =
165 endif
166
167
168 ifndef VBOX_ONLY_SDK
169 VBOX_MANUAL_PACK += \
170 $(PATH_STAGE_BIN)/UserManual.pdf \
171 $(VBOX_PATH_BIN_HTML) \
172 $(VBOX_PATH_BIN_CHM) \
173 $(VBOX_PATH_BIN_QHELP)
174 INSTALLS += VBox-docs-usermanual
175
176 ifdef VBOX_WITH_DOCS_TRANSLATIONS
177 INSTALLS += VBox-docs-usermanual-l10n
178 VBOX_MANUAL_PACK += \
179 $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf)
180 ifdef VBOX_WITH_DOCS_CHM
181 INSTALLS += VBox-docs-usermanual-l10n-chm
182 VBOX_MANUAL_PACK += \
183 $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm)
184 endif
185 endif
186 endif # !VBOX_ONLY_SDK
187
188 ifdef VBOX_WITH_DOCS_ACCESSIBILITY
189 INSTALLS += VBox-docs-accessibility
190 INSTALLS += VBox-docs-accessibility-html
191 endif
192
193 ifdef VBOX_ONLY_DOCS
194 PACKING += $(PATH_STAGE_BIN)/VBoxDocumentation.zip
195 endif
196
197 ifdef VBOX_WITH_DOCS_TRANSLATIONS
198 VBOX_MANUAL_LANGUAGES += $(VBOX_MANUAL_ADD_LANGUAGES)
199 endif
200
201$(foreach lang,$(VBOX_MANUAL_LANGUAGES), \
202 $(eval VBOX_MANUAL_XML_FILES_GENERATED_$$(lang) := \
203 $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
204 $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/overview_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
205 $$(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml \
206 $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_man_VBoxHeadless.xml \
207 $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_man_vboximg-mount.xml \
208 $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_isomakercmd-man.xml))
209
210 VBOX_SDKREF_XML_FILES = \
211 SDKRef.xml
212
213 VBOX_ACCESSIBILITY_XML_FILES = \
214 Accessibility.xml
215
216
217 # Wildcard the images path for every supported language
218 $(foreach f,$(VBOX_MANUAL_LANGUAGES), \
219 $(eval VBOX_MANUAL_PNG_FILES_$$(f) := $$(patsubst $$(VBOX_PATH_MANUAL_SRC)/$$(f)/%,%,$$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$$(f)/images/*.png))))
220
221 VBOX_MANUAL_TEX_UNICODE_FILES = \
222 $(wildcard $(VBOX_PATH_MANUAL_SRC)/texfiles/unicode/*)
223
224 VBOX_MANUAL_LATEX_FILES_TARGET = \
225 $(addprefix UserManual.,aux log out toc tex)
226
227 VBOX_SDKREF_LATEX_FILES_TARGET = \
228 $(addprefix SDKRef.,aux log out toc tex)
229
230 VBOX_ACCESSIBILITY_LATEX_FILES_TARGET = \
231 $(addprefix Accessibility.,aux log out toc tex)
232
233 BLDDIRS += \
234 $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/,\
235 $(addsuffix /images, $(VBOX_MANUAL_LANGUAGES)) \
236 $(addsuffix /html-single, $(VBOX_MANUAL_LANGUAGES)) \
237 $(addsuffix /html-chunks, $(VBOX_MANUAL_LANGUAGES)) \
238 $(addsuffix /qhelp, $(VBOX_MANUAL_LANGUAGES)) \
239 $(addsuffix /qhelp/images, $(VBOX_MANUAL_LANGUAGES)) \
240 $(addsuffix /HTMLHelp, $(VBOX_MANUAL_LANGUAGES)) \
241 $(addsuffix /HTMLHelp/images, $(VBOX_MANUAL_LANGUAGES)) \
242 )
243
244 # Explicit cleaning has some overlap with default cleaning rules, since this
245 # Makefile is using very complex conditionals for selectively creating
246 # specific files, and not everyone remembers to use the same with "kmk clean".
247 OTHER_CLEAN += \
248 $(VBOX_XML_CATALOG) \
249 $(VBOX_XML_CATALOG_DOCBOOK) \
250 $(VBOX_XML_CATALOG_MANUAL) \
251 $(VBOX_XML_ENTITIES) \
252 $(VBOX_XML_XREF_TO_TEXT) \
253 $(VBOX_XML_XREF_TO_TEXT).cat \
254 $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/, \
255 $(addprefix user_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \
256 $(VBOX_MANUAL_XML_REFENTRY_FILES) \
257 $(patsubst man_%,%.1,$(basename $(VBOX_MANUAL_XML_REFENTRY_FILES))) \
258 man_VBoxHeadless.xml \
259 user_man_VBoxHeadless.xml \
260 man_vboximg-mount.xml \
261 user_man_vboximg-mount.xml \
262 isomakercmd-man.xml \
263 user_isomakercmd-man.xml \
264 $(VBOX_MANUAL_LATEX_FILES_TARGET) \
265 $(VBOX_MANUAL_PNG_FILES_$(lang)) \
266 $(notdir $(VBOX_MANUAL_TEX_UNICODE_FILES)) \
267 $(addprefix HTMLHelp/,$(VBOX_MANUAL_PNG_FILES_$(lang))) \
268 html-single/UserManual.html \
269 html-single/UserManual.qhp \
270 html-single/UserManual.qhcp \
271 html-single/UserManual.qhc \
272 html-single/UserManual.qch \
273 $(addprefix HTMLHelp/, index.html go01.html) \
274 $(addprefix html-chunks/, index.html go01.html) \
275 $(foreach n,01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 \
276 ,html-chunks/ch$(n).html \
277 html-chunks/re$(n).html \
278 HTMLHelp/ch$(n).html \
279 HTMLHelp/re$(n).html \
280 $(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)) ) \
281 $(foreach n,a b c \
282 ,html-chunks/ap$(n).html \
283 HTMLHelp/ap$(n).html \
284 $(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) ) \
285 $(foreach n,01 02 03 04 05 \
286 ,html-chunks/pr$(n).html \
287 HTMLHelp/pr$(n).html \
288 $(foreach s,01 02 03 04 05 06 07 08,HTMLHelp/pr$(n)s$(s).html) ) \
289 HTMLHelp/toc.hhc \
290 HTMLHelp/htmlhelp.hhp \
291 UserManual.pdf \
292 VirtualBox.chm \
293 ChangeLog.html \
294 validatemanual.run \
295 validateaccessibility.run \
296 validatesdkref.run \
297 )) \
298 $(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl \
299 $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/overview_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \
300 $(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml \
301 $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf) \
302 $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm) \
303 $(PATH_STAGE_BIN)/UserManual.pdf \
304 $(PATH_STAGE_BIN)/VirtualBox.chm \
305 \
306 $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \
307 $(VBOX_SDKREF_LATEX_FILES_TARGET) \
308 SDKRef.pdf \
309 ) \
310 $(PATH_STAGE_BIN)/sdk/docs/SDKRef.pdf \
311 \
312 $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \
313 $(VBOX_ACCESSIBILITY_LATEX_FILES_TARGET) \
314 html-single/Accessibility.html \
315 Accessibility.pdf \
316 ) \
317 $(PATH_STAGE_BIN)/Accessibility.html \
318 $(PATH_STAGE_BIN)/Accessibility.pdf \
319 \
320 $(VBOX_DOC_XIDL_SRC_TMP) \
321 $(VBOX_MANUAL_APIREF_TMP)
322
323endif # if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK))
324
325#
326# target for installing UserManual.pdf
327#
328VBox-docs-usermanual_INST = $(INST_BIN)
329VBox-docs-usermanual_MODE = a+r,u+w
330VBox-docs-usermanual_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.pdf
331
332VBox-docs-usermanual-qhc_INST = $(INST_BIN)
333VBox-docs-usermanual-qhc_MODE = a+r,u+w
334VBox-docs-usermanual-qhc_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qhc
335
336VBox-docs-usermanual-qch_INST = $(INST_BIN)
337VBox-docs-usermanual-qch_MODE = a+r,u+w
338VBox-docs-usermanual-qch_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qch
339
340#
341# target for installing translated UserManual_*.pdf
342#
343VBox-docs-usermanual-l10n_INST = $(INST_BIN)
344VBox-docs-usermanual-l10n_MODE = a+r,u+w
345VBox-docs-usermanual-l10n_SOURCES = $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$(f)/UserManual.pdf=>UserManual_$(f).pdf)
346
347#
348# target for installing the chunked HTML docs
349#
350VBox-docs-usermanual-html_INST = $(INST_BIN)
351VBox-docs-usermanual-html_MODE = a+r,u+w
352VBox-docs-usermanual-html_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip=>UserManual-html.zip
353
354#
355# target for installing VirtualBox.chm
356#
357VBox-docs-usermanual-chm_INST = $(INST_BIN)
358VBox-docs-usermanual-chm_MODE = a+r,u+w
359VBox-docs-usermanual-chm_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.chm
360
361#
362# target for installing translated VirtualBox_*.chm
363#
364VBox-docs-usermanual-l10n-chm_INST = $(INST_BIN)
365VBox-docs-usermanual-l10n-chm_MODE = a+r,u+w
366VBox-docs-usermanual-l10n-chm_SOURCES = $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$(f)/VirtualBox.chm=>VirtualBox_$(f).chm)
367
368#
369# target for installing SDKRef.pdf
370#
371VBox-docs-sdkref_INST = $(INST_SDK)docs/
372VBox-docs-sdkref_MODE = a+r,u+w
373VBox-docs-sdkref_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.pdf
374
375#
376# target for installing Accessibility.pdf
377#
378VBox-docs-accessibility_INST = $(INST_BIN)
379VBox-docs-accessibility_MODE = a+r,u+w
380VBox-docs-accessibility_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.pdf
381
382#
383# target for installing Accessibility.html
384#
385VBox-docs-accessibility-html_INST = $(INST_BIN)
386VBox-docs-accessibility-html_MODE = a+r,u+w
387VBox-docs-accessibility-html_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html
388
389if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK))
390
391##
392# Morph man pages into manual sections.
393# $(evalcall2 def_vbox_refentry_to_user_sect1)
394# @param 1 Language.
395# @param 2 the refentry xml base file name.
396# @param 3 the full refentry xml file path.
397define def_vbox_refentry_to_user_sect1
398$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/user_$(2): $(3) \
399 $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl \
400 $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
401 $$(VBOX_XML_ENTITIES) $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@)
402 $$(call MSG_TOOL,xsltproc $$(notdir $$(filter %.xsl,$$^)),,$$(filter %.xml,$$^),$$@)
403 $$(QUIET)$$(RM) -f "$$@"
404 $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl $$<
405endef
406$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \
407man_VBoxHeadless.xml \
408man_vboximg-mount.xml \
409, $(evalcall2 def_vbox_refentry_to_user_sect1,$(lang),$(file),$(VBOX_PATH_MANUAL_SRC)/$(lang)/$(file))))
410$(foreach lang,$(VBOX_MANUAL_LANGUAGES) \
411,$(evalcall2 def_vbox_refentry_to_user_sect1,$(lang),isomakercmd-man.xml,$(PATH_ROOT)/src/VBox/Runtime/common/fs/isomakercmd-man.xml))
412
413
414# Generates the VBoxManage command overview include file (shared between
415# languages) from the refsynopsisdiv section of the man pages.
416$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/overview_,$(VBOX_MANUAL_XML_REFENTRY_FILES)): \
417 $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-overview.xsl \
418 $$(patsubst overview_%,$$(VBOX_PATH_MANUAL_SRC)/en_US/%,$$(notdir $$@)) \
419 $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
420 $(VBOX_XML_ENTITIES) | $$(dir $$@)
421 $(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@)
422 $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --output "$@" $< $(filter %.xml,$^)
423
424$(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml: $(VBOXMANAGEHELP_PATH) $(MAKEFILE_CURRENT) | $$(dir $$@)
425 $(call MSG_GENERATE,,$@,)
426 $(QUIET)$(RM) -f $@ [email protected]
427 $(QUIET)$(APPEND) -tn "$@" \
428 '<?xml version="1.0" encoding="UTF-8"?>' \
429 '<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">' \
430 '<sect1> <!-- this will be skipped via xpointer in the include. --> '
431 $(QUIET)$(REDIRECT) -wo [email protected] -E 'VBOX_LOG_FLAGS=disabled' -E 'VBOX_LOG_DEST=nofile' \
432 $(if $(eq $(KBUILD_TARGET),darwin), -E 'DYLD_FALLBACK_LIBRARY_PATH=$(dir $(LIB_RUNTIME))') \
433 -- \
434 $(VBOXMANAGEHELP_PATH) --dumpopts
435 $(QUIET)$(SED) \
436 -e ':a' \
437 -e 'N' \
438 -e '$(DOLLAR)!ba' \
439 -e 's/</\&lt\;/g' \
440 -e 's/>/\&gt\;/g' \
441 -e 's/\n*$(DOLLAR)/<\/screen>/' \
442 -e 's/^/<screen>/' \
443 --append $@ [email protected]
444 $(QUIET)$(RM) -f [email protected]
445 $(QUIET)$(APPEND) -n "$@" \
446 ' <remark role="VBoxManage-overview">' \
447 $(foreach refentry, $(filter man_VBoxManage%,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \
448 , ' <xi:include href="overview_$(refentry)" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />') \
449 ' </remark>' \
450 '</sect1>'
451
452
453
454
455##########################################################################################
456#
457# Shared rules for PDF generation
458#
459##########################################################################################
460
461ifndef VBOX_OSE
462# copy ucs.sty and related files
463$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/ucs.sty):
464 $(call MSG_L1,Copying unicode support for LaTeX)
465 $(QUIET)$(INSTALL_STAGING) -m0644 -- $(VBOX_MANUAL_TEX_UNICODE_FILES) "$(@D)"
466endif
467
468# copy the PNG files.
469# Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
470define def_vbox_cp_images_pdf
471local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)
472$(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \
473 $$(out_dir)/%: $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@)
474 $$(call MSG_L1,Copying temporary $$< => $$@)
475 $$(QUIET)$$(INSTALL_STAGING) -m0644 -- '$$<' '$$(@D)'
476endef
477$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_cp_images_pdf))
478
479
480##########################################################################################
481#
482# UserManual.pdf
483#
484##########################################################################################
485
486
487# Generate PDF from LaTeX
488# Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
489define def_vbox_usermanual_tex_to_pdf
490local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)
491$$(out_dir)/UserManual.pdf: \
492 $$(out_dir)/UserManual.tex \
493 $$(if $$(VBOX_OSE),,$$(out_dir)/ucs.sty) \
494 $$(addprefix $$(out_dir)/,$$(VBOX_MANUAL_PNG_FILES_$(lang))) | $$$$(dir $$$$@)
495# PDF generation via Latex: generate the .tex file
496 $$(call MSG_L1,pdflatex $$< (four passes) -> $$@)
497 $$(QUIET)$$(REDIRECT) -w+ti /dev/null -C $$(@D) -- $$(VBOX_PDFLATEX_CMD) UserManual.tex
498 $$(QUIET)$$(REDIRECT) -w+ti /dev/null -C $$(@D) -- $$(VBOX_PDFLATEX_CMD) UserManual.tex
499 $$(QUIET)$$(REDIRECT) -w+ti /dev/null -C $$(@D) -- $$(VBOX_PDFLATEX_CMD) UserManual.tex
500 $$(QUIET)$$(REDIRECT) -w+ti /dev/null -C $$(@D) -- $$(VBOX_PDFLATEX_CMD) UserManual.tex
501 $$(QUIET)$$(SED) -ne '/Warning: Hyper reference/p' $$(basename $$<).log
502 $$(QUIET)$$(SED) -n \
503 -e '/Warning: There were \(undefined references\|multiply-defined labels\)/{p; q 1}' \
504 $$(basename $$@).log
505 $$(call MSG_L1,Fresh LaTeX-generated PDF is now at $$@)
506endef
507$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_tex_to_pdf))
508
509# Generate LaTeX from XML
510# Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
511define def_vbox_usermanual_xml_to_tex
512local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)
513$$(out_dir)/UserManual.tex: \
514 $$(addprefix $$(VBOX_PATH_MANUAL_SRC)/$(lang)/,$$(VBOX_MANUAL_XML_FILES)) \
515 $$(VBOX_MANUAL_XML_FILES_COMMON) \
516 $$(VBOX_MANUAL_XML_FILES_GENERATED_$(lang)) \
517 $$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \
518 $$(if $$(VBOX_HAVE_XMLLINT),$$(out_dir)/validatemanual.run,) \
519 $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
520 $$(VBOX_XML_ENTITIES) $$(MAKEFILE_CURRENT) | $$$$(dir $$$$@)
521 $$(call MSG_TOOL,xsltproc $$(notdir $$(filter %.xsl,$$^)),,$$(firstword $$(filter %.xml,$$^)),$$@)
522 $$(QUIET)$$(RM) -f $$(addprefix $$(@D)/,$$(VBOX_MANUAL_LATEX_FILES_TARGET))
523# generate TeX source from processed docbook and store it in UserManual.tex.tmp;
524# pass current language to xsltproc in TARGETLANG variable
525 $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG $(lang) \
526 -o [email protected] $$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $$<
527# for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word;
528# the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections
529 $$(QUIET)$$(SED) \
530 -e 's|^\\QUOTE{}|\\OQ{}|g' \
531 -e 's|\(\W\)\\QUOTE{}|\1\\OQ{}|g' \
532 -e 's|\(\w\)\\QUOTE{}|\1\\CQ{}|g' \
533 --output $$@ [email protected]
534 $$(QUIET)$$(RM) -f [email protected]
535endef
536$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_xml_to_tex))
537
538# Useful aliases
539usermanual UserManual.pdf:: $(PATH_STAGE_BIN)/UserManual.pdf
540
541debug-usermanual:
542 $(MAKE) --pretty-command-printing -j1 VBOX_PDFLATEX_INTERACTION=errorstopmode $(PATH_STAGE_BIN)/UserManual.pdf
543
544#
545# Generate rules for validating the UserManual.xml. These are invoked
546# automatically at build time, but can also be manually invoked via the
547# 'validatemanual' and 'validatemanual_<lang>' aliases.
548#
549define def_vbox_validate_xml
550validatemanual_$(lang):: $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/validatemanual.run
551$$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/validatemanual.run: \
552 $$(addprefix $$(VBOX_PATH_MANUAL_SRC)/$(lang)/,$$(VBOX_MANUAL_XML_FILES)) \
553 $$(VBOX_MANUAL_XML_FILES_COMMON) \
554 $$(VBOX_MANUAL_XML_FILES_GENERATED_$(lang)) \
555 $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
556 $$(VBOX_XML_ENTITIES) $$(MAKEFILE_CURRENT) | $$$$(dir $$$$@)
557 $$(call MSG_L1,Validating $$<)
558 $$(QUIET)$$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$<
559 $$(QUIET)$$(APPEND) -t "$$@" "done"
560endef
561$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_validate_xml))
562
563
564# Handy aliases.
565validatemanual:: $(foreach lang,$(VBOX_MANUAL_LANGUAGES),validatemanual_$(lang))
566
567
568
569#
570# SDKRef.pdf
571#
572
573# Replace <tt> tags in VirtualBox.xidl.
574$(VBOX_DOC_XIDL_SRC_TMP): $(VBOX_DOC_XIDL_SRC) $(MAKEFILE_CURRENT) | $$(dir $$@)
575 $(call MSG_L1,Generating $@)
576 $(QUIET)$(SED) -e 's|@a \+\(\w\+\)|<tt>\1</tt>|g' \
577 -e 's|@c \+\(\w\+\)|<tt>\1</tt>|g' \
578 --output $@ $<
579
580# Generate SDKRef_apiref.xml as a docbook file excerpt that will be referenced from the SDKRef.xml.
581$(VBOX_MANUAL_APIREF_TMP): $(VBOX_PATH_MANUAL_SRC)/xidl2docbook.xsl $(VBOX_DOC_XIDL_SRC_TMP)
582 $(call MSG_L1,Generating $@)
583 $(QUIET)$(VBOX_XSLTPROC) $(VBOX_XSLTPROC_OPTS) --xinclude --nonet -o $@ $< $(VBOX_DOC_XIDL_SRC_TMP)
584
585# Turn SDKRef.xml into LaTeX.
586$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex: \
587 $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_SDKREF_XML_FILES)) \
588 $(VBOX_MANUAL_APIREF_TMP) \
589 $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \
590 $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run,) \
591 $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
592 $(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) | $$(dir $$@)
593 $(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@)
594 $(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_SDKREF_LATEX_FILES_TARGET))
595# generate TeX source from processed docbook and store it in SDKRef.tex.tmp
596 $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG en_US \
597 -o [email protected] $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $<
598# for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word;
599# the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections
600 $(QUIET)$(SED) \
601 -e 's|^\\QUOTE{}|\\OQ{}|g' \
602 -e 's|\(\W\)\\QUOTE{}|\1\\OQ{}|g' \
603 -e 's|\(\w\)\\QUOTE{}|\1\\CQ{}|g' \
604 --output $@ [email protected]
605 $(QUIET)$(RM) -f [email protected]
606
607# Turn SDKRef.tex into a PDF.
608$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.pdf: \
609 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex \
610 $(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ucs.sty) \
611 $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) | $$(dir $$@)
612 $(call MSG_L1,pdflatex $< (three passes))
613 $(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) SDKRef.tex
614 $(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) SDKRef.tex
615 $(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) SDKRef.tex
616 $(QUIET)$(SED) -ne '/Warning: Hyper reference/p' $(basename $<).log
617 $(QUIET)$(SED) -n \
618 -e '/Warning: There were \(undefined references\|multiply-defined labels\)/{p; q 1}' \
619 $(basename $<).log
620 $(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)
621
622# Validating SDKRef.xml. It is invoked automatically at build time,
623# but can also be manually invoked via the 'validate-sdkref' alias.
624$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run: \
625 $(VBOX_PATH_MANUAL_SRC)/en_US/SDKRef.xml \
626 $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_SDKREF_XML_FILES)) \
627 $(VBOX_MANUAL_APIREF_TMP) \
628 $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
629 $(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) | $$(dir $$@)
630 $(call MSG_L1,Validating $<)
631 $(QUIET)$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $<
632 $(QUIET)$(APPEND) -t "$@" "done"
633
634
635# Handy aliases.
636validate-sdkref:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run
637sdkref:: $(PATH_STAGE_BIN)/sdk/docs/SDKRef.pdf
638
639
640
641#
642# Accessibility.pdf
643#
644
645# Turn Accessibility.xml into LaTeX.
646$(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.tex: \
647 $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \
648 $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \
649 $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run,) \
650 $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
651 $(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) | $$(dir $$@)
652 $(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@)
653 $(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_ACCESSIBILITY_LATEX_FILES_TARGET))
654# generate TeX source from processed docbook and store it in Accessibility.tex.tmp
655 $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG en_US \
656 -o [email protected] $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $<
657# for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word;
658# the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections
659 $(QUIET)$(SED) \
660 -e 's|^\\QUOTE{}|\\OQ{}|g' \
661 -e 's|\(\W\)\\QUOTE{}|\1\\OQ{}|g' \
662 -e 's|\(\w\)\\QUOTE{}|\1\\CQ{}|g' \
663 --output $@ [email protected]
664 $(QUIET)$(RM) -f [email protected]
665
666# Turn Accessibility.tex into a PDF.
667$(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.pdf: \
668 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.tex \
669 $(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ucs.sty) \
670 $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) | $$(dir $$@)
671 $(call MSG_L1,pdflatex $< (three passes))
672 $(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) Accessibility.tex
673 $(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) Accessibility.tex
674 $(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) Accessibility.tex
675 $(QUIET)$(SED) -ne '/Warning: Hyper reference/p' $(basename $<).log
676 $(QUIET)$(SED) -n \
677 -e '/Warning: There were \(undefined references\|multiply-defined labels\)/{p; q 1}' \
678 $(basename $<).log
679 $(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)
680
681$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html: \
682 $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \
683 $(VBOX_DOCBOOK_HTML_ONE_PAGE_FORMATCFG) \
684 $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
685 $(VBOX_XML_ENTITIES) | $$(dir $$@)
686 $(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@)
687 $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) \
688 --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html \
689 $(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-formatcfg.xsl \
690 $<
691
692# Validating Accessibility.xml. It is invoked automatically at build time,
693# but can also be manually invoked via the 'validate-accessibility' alias.
694$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run: \
695 $(VBOX_PATH_MANUAL_SRC)/en_US/Accessibility.xml \
696 $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \
697 $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
698 $(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) | $$(dir $$@)
699 $(call MSG_L1,Validating $<)
700 $(QUIET)$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $<
701 $(QUIET)$(APPEND) -t "$@" "done"
702
703
704# Handy aliases.
705validate-accessibility:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run
706accessibility:: $(PATH_STAGE_BIN)/Accessibility.pdf
707accessibility-html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html
708
709
710
711ifdef VBOX_WITH_DOCS_CHM
712 #
713 # VirtualBox.chm
714 #
715 # We first generate a .hhp help source file from the preprocessed
716 # DocBook XML files, as defined above, then feed that into the
717 # Microsoft Help Compiler.
718 #
719 VBOX_DOCBOOK_HTMLHELP_FORMATCFG = \
720 $(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl \
721 $(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl \
722 $(VBOX_PATH_MANUAL_SRC)/common-html-formatcfg.xsl
723
724 # Prepare the XSL file for our title page, htmlhelp variant.
725 $(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl: \
726 $(VBOX_PATH_MANUAL_SRC)/titlepage-htmlhelp.xml $(MAKEFILE_CURRENT) | $$(dir $$@)
727 $(call MSG_L1,xsltproc $<)
728 $(QUIET)$(RM) -f [email protected] $@
729 $(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet -o [email protected] $(VBOX_PATH_DOCBOOK)/template/titlepage.xsl $<
730 $(QUIET)$(MV) -f [email protected] $@
731
732 # Generate CHM from HHP
733 # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
734 define def_vbox_usermanual_hhp_to_chm
735 local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)
736 $$(out_dir)/VirtualBox.chm: \
737 $$(out_dir)/HTMLHelp/htmlhelp.hhp \
738 $$(addprefix $$(out_dir)/HTMLHelp/,$$(VBOX_MANUAL_PNG_FILES_$(lang))) \
739 | $$$$(dir $$$$@)
740 $$(call MSG_L1,hhc $$<,=> $$@)
741 $$(QUIET)$$(RM) -f $$@
742 $$(QUIET)$$(VBOX_HHC) $$(subst /,\\,$$<)
743 $$(call MSG_L1,Fresh CHM is now at $$@)
744 endef
745 $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_hhp_to_chm))
746
747 # Generate HHP from XML
748 # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
749 define def_vbox_usermanual_xml_to_hhp
750 local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)
751 $$(out_dir)/HTMLHelp/htmlhelp.hhp: \
752 $$(addprefix $$(VBOX_PATH_MANUAL_SRC)/$(lang)/,$$(VBOX_MANUAL_XML_FILES)) \
753 $$(VBOX_MANUAL_XML_FILES_COMMON) \
754 $$(VBOX_MANUAL_XML_FILES_GENERATED_$(lang)) \
755 $$(VBOX_DOCBOOK_HTMLHELP_FORMATCFG) \
756 $$(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl \
757 $$(if $$(VBOX_HAVE_XMLLINT),$$(out_dir)/validatemanual.run,) \
758 $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
759 $$(VBOX_XML_ENTITIES) | $$$$(dir $$$$@)
760 $$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@)
761 $$(QUIET)$$(RM) -f $$@
762 $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$(@D)/ \
763 --stringparam htmlhelp.chm \
764 $$(subst /,\\,$$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/VirtualBox.chm) \
765 $$(HTMLHELPOPTS) $$(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl \
766 $$<
767 endef
768 $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_xml_to_hhp))
769
770 # copy the PNG files.
771 # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
772 define def_vbox_cp_images_htmlhelp
773 local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/HTMLHelp
774 $(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \
775 $$(out_dir)/%: $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@)
776 $$(call MSG_L1,Copying temporary $$< => $$@)
777 $$(QUIET)$$(INSTALL_STAGING) -m0644 -- '$$<' '$$(@D)'
778 endef
779 $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(eval $(def_vbox_cp_images_htmlhelp)))
780
781endif # VBOX_WITH_DOCS_CHM
782
783
784# Packing the docs into a zip file
785$(PATH_STAGE_BIN)/VBoxDocumentation.zip: $(VBOX_MANUAL_PACK)
786 $(call MSG_L1,Packing documentation $@)
787 $(QUIET)$(RM) -f $@
788 $(QUIET)$(REDIRECT) -C $(PATH_STAGE_BIN) -- $(VBOX_ZIP) -9 $@ $(notdir $^)
789
790
791##########################################################################################
792#
793# UserManual.html
794#
795##########################################################################################
796VBOX_DOCBOOK_HTML_ONE_PAGE_FORMATCFG = \
797 $(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-formatcfg.xsl \
798 $(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl \
799 $(VBOX_PATH_MANUAL_SRC)/common-html-formatcfg.xsl
800
801$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html: \
802 $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_XML_FILES)) \
803 $(VBOX_MANUAL_XML_FILES_COMMON) \
804 $(VBOX_MANUAL_XML_FILES_GENERATED_en_US) \
805 $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \
806 $(VBOX_DOCBOOK_HTML_ONE_PAGE_FORMATCFG) \
807 $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatemanual.run,) \
808 $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
809 $(VBOX_XML_ENTITIES) | $$(dir $$@)
810 $(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@)
811 $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) \
812 --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html \
813 $(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-formatcfg.xsl \
814 $<
815
816VBOX_DOCBOOK_HTML_CHUNKS_FORMATCFG = \
817 $(VBOX_PATH_MANUAL_SRC)/docbook-html-chunks-formatcfg.xsl \
818 $(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl \
819 $(VBOX_PATH_MANUAL_SRC)/common-html-formatcfg.xsl
820
821$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html: \
822 $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_XML_FILES)) \
823 $(VBOX_MANUAL_XML_FILES_COMMON) \
824 $(VBOX_MANUAL_XML_FILES_GENERATED_en_US) \
825 $(VBOX_DOCBOOK_HTML_CHUNKS_FORMATCFG) \
826 $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \
827 $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatemanual.run,) \
828 $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
829 $(VBOX_XML_ENTITIES) | $$(dir $$@)
830 $(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@)
831 $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) \
832 --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html \
833 --stringparam chunk.section.depth 0 \
834 $(VBOX_PATH_MANUAL_SRC)/docbook-html-chunks-formatcfg.xsl \
835 $<
836
837$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip: \
838 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html \
839 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html \
840 $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US))
841 $(call MSG_L1,Packing documentation $@)
842 $(QUIET)$(RM) -f $@
843 $(QUIET)$(REDIRECT) -C $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ -- $(VBOX_ZIP) \
844 -9 -r $@ html-single html-chunks $(VBOX_MANUAL_PNG_FILES_en_US)
845
846html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html
847html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html
848qhelp:: $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/, $(VBOX_QHELP_OUTPUT_FILES))
849html-zip:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip
850
851#
852# ChangeLog.html
853#
854# This XSLT rule formats en_US/user_ChangeLog.xml (which includes the actual change log
855# contained in user_ChangeLogImpl.xml) as a standalone HTML file.
856#
857$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html: \
858 $(VBOX_PATH_MANUAL_SRC)/en_US/docbook-changelog-formatcfg.xsl \
859 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml \
860 $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
861 $(VBOX_XML_ENTITIES) | $$(dir $$@)
862 $(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@)
863 $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --output "$@" "$<" $(filter %.xml,$^)
864 $(call MSG_L1,Fresh ChangeLog.html is now at $@)
865
866cl-html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html
867
868
869
870endif # if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK))
871
872
873#
874# VBoxManage man pages (parts also required by VBoxManage built-in help).
875#
876
877##
878# Emits rules for preprocessing refentry sources (applying remarks element),
879# and for producing the actual man pages.
880# $(evalcall2 def_vbox_refentry_to_manpage)
881# @param 1 The language
882# @param 2 The file name (no path).
883define def_vbox_refentry_to_manpage
884$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(2): \
885 $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2) \
886 $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl \
887 $$(VBOX_XML_XREF_TO_TEXT) \
888 $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
889 $$(VBOX_XML_ENTITIES) $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@)
890 $$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@)
891 $$(QUIET)$$(RM) -f "$$@"
892 $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ \
893 $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl $$<
894 $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output [email protected] $$(VBOX_XML_XREF_TO_TEXT) $$@
895 $$(QUIET)$$(MV) -f -- "[email protected]" "$$@"
896if defined(VBOX_HAVE_XMLLINT)
897 $$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$@
898endif
899
900$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(patsubst man_%,%.1,$(basename $(2))): \
901 $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(2) \
902 $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage.xsl \
903 $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
904 $$(VBOX_XML_ENTITIES) $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@)
905 $$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@)
906 $$(QUIET)$$(RM) -f "$$@"
907 $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage.xsl $$<
908endef
909$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \
910, $(evalcall2 def_vbox_refentry_to_manpage,$(lang),$(file))))
911
912$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/,$(VBOX_MANUAL_PNG_FILES_en_US)): \
913 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/%: $(VBOX_PATH_MANUAL_SRC)/en_US/% | $$(dir $$@)
914 $(call MSG_L1,Copying temporary $< => $@)
915 $(QUIET)$(INSTALL_STAGING) -m0644 -- '$<' '$(@D)'
916
917################Generate qHelp's qhp file out of HTMLHelp###############################
918$(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl: \
919 $(VBOX_PATH_MANUAL_SRC)/titlepage-htmlhelp.xml $(MAKEFILE_CURRENT) | $$(dir $$@)
920 $(call MSG_L1,xsltproc $<)
921 $(QUIET)$(RM) -f [email protected] $@
922 $(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet -o [email protected] $(VBOX_PATH_DOCBOOK)/template/titlepage.xsl $<
923 $(QUIET)$(MV) -f [email protected] $@
924
925$(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/htmlhelp.hhp: \
926 $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_XML_FILES)) \
927 $(VBOX_MANUAL_XML_FILES_COMMON) \
928 $(VBOX_MANUAL_XML_FILES_GENERATED_en_US) \
929 $(VBOX_DOCBOOK_HTMLHELP_FORMATCFG) \
930 $(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl \
931 $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatemanual.run,) \
932 $(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
933 $(VBOX_XML_ENTITIES) \
934 $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/,$(VBOX_MANUAL_PNG_FILES_en_US)) | $$(dir $$@)
935 $(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$$^))),,$(firstword $(filter %.xml,$^)),$@)
936 $(QUIET)$(RM) -f $@
937 $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --output $(@D)/ \
938 --stringparam htmlhelp.chm \
939 $(subst /,\\,$(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.chm) \
940 $(HTMLHELPOPTS) $(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl \
941 $<
942
943$(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qhp: \
944 $(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatemanual.run,) \
945 $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
946 $(VBOX_XML_ENTITIES) | $$(dir $$@) \
947 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/htmlhelp.hhp
948 $(VBOX_PATH_MANUAL_SRC)/htmlhelp-qthelp.py -d $(@D) -o $@
949
950################Copy qhcp file from the source directory###############################
951$(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qhcp: \
952 $$(dir $$@)
953 $(QUIET)$(INSTALL_STAGING) -m0664 -- $(addprefix $(VBOX_PATH_MANUAL_SRC)/, $(VBOX_QHCP_FILES)) $@
954
955$(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qhc: \
956 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qhcp \
957 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qhp \
958 $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/, $(VBOX_MANUAL_PNG_FILES_en_US))
959 $(PATH_TOOL_QT5_BIN)/qcollectiongenerator $<
960
961$(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qch: \
962 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qhc
963
964
965# Handy aliases.
966validate-manpages:: $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_REFENTRY_FILES))
967man-experiment:: $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \
968 ,$$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/$(patsubst man_%,%.1,$(basename $(file)))))
969
970#
971# Manually updating the DHCP option list taken from VirtualBox.xidl
972#
973dhcpoptions: $(PATH_ROOT)/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xsl \
974 $(PATH_ROOT)/src/VBox/Main/idl/VirtualBox.xidl
975 $(call VBOX_XSLTPROC) --output "$(PATH_ROOT)/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xml" $+
976
977
978include $(FILE_KBUILD_SUB_FOOTER)
979
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette