Makefile.kmk@ 74321

Last change on this file since 74321 was 73276, checked in by vboxsync, 6 years ago
doc/manual: Big build system overhaul, because the use of entities and catalogs eliminates the need to have placeholders in XML which previously needed separate preprocessing. Many cleanups, including replacing almost all pattern rules (since their dependencies had to be too generous) and using defines instead. Also integrated many cleanups for the user manual text (which needs careful review, couldn't check yet if it uses any additional tags which some of our XSLT would ignore).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 36.0 KB

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

Note: See TracBrowser for help on using the repository browser.

Download in other formats:

Original Format