VirtualBox

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

Last change on this file since 94822 was 94822, checked in by vboxsync, 3 years ago

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