VirtualBox

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

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

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