Makefile.kmk@ 56192

Last change on this file since 56192 was 56192, checked in by vboxsync, 10 years ago
Extract the necessary bits for the VBoxManage Commands Overview section from the refentry file(s).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 41.0 KB

Line
1	# $Id: Makefile.kmk 56192 2015-06-01 15:46:50Z vboxsync $
2	## @file
3	# Sub-Makefile for the VBox User Manual.
4	#
5
6	#
7	# Copyright (C) 2006-2012 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
52	#
53	# Globals
54	#
55
56	# Error out if someone tries to override old globals.
57	ifdef HTMLHELPOPTS
58	$(error HTMLHELPOPTS was renamed to VBOX_HTMLHELP_OPTS!)
59	endif
60	ifdef DOCBOOKPATH
61	$(error DOCBOOKPATH was renamed to VBOX_PATH_DOCBOOK!)
62	endif
63	ifdef DOCBOOKPATH
64	$(error DOCBOOKPATH was renamed to VBOX_PATH_DOCBOOK!)
65	endif
66	ifdef XML_CATALOG
67	$(error XML_CATALOG was renamed to VBOX_XML_CATALOG!)
68	endif
69	ifdef VBOX_XML_CATALOG_DOCBOOK
70	$(error XML_CATALOG_DOCBOOK was renamed to VBOX_XML_CATALOG_DOCBOOK!)
71	endif
72	ifdef VBOXMANAGEPATH
73	$(error VBOXMANAGEPATH was renamed to VBOXMANAGEHELP_PATH!)
74	endif
75	ifdef PDFLATEX_INTERACTION
76	$(error PDFLATEX_INTERACTION was renamed to VBOX_PDFLATEX_INTERACTION!)
77	endif
78	ifdef PDFLATEX
79	$(error PDFLATEX was renamed to VBOX_PDFLATEX_CMD!)
80	endif
81	ifdef HHC
82	$(error HHC was renamed to VBOX_HHC!)
83	endif
84
85	# Source and output locations.
86	VBOX_PATH_MANUAL_SRC := $(PATH_SUB_CURRENT)
87	VBOX_PATH_MANUAL_OUTBASE := $(PATH_TARGET)/manual
88
89	# tool locations
90	ifndef VBOX_OSE
91	# use docbook from our tools directory
92	VBOX_PATH_DOCBOOK ?= $(PATH_DEVTOOLS)/common/DocBook/v1.69.1
93	VBOX_PATH_DOCBOOK_DTD ?= $(PATH_DEVTOOLS)/common/docbook-xml/v4.3
94	VBOX_XML_CATALOG ?= $(VBOX_PATH_MANUAL_OUTBASE)/catalog
95	VBOX_XML_CATALOG_DOCBOOK ?= $(VBOX_PATH_MANUAL_OUTBASE)/docbook
96	else
97	# use docbook of the build host
98	VBOX_PATH_DOCBOOK ?= http://docbook.sourceforge.net/release/xsl/current/
99	endif
100
101	# xsltproc with the catalog trick if applicable.
102	ifdef VBOX_XML_CATALOG
103	VBOX_XSLTPROC_WITH_CAT = $(REDIRECT) -E "XML_CATALOG_FILES=$(VBOX_XML_CATALOG)" -- $(VBOX_XSLTPROC)
104	else
105	VBOX_XSLTPROC_WITH_CAT = $(VBOX_XSLTPROC)
106	endif
107
108	VBOXMANAGEHELP_PATH ?= $(PATH_STAGE_BIN)/VBoxManageHelp$(SUFF_EXE)
109
110	# VBOX_PDFLATEX_INTERACTION = errorstopmode - Use this when you wants to figure out build failures
111	# without catting the log a million times.
112	VBOX_PDFLATEX_INTERACTION ?= batchmode
113	ifeq ($(KBUILD_HOST),win)
114	ifndef VBOX_PDFLATEX
115	VBOX_PDFLATEX := $(firstword $(rsort $(wildcard $(PATH_DEVTOOLS)/win.x86/miktex-portable/*/miktex/bin/pdflatex.exe)))
116	ifneq ($(VBOX_PDFLATEX),)
117	VBOX_PDFLATEX_CMD = $(VBOX_PDFLATEX) -halt-on-error -interaction $(VBOX_PDFLATEX_INTERACTION)
118	endif
119	endif
120	ifndef VBOX_PDFLATEX
121	# Tell MiKTeX to automatically download packages if system wide install.
122	VBOX_PDFLATEX := pdflatex
123	VBOX_PDFLATEX_CMD = $(VBOX_PDFLATEX) -halt-on-error -interaction $(VBOX_PDFLATEX_INTERACTION) --enable-installer
124	endif
125	else
126	VBOX_PDFLATEX ?= pdflatex
127	VBOX_PDFLATEX_HALT = $(shell ( $(VBOX_PDFLATEX) -version \| head -1 \| grep 141592 > /dev/null ) && echo -halt-on-error )
128	VBOX_PDFLATEX_CMD = pdflatex $(VBOX_PDFLATEX_HALT) -interaction $(VBOX_PDFLATEX_INTERACTION)
129	endif
130
131	# Windows HTML Help Workshop compiler (stupid thing always returns an error!)
132	VBOX_HHC = -$(EXEC_X86_WIN32) $(VBOX_PATH_HTML_HELP_WORKSHOP)/hhc.exe
133
134
135	# Additional xsltproc options when generating
136	VBOX_HTMLHELP_OPTS ?=
137
138	# SDK related globals.
139	VBOX_MANUAL_APIREF_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef_apiref.xml
140	VBOX_DOC_XIDL_SRC = $(PATH_ROOT)/src/VBox/Main/idl/VirtualBox.xidl
141	VBOX_DOC_XIDL_SRC_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.xidl.tmp
142
143	##
144	# Non-pattern-rule approach to editing XSLT files.
145	# $(evalcall2 def_vbox_replace_paths_in_xslt)
146	# @param 1 The XSLT source file.
147	# @param 2 Optional output subdirectory.
148	define def_vbox_replace_paths_in_xslt
149	OTHER_CLEAN += $$(VBOX_PATH_MANUAL_OUTBASE)/$2$(notdir $1)
150	$$(VBOX_PATH_MANUAL_OUTBASE)/$2$(notdir $1): $1 \| $$$$(dir $$$$@)
151	$$(call MSG_GENERATE,,$$@,$$<)
152	$$(QUIET)$$(SED) \
153	-e 's\|@VBOX_PATH_DOCBOOK@\|$$(VBOX_PATH_DOCBOOK)\|g' \
154	-e 's\|@VBOX_PATH_MANUAL_SRC@\|$$(VBOX_PATH_MANUAL_SRC)\|g' \
155	-e 's\|@VBOX_PATH_MANUAL_OUTBASE@\|$$(VBOX_PATH_MANUAL_OUTBASE)\|g' \
156	\
157	-e 's\|@CFGPATH@\|$$(VBOX_PATH_MANUAL_SRC)\|g' \
158	-e 's\|@TARGETPATH@\|$$(@D)\|g' \
159	--output "$$(@)" $$<
160	endef
161
162
163
164	#
165	# Targets
166	#
167
168	BLDDIRS += $(VBOX_PATH_MANUAL_OUTBASE)
169
170	ifdef VBOX_WITH_DOCS
171	if defined(VBOX_ONLY_SDK) \|\| defined(VBOX_WITH_DOCS_SDKREF)
172	## @todo make this an install target, drop the BLDDIRS.
173	OTHERS += \
174	$(VBOX_PATH_SDK)/docs/SDKRef.pdf
175	BLDDIRS += \
176	$(VBOX_PATH_SDK)/docs
177	endif
178
179	ifdef VBOX_WITH_DOCS_CHM
180	VBOX_PATH_BIN_CHM = $(PATH_STAGE_BIN)/VirtualBox.chm
181	else # Do not build chm.
182	VBOX_PATH_BIN_CHM =
183	endif
184
185	ifndef VBOX_ONLY_SDK
186	VBOX_MANUAL_PACK += \
187	$(PATH_STAGE_BIN)/UserManual.pdf \
188	$(VBOX_PATH_BIN_CHM)
189	OTHERS += \
190	$(PATH_STAGE_BIN)/UserManual.pdf
191	OTHERS.win += \
192	$(VBOX_PATH_BIN_CHM)
193	OTHERS.linux += \
194	$(VBOX_PATH_BIN_CHM)
195
196	ifdef VBOX_WITH_DOCS_TRANSLATIONS
197	OTHERS += \
198	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf)
199	ifdef VBOX_WITH_DOCS_CHM
200	OTHERS.win += \
201	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm)
202	OTHERS.linux += \
203	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm)
204	endif
205	endif
206	endif # !VBOX_ONLY_SDK
207	ifdef VBOX_ONLY_DOCS
208	PACKING += $(PATH_STAGE_BIN)/VBoxDocumentation.zip
209	endif
210
211	ifdef VBOX_WITH_DOCS_TRANSLATIONS
212	VBOX_MANUAL_LANGUAGES += $(VBOX_MANUAL_ADD_LANGUAGES)
213	endif
214
215	VBOX_MANUAL_XML_CHANGELOG = \
216	user_ChangeLogImpl.xml
217
218	VBOX_MANUAL_XML_FILES = \
219	UserManual.xml \
220	user_AdvancedTopics.xml \
221	user_BasicConcepts.xml \
222	user_Glossary.xml \
223	user_Frontends.xml \
224	user_Installation.xml \
225	user_GuestAdditions.xml \
226	user_Introduction.xml \
227	user_KnownIssues.xml \
228	user_PrivacyPolicy.xml \
229	user_Security.xml \
230	user_Technical.xml \
231	user_ThirdParty.xml \
232	user_Troubleshooting.xml \
233	user_VBoxManage.xml \
234	user_VirtualBoxAPI.xml \
235	user_Storage.xml \
236	user_Networking.xml
237
238	VBOX_MANUAL_XML_FILES_INCL_CHANGELOG = $(VBOX_MANUAL_XML_FILES) \
239	user_ChangeLog.xml
240
241	VBOX_MANUAL_XML_REFENTRY_FILES = \
242	man_VBoxManage_extpack.xml
243
244	VBOX_SDKREF_XML_FILES = \
245	SDKRef.xml
246
247	# Wildcard the images path for every supported language
248	$(foreach f,$(VBOX_MANUAL_LANGUAGES), \
249	$(eval VBOX_MANUAL_PNG_FILES_$$(f) := $$(patsubst $$(VBOX_PATH_MANUAL_SRC)/$$(f)/%,%,$$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$$(f)/images/*.png))))
250
251	VBOX_MANUAL_TEX_UNICODE_FILES = \
252	$(wildcard $(VBOX_PATH_MANUAL_SRC)/texfiles/unicode/*)
253
254	VBOX_MANUAL_LATEX_FILES_TARGET = \
255	$(addprefix UserManual.,aux log out toc tex)
256
257	VBOX_SDKREF_LATEX_FILES_TARGET = \
258	$(addprefix SDKRef.,aux log out toc tex)
259
260	BLDDIRS += \
261	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/,\
262	$(VBOX_MANUAL_LANGUAGES) \
263	$(addsuffix /images, $(VBOX_MANUAL_LANGUAGES)) \
264	$(addsuffix /html-single, $(VBOX_MANUAL_LANGUAGES)) \
265	$(addsuffix /html-chunks, $(VBOX_MANUAL_LANGUAGES)) \
266	$(addsuffix /HTMLHelp, $(VBOX_MANUAL_LANGUAGES)) \
267	$(addsuffix /HTMLHelp/images, $(VBOX_MANUAL_LANGUAGES)) \
268	)
269
270	ifdef VBOX_WITH_DOCS_CHM
271	VBOX_MANUAL_PACK += \
272	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf $(PATH_STAGE_BIN)/VirtualBox_$(f).chm)
273	endif
274
275	OTHER_CLEAN += \
276	$(VBOX_XML_CATALOG) \
277	$(VBOX_XML_CATALOG_DOCBOOK) \
278	$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/, \
279	$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG) \
280	$(VBOX_MANUAL_XML_REFENTRY_FILES) \
281	$(VBOX_MANUAL_LATEX_FILES_TARGET) \
282	$(VBOX_MANUAL_PNG_FILES_$(lang)) \
283	$(notdir $(VBOX_MANUAL_TEX_UNICODE_FILES)) \
284	$(addprefix HTMLHelp/,$(VBOX_MANUAL_PNG_FILES_$(lang))) \
285	html-single/UserManual.html \
286	$(addprefix html-chunks/ HTMLHelp/, index.html go01.html) \
287	$(foreach n,01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 \
288	,html-chunks/ch$(n).html \
289	HTMLHelp/ch$(n).html \
290	$(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)) ) \
291	$(foreach n,a b c \
292	,html-chunks/ap$(n).html \
293	HTMLHelp/ap$(n).html \
294	$(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) ) \
295	HTMLHelp/toc.hhc \
296	HTMLHelp/htmlhelp.hhp \
297	docbook-htmlhelp-formatcfg.xsl \
298	docbook-html-one-page-formatcfg.xsl \
299	docbook-html-chunks-formatcfg.xsl \
300	titlepage-htmlhelp.xsl \
301	UserManual.pdf \
302	VirtualBox.chm \
303	)) \
304	$(VBOX_PATH_MANUAL_OUTBASE)/$(VBOX_MANUAL_XML_CHANGELOG) \
305	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf) \
306	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm) \
307	$(PATH_STAGE_BIN)/UserManual.pdf \
308	$(PATH_STAGE_BIN)/VirtualBox.chm \
309	\
310	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \
311	$(VBOX_SDKREF_XML_FILES) \
312	$(VBOX_SDKREF_LATEX_FILES_TARGET) \
313	SDKRef.pdf \
314	) \
315	$(VBOX_DOC_XIDL_SRC_TMP) \
316	$(VBOX_MANUAL_APIREF_TMP) \
317	$(PATH_STAGE_BIN)/sdk/docs/SDKRef.pdf
318
319	endif # VBOX_WITH_DOCS
320
321
322
323	#
324	# To avoid network I/O for fetching DTDs, we generate catalogs mapping the public
325	# entity IDs to local files. (Obviously, only done when we have local files.)
326	#
327	ifdef VBOX_XML_CATALOG
328	# Create a catalog file for xsltproc that points to docbook catalog.
329	$(VBOX_XML_CATALOG): $(MAKEFILE_CURRENT) \| $$(dir $$@)
330	$(call MSG_L1,Creating catalog $@)
331	$(QUIET)$(RM) -f [email protected] $@
332	$(QUIET)$(APPEND) [email protected] '<?xml version="1.0"?>'
333	$(QUIET)$(APPEND) [email protected] '<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">'
334	$(QUIET)$(APPEND) [email protected] '<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">'
335	$(QUIET)$(APPEND) [email protected] ' <delegatePublic publicIdStartString="-//OASIS/ENTITIES DocBook XML" catalog="file:///$(VBOX_XML_CATALOG_DOCBOOK)"/>'
336	$(QUIET)$(APPEND) [email protected] ' <delegatePublic publicIdStartString="-//OASIS/DTD DocBook XML" catalog="file:///$(VBOX_XML_CATALOG_DOCBOOK)"/>'
337	$(QUIET)$(APPEND) [email protected] ' <delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/" catalog="file:///$(VBOX_XML_CATALOG_DOCBOOK)"/>'
338	$(QUIET)$(APPEND) [email protected] ' <delegateURI uriStartString="http://www.oasis-open.org/docbook/" catalog="file:///$(VBOX_XML_CATALOG_DOCBOOK)"/>'
339	$(QUIET)$(APPEND) [email protected] '</catalog>'
340	$(QUIET)$(MV) -f [email protected] $@
341
342	# Create a docbook catalog file for xsltproc that points to the local docbook files.
343	$(VBOX_XML_CATALOG_DOCBOOK): $(MAKEFILE_CURRENT) \| $$(dir $$@)
344	$(call MSG_L1,Creating catalog $@)
345	$(QUIET)$(RM) -f [email protected] $@
346	$(QUIET)$(APPEND) [email protected] '<?xml version="1.0"?>'
347	$(QUIET)$(APPEND) [email protected] '<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">'
348	$(QUIET)$(APPEND) [email protected] '<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">'
349	$(QUIET)$(APPEND) [email protected] ' <public publicId="-//OASIS//ELEMENTS DocBook XML Information Pool V4.3//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbpoolx.mod"/>'
350	$(QUIET)$(APPEND) [email protected] ' <public publicId="-//OASIS//DTD DocBook XML V4.3//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd"/>'
351	$(QUIET)$(APPEND) [email protected] ' <public publicId="-//OASIS//DTD DocBook XML V4.4//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd"/>'
352	$(QUIET)$(APPEND) [email protected] ' <public publicId="-//OASIS//ENTITIES DocBook XML Character Entities V4.3//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbcentx.mod"/>'
353	$(QUIET)$(APPEND) [email protected] ' <public publicId="-//OASIS//ENTITIES DocBook XML Notations V4.3//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbnotnx.mod"/>'
354	$(QUIET)$(APPEND) [email protected] ' <public publicId="-//OASIS//ENTITIES DocBook XML Additional General Entities V4.3//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbgenent.mod"/>'
355	$(QUIET)$(APPEND) [email protected] ' <public publicId="-//OASIS//ELEMENTS DocBook XML Document Hierarchy V4.3//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbhierx.mod"/>'
356	$(QUIET)$(APPEND) [email protected] ' <public publicId="-//OASIS//DTD XML Exchange Table Model 19990315//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/soextblx.dtd"/>'
357	$(QUIET)$(APPEND) [email protected] ' <public publicId="-//OASIS//DTD DocBook XML CALS Table Model V4.3//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/calstblx.dtd"/>'
358	$(QUIET)$(APPEND) [email protected] ' <rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.3" rewritePrefix="file:///$(VBOX_PATH_DOCBOOK_DTD)"/>'
359	$(QUIET)$(APPEND) [email protected] ' <rewriteURI uriStartString="http://www.oasis-open.org/docbook/xml/4.3" rewritePrefix="file:///$(VBOX_PATH_DOCBOOK_DTD)"/>'
360	$(QUIET)$(APPEND) [email protected] ' <rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.4" rewritePrefix="file:///$(VBOX_PATH_DOCBOOK_DTD)"/>'
361	$(QUIET)$(APPEND) [email protected] ' <rewriteURI uriStartString="http://www.oasis-open.org/docbook/xml/4.4" rewritePrefix="file:///$(VBOX_PATH_DOCBOOK_DTD)"/>'
362	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsa.ent"/>'
363	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Binary Operators//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsb.ent"/>'
364	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Delimiters//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsc.ent"/>'
365	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Negated Relations//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsn.ent"/>'
366	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Ordinary//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amso.ent"/>'
367	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Relations//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsr.ent"/>'
368	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Box and Line Drawing//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-box.ent"/>'
369	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Russian Cyrillic//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-cyr1.ent"/>'
370	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Non-Russian Cyrillic//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-cyr2.ent"/>'
371	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Diacritical Marks//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-dia.ent"/>'
372	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Greek Letters//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-grk1.ent"/>'
373	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Monotoniko Greek//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-grk2.ent"/>'
374	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Greek Symbols//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-grk3.ent"/>'
375	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Alternative Greek Symbols//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-grk4.ent"/>'
376	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Added Latin 1//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-lat1.ent"/>'
377	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Added Latin 2//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-lat2.ent"/>'
378	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-num.ent"/>'
379	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES Publishing//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-pub.ent"/>'
380	$(QUIET)$(APPEND) [email protected] ' <public publicId="ISO 8879:1986//ENTITIES General Technical//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-tech.ent"/>'
381	$(QUIET)$(APPEND) [email protected] '</catalog>'
382	$(QUIET)$(MV) -f [email protected] $@
383	endif
384
385
386	##########################################################################################
387	#
388	# Rules: Preprocess DocBook XML files
389	# (preliminary step for both CHM and PDF generation)
390	#
391	##########################################################################################
392
393	#
394	# The following rules for $(VBOX_PATH_MANUAL_OUTBASE)/*.xml process the XML files
395	# in doc/manual to allow for some magic variable replacements. The PDF and CHM
396	# targets do not depend on the XML files in doc/manual, but those in
397	# $(VBOX_PATH_MANUAL_OUTBASE) instead, which we copy there from here, after that magic
398	# processing.
399	#
400	# So, before copying, the following steps are performed:
401	#
402	# -- $VBOX_VERSION_* strings are replaced with the actual current VBox version.
403	# -- $VBOX_MANAGE_OUTPUT (in VBoxManage.xml) is replaced with the current
404	# output of the actual VBoxManage program, to save us from having to
405	# update the manual all the time.
406	#
407
408	# Only one changelog for all languages
409	# $(VBOX_PATH_MANUAL_OUTBASE)/$(VBOX_MANUAL_XML_CHANGELOG): $(VBOX_PATH_MANUAL_SRC)/$(VBOX_MANUAL_XML_CHANGELOG) \| $$(dir $$@)
410	# $(QUIET)$(INSTALL) -m 0644 $< $@
411
412	# intermediate step to do some variable replacement in the document
413	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(filter-out user_VBoxManage.xml,$(VBOX_MANUAL_XML_FILES)))): \
414	$(VBOX_PATH_MANUAL_OUTBASE)/% : $(VBOX_PATH_MANUAL_SRC)/% $(VBOX_VERSION_STAMP) \| $$(dir $$@)
415	$(call MSG_L1,Pre-processing [1] $(@F) to $@)
416	$(QUIET)$(RM) -f $@ [email protected]
417	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
418	-e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
419	-e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
420	-e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
421	-e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
422	-e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
423	-e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
424	--output [email protected] $<
425	$(QUIET)$(MV) -f [email protected] $@
426
427	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/user_ChangeLog.xml): \
428	$(VBOX_PATH_MANUAL_OUTBASE)/% : \
429	$(VBOX_PATH_MANUAL_SRC)/% $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml \| $$(dir $$@)
430	$(call MSG_L1,Pre-processing [3] $(@F) to $@)
431	$(QUIET)$(RM) -f $@ [email protected] [email protected]
432	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
433	-e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
434	-e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
435	-e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
436	-e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
437	-e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
438	-e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
439	--output [email protected] $<
440	$(QUIET)$(SED) -e '1,/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/!d' \
441	-e 's/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->//' \
442	--output $@ [email protected]
443	var=`$(SED) -n '/!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/p' $<`; \
444	test -n "$${var}" \
445	&& $(SED) -e 's/<?xml version=\"1.0\" encoding=\"UTF-8\"?>//g' \
446	--append $@ $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml; \
447	true
448	$(QUIET)$(SED) -e '/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/,$$!d' \
449	-e 's/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->//' --append $@ [email protected]
450	$(QUIET)$(RM) -f -- "[email protected]"
451
452	# TODO: figure why the rule below doesn't cause kmk to rebuild the manual when a man page changes!
453	$(foreach lang,$(VBOX_MANUAL_LANGUAGES), \
454	$(eval $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/user_VBoxManage.xml: $(VBOX_PATH_MANUAL_SRC)/$(lang)/user_VBoxManage.xml \
455	$$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
456	$(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml ))
457
458	# user_VBoxManage.xml currently needs some extra processing to stitch in the VBoxManage usage blob.
459	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/user_VBoxManage.xml): \
460	$(VBOX_PATH_MANUAL_OUTBASE)/% : \
461	$(VBOX_PATH_MANUAL_SRC)/% \
462	$$(addprefix $$(@D)/,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
463	$(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml \
464	$(VBOX_XML_CATALOG) \
465	$(VBOX_XML_CATALOG_DOCBOOK) \
466	$(VBOXMANAGEHELP_PATH) \| $$(dir $$@)
467	$(call MSG_L1,Pre-processing [2] $(@F) to $@)
468	$(QUIET)$(RM) -f $@ [email protected] [email protected]
469	$(QUIET)$(SED) \
470	-e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
471	-e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
472	-e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
473	-e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
474	-e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
475	-e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
476	-e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
477	-e 's\|@VBOX_PATH_DOCBOOK@\|$(VBOX_PATH_DOCBOOK)\|g' \
478	-e 's\|@VBOX_PATH_MANUAL_SRC@\|$(VBOX_PATH_MANUAL_SRC)\|g' \
479	--output [email protected] $<
480	$(QUIET)$(SED) \
481	-e '1,/\$$VBOX_MANAGE_OUTPUT/!d' \
482	-e 's/\$$VBOX_MANAGE_OUTPUT.*//' \
483	--output [email protected] [email protected]
484	$(QUIET)$(REDIRECT) -wo [email protected] -E 'VBOX_LOG_FLAGS=disabled' -E 'VBOX_LOG_DEST=nofile' \
485	$(if $(eq $(KBUILD_TARGET),darwin), -E 'DYLD_FALLBACK_LIBRARY_PATH=$(dir $(LIB_RUNTIME))') \
486	-- \
487	$(VBOXMANAGEHELP_PATH) --dumpopts
488	$(QUIET)$(SED) -e 's/</\</g' -e 's/>/\>/g' --append [email protected] [email protected]
489	$(QUIET)$(SED) \
490	-e '/\$$VBOX_MANAGE_OUTPUT/,$$!d' \
491	-e 's/.*\$$VBOX_MANAGE_OUTPUT//' \
492	--append [email protected] [email protected]
493	if 0 # Not currently needed.
494	$(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output $@ \
495	$(VBOX_PATH_MANUAL_SRC)/usage-to-docbook-manual.xsl \
496	[email protected]
497	else
498	$(QUIET)$(CP) [email protected] $@
499	endif
500	$(QUIET)$(RM) -f [email protected] [email protected] [email protected]
501
502
503	# Morph man pages into manual sections.
504	$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/,$(VBOX_MANUAL_XML_REFENTRY_FILES))): \
505	$(VBOX_PATH_MANUAL_OUTBASE)/% : $(VBOX_PATH_MANUAL_SRC)/% \
506	$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl \
507	$(VBOX_VERSION_STAMP) \| $$(dir $$@)
508	$(call MSG_GENERATE,,$@,$<)
509	$(QUIET)$(RM) -f $@
510	$(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output $@ \
511	$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl $<
512
513
514	$(VBOX_DOC_XIDL_SRC_TMP): $(VBOX_DOC_XIDL_SRC) $(MAKEFILE_CURRENT) \| $$(dir $$@)
515	$(call MSG_L1,Generating $@)
516	$(QUIET)$(SED) -e 's\|@a \+$\w\+$\|<tt>\1</tt>\|g' \
517	-e 's\|@c \+$\w\+$\|<tt>\1</tt>\|g' \
518	--output $@ $<
519
520	# Generates the VBoxManage command overview include file (shared between
521	# languages) from the refsynopsisdiv section of the man pages.
522	$(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml: \
523	$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-overview.xsl \
524	$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(filter man_VBoxManage_%,$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
525	\| $$(dir $$@)
526	$(call MSG_GENERATE,,$@,en_US/man_VBoxManage_*.xml)
527	$(QUIET)$(RM) -f -- "$@"
528	$(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output "$@" \
529	$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-overview.xsl \
530	$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(filter man_VBoxManage_%,$(VBOX_MANUAL_XML_REFENTRY_FILES)))
531
532	xxxx:: $(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml
533
534	# generate SDKRef_apiref.xml as a docbook file excerpt that will be referenced from the SDKRef.xml.
535	$(VBOX_MANUAL_APIREF_TMP): $(VBOX_DOC_XIDL_SRC_TMP) $(VBOX_PATH_MANUAL_SRC)/xidl2docbook.xsl
536	$(call MSG_L1,Generating $@)
537	$(QUIET)$(VBOX_XSLTPROC) --xinclude -o $@ $(VBOX_PATH_MANUAL_SRC)/xidl2docbook.xsl $(VBOX_DOC_XIDL_SRC_TMP)
538
539	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.xml: \
540	$(VBOX_PATH_MANUAL_SRC)/en_US/SDKRef.xml $(VBOX_MANUAL_APIREF_TMP) \
541	\| $$(dir $$@)
542	$(call MSG_L1,Pre-processing [2] $(@F) to $@)
543	$(QUIET)$(RM) -f $@ [email protected]
544	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
545	-e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
546	-e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
547	-e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
548	-e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
549	-e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
550	-e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
551	--output [email protected] $<
552	$(QUIET)$(SED) -e '1,/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->/!d' \
553	-e 's/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->//' \
554	--output $@ [email protected]
555	$(QUIET)$(SED) -e 's/<?xml version=\"1.0\" encoding=\"utf-8\"?>//g' --append $@ $(VBOX_MANUAL_APIREF_TMP)
556	$(QUIET)$(SED) -e '/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->/,$$!d' \
557	-e 's/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->//' --append $@ [email protected]
558	# $(QUIET)$(MV) -f [email protected] $@
559	$(QUIET)$(RM) -f -- "[email protected]"
560
561
562	##########################################################################################
563	#
564	# Shared rules for PDF generation
565	#
566	##########################################################################################
567
568	ifndef VBOX_OSE
569	# copy ucs.sty and related files
570	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/ucs.sty):
571	$(call MSG_L1,Copying unicode support for LaTeX)
572	$(QUIET)$(INSTALL_STAGING) -- $(VBOX_MANUAL_TEX_UNICODE_FILES) "$(@D)"
573	endif
574
575	# copy the PNG files.
576	# Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
577	define def_vbox_cp_images_pdf
578	local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)
579	$(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \
580	$$(out_dir)/%: $(VBOX_PATH_MANUAL_SRC)/$(lang)/% \| $$$$(dir $$$$@)
581	$$(call MSG_L1,Copying temporary $$< => $$@)
582	$$(QUIET)$$(INSTALL_STAGING) -- '$$<' '$$(@D)'
583	endef
584
585	$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(eval $(def_vbox_cp_images_pdf)))
586
587
588	##########################################################################################
589	#
590	# UserManual.pdf
591	#
592	##########################################################################################
593
594	## @todo INSTALLS target for this!
595	$(PATH_STAGE_BIN)/UserManual.pdf: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.pdf \| $$(dir $$@)
596	$(QUIET)$(CP) $< $@
597	$(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)
598
599	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf): \
600	$(PATH_STAGE_BIN)/UserManual_%.pdf : $(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.pdf
601	$(QUIET)$(CP) $< $@
602	$(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)
603
604	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/UserManual.pdf): \
605	$(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.pdf : \
606	$(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.tex \
607	$(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/%/ucs.sty) \
608	$(foreach f,$(VBOX_MANUAL_LANGUAGES),\
609	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_MANUAL_PNG_FILES_$(f)))) \| $$(dir $$@)
610	# PDF generation via Latex: generate the .tex file
611	$(call MSG_L1,pdflatex $< (four passes) -> $@)
612	$(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(VBOX_PDFLATEX_CMD) UserManual.tex
613	$(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(VBOX_PDFLATEX_CMD) UserManual.tex
614	$(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(VBOX_PDFLATEX_CMD) UserManual.tex
615	$(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(VBOX_PDFLATEX_CMD) UserManual.tex
616	$(QUIET)$(SED) -ne '/Warning: Hyper reference/p' $(basename $<).log
617	$(QUIET)$(SED) -n \
618	-e '/Warning: There were $undefined references\\|multiply-defined labels$/{p; q 1}' \
619	$(basename $@).log
620
621	##@todo restore this when above has been converted to INSTALLS target. $(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)
622
623	# generate temporary LaTeX source from processed XML
624	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/UserManual.tex): \
625	$(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.tex : \
626	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/%/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
627	$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \
628	$(MAKEFILE_CURRENT)
629	$(call MSG_L1,Generating $@ from DocBook XML)
630	$(QUIET)$(RM) -f $(addprefix $(@D)/,$(VBOX_MANUAL_LATEX_FILES_TARGET))
631	# generate TeX source from processed docbook and store it in UserManual.tex.tmp;
632	# pass current language to xsltproc in TARGETLANG variable (extract it from the
633	# current directory, should become "de_DE" or the like)
634	$(QUIET)$(VBOX_XSLTPROC_WITH_CAT) $(XSLTPROC_VERBOSE) --xinclude --nonet --stringparam TARGETLANG $(notdir $(@D)) \
635	-o [email protected] $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $<
636	# for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word;
637	# the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections
638	$(QUIET)$(SED) \
639	-e 's\|^\\QUOTE{}\|\\OQ{}\|g' \
640	-e 's\|$\W$\\QUOTE{}\|\1\\OQ{}\|g' \
641	-e 's\|$\w$\\QUOTE{}\|\1\\CQ{}\|g' \
642	--output $@ [email protected]
643	$(QUIET)$(RM) -f [email protected]
644
645
646	#
647	# SDKRef.pdf
648	#
649	$(VBOX_PATH_SDK)/docs/SDKRef.pdf: \
650	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex \
651	$(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ucs.sty) \
652	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \| $$(dir $$@)
653	# PDF generation via Latex: generate the .tex file
654	$(QUIET)$(MKDIR) -p $(VBOX_PATH_SDK)/docs
655	$(call MSG_L1,pdflatex $< (three passes))
656	$(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) SDKRef.tex
657	$(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) SDKRef.tex
658	$(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) SDKRef.tex
659	$(QUIET)$(SED) -ne '/Warning: Hyper reference/p' $(basename $<).log
660	$(QUIET)$(SED) -n \
661	-e '/Warning: There were $undefined references\\|multiply-defined labels$/{p; q 1}' \
662	$(basename $<).log
663	$(QUIET)$(CP) $(<D)/SDKRef.pdf $@
664	$(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)
665
666	# generate temporary LaTeX source from processed XML
667	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex: $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_SDKREF_XML_FILES)) \
668	$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $(MAKEFILE_CURRENT)
669	$(call MSG_L1,Generating $@ from DocBook XML)
670	$(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_SDKREF_LATEX_FILES_TARGET))
671	# generate TeX source from processed docbook and store it in SDKRef.tex.tmp
672	$(QUIET)$(VBOX_XSLTPROC_WITH_CAT) $(XSLTPROC_VERBOSE) --xinclude --nonet --stringparam TARGETLANG en_US \
673	-o [email protected] $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $<
674	# for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word;
675	# the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections
676	$(QUIET)$(SED) \
677	-e 's\|^\\QUOTE{}\|\\OQ{}\|g' \
678	-e 's\|$\W$\\QUOTE{}\|\1\\OQ{}\|g' \
679	-e 's\|$\w$\\QUOTE{}\|\1\\CQ{}\|g' \
680	--output $@ [email protected]
681	$(QUIET)$(RM) -f [email protected]
682
683
684
685	ifdef VBOX_WITH_DOCS_CHM
686	#
687	# VirtualBox.chm
688	#
689	# We first generate a .hhp help source file from the preprocessed
690	# DocBook XML files, as defined above, then feed that into the
691	# Microsoft Help Compiler.
692	#
693	$(PATH_STAGE_BIN)/VirtualBox.chm: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.chm
694	$(QUIET)$(CP) $< $@
695	$(call MSG_L1,Fresh CHM is now at $@)
696
697	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm): \
698	$(PATH_STAGE_BIN)/VirtualBox_%.chm : $(VBOX_PATH_MANUAL_OUTBASE)/%/VirtualBox.chm
699	$(QUIET)$(CP) $< $@
700	$(call MSG_L1,Fresh CHM is now at $@)
701
702	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/VirtualBox.chm): \
703	$(VBOX_PATH_MANUAL_OUTBASE)/%/VirtualBox.chm: \
704	$(VBOX_PATH_MANUAL_OUTBASE)/%/HTMLHelp/htmlhelp.hhp \
705	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/HTMLHelp/,$(VBOX_MANUAL_PNG_FILES_$(f))))
706	$(call MSG_L1,hhc $<,=> $@)
707	$(QUIET)$(RM) -f $@
708	$(QUIET)$(VBOX_HHC) $(subst /,\\,$<)
709
710
711	# intermediate step to do some variable replacement in the XSL configuration
712	$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/docbook-htmlhelp-formatcfg.xsl): \
713	$(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl $(MAKEFILE_CURRENT) \| $$(dir $$@)
714	$(call MSG_GENERATE,,$@,$<)
715	$(QUIET)$(RM) -f $@
716	$(QUIET)$(SED) -e 's\|\$$DOCBOOKPATH\|$(VBOX_PATH_DOCBOOK)\|g' \
717	-e 's\|\$$CFGPATH\|$(VBOX_PATH_MANUAL_SRC)\|g' \
718	-e 's\|\$$TARGETPATH\|$(@D)\|g' --output $@ $<
719
720	# Prepare the XSL file for our title page, htmlhelp variant.
721	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/titlepage-htmlhelp.xsl): \
722	$(VBOX_PATH_MANUAL_SRC)/titlepage-htmlhelp.xml $(MAKEFILE_CURRENT) \| $$(dir $$@)
723	$(call MSG_L1,xsltproc $<)
724	$(QUIET)$(RM) -f [email protected] $@
725	$(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet -o [email protected] $(VBOX_PATH_DOCBOOK)/template/titlepage.xsl $<
726	$(QUIET)$(MV) -f [email protected] $@
727
728
729	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/HTMLHelp/htmlhelp.hhp): \
730	$(VBOX_PATH_MANUAL_OUTBASE)/%/HTMLHelp/htmlhelp.hhp: \
731	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/%/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
732	$(VBOX_PATH_MANUAL_OUTBASE)/%/docbook-htmlhelp-formatcfg.xsl \
733	$(VBOX_PATH_MANUAL_OUTBASE)/%/titlepage-htmlhelp.xsl \
734	$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK)
735	$(call MSG_L1,xsltproc $<,=> $@)
736	$(QUIET)$(RM) -f $@
737	$(QUIET)$(MKDIR) -p $(@D)
738	$(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output $(@D)/ \
739	--stringparam htmlhelp.chm \
740	$(subst /,\\,$(@D)/../VirtualBox.chm) \
741	$(HTMLHELPOPTS) $(@D)/../docbook-htmlhelp-formatcfg.xsl \
742	$<
743
744	# copy the PNG files.
745	# Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
746	define def_vbox_cp_images_html
747	local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/HTMLHelp
748	$$(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \
749	$$(out_dir)/%: $(VBOX_PATH_MANUAL_SRC)/$(lang)/% \| $$$$(dir $$$$@)
750	$$(call MSG_L1,Copying temporary $$< => $$@)
751	$$(QUIET)$$(CP) -f $$< $$@
752	endef
753
754	$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(eval $(def_vbox_cp_images_html)))
755
756	# Packing the docs into a zip file
757	$(PATH_STAGE_BIN)/VBoxDocumentation.zip: $(VBOX_MANUAL_PACK)
758	$(call MSG_L1,Packing documentation $@)
759	$(QUIET)$(RM) -f $@
760	$(QUIET)$(REDIRECT) -C $(PATH_STAGE_BIN) -- zip$(HOSTSUFF_EXE) -9 $@ $(notdir $^)
761
762	endif # VBOX_WITH_DOCS_CHM
763
764
765	##########################################################################################
766	#
767	# UserManual.html
768	#
769	##########################################################################################
770
771	# intermediate step to do some variable replacement in the XSL configuration
772	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl: \
773	$(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-formatcfg.xsl $(MAKEFILE_CURRENT) \| $$(dir $$@)
774	$(call MSG_L1,Pre-processing $(@F) to $@)
775	$(QUIET)$(RM) -f [email protected] $@
776	$(QUIET)$(SED) -e 's\|\$$DOCBOOKPATH\|$(VBOX_PATH_DOCBOOK)\|g' \
777	-e 's\|\$$CFGPATH\|$(VBOX_PATH_MANUAL_SRC)\|g' \
778	-e 's\|\$$TARGETPATH\|$(@D)\|g' --output [email protected] $<
779	$(QUIET)$(MV) -f [email protected] $@
780
781	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl: \
782	$(VBOX_PATH_MANUAL_SRC)/docbook-html-chunks-formatcfg.xsl $(MAKEFILE_CURRENT) \| $$(dir $$@)
783	$(call MSG_L1,Pre-processing $(@F) to $@)
784	$(QUIET)$(RM) -f [email protected] $@
785	$(QUIET)$(SED) -e 's\|\$$DOCBOOKPATH\|$(VBOX_PATH_DOCBOOK)\|g' \
786	-e 's\|\$$CFGPATH\|$(VBOX_PATH_MANUAL_SRC)\|g' \
787	-e 's\|\$$TARGETPATH\|$(@D)\|g' --output [email protected] $<
788	$(QUIET)$(MV) -f [email protected] $@
789
790	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html: \
791	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \
792	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.xml \
793	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
794	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \
795	$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \
796	\| $$(dir $$@)
797	$(call MSG_L1,xsltproc $<)
798	$(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet \
799	--output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html \
800	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \
801	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.xml
802
803	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html: \
804	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl \
805	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.xml \
806	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
807	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \
808	$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \
809	\| $$(dir $$@)
810	$(call MSG_L1,xsltproc $<)
811	$(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet \
812	--output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html \
813	--stringparam chunk.section.depth 0 \
814	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl \
815	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.xml
816
817	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip: \
818	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html \
819	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html
820	$(call MSG_L1,Packing documentation $@)
821	$(QUIET)$(RM) -f $@
822	$(QUIET)$(REDIRECT) -C $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ -- zip$(HOSTSUFF_EXE) \
823	-9 -r $@ html-single html-chunks $(VBOX_MANUAL_PNG_FILES_en_US)
824
825	html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html
826
827	html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html
828
829	html-zip:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip
830
831	##########################################################################################
832	#
833	# ChangeLog.html
834	#
835	##########################################################################################
836
837	# intermediate step to do some variable replacement in the XSL configuration
838	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-changelog-formatcfg.xsl: \
839	$(VBOX_PATH_MANUAL_SRC)/docbook-changelog-formatcfg.xsl $(MAKEFILE_CURRENT) \| $$(dir $$@)
840	$(call MSG_L1,Pre-processing $(@F) to $@)
841	$(QUIET)$(RM) -f [email protected] $@
842	$(QUIET)$(SED) -e 's\|\$$DOCBOOKPATH\|$(VBOX_PATH_DOCBOOK)\|g' \
843	-e 's\|\$$CFGPATH\|$(VBOX_PATH_MANUAL_SRC)\|g' \
844	-e 's\|\$$TARGETPATH\|$(@D)\|g' --output [email protected] $<
845	$(QUIET)$(MV) -f [email protected] $@
846
847	# This XSLT rule depends on $(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml, which is build by the complex rule
848	# $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/user_ChangeLog.xml): ...
849	# much further above. That rule takes en_US/user_ChangeLog.xml and replaces $VIRTUALBOX_CHANGELOG_IMPL
850	# with the actual change log contained in user_ChangeLogImpl.xml
851	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html: \
852	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-changelog-formatcfg.xsl \
853	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml
854	$(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html \
855	$(@D)/docbook-changelog-formatcfg.xsl \
856	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml
857	$(call MSG_L1,Fresh ChangeLog.html is now at $@)
858
859	cl-html: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html
860
861
862	##########################################################################################
863	#
864	# VBoxManage man pages.
865	#
866	##########################################################################################
867	$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-man.xsl,)
868
869	man-experiment: \
870	$(VBOX_PATH_MANUAL_SRC)/en_US/man_VBoxManage_extpack.xml \
871	$(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-man.xsl \
872	$(VBOX_XML_CATALOG) \
873	$(VBOX_XML_CATALOG_DOCBOOK)
874	$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output z:/tmp/vboxmanage-extpack.1 \
875	$(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-man.xsl \
876	$(VBOX_PATH_MANUAL_SRC)/en_US/man_VBoxManage_extpack.xml
877
878
879	include $(FILE_KBUILD_SUB_FOOTER)
880

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

Download in other formats:

Original Format