Makefile.kmk@ 105605

Last change on this file since 105605 was 105564, checked in by vboxsync, 4 months ago

doc/manual/Config.kmk, doc/manual/Makefile: Add catalog for DITA DTD essentials (won't do any harm for pure DocBook format documentation, the dita.v1_3 stuff didn't work due to xsltproc tripping over SVG entity definitions) and remove the related XML search path hack. Adjust XML search path so that the licensing content is found. bugref:10348

doc/manual/en_US/dita/UserManual.ditamap: Enable LIUM chapter, the XML search path fix resolved the errors when building the VirtualBox help. bugref:10705

doc/manual/pdf-theme-UserManual.yaml: lower the monospace font size for various tags to get more into a line, avoiding ugly line breaks

Property svn:eol-style set to native
Property svn:keywords set to Author Date Id Revision

File size: 53.6 KB

Line
1	# /# $Id: Makefile.kmk 105564 2024-08-01 12:18:48Z vboxsync $
2	## @file
3	# Sub-Makefile for the VirtualBox User Manual, SDK reference and other manuals.
4	#
5
6	#
7	# Copyright (C) 2006-2023 Oracle and/or its affiliates.
8	#
9	# This file is part of VirtualBox base platform packages, as
10	# available from https://www.virtualbox.org.
11	#
12	# This program is free software; you can redistribute it and/or
13	# modify it under the terms of the GNU General Public License
14	# as published by the Free Software Foundation, in version 3 of the
15	# License.
16	#
17	# This program is distributed in the hope that it will be useful, but
18	# WITHOUT ANY WARRANTY; without even the implied warranty of
19	# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20	# General Public License for more details.
21	#
22	# You should have received a copy of the GNU General Public License
23	# along with this program; if not, see <https://www.gnu.org/licenses>.
24	#
25	# SPDX-License-Identifier: GPL-3.0-only
26	#
27
28	#
29	# This makefile produces our user manual (among a few other things) in
30	# 3 formats: qHelp, pdf, and html (chunked and single page). User manual
31	# files are kept in dita format. VBoxManage commands are documented using docbook
32	# refentry elements and integrated into VBoxManage binary after converting those
33	# to .cpp and .h files (not here). Additionally, we add these refentry's into the
34	# user manual as a chapter after converting them into dita files. Both the user manual
35	# and converted VBoxManage commands files are referenced with a single ditamap.
36	# This ditamap is then transformed into html, htmlhelp (for qHelp), and pdf.
37	#
38
39
40	SUB_DEPTH = ../..
41	include $(KBUILD_PATH)/subheader.kmk
42
43	ifndef VBOX_DOC_MANUAL_CONFIG_KMK_INCLUDED
44	include $(PATH_SUB_CURRENT)/Config.kmk
45	endif
46
47	if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) \|\| defined(VBOX_ONLY_DOCS) \|\| defined(VBOX_ONLY_SDK)) # Whole file.
48
49	#
50	# Globals
51	#
52
53	## Combines the VBOX_MANUAL_LANGUAGES and VBOX_MANUAL_ADD_LANGUAGES lists from
54	# /Config.kmk, as per the VBOX_WITH_DOCS_TRANSLATIONS setting.
55	ifdef VBOX_WITH_DOCS_TRANSLATIONS
56	VBOX_MANUAL_ALL_LANGUAGES := $(VBOX_MANUAL_LANGUAGES) $(VBOX_MANUAL_ADD_LANGUAGES)
57	else
58	VBOX_MANUAL_ALL_LANGUAGES := $(VBOX_MANUAL_LANGUAGES)
59	endif
60
61	## The files that should go into VBoxDocumentation.zip (must be immediately under PATH_STAGE_BIN).
62	VBOX_MANUAL_PACK =
63
64	# Various file lists (mainly needed for OTHER_CLEAN).
65	VBOX_QHELP_OUTPUT_FILES := UserManual.qch UserManual.qhc
66	VBOX_ACCESSIBILITY_XML_FILES := Accessibility.xml
67	VBOX_MANUAL_LATEX_FILES_TARGET := $(addprefix UserManual.,aux log out toc tex)
68	VBOX_SDKREF_LATEX_FILES_TARGET := $(addprefix SDKRef.,aux log out toc tex)
69	VBOX_ACCESSIBILITY_LATEX_FILES_TARGET := $(addprefix Accessibility.,aux log out toc tex)
70
71	VBOX_MANUAL_TEX_UNICODE_FILES = $(wildcard $(VBOX_PATH_MANUAL_SRC)/texfiles/unicode/*)
72
73	# Wildcard the images path for every supported language
74	$(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES) \
75	,$(eval VBOX_MANUAL_PNG_FILES_$$(lang) := $$(patsubst $$(VBOX_PATH_MANUAL_SRC)/$$(lang)/%,%, \
76	$$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$$(lang)/images/*.png))))
77
78	# SDK related globals.
79	VBOX_MANUAL_APIREF_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef_apiref.xml
80	VBOX_DOC_XIDL_SRC = $(PATH_ROOT)/src/VBox/Main/idl/VirtualBox.xidl
81	VBOX_DOC_XIDL_SRC_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.xidl.tmp
82
83
84	#
85	# PDF LaTeX related globals.
86	#
87
88	VBOX_PDFLATEX_INTERACTION ?= batchmode
89	# VBOX_PDFLATEX_INTERACTION = errorstopmode - Use this when you wants to figure out build failures
90	# without catting the log a million times.
91	ifeq ($(KBUILD_HOST),win)
92	ifndef VBOX_PDFLATEX
93	VBOX_PDFLATEX := $(firstword $(rsort $(wildcard $(KBUILD_DEVTOOLS)/win.x86/miktex-portable/*/miktex/bin/pdflatex.exe)))
94	ifneq ($(VBOX_PDFLATEX),)
95	VBOX_PDFLATEX_CMD = $(VBOX_PDFLATEX) -halt-on-error -interaction $(VBOX_PDFLATEX_INTERACTION)
96	endif
97	endif
98	ifndef VBOX_PDFLATEX
99	# Tell MiKTeX to automatically download packages if system wide install.
100	VBOX_PDFLATEX := pdflatex
101	VBOX_PDFLATEX_CMD = $(VBOX_PDFLATEX) -halt-on-error -interaction $(VBOX_PDFLATEX_INTERACTION) --enable-installer
102	endif
103	else
104	VBOX_PDFLATEX ?= pdflatex
105	VBOX_PDFLATEX_HALT = $(shell ( $(VBOX_PDFLATEX) -version \| head -1 \| grep 141592 > /dev/null ) && echo -halt-on-error )
106	VBOX_PDFLATEX_CMD = pdflatex $(VBOX_PDFLATEX_HALT) -interaction $(VBOX_PDFLATEX_INTERACTION)
107	endif
108
109	#
110	# Java v17 or later (JAVA_HOME), used by DITA-OT.
111	#
112	ifeq ($(VBOX_JAVA17PLUS_HOME),)
113	if defined(VBOX_JAVA_VERSION) && $(VBOX_JAVA_VERSION) >= 170000 && "$(VBOX_JAVA_BIN_PATH)" != ""
114	VBOX_JAVA17PLUS_HOME := $(qabspath ,$(VBOX_JAVA_BIN_PATH)/..)
115	else
116	VBOX_JAVA17PLUS_HOME := $(firstfile \
117	$(rversortfiles $(qwildcard , $(KBUILD_DEVTOOLS_HST)/jdk/v1[789].* $(KBUILD_DEVTOOLS_HST)/jdk/v[2-9][0-9].* )) \
118	$(rversortfiles $(qwildcard ,$(KBUILD_DEVTOOLS_HST_ALT)/jdk/v1[789].* $(KBUILD_DEVTOOLS_HST_ALT)/jdk/v[2-9][0-9].* )) \
119	)
120	if "$(KBUILD_HOST)" == "darwin" && "$(VBOX_JAVA17PLUS_HOME)" != ""
121	VBOX_JAVA17PLUS_HOME := $(VBOX_JAVA17PLUS_HOME)/Contents/Home
122	endif
123	endif
124	endif
125
126	#
127	# DITA-OT related globals.
128	#
129	VBOX_DITA_TECHNICAL_CONTENT_DTD_PATH = $(VBOX_DITA_OT_PATH)/plugins/org.oasis-open.dita.v1_2/dtd/technicalContent/dtd
130
131	##
132	# Runs the dost.jar.
133	#
134	# @param 1 Additional kmk_redirect options.
135	# @param 2 Parameters for the invoker.
136	#
137	VBOX_DITA_RUN_DOST = $(REDIRECT_EXT) \
138	-E 'ANT_HOME=$(VBOX_DITA_OT_PATH)' \
139	-E 'DITA_DIR=$(VBOX_DITA_OT_PATH)' \
140	-E 'JAVA_HOME=$(VBOX_JAVA17PLUS_HOME)' \
141	-E 'CLASSPATH=$(VBOX_DITA_CLASSPATH)' \
142	$1 \
143	-- \
144	"$(VBOX_JAVA17PLUS_HOME)/bin/java" \
145	"-Djava.awt.headless=true" \
146	"-Dsun.io.useCanonCaches=true" \
147	"-Dant.home=$(VBOX_DITA_OT_PATH)" \
148	"-Ddita.dir=$(VBOX_DITA_OT_PATH)" \
149	org.apache.tools.ant.launch.Launcher \
150	-cp "$(VBOX_DITA_CLASSPATH)" \
151	-buildfile "$(VBOX_DITA_OT_PATH)/build.xml" \
152	-main "org.dita.dost.invoker.Main" \
153	--args.grammar.cache=yes \
154	--verbose \
155	$(if-expr defined(VBOX_DITA_DEBUG),"--clean.temp=no" "--debug",) \
156	$2
157
158	VBOX_DITA_CLASSPATH = \
159	$(subst $(SP),$(HOST_PATH_SEP),$(strip \
160	$(VBOX_DITA_OT_PATH)/lib/ant-launcher.jar \
161	$(VBOX_DITA_OT_PATH)/config \
162	$(VBOX_DITA_OT_PATH)/lib \
163	$(wildcard \
164	$(VBOX_DITA_OT_PATH)/lib/*.jar \
165	$(VBOX_DITA_OT_PATH)/plugins//lib/.jar)))
166
167
168	#
169	# Targets
170	#
171
172	BLDDIRS += $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/, $(VBOX_MANUAL_ALL_LANGUAGES))
173
174	ifdef VBOX_ONLY_DOCS
175	PACKING += $(PATH_STAGE_BIN)/VBoxDocumentation.zip
176	endif
177
178	BLDDIRS += \
179	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita \
180	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/topics \
181	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/topics/images \
182	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/topics/licensing \
183	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/topics/licensing/vbox-base \
184	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/topics/licensing/vbox-ext
185
186	BLDDIRS += \
187	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/, \
188	$(addsuffix /images, $(VBOX_MANUAL_ALL_LANGUAGES)) \
189	$(addsuffix /html-single, $(VBOX_MANUAL_ALL_LANGUAGES)) \
190	$(addsuffix /html-chunks, $(VBOX_MANUAL_ALL_LANGUAGES)) \
191	$(addsuffix /qhelp, $(VBOX_MANUAL_ALL_LANGUAGES)) \
192	$(addsuffix /qhelp/images, $(VBOX_MANUAL_ALL_LANGUAGES)) \
193	$(addsuffix /HTMLHelp, $(VBOX_MANUAL_ALL_LANGUAGES)) \
194	$(addsuffix /HTMLHelp/images, $(VBOX_MANUAL_ALL_LANGUAGES)) \
195	)
196
197	# Explicit cleaning has some overlap with default cleaning rules, since this
198	# Makefile is using very complex conditionals for selectively creating
199	# specific files, and not everyone remembers to use the same with "kmk clean".
200	OTHER_CLEAN += \
201	$(VBOX_XML_CATALOG) \
202	$(VBOX_XML_CATALOG_DOCBOOK) \
203	$(VBOX_XML_CATALOG_DITA) \
204	$(VBOX_XML_CATALOG_MANUAL) \
205	$(VBOX_XML_ENTITIES) \
206	$(foreach lang, $(VBOX_MANUAL_ALL_LANGUAGES) \
207	,$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/, \
208	$(VBOX_XML_XREF_TO_TEXT) \
209	$(VBOX_XML_XREF_TO_TEXT).cat \
210	$(addprefix user_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \
211	$(VBOX_MANUAL_XML_REFENTRY_FILES) \
212	$(patsubst man_%,%.1,$(basename $(VBOX_MANUAL_XML_REFENTRY_FILES))) \
213	man_VBoxHeadless.xml \
214	user_man_VBoxHeadless.xml \
215	man_vboximg-mount.xml \
216	user_man_vboximg-mount.xml \
217	isomakercmd-man.xml \
218	user_isomakercmd-man.xml \
219	$(VBOX_MANUAL_LATEX_FILES_TARGET) \
220	$(VBOX_MANUAL_PNG_FILES_$(lang)) \
221	$(notdir $(VBOX_MANUAL_TEX_UNICODE_FILES)) \
222	$(addprefix HTMLHelp/,$(VBOX_MANUAL_PNG_FILES_$(lang))) \
223	$(addprefix qhelp/, $(VBOX_MANUAL_PNG_FILES_$(lang))) \
224	html-single/UserManual.html \
225	$(addprefix qhelp/, UserManual.qhp UserManual.qhcp $(VBOX_QHELP_OUTPUT_FILES)) \
226	$(addprefix HTMLHelp/, index.html go01.html) \
227	$(addprefix qhelp/, index.html go01.html) \
228	$(addprefix html-chunks/, index.html go01.html) \
229	$(foreach n,01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 \
230	,html-chunks/ch$(n).html \
231	html-chunks/re$(n).html \
232	HTMLHelp/ch$(n).html \
233	HTMLHelp/re$(n).html \
234	$(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)) \
235	qhelp/ch$(n).html \
236	qhelp/re$(n).html \
237	$(foreach d2,0 1 2 3 4 5 6 7 8 9,$(foreach d1,0 1 2 3 4 5 6 7 8 9,qhelp/ch$(n)s$(d2)$(d1).html)) ) \
238	$(foreach n,a b c \
239	,html-chunks/ap$(n).html \
240	HTMLHelp/ap$(n).html \
241	$(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) \
242	qhelp/ap$(n).html \
243	$(foreach s,01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20,qhelp/ap$(n)s$(s).html) ) \
244	$(foreach n,01 02 03 04 05 \
245	,html-chunks/pr$(n).html \
246	HTMLHelp/pr$(n).html \
247	$(foreach s,01 02 03 04 05 06 07 08,HTMLHelp/pr$(n)s$(s).html) \
248	qhelp/pr$(n).html \
249	$(foreach s,01 02 03 04 05 06 07 08,qhelp/pr$(n)s$(s).html) ) \
250	HTMLHelp/toc.hhc \
251	HTMLHelp/htmlhelp.hhp \
252	qhelp/toc.hhc \
253	qhelp/htmlhelp.hhp \
254	UserManual.pdf \
255	$(VBOX_QHELP_OUTPUT_FILES) \
256	ChangeLog.html \
257	validatemanual.run \
258	validateaccessibility.run \
259	validatesdkref.run \
260	) \
261	) \
262	$(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl \
263	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/overview_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \
264	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf) \
265	$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_en_US) \
266	$(addsuffix .kmk,$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_en_US)) \
267	$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES2_en_US) \
268	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/RefEntryDITA.zip \
269	$(PATH_STAGE_BIN)/RefEntryDITA.zip \
270	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLogDITA.zip \
271	$(PATH_STAGE_BIN)/ChangeLogDITA.zip \
272	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip \
273	$(PATH_STAGE_BIN)/UserManual-html.zip \
274	$(PATH_STAGE_BIN)/UserManual.pdf \
275	$(PATH_STAGE_BIN)/VBoxDocumentation.zip \
276	\
277	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \
278	$(VBOX_SDKREF_LATEX_FILES_TARGET) \
279	SDKRef.pdf \
280	) \
281	$(PATH_STAGE_BIN)/sdk/docs/SDKRef.pdf \
282	\
283	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \
284	$(VBOX_ACCESSIBILITY_LATEX_FILES_TARGET) \
285	html-single/Accessibility.html \
286	Accessibility.pdf \
287	) \
288	$(PATH_STAGE_BIN)/Accessibility.html \
289	$(PATH_STAGE_BIN)/Accessibility.pdf \
290	\
291	$(VBOX_DOC_XIDL_SRC_TMP) \
292	$(VBOX_MANUAL_APIREF_TMP)
293
294
295	ifndef VBOX_ONLY_SDK
296	#
297	# target for installing UserManual.pdf
298	#
299	INSTALLS += VBox-docs-usermanual
300	VBox-docs-usermanual_INST = $(INST_BIN)
301	VBox-docs-usermanual_MODE = a+r,u+w
302	VBox-docs-usermanual_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.pdf
303	VBOX_MANUAL_PACK += $(PATH_STAGE_BIN)/UserManual.pdf
304
305	ifdef VBOX_WITH_DOCS_TRANSLATIONS
306	#
307	# target for installing translated UserManual_*.pdf
308	#
309	INSTALLS += VBox-docs-usermanual-l10n
310	VBox-docs-usermanual-l10n_INST = $(INST_BIN)
311	VBox-docs-usermanual-l10n_MODE = a+r,u+w
312	VBox-docs-usermanual-l10n_SOURCES = \
313	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$(f)/UserManual.pdf=>UserManual_$(f).pdf)
314	VBOX_MANUAL_PACK += $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf)
315	endif
316
317	ifdef VBOX_WITH_DOCS_HTML
318	#
319	# target for installing the chunked HTML docs
320	#
321	INSTALLS += VBox-docs-usermanual-html
322	VBox-docs-usermanual-html_INST = $(INST_BIN)
323	VBox-docs-usermanual-html_MODE = a+r,u+w
324	VBox-docs-usermanual-html_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip=>UserManual-html.zip
325	VBOX_MANUAL_PACK += $(PATH_STAGE_BIN)/UserManual-html.zip
326	endif
327
328	ifdef VBOX_WITH_DOCS_QHELP
329	#
330	# Installs the qhelp version of the manual.
331	#
332	INSTALLS += VBox-docs-usermanual-qhelp
333	VBox-docs-usermanual-qhelp_INST = $(INST_BIN)
334	VBox-docs-usermanual-qhelp_MODE = a+r,u+w
335	VBox-docs-usermanual-qhelp_SOURCES = \
336	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qhc \
337	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/UserManual.qch
338	ifdef VBOX_WITH_DOCS_QHELP_PACKING
339	VBOX_MANUAL_PACK += \
340	$(PATH_STAGE_BIN)/UserManual.qch \
341	$(PATH_STAGE_BIN)/UserManual.qhc
342	endif
343	endif
344
345	ifdef VBOX_WITH_DOCS_USERMANUAL_REFENTRY_DITA
346	#
347	# target for installing the ZIP containing the manpages in DITA format
348	#
349	INSTALLS += VBox-docs-usermanual-refentry-dita
350	VBox-docs-usermanual-refentry-dita_INST = $(INST_BIN)
351	VBox-docs-usermanual-refentry-dita_MODE = a+r,u+w
352	VBox-docs-usermanual-refentry-dita_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/RefEntryDITA.zip
353	VBOX_MANUAL_PACK += $(PATH_STAGE_BIN)/RefEntryDITA.zip
354	endif
355
356	ifdef VBOX_WITH_DOCS_USERMANUAL_CHANGELOG_DITA
357	#
358	# target for installing the ZIP containing the change log in DITA format
359	#
360	INSTALLS += VBox-docs-usermanual-changelog-dita
361	VBox-docs-usermanual-changelog-dita_INST = $(INST_BIN)
362	VBox-docs-usermanual-changelog-dita_MODE = a+r,u+w
363	VBox-docs-usermanual-changelog-dita_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLogDITA.zip
364	VBOX_MANUAL_PACK += $(PATH_STAGE_BIN)/ChangeLogDITA.zip
365	endif
366
367	ifdef VBOX_WITH_DOCS_ACCESSIBILITY
368	#
369	# target for installing Accessibility.pdf
370	#
371	INSTALLS += VBox-docs-accessibility
372	VBox-docs-accessibility_INST = $(INST_BIN)
373	VBox-docs-accessibility_MODE = a+r,u+w
374	VBox-docs-accessibility_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.pdf
375
376	#
377	# target for installing Accessibility.html
378	#
379	INSTALLS += VBox-docs-accessibility-html
380	VBox-docs-accessibility-html_INST = $(INST_BIN)
381	VBox-docs-accessibility-html_MODE = a+r,u+w
382	VBox-docs-accessibility-html_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html
383	endif
384
385	endif # !VBOX_ONLY_SDK
386
387	if defined(VBOX_ONLY_SDK) \|\| defined(VBOX_WITH_DOCS_SDKREF)
388	#
389	# target for installing SDKRef.pdf
390	#
391	INSTALLS += VBox-docs-sdkref
392	VBox-docs-sdkref_INST = $(INST_SDK)docs/
393	VBox-docs-sdkref_MODE = a+r,u+w
394	VBox-docs-sdkref_SOURCES = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.pdf
395	endif
396
397
398	#
399	# Shared rules for LaTeX based PDF generation - Only used for SDK & Accessibility.
400	#
401
402	ifndef VBOX_OSE
403	# Copy ucs.sty and associated files.
404	## @todo r=bird: This is ugly since only ucs.sty is listed as output while we're actually copying 177 other files.
405	$(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/ucs.sty): \| $$(dir $$@)
406	$(call MSG_L1,Copying unicode support for LaTeX)
407	$(QUIET)$(INSTALL_STAGING) -m0644 -- $(VBOX_MANUAL_TEX_UNICODE_FILES) "$(@D)"
408	endif
409
410	# Copy the PNG files.
411	define def_vbox_cp_images_pdf
412	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \
413	$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/% : \
414	$(VBOX_PATH_MANUAL_SRC)/$(lang)/% \| $$$$(dir $$$$@)
415	$$(call MSG_L1,Copying temporary $$< => $$@)
416	$$(QUIET)$$(INSTALL_STAGING) -m0644 -- '$$<' '$$(@D)'
417	endef
418	$(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(evalcall2 def_vbox_cp_images_pdf))
419
420
421	#################################################################################################################################
422	# SDKRef.pdf - xidl => Docbook => LaTeX => PDF #
423	#################################################################################################################################
424
425	VBOX_SDKREF_XML_FILES = SDKRef.xml
426
427	# Replace @a and @c with <tt> tags in VirtualBox.xidl.
428	$(VBOX_DOC_XIDL_SRC_TMP): $(VBOX_DOC_XIDL_SRC) $(MAKEFILE_CURRENT) \| $$(dir $$@)
429	$(call MSG_L1,Generating $@)
430	$(QUIET)$(SED) \
431	-e 's\|@a \+$\w\+$\|<tt>\1</tt>\|g' \
432	-e 's\|@c \+$\w\+$\|<tt>\1</tt>\|g' \
433	--output $@ $<
434
435	# Generate SDKRef_apiref.xml as a docbook file excerpt that will be referenced from the SDKRef.xml.
436	$(VBOX_MANUAL_APIREF_TMP): $(VBOX_PATH_MANUAL_SRC)/xidl2docbook.xsl $(VBOX_DOC_XIDL_SRC_TMP)
437	$(call MSG_L1,Generating $@)
438	$(QUIET)$(VBOX_XSLTPROC) $(VBOX_XSLTPROC_OPTS) --xinclude --nonet -o $@ $< $(VBOX_DOC_XIDL_SRC_TMP)
439
440	# Turn SDKRef.xml into LaTeX.
441	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex: \
442	$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_SDKREF_XML_FILES)) \
443	$(VBOX_MANUAL_APIREF_TMP) \
444	$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \
445	$(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run,) \
446	$(VBOX_XML_ALL_CATALOGS_DEP) \
447	$(VBOX_XML_ENTITIES) \
448	$(MAKEFILE_CURRENT) \
449	\| $$(dir $$@)
450	$(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@)
451	$(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_SDKREF_LATEX_FILES_TARGET))
452	# generate TeX source from processed docbook and store it in SDKRef.tex.tmp
453	$(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG en_US \
454	-o $@.tmp $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $<
455	# for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word;
456	# the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections
457	$(QUIET)$(SED) \
458	-e 's\|^\\QUOTE{}\|\\OQ{}\|g' \
459	-e 's\|$\W$\\QUOTE{}\|\1\\OQ{}\|g' \
460	-e 's\|$\w$\\QUOTE{}\|\1\\CQ{}\|g' \
461	--output $@ $@.tmp
462	$(QUIET)$(RM) -f $@.tmp
463
464	# Turn SDKRef.tex into a PDF.
465	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.pdf: \
466	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex \
467	$(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ucs.sty) \
468	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \
469	\| $$(dir $$@)
470	$(call MSG_L1,pdflatex $< (three passes))
471	$(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) SDKRef.tex
472	$(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) SDKRef.tex
473	$(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) SDKRef.tex
474	$(QUIET)$(SED) -ne '/Warning: Hyper reference/p' $(basename $<).log
475	$(QUIET)$(SED) -n \
476	-e '/Warning: There were $undefined references\\|multiply-defined labels$/{p; q 1}' \
477	$(basename $<).log
478	$(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)
479
480	# Validating SDKRef.xml. It is invoked automatically at build time,
481	# but can also be manually invoked via the 'validate-sdkref' alias.
482	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run: \
483	$(VBOX_PATH_MANUAL_SRC)/en_US/SDKRef.xml \
484	$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_SDKREF_XML_FILES)) \
485	$(VBOX_MANUAL_APIREF_TMP) \
486	$(VBOX_XML_ALL_CATALOGS_DEP) \
487	$(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) \| $$(dir $$@)
488	$(call MSG_L1,Validating $<)
489	$(QUIET)$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $<
490	$(QUIET)$(APPEND) -t "$@" "done"
491
492
493	# Handy aliases.
494	validate-sdkref:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run
495	sdkref:: $(PATH_STAGE_BIN)/sdk/docs/SDKRef.pdf
496
497
498	#################################################################################################################################
499	# Accessibility.pdf - Docbook => LaTeX => PDF #
500	#################################################################################################################################
501
502	# Turn Accessibility.xml into LaTeX.
503	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.tex: \
504	$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \
505	$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \
506	$(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run,) \
507	$(VBOX_XML_ALL_CATALOGS_DEP) \
508	$(VBOX_XML_ENTITIES) \
509	$(MAKEFILE_CURRENT) \
510	\| $$(dir $$@)
511	$(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@)
512	$(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_ACCESSIBILITY_LATEX_FILES_TARGET))
513	# generate TeX source from processed docbook and store it in Accessibility.tex.tmp
514	$(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG en_US \
515	-o $@.tmp $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $<
516	# for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word;
517	# the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections
518	$(QUIET)$(SED) \
519	-e 's\|^\\QUOTE{}\|\\OQ{}\|g' \
520	-e 's\|$\W$\\QUOTE{}\|\1\\OQ{}\|g' \
521	-e 's\|$\w$\\QUOTE{}\|\1\\CQ{}\|g' \
522	--output $@ $@.tmp
523	$(QUIET)$(RM) -f $@.tmp
524
525	# Turn Accessibility.tex into a PDF.
526	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.pdf: \
527	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.tex \
528	$(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ucs.sty) \
529	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US))
530	$(call MSG_L1,pdflatex $< (three passes))
531	$(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) Accessibility.tex
532	$(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) Accessibility.tex
533	$(QUIET)$(REDIRECT) -C $(<D) -- $(VBOX_PDFLATEX_CMD) Accessibility.tex
534	$(QUIET)$(SED) -ne '/Warning: Hyper reference/p' $(basename $<).log
535	$(QUIET)$(SED) -n \
536	-e '/Warning: There were $undefined references\\|multiply-defined labels$/{p; q 1}' \
537	$(basename $<).log
538	$(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)
539
540	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html: \
541	$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \
542	$(VBOX_DOCBOOK_HTML_ONE_PAGE_FORMATCFG) \
543	$(VBOX_XML_ALL_CATALOGS_DEP) \
544	$(VBOX_XML_ENTITIES) \| $$(dir $$@)
545	$(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@)
546	$(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) \
547	--output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html \
548	$(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-formatcfg.xsl \
549	$<
550
551	# Validating Accessibility.xml. It is invoked automatically at build time,
552	# but can also be manually invoked via the 'validate-accessibility' alias.
553	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run: \
554	$(VBOX_PATH_MANUAL_SRC)/en_US/Accessibility.xml \
555	$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \
556	$(VBOX_XML_ALL_CATALOGS_DEP) \
557	$(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) \| $$(dir $$@)
558	$(call MSG_L1,Validating $<)
559	$(QUIET)$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $<
560	$(QUIET)$(APPEND) -t "$@" "done"
561
562
563	# Handy aliases.
564	validate-accessibility:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run
565	accessibility:: $(PATH_STAGE_BIN)/Accessibility.pdf
566	accessibility-html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html
567
568
569	#################################################################################################################################
570	# UserManual.* - The user manual in all its output variations (DITA-OT). #
571	#################################################################################################################################
572
573	#
574	# 1. We copy/hardlink all the files under <lang>/dita/* to the corresponding
575	# VBOX_PATH_MANUAL_OUTBASE location. This is mainly to deal with DITO-OT's
576	# inability to search for topic files in more than one place, so we have to
577	# gather generated and static topic sources + the .ditamap-file(s) in one
578	# place.
579	#
580
581	# Determine the basic set of files as dictated by the en_US version of the
582	# user manual (relative to $(lang)/dita). We'll use these to supply
583	# incomplete manual translations.
584	# Note! This includes .png as well as .dita and .ditamap files.
585	VBOX_USER_MANUAL_DITA_BASIC_SRC_FILES := \
586	$(notdir $(wildcard $(VBOX_PATH_MANUAL_SRC)/en_US/dita/.dita)) \
587	$(addprefix topics/,$(notdir $(wildcard $(VBOX_PATH_MANUAL_SRC)/en_US/dita/topics/*dita))) \
588	$(addprefix topics/images/,$(notdir $(wildcard $(VBOX_PATH_MANUAL_SRC)/en_US/dita/topics/images/*png))) \
589	$(addprefix topics/licensing/,$(notdir $(wildcard $(VBOX_PATH_MANUAL_SRC)/en_US/dita/topics/licensing/dita))) \
590	$(addprefix topics/licensing/vbox-base/,$(notdir $(wildcard $(VBOX_PATH_MANUAL_SRC)/en_US/dita/topics/licensing/vbox-base/*dita))) \
591	$(addprefix topics/licensing/vbox-ext/,$(notdir $(wildcard $(VBOX_PATH_MANUAL_SRC)/en_US/dita/topics/licensing/vbox-ext/*dita)))
592
593	##
594	# Produce copying rules for one language and defining the variable
595	# VBOX_USER_MANUAL_DITA_STAGED_FILES_<lang> for use in prerequisite to
596	# anything producing a version of the user manual.
597	#
598	# @param 1 lang
599	define def_vbox_copy_manual_dita_src_files
600	VBOX_USER_MANUAL_DITA_SRC_FILES_$(1) := \
601	$$(notdir $$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$1/dita/*.ditamap)) \
602	$$(addprefix topics/,$$(notdir $$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$1/dita/topics/*dita))) \
603	$$(addprefix topics/images/,$$(notdir $$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$1/dita/topics/images/*png))) \
604	$$(addprefix topics/licensing/,$$(notdir $$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$1/dita/topics/licensing/dita))) \
605	$$(addprefix topics/licensing/vbox-base/,$$(notdir $$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$1/dita/topics/licensing/vbox-base/*dita))) \
606	$$(addprefix topics/licensing/vbox-ext/,$$(notdir $$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$1/dita/topics/licensing/vbox-ext/*dita)))
607	VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)_FALLBACK := \
608	$$(filter-out $$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)), $$(VBOX_USER_MANUAL_DITA_BASIC_SRC_FILES))
609
610	VBOX_USER_MANUAL_DITA_STAGED_FILES_$(1) = \
611	$$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/, \
612	$$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)) \
613	$$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)_FALLBACK) )
614
615	ifneq ($$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)),)
616	$$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/,$$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1))): \
617	$$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/% : \
618	$$(VBOX_PATH_MANUAL_SRC)/$1/dita/% \| $$$$(dir $$$$@)
619	$$(QUIET)$$(INSTALL_STAGING) -m 0644 -- "$$<" "$$(@D)/"
620	endif
621
622	ifneq ($$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)_FALLBACK),)
623	$$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/,$$(VBOX_USER_MANUAL_DITA_SRC_FILES_$(1)_FALLBACK)): \
624	$$(VBOX_PATH_MANUAL_OUTBASE)/$1/dita/% : \
625	$$(VBOX_PATH_MANUAL_SRC)/en_US/dita/% \| $$$$(dir $$$$@)
626	$$(QUIET)$$(INSTALL_STAGING) -m 0644 -- "$$<" "$$(@D)/"
627	endif
628
629	endef
630	$(foreach lang, $(VBOX_MANUAL_ALL_LANGUAGES),$(evalcall2 def_vbox_copy_manual_dita_src_files,$(lang)))
631
632
633	#
634	# 2. Convert the manpages from Docbook refentry files to DITA reference files.
635	#
636	# In DITA links needs proper href values, with both file and ID. Since the
637	# source only has IDs, we scan all topics and refentry-files alike and
638	# generate a mapping database before we start converting them. This DB is
639	# then used at the end of each conversion to fix the hrefs.
640	#
641
642	##
643	# Do per-language stuff for the refentry -> dita file conversion.
644	#
645	# The variable VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_<lang> is defined
646	# by this define and should be expanded as a prerequisite for any rule
647	# producing a version of the user manual.
648	#
649	# @param 1 Language.
650	#
651	define def_vbox_refentry_to_dita
652	# Generate a ID to FILE mapping database that def_vbox_refentry_to_dita can apply below.
653	VBOX_USER_MANUAL_ID_MAPPING_FILE_$(1) := $$(VBOX_PATH_MANUAL_OUTBASE)/$1/id-mapping-file.db
654	OTHER_CLEAN += $(VBOX_USER_MANUAL_ID_MAPPING_FILE_$(1))
655	$$(VBOX_USER_MANUAL_ID_MAPPING_FILE_$(1)) + $$(VBOX_USER_MANUAL_ID_MAPPING_FILE_$(1)).lst: \
656	$$(VBOX_PATH_MANUAL_SRC)/build_id_to_file_mapping.py \
657	$$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$1/*.xml) \
658	$$(filter %.dita,$$(VBOX_USER_MANUAL_DITA_STAGED_FILES_$(1))) \
659	\| $$$$(dir $$$$@)
660	$$(call MSG_L1, $$<)
661	$$(QUIET)$$(APPEND) -nt "$$@.lst" $$(filter-out %.py,$$^)
662	$$(QUIET)$$(VBOX_BLD_PYTHON) "$$<" --output "$$@" @"$$@.lst"
663
664	# Accumulated list of conversion output file names to be used as a
665	# prerequisite in rules producing a version of the user manual.
666	VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$1 :=
667
668	endef # def_vbox_refentry_to_dita
669
670	## Convert a single refentry file to dita.
671	# @param 1 Language
672	# @param 2 Filename w/o extension.
673	# @param 3 Alternative fallback filename (for isomakercmd-man.xml).
674	# @note This produces more files than listed in the output, but we currently let kmk be ignorant of that.
675	define def_vbox_refentry_file_to_dita
676	VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$1 += $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).ditamap
677	$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).ditamap \
678	+ $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).ditamap.kmk \
679	+ $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).dita \
680	+ $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).xml: \
681	$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-dita-pre.xsl \
682	$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-dita.xsl \
683	$$(VBOX_PATH_MANUAL_SRC)/dita-refentry-flat-to-single-topic.sh \
684	$$(VBOX_PATH_MANUAL_SRC)/dita-refentry-flat-to-single-topic.xsl \
685	$$(VBOX_PATH_MANUAL_SRC)/dita-refentry-flat-topic-ids.xsl \
686	$$(VBOX_PATH_MANUAL_SRC)/add_file_to_id_only_references.py \
687	$$(VBOX_USER_MANUAL_ID_MAPPING_FILE_$1) \
688	$$(qfirstfile , $$(qwildcard , $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2).xml) $(3) $$(VBOX_PATH_MANUAL_SRC)/en_US/$(2).xml) \
689	$$(VBOX_XML_ALL_CATALOGS_DEP) \
690	$$(VBOX_XML_ENTITIES) \
691	$$(VBOX_VERSION_STAMP) \
692	\| $$$$(dir $$$$@)
693	$$(call MSG_TOOL,xsltproc docbook-refentry-to-manual-dita[-pre].xsl,,$$(firstword $$(filter %.xml,$$^)),$$@)
694	$$(QUIET)$$(RM) -f -- "$$@" \
695	"$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).xml" \
696	"$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).dita"
697	$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) \
698	--output "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).xml" \
699	$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-dita-pre.xsl \
700	$$(qfirstfile , $$(qwildcard , $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2).xml) $(3) $$(VBOX_PATH_MANUAL_SRC)/en_US/$(2).xml)
701	$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) \
702	--stringparam "g_fReplaceHyphens" "true" \
703	--output "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).dita" \
704	$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-dita.xsl \
705	"$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).xml"
706	$$(QUIET)$$(VBOX_BLD_PYTHON) $$(VBOX_PATH_MANUAL_SRC)/add_file_to_id_only_references.py \
707	--mapping-file "$$(VBOX_USER_MANUAL_ID_MAPPING_FILE_$1)" \
708	"$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).dita"
709	$$(QUIET)$$(ASH) \
710	"$$(VBOX_PATH_MANUAL_SRC)/dita-refentry-flat-to-single-topic.sh" \
711	"$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).dita" \
712	"$$(VBOX_PATH_MANUAL_SRC)/dita-refentry-flat-topic-ids.xsl" \
713	"$$(VBOX_PATH_MANUAL_SRC)/dita-refentry-flat-to-single-topic.xsl" \
714	"$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).ditamap.kmk" \
715	"VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES2_$(1)" \
716	"$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics" \
717	-- $$(subst $$(REDIRECT),$$(REDIRECT_EXT),$$(call VBOX_XSLTPROC_WITH_CAT)) $(VBOX_XSLTPROC_WORKAROUND) \
718	--path "$$(VBOX_DITA_TECHNICAL_CONTENT_DTD_PATH)"
719	$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) $(VBOX_XSLTPROC_WORKAROUND) \
720	--path "$$(VBOX_DITA_TECHNICAL_CONTENT_DTD_PATH)" \
721	--stringparam g_sMode map \
722	--output "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/$(2).ditamap" \
723	$$(VBOX_PATH_MANUAL_SRC)/dita-refentry-flat-to-single-topic.xsl \
724	"$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/flat-$(2).dita"
725
726	endef # def_vbox_refentry_file_to_dita
727
728	$(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES) \
729	,$(evalcall2 def_vbox_refentry_to_dita,$(lang)) \
730	$(foreach file, $(basename $(VBOX_MANUAL_XML_REFENTRY_FILES) man_vboximg-mount man_VBoxHeadless) \
731	,$(evalcall2 def_vbox_refentry_file_to_dita,$(lang),$(file))) \
732	$(evalcall2 def_vbox_refentry_file_to_dita,$(lang),user_isomakercmd-man, \
733	$(PATH_ROOT)/src/VBox/Runtime/common/fs/isomakercmd-man.xml))
734
735	ifdef VBOX_ONLY_DOCS
736	include $(VBOX_PATH_MANUAL_OUTBASE)/refentry.kmk
737
738	$(VBOX_PATH_MANUAL_OUTBASE)/refentry.kmk: \
739	$(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES) \
740	,$(VBOX_PATH_MANUAL_OUTBASE)/refentry_$(lang).kmk)
741	$(QUIET)$(RM) -f -- "$@"
742	$(APPEND) -tn "$@" '# refentry.kmk'
743	$(APPEND) -n "$@" $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),'include $(VBOX_PATH_MANUAL_OUTBASE)/refentry_$(lang).kmk')
744	$(APPEND) -n "$@" '# done'
745
746	## Include file for all language specific refentry files.
747	# @param 1 Language
748	define def_vbox_refentry_lang_kmk
749	$$(VBOX_PATH_MANUAL_OUTBASE)/refentry_$(1).kmk: \
750	$$(addsuffix .kmk,$$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$(1)))
751	$$(QUIET)$$(RM) -f -- "$$@"
752	$$(APPEND) -tn "$$@" '# refentry_$(1).kmk'
753	$$(APPEND) -n "$$@" $$(addprefix 'include ,$$(addsuffix .kmk',$$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$(1))))
754	$$(APPEND) -n "$$@" '# done'
755
756	endef # def_vbox_refentry_lang_kmk
757
758	$(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES) \
759	,$(evalcall2 def_vbox_refentry_lang_kmk,$(lang)))
760	endif
761
762	# Run conversion testcase.
763	refentry-to-dita-test:
764	$(RM) -f -- \
765	"$(VBOX_PATH_MANUAL_OUTBASE)/testcase-refentry1.xml" \
766	"$(VBOX_PATH_MANUAL_OUTBASE)/testcase-refentry1.dita"
767	$(call VBOX_XSLTPROC_WITH_CAT) \
768	--output "$(VBOX_PATH_MANUAL_OUTBASE)/testcase-refentry1.xml" \
769	$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-dita-pre.xsl \
770	$(VBOX_PATH_MANUAL_SRC)/testcase/refentry1.xml
771	$(call VBOX_XSLTPROC_WITH_CAT) \
772	--output "$(VBOX_PATH_MANUAL_OUTBASE)/testcase-refentry1.dita" \
773	$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-dita.xsl \
774	"$(VBOX_PATH_MANUAL_OUTBASE)/testcase-refentry1.xml"
775
776	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/RefEntryDITA.zip: \
777	$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_en_US) \
778	$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES2_en_US) \
779	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/topics/vboxmanage-cmd-overview.dita
780	$(call MSG_L1,Packing documentation $@)
781	$(QUIET)$(RM) -f $@
782	$(QUIET)$(REDIRECT) -C $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ -- $(VBOX_ZIP) \
783	-9 -r "$@" \
784	$(patsubst $(VBOX_PATH_MANUAL_OUTBASE)/en_US/%,%,$^)
785
786	refentry-dita-zip:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/RefEntryDITA.zip
787
788	#
789	# 2b. Generate the VBoxManage commands overview topic based upon the
790	# command synopis dita files generated in the above step.
791	#
792
793	# @param 1 Language
794	define def_vbox_generate_vboxmanage_overview
795	VBOX_USER_MANUAL_DITA_STAGED_FILES_$1 += $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/vboxmanage-cmd-overview.dita
796	$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/vboxmanage-cmd-overview.dita \
797	+ $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/vboxmanage-cmd-overview.dita.files.xml: \
798	$$(VBOX_PATH_MANUAL_SRC)/$(1)/vboxmanage-cmd-overview.xsl \
799	$$(VBOX_PATH_MANUAL_SRC)/vboxmanage-cmd-overview.xsl \
800	$$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$(1)) \
801	\| $$$$(dir $$$$@)
802	$$(call MSG_TOOL,xsltproc vboxmanage-cmd-overview.dita.xsl,,,$$@)
803	$$(QUIET)$$(RM) -f -- "$$@" "$$@.files.xml"
804	$$(APPEND) -tn "$$@.files.xml" '<?xml version="1.0"?>' '<files>'
805	$$(SED) -n \
806	-e 's/^.topicref .topics\/man_VBoxManage-$[^.]$\.ditamap.$$(DOLLAR)/<file>vboxmanage-\1-synopsis.dita<\/file>/p' \
807	--append "$$@.files.xml" \
808	$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/UserManual.ditamap
809	$$(APPEND) -n "$$@.files.xml" '</files>'
810	$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) $(VBOX_XSLTPROC_WORKAROUND) --path "$$(VBOX_DITA_TECHNICAL_CONTENT_DTD_PATH)" \
811	--output "$$@" \
812	$$(VBOX_PATH_MANUAL_SRC)/$(1)/vboxmanage-cmd-overview.xsl \
813	"$$@.files.xml"
814
815	endef # def_vbox_generate_vboxmanage_overview
816	$(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(evalcall2 def_vbox_generate_vboxmanage_overview,$(lang)))
817
818
819	#
820	# 3. Convert the changelog from DocBook to a bunch of DITA topics and corresponding map.
821	#
822
823	##
824	# @param 1 Language
825	# @note We don't really need to do this for each language, but whatever.
826	# @note Outputs a bunch of .dita files for each version too...
827	define def_vbox_convert_changelog_to_dita
828	VBOX_USER_MANUAL_DITA_STAGED_FILES_$1 += $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/changelog-versions.ditamap
829	$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/changelog-versions.ditamap \
830	+ $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics/changelog-versions.ditamap.kmk: \
831	$$(VBOX_PATH_MANUAL_SRC)/docbook-changelog-to-manual-dita.sh \
832	$$(VBOX_PATH_MANUAL_SRC)/docbook-changelog-to-manual-dita.xsl \
833	$$(VBOX_XML_ALL_CATALOGS_DEP) \
834	\| $$$$(dir $$$$@)
835	$$(call MSG_TOOL,xsltproc docbook-changelog-to-manual-dita.xsl,,,$$@)
836	$$(QUIET)$$(RM) -f -- "$$@" "$$@.files.xml"
837	$$(QUIET)$$(ASH) \
838	$$(VBOX_PATH_MANUAL_SRC)/docbook-changelog-to-manual-dita.sh \
839	$$(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml \
840	$$(VBOX_PATH_MANUAL_SRC)/docbook-changelog-to-manual-dita.xsl \
841	$$(@).kmk \
842	VBOX_USER_MANUAL_CONVERTED_CHANGELOG_DITA_FILES_$(1) \
843	$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/topics \
844	-- \
845	$$(call VBOX_XSLTPROC_WITH_CAT)
846	endef # def_vbox_convert_changelog_to_dita
847	$(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(evalcall2 def_vbox_convert_changelog_to_dita,$(lang)))
848
849	ifdef VBOX_ONLY_DOCS
850	include $(VBOX_PATH_MANUAL_OUTBASE)/changelog.kmk
851
852	$(VBOX_PATH_MANUAL_OUTBASE)/changelog.kmk: \
853	$(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES) \
854	,$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/dita/topics/changelog-versions.ditamap.kmk)
855	$(QUIET)$(RM) -f -- "$@"
856	$(APPEND) -tn "$@" '# changelog.kmk'
857	$(APPEND) -n "$@" $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),'include $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/dita/topics/changelog-versions.ditamap.kmk')
858	$(APPEND) -n "$@" '# done'
859
860	endif
861
862	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLogDITA.zip: \
863	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/topics/changelog-versions.ditamap \
864	$(VBOX_USER_MANUAL_CONVERTED_CHANGELOG_DITA_FILES_en_US)
865	$(call MSG_L1,Packing documentation $@)
866	$(QUIET)$(RM) -f $@
867	$(QUIET)$(REDIRECT) -C $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ -- $(VBOX_ZIP) \
868	-9 -r "$@" \
869	$(patsubst $(VBOX_PATH_MANUAL_OUTBASE)/en_US/%,%,$^)
870
871	changelog-dita-zip:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLogDITA.zip
872
873
874	#
875	# 4a. UserManual.pdf - Run dost.jar from DITA-OT to produce the PDF version.
876	#
877	# Note! The --temp (dir) is deleted, recreated, used and deleted again for each
878	# run. So, be careful where you point it.
879	# Note! This crappy utility may fail to find files (or fail to parse the
880	# command line) and still return a successfully (0) exit code.
881	#
882	define def_ditamap_to_pdf
883	$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/UserManual.pdf \
884	+ $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/UserManual_pdf.log \
885	+\| $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita.list \
886	+\| $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita.xml.properties: \
887	$$(VBOX_MANUAL_XML_FILES_COMMON) \
888	$$(VBOX_MANUAL_XML_FILES_GENERATED_$(lang)) \
889	$$(VBOX_USER_MANUAL_DITA_STAGED_FILES_$(lang)) \
890	$$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$(lang)) \
891	$$(VBOX_PATH_MANUAL_SRC)/pdf-theme-UserManual.yaml \
892	$$(VBOX_PATH_MANUAL_SRC)/en_US/images/vboxlogo.png
893	$$(call MSG_L1,Building $$@ ($$(@D)/UserManual_pdf.log))
894	$$(QUIET)$$(RM) -f -- "$$@"
895	$$(QUIET)$$(RM) -Rf -- "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/temp_pdf"
896	$$(QUIET)$$(call VBOX_DITA_RUN_DOST,, \
897	"--input=$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/UserManual.ditamap" \
898	"--format=pdf" \
899	"--filter=$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/ohc.ditaval" \
900	"--output=$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)" \
901	"--temp=$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/temp_pdf" \
902	"--theme=$$(VBOX_PATH_MANUAL_SRC)/pdf-theme-UserManual.yaml" \
903	"--logfile=$$(@D)/UserManual_pdf.log" \
904	)
905
906	ditamap-to-pdf: $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/UserManual.pdf
907	.PRECIOUS: $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/UserManual_pdf.log
908	endef
909	$(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(evalcall2 def_ditamap_to_pdf,$(lang)))
910
911	# Useful aliases
912	usermanual UserManual.pdf:: $(PATH_STAGE_BIN)/UserManual.pdf
913
914
915	#
916	# 4b. UserManual.html - Run dost.jar from DITA-OT to produce the HTML versions.
917	#
918	# We produce both chunked and singled paged HTML versions of the en_US manual
919	# mainly for uploading to virtualbox.org. The docs build box produces a zip
920	# including these.
921	#
922
923	## @todo front page
924	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html: \
925	$(VBOX_USER_MANUAL_DITA_STAGED_FILES_en_US) \
926	$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_en_US)
927	$(QUIET)$(RM) -Rf -- "$(@D)" \
928	"$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/temp_xhtml_chunks"
929	$(call MSG_L1,Building html chunks $@ ($(@D)/UserManual_xhtml.log))
930	$(QUIET)$(MKDIR) -- "$(@D)"
931	$(QUIET)$(call VBOX_DITA_RUN_DOST,, \
932	"--input=$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/UserManual.ditamap" \
933	"--format=xhtml" \
934	"--filter=$(VBOX_PATH_MANUAL_SRC)/en_US/dita/htmlhelp.ditaval" \
935	"--output=$(@D)" \
936	"--temp=$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/temp_xhtml_chunks" \
937	"--logfile=$(@D)/UserManual_xhtml.log" \
938	"--store-type=memory" \
939	)
940
941	html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html
942
943	# We must modify UserManual.ditamap here, removing all chunk attributes and put
944	# a chunk="to-content" on the root element (bookmap). For clues see:
945	# https://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/chunking.html
946	# https://www.oxygenxml.com/forum/post25114.html?hilit=dita%20xhtml%20chunk#p25114
947	# We stich the index.html and UserManual-Single.html files together using
948	# SED since we haven't been able to convince DITA-OT to combine them.
949	#
950	## @todo This is excruciatingly slow with 4.0.2 because of a preprocessing step
951	# (move-meta in the org.dita.base plugin) is doing 986 read+writes of
952	# the singled combined dita document (XML). This is probably the two
953	# for loops in the pushMetadata() method in
954	# src/main/java/org/dita/dost/module/MoveMetaModule.java. The netbeans
955	# profiler says that ouf 283 sec runtime, 64 secs are spent reading
956	# the xml big doc and 212 secs spent writing it out again (212+64=276).
957	#
958	# For the chunked version, the move-meta work is done on each .ditamap
959	# and .dita (topic) file instead, which is a lot less expensive.
960	#
961	# The problem is forced by the AbstractDomFilter.read() design, which
962	# reads XML to DOM, modifies DOM, writes out DOM as XML. The
963	# modifications done by the DitaMetaWriter.process function is
964	# restricted to a single topic, which is means this must be done this
965	# way.
966	#
967	# A workaround, though, would be to implement a custom cache that
968	# cache the document and doesn't write it to disk until the loops
969	# finishes. This could build on the CacheStore.java code, only
970	# potential challenge is to clone the job as the Job.store property is
971	# immutable.
972	#
973	## @todo front page
974	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html: \
975	$(VBOX_USER_MANUAL_DITA_STAGED_FILES_en_US) \
976	$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_en_US)
977	$(call MSG_L1,Building html chunks $@ ($(@D)/UserManual-Single_xhtml.log))
978	$(QUIET)$(RM) -Rf -- "$(@D)" \
979	"$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita-ot-html-single/" \
980	"$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/UserManual-Single.ditamap"
981	$(SED) -r -e 's/ chunk=["][^"]+["]//g' -e 's/<bookmap /<bookmap chunk="to-content" /' \
982	--output "$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/UserManual-Single.ditamap" \
983	"$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/UserManual.ditamap"
984	$(QUIET)$(MKDIR) -- "$(@D)"
985	$(QUIET)$(call VBOX_DITA_RUN_DOST,, \
986	"--input=$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/UserManual-Single.ditamap" \
987	"--format=xhtml" \
988	"--output=$(@D)" \
989	"--temp=$(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/temp_xhtml_single" \
990	"--logfile=$(@D)/UserManual-Single_xhtml.log" \
991	"--store-type=memory" \
992	)
993	$(SED) -ne '1,/<body>/{p}' \
994	--output "$@" "$(@D)/UserManual-Single.html"
995	$(APPEND) -n "$@" "<!-- index inject: -->"
996	$(SED) -ne '/<body>/,/<\/body>/{/<body>/d;/<\/body>/d;s/UserManual-Single.html/UserManual.html/g;p}' \
997	--append "$@" "$(@D)/index.html"
998	$(APPEND) -n "$@" "<!-- resuming main file: -->"
999	$(SED) -ne '/<body>/,99999999{/<body>/d;s/UserManual-Single.html/UserManual.html/g;p}' \
1000	--append "$@" "$(@D)/UserManual-Single.html"
1001
1002	html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html
1003
1004	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip: \
1005	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html \
1006	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html
1007	$(call MSG_L1,Packing documentation $@)
1008	$(QUIET)$(RM) -f $@
1009	$(QUIET)$(REDIRECT) -C $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ -- $(VBOX_ZIP) \
1010	-9 -r "$@" \
1011	"html-chunks" \
1012	"html-single" \
1013	-x "html-chunks/dita.list" \
1014	-x "html-chunks/dita.xml.properties" \
1015	-x "html-chunks/UserManual_xhtml.log" \
1016	-x "html-single/dita.list" \
1017	-x "html-single/dita.xml.properties" \
1018	-x "html-single/UserManual-Single_xhtml.log" \
1019	-x "html-single/index.html" \
1020	-x "html-single/UserManual-Single.html"
1021
1022	html-zip:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip
1023
1024
1025	#
1026	# A few things which are shared between htmlhelp and qhelp docs.
1027	# TODO: This is Docbook related work. Left here in case we can reuse some of
1028	# the ideas from it for DITA-OT.
1029	#
1030
1031	VBOX_DOCBOOK_HTMLHELP_FORMATCFG = \
1032	$(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl \
1033	$(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl \
1034	$(VBOX_PATH_MANUAL_SRC)/common-html-formatcfg.xsl
1035
1036	# Prepare the XSL file for our title page, htmlhelp and qhelp variant.
1037	$(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl: \
1038	$(VBOX_PATH_MANUAL_SRC)/titlepage-htmlhelp.xml $(MAKEFILE_CURRENT) \| $$(dir $$@)
1039	$(call MSG_L1,xsltproc $<)
1040	$(QUIET)$(RM) -f $@.tmp $@
1041	$(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet -o $@.tmp $(VBOX_PATH_DOCBOOK)/template/titlepage.xsl $<
1042	$(QUIET)$(MV) -f $@.tmp $@
1043
1044	# end old stuff.
1045
1046	if defined(VBOX_WITH_DOCS_QHELP) && !defined(VBOX_ONLY_SDK)
1047	#
1048	# 4c. VirtualBox.qch + VirtualBox.qhc - Qt compressed help and collection file.
1049	#
1050	# See usermanual.pdf under DITA-OT-xxxxx/doc folder for details.
1051	#
1052
1053	# Enable Qt and locate the Qt help generator.
1054	USES += qt6
1055	VBOX_QHELPGENERATOR = $(PATH_TOOL_QT6_LIBEXEC)/qhelpgenerator
1056
1057	## Build QHelp version of manual for given language.
1058	# @param 1 Language
1059	# @param 2 The language specific qhelp output directory.
1060	define def_vbox_usermanual_as_qhelp
1061
1062	# 1. Generate UserManual.hpp using DITA-OT.
1063	#
1064	# Setting HHCDIR here so that it fails to locate hcc.exe and always skips the
1065	# compilation step that produces the .chm-file, since we don't need it and it
1066	# mangles the path so it always fails anyway.
1067	#
1068	# HACK ALERT! Putting MSG_L1 between RM and MKDIR as the latter sometimes fails
1069	# on windows because the deleted directory still exists on Windows.
1070	#
1071	# HACK ALERT! For 4.0.2 we must set Ant property dita.output.dir to the output
1072	# dir to prevent the .hhp+.html+*.png files from being placed in
1073	# the temporary directory and removed upon completion (idea being
1074	# that hhc.exe had run and the files weren't needed any more - the
1075	# htmlhelp plugin sets temp.output.dir.name to 'temp_chm_dir').
1076	#
1077	## @todo front page.
1078	$(2)/UserManual.hhp: \
1079	$(VBOX_USER_MANUAL_DITA_STAGED_FILES_$(1)) \
1080	$(VBOX_USER_MANUAL_CONVERTED_REFENTRY_DITA_FILES_$(1))
1081	$$(QUIET)$$(RM) -Rf -- "$$(@D)" \
1082	"$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/temp_qhelp"
1083	$$(call MSG_L1,dita-ot-qhelp, => $$@ ($(2)/UserManual_htmlhelp.log))
1084	$$(QUIET)$$(MKDIR) -- "$$(@D)"
1085	$$(QUIET)$$(call VBOX_DITA_RUN_DOST, -EHHCDIR="$$(@D)", \
1086	"--input=$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/UserManual.ditamap" \
1087	"--format=htmlhelp" \
1088	"--filter=$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/htmlhelp.ditaval" \
1089	"--output=$(2)" \
1090	"--temp=$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/dita/temp_qhelp" \
1091	"--logfile=$(2)/UserManual_htmlhelp.log" \
1092	"-Ddita.output.dir=$(2)" \
1093	)
1094
1095	ditamap-to-htmlhelp: $(2)/UserManual.hhp
1096
1097	# 2. Generate a Qt Help Project file (QHP) using htmlhelp-qthelp.py.
1098	$(2)/UserManual.qhp: \
1099	$(2)/UserManual.hhp \
1100	$$(VBOX_PATH_MANUAL_SRC)/htmlhelp-qthelp.py
1101	$$(call MSG_L1,htmlhelp-qthelp.py $$<,=> $$@)
1102	$$(QUIET)$$(RM) -f -- "$$@"
1103	$$(QUIET)$$(VBOX_BLD_PYTHON) $$(VBOX_PATH_MANUAL_SRC)/htmlhelp-qthelp.py \
1104	-d "$$(<D)" -o "$$@" -f UserManual.hhp -t UserManual.hhc
1105
1106	# 3. Copy the Qt help configuration file from source to the output dir.
1107	$(2)/UserManual.qhcp: \
1108	$$(VBOX_PATH_MANUAL_SRC)/UserManual.qhcp \
1109	$(2)/UserManual.hhp # Order-only gets confused by rm -Rf, as kmk will cache the existance of the target \
1110	# file and not remake it because kmk thinks it still exists. Real dep fixes this.
1111	$$(call MSG_L1,, => $$@ ($(2)/UserManual_htmlhelp.log))
1112	$$(QUIET)$$(INSTALL_STAGING) -m0644 -- '$$<' '$$(@D)'
1113
1114	# 4. Run the Qt help generator to produce the .qhc and .qch files.
1115	$(2)/UserManual.qch \
1116	+ $(2)/UserManual.qhc: \
1117	$(2)/UserManual.qhcp \
1118	$(2)/UserManual.qhp
1119	$$(call MSG_L1,$$(notdir $$(VBOX_QHELPGENERATOR)) $$<,=> $$@)
1120	$$(QUIET)$$(RM) -f -- "$$@"
1121	$$(QUIET)$$(REDIRECT) -E "QT_PLUGIN_PATH=$$(PATH_SDK_QT6)/plugins" -E "QT_QPA_PLATFORM_PLUGIN_PATH=$$(PATH_SDK_QT6)/plugins/platforms" -- $$(VBOX_QHELPGENERATOR) $$<
1122	$$(call MSG_L1,Fresh QCH is now at $$@)
1123
1124	endef # def_vbox_usermanual_as_qhelp
1125
1126	$(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES) \
1127	,$(evalcall2 def_vbox_usermanual_as_qhelp,$(lang),$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/qhelp))
1128
1129	qhelp:: $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/qhelp/, $(VBOX_QHELP_OUTPUT_FILES))
1130
1131	endif # VBOX_WITH_DOCS_QHELP && !VBOX_ONLY_SDK
1132
1133
1134	#################################################################################################################################
1135	# Miscellaneous #
1136	#################################################################################################################################
1137
1138	#
1139	# ChangeLog.html
1140	#
1141	# This XSLT rule formats en_US/user_ChangeLog.xml (which includes the actual change log
1142	# contained in user_ChangeLogImpl.xml) as a standalone HTML file.
1143	#
1144	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html: \
1145	$(VBOX_PATH_MANUAL_SRC)/en_US/docbook-changelog-formatcfg.xsl \
1146	$(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml \
1147	$(VBOX_XML_ALL_CATALOGS_DEP) \
1148	$(VBOX_XML_ENTITIES) \| $$(dir $$@)
1149	$(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@)
1150	$(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --output "$@" "$<" $(filter %.xml,$^)
1151	$(call MSG_L1,Fresh ChangeLog.html is now at $@)
1152
1153	cl-html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html
1154
1155
1156	#
1157	# VBoxManage man pages (parts also required by VBoxManage built-in help).
1158	#
1159
1160	##
1161	# Emits rules for preprocessing refentry sources (applying remarks element),
1162	# and for producing the actual man pages.
1163	# $(evalcall2 def_vbox_refentry_to_manpage)
1164	# @param 1 The language
1165	# @param 2 The file name (no path).
1166	define def_vbox_refentry_to_manpage
1167	$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(2): \
1168	$$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2) \
1169	$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl \
1170	$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT) \
1171	$$(VBOX_XML_ALL_CATALOGS_DEP) \
1172	$$(VBOX_XML_ENTITIES) $$(VBOX_VERSION_STAMP) \| $$$$(dir $$$$@)
1173	$$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@)
1174	$$(QUIET)$$(RM) -f "$$@"
1175	$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ \
1176	$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl $$<
1177	$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@.tmp $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT) $$@
1178	$$(QUIET)$$(MV) -f -- "$$@.tmp" "$$@"
1179	if defined(VBOX_HAVE_XMLLINT)
1180	$$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$@
1181	endif
1182
1183	$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(patsubst man_%,%.1,$(basename $(2))): \
1184	$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(2) \
1185	$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage.xsl \
1186	$$(VBOX_XML_ALL_CATALOGS_DEP) \
1187	$$(VBOX_XML_ENTITIES) $$(VBOX_VERSION_STAMP) \| $$$$(dir $$$$@)
1188	$$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@)
1189	$$(QUIET)$$(RM) -f "$$@"
1190	$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --maxdepth 6000 --output $$@ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage.xsl $$<
1191	endef
1192	$(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \
1193	, $(evalcall2 def_vbox_refentry_to_manpage,$(lang),$(file))))
1194
1195	# Handy aliases.
1196	validate-manpages:: $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_REFENTRY_FILES))
1197	man-experiment:: $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \
1198	,$$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/$(patsubst man_%,%.1,$(basename $(file)))))
1199
1200	#
1201	# Manually updating the DHCP option list taken from VirtualBox.xidl
1202	#
1203	dhcpoptions: $(PATH_ROOT)/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xsl \
1204	$(PATH_ROOT)/src/VBox/Main/idl/VirtualBox.xidl
1205	$(call VBOX_XSLTPROC) --output "$(PATH_ROOT)/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xml" $^
1206
1207
1208	#
1209	# Packing the docs into a zip file (part of the packing pass on the docs build box).
1210	#
1211	ifneq ($(VBOX_MANUAL_PACK),)
1212	$(PATH_STAGE_BIN)/VBoxDocumentation.zip: $(VBOX_MANUAL_PACK)
1213	$(call MSG_L1,Packing documentation $@)
1214	$(QUIET)$(RM) -f $@
1215	$(QUIET)$(REDIRECT) -C $(PATH_STAGE_BIN) -- $(VBOX_ZIP) -9 $@ $(notdir $^)
1216	endif
1217
1218
1219	endif # if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) \|\| defined(VBOX_ONLY_DOCS) \|\| defined(VBOX_ONLY_SDK))
1220
1221	include $(FILE_KBUILD_SUB_FOOTER)
1222

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

Download in other formats:

Original Format