Makefile.kmk@ 69483

Last change on this file since 69483 was 69111, checked in by vboxsync, 7 years ago
(C) year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 37.9 KB

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

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

Download in other formats:

Original Format