Makefile.kmk@ 107390

Last change on this file since 107390 was 107390, checked in by vboxsync, 5 months ago

Docs: bugref:10705. bugref: 10829. The docs build has been modified to split generated refentry dita files and the user manual files and the following commits from doc's team git repo has been applied:

0946136c74dda0483704db891345cb39548b4e28 Started consolidating known issues and troubleshooting information
845b847e6a8e778b38a57867e25ee5e086a73800 Added individual topics for list of known issues, integrated into Troubleshooting section.
bb574836aac775889bd61e4a72f489617fcb7d18 Removed EFI firmware from experimental features for 7.2
6d2e68b244869991e713d170ecd239739d99ba56 Moved known issues into Known Issues section
e2630c896561587718b5c3197c384a38d07014d5 Merge branch 'VBP-1461_experimental-features' into 'main'
0512e2cce51f49ccdc56f3381a2a0c924f2bd278 Feedback on known issues
a77d6c980f6ff5cad9d32b2fb9290990093a03fa Restructured host and guest OS topics
988af5cc9628f5de0806531bc98686f691a911fd Updates with feedbback from Jacob
982a61c9f25b22b745ec483e763e3d88efe59c40 Included feedback from Jacob
93181c8c6cc2d9a26bcccb1145cb0423c0d9f4c9 Updated known issues with feedback from Klaus
8bc369561c383f09b409fe5e44f507440b3735fb Created Legacy Guest OS section
d7932f55accdab7a03666302d58b8c941cd48be2 Moved known issues to more appropriate places for the info
2a4aa094ba8a7ac6894d2a777316eabf41746580 Further moving of known issues
baeabd5308c5519a4dc26b4197be9b00e419a85a Updated links to cli_topics

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

File size: 54.2 KB

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

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

Download in other formats:

Original Format