1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
|
# $Id: Config.kmk $
## @file
# kBuild Configuration file for the manual.
#
#
# Copyright (C) 2010-2024 Oracle and/or its affiliates.
#
# This file is part of VirtualBox base platform packages, as
# available from https://www.virtualbox.org.
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation, in version 3 of the
# License.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, see <https://www.gnu.org/licenses>.
#
# SPDX-License-Identifier: GPL-3.0-only
#
ifndef VBOX_DOC_MANUAL_CONFIG_KMK_INCLUDED
VBOX_DOC_MANUAL_CONFIG_KMK_INCLUDED = 1
# Include the top-level configure file.
ifndef VBOX_ROOT_CONFIG_KMK_INCLUDED
include $(PATH_ROOT)/Config.kmk
endif
#
# Globals.
#
# DITA stuff.
VBOX_DITA_OT_PATH ?= $(PATH_ROOT)/src/libs/dita-ot-1.8.5
ifneq ($(VBOX_DITA_OT_PATH),)
VBOX_DITA_OT_PATH := $(firstfile \
$(rversortfiles $(qwildcard ,$(KBUILD_DEVTOOLS)/common/dita-ot/v[4-9].*)) \
$(KBUILD_DEVTOOLS)/common/dita-ot/v4.0.2-r1)
endif
# Source location.
VBOX_PATH_MANUAL_SRC := $(PATH_ROOT)/doc/manual
# Output location.
VBOX_PATH_MANUAL_OUTBASE := $(PATH_OBJ)/manual
## List of refentry files (manpages).
VBOX_MANUAL_XML_REFENTRY_FILES := \
man_VBoxManage-common.xml \
man_VBoxManage-list.xml \
man_VBoxManage-showvminfo.xml \
man_VBoxManage-registervm.xml \
man_VBoxManage-unregistervm.xml \
man_VBoxManage-createvm.xml \
man_VBoxManage-modifyvm.xml \
man_VBoxManage-snapshot.xml \
man_VBoxManage-clonevm.xml \
man_VBoxManage-movevm.xml \
man_VBoxManage-encryptvm.xml \
man_VBoxManage-startvm.xml \
man_VBoxManage-controlvm.xml \
man_VBoxManage-import.xml \
man_VBoxManage-export.xml \
man_VBoxManage-mediumio.xml \
man_VBoxManage-sharedfolder.xml \
man_VBoxManage-dhcpserver.xml \
man_VBoxManage-debugvm.xml \
man_VBoxManage-extpack.xml \
man_VBoxManage-unattended.xml \
man_VBoxManage-cloud.xml \
man_VBoxManage-cloudprofile.xml \
man_VBoxManage-signova.xml \
man_VBoxManage-modifynvram.xml \
man_VBoxManage-hostonlynet.xml \
man_VBoxManage-updatecheck.xml \
man_VBoxManage-discardstate.xml \
man_VBoxManage-adoptstate.xml \
man_VBoxManage-closemedium.xml \
man_VBoxManage-storageattach.xml \
man_VBoxManage-storagectl.xml \
man_VBoxManage-bandwidthctl.xml \
man_VBoxManage-showmediuminfo.xml \
man_VBoxManage-createmedium.xml \
man_VBoxManage-modifymedium.xml \
man_VBoxManage-clonemedium.xml \
man_VBoxManage-mediumproperty.xml \
man_VBoxManage-encryptmedium.xml \
man_VBoxManage-checkmediumpwd.xml \
man_VBoxManage-convertfromraw.xml \
man_VBoxManage-setextradata.xml \
man_VBoxManage-getextradata.xml \
man_VBoxManage-setproperty.xml \
man_VBoxManage-usbfilter.xml \
man_VBoxManage-guestproperty.xml \
man_VBoxManage-guestcontrol.xml \
man_VBoxManage-metrics.xml \
man_VBoxManage-natnetwork.xml \
man_VBoxManage-hostonlyif.xml \
man_VBoxManage-usbdevsource.xml
## List of user manual XML files common for all languages.
VBOX_MANUAL_XML_FILES_COMMON = \
$(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml
# Tool locations.
ifndef VBOX_OSE
# use docbook from our tools directory
VBOX_PATH_DOCBOOK ?= $(KBUILD_DEVTOOLS)/common/DocBook/v1.69.1
VBOX_PATH_DOCBOOK_DTD ?= $(KBUILD_DEVTOOLS)/common/docbook-xml/v4.5
VBOX_PATH_DITA_DTD ?= $(VBOX_DITA_OT_PATH)/plugins/org.dita.specialization.dita11/dtd/
else
# use docbook of the build host
VBOX_PATH_DOCBOOK ?= /usr/share/xml/docbook/stylesheet/docbook-xsl
VBOX_PATH_DOCBOOK_DTD ?= /usr/share/xml/docbook/schema/dtd/4.5
VBOX_PATH_DITA_DTD ?= $(VBOX_DITA_OT_PATH)/plugins/org.dita.specialization.dita11/dtd/
endif
VBOX_XML_CATALOG ?= $(VBOX_PATH_MANUAL_OUTBASE)/vbox-doc.cat
VBOX_XML_CATALOG_DOCBOOK ?= $(VBOX_PATH_MANUAL_OUTBASE)/docbook.cat
VBOX_XML_CATALOG_DITA ?= $(VBOX_PATH_MANUAL_OUTBASE)/dita.cat
VBOX_XML_CATALOG_MANUAL ?= $(VBOX_PATH_MANUAL_OUTBASE)/manual.cat
VBOX_XML_ALL_CATALOGS_DEP ?= $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_DITA) $(VBOX_XML_CATALOG_MANUAL)
VBOX_XML_ENTITIES ?= $(VBOX_PATH_MANUAL_OUTBASE)/all-entities.ent
# xsltproc with the catalog trick if applicable (set XML_DEBUG_CATALOG to
# non-zero value to debug file/uri resolution through the catalogs, using
# one of them is enough, they show the same information).
ifdef VBOX_XML_CATALOG
VBOX_XSLTPROC_WITH_CAT = $(REDIRECT) -E "XML_CATALOG_FILES=$(if $(2),$(2),$(VBOX_XML_CATALOG))" -E "XML_DEBUG_CATALOG=" $1 -- \
$(VBOX_XSLTPROC) --nonet --xinclude $(VBOX_XSLTPROC_OPTS) --path "$(VBOX_PATH_MANUAL_OUTBASE)"
VBOX_XMLLINT_WITH_CAT = $(REDIRECT) -E "XML_CATALOG_FILES=$(VBOX_XML_CATALOG)" -E "XML_DEBUG_CATALOG=" -- \
$(VBOX_XMLLINT) --nonet --xinclude --noout $(VBOX_XMLLINT_OPTS) --path "$(VBOX_PATH_MANUAL_OUTBASE)"
else
VBOX_XSLTPROC_WITH_CAT = $(if $(1), $(REDIRECT) $1 --,) $(VBOX_XSLTPROC) --nonet --xinclude $(VBOX_XSLTPROC_OPTS) \
--path "$(VBOX_PATH_MANUAL_OUTBASE)"
VBOX_XMLLINT_WITH_CAT = $(VBOX_XMLLINT) --nonet --xinclude --noout $(VBOX_XMLLINT_OPTS) --path "$(VBOX_PATH_MANUAL_OUTBASE)"
endif
# Workaround for a security (?) fix in libxml (xsltproc doesn't have a way of setting the max amp level):
# utilitiesDomain.mod:135: parser error : Maximum entity amplification factor exceeded, see xmlCtxtSetMaxAmplification.
if $(firstword $(VBOX_XSLTPROC_LIBXML_VERSION) 0) >= 21206 ## @todo not sure which version introduced this issue.
VBOX_XSLTPROC_WORKAROUND := --novalid
else
VBOX_XSLTPROC_WORKAROUND :=
endif
# File name of the generated stylesheet for transforming xref elements into
# name user manual sections.
VBOX_XML_XREF_TO_TEXT = xref-to-text.xsl
##
# Emits rules for preprocessing refentry sources (applying remarks element),
# and for producing the actual man pages.
#
# $(evalcall2 def_vbox_refentry_preprocess_for_manpage)
# @param 1 The output directory.
# @param 2 The XML file name (no path).
# @param 3 The XML file with full path.
# @param 4 Non-empty if xrefs to replace.
# @param 5 Language code (optional if $4 is empty).
define def_vbox_refentry_preprocess_for_manpage
$(1)/$(2): \
$(3) \
$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl \
$(if $(4), $$(VBOX_PATH_MANUAL_OUTBASE)/$(5)/$$(VBOX_XML_XREF_TO_TEXT),) \
$$(VBOX_XML_ALL_CATALOGS_DEP) \
$$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@)
$$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@)
$$(QUIET)$$(RM) -f "$$@"
$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ \
"$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl" $$<
ifneq ($(4),)
$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@.tmp \
$$(VBOX_PATH_MANUAL_OUTBASE)/$(5)/$$(VBOX_XML_XREF_TO_TEXT) $$@
$$(QUIET)$$(MV) -f -- "$$@.tmp" "$$@"
endif
if defined(VBOX_HAVE_XMLLINT) && "$(USER)" == "bird" # Effing stuff happends on build servers, probably kmk related...
$$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$@
endif
endef
##
# Generate a single header file containing everything (no C file).
#
# @param 1 Destination file.
# @param 2 Full source file path.
# @param 3 Help infix.
define def_vbox_single_refentry_to_h
$(1).ts +| $(1): \
$$(VBOX_DOCBOOK_REFENTRY_TO_C_HELP) \
$$(VBOX_DOCBOOK_REFENTRY_TO_H_HELP) \
$(2) \
$$(VBOX_XML_ALL_CATALOGS_DEP) $(MAKEFILE) | $$$$(dir $$$$@)
$$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(filter %.xml,$$^),$$(patsubst %.ts,%,$$@))
$$(QUIET)$$(APPEND) -tn "$$@" \
'/* Autogenerated by $$(notdir $$(filter %.xsl,$$^)), do not edit! */' \
'' \
'#include <iprt/message.h>' \
'#include <iprt/assertcompile.h>' \
'' \
'typedef enum HELP_CMD_$(3)' \
'{' \
' HELP_CMD_INVALID = 0,'
$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT, -a+to "$$@") \
--stringparam 'g_sMode' 'cmd' $$(VBOX_DOCBOOK_REFENTRY_TO_H_HELP) $(2)
$$(QUIET)$$(APPEND) -n "$$@" \
' HELP_CMD_END' \
'} HELP_CMD_VBOXMANAGE;' \
''
$$(NLTAB)$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT, -a+to "$$@") \
--stringparam 'g_sMode' 'subcmd' $$(VBOX_DOCBOOK_REFENTRY_TO_H_HELP) $(2)
$$(QUIET)$$(APPEND) -n "$$@" \
''
$$(NLTAB)$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT, -a+to "$$@") $$(VBOX_DOCBOOK_REFENTRY_TO_C_HELP) $(2)
$$(QUIET)$$(APPEND) -n "$$@" \
'' \
'/* end of file */'
$$(QUIET)$$(CP) --changed -- "$$@" "$$(patsubst %.ts,%,$$@)"
endef
#
# Make sure we've got a rule to make the output directory.
#
BLDDIRS += $(VBOX_PATH_MANUAL_OUTBASE)
ifdef VBOX_XML_CATALOG
# Trickery for making sure that the file:/// URLs end up with exactly 3
# slashes, both on Unixy OSes (where the absolute path contributes one more,
# and some very picky xsltproc variants are floating around which do not work
# quite correctly with file:////, doing incorrect filename transformations)
# and on Windows (where the absolute path starts with a drive letter).
VBOX_FILE_URL_MAYBE_SLASH = $(if $(eq $(KBUILD_HOST),win),/,)
#
# To avoid network I/O for fetching DTDs, we generate catalogs mapping the public
# entity IDs to local files. (Obviously, only done when we have local files.)
#
# Create a catalog file for xsltproc that points to docbook catalog.
$(VBOX_XML_CATALOG): $(VBOX_PATH_MANUAL_SRC)/Config.kmk | $$(dir $$@)
$(call MSG_L1,Creating catalog $@)
$(QUIET)$(APPEND) -tn "$@" \
'<?xml version="1.0"?>' \
'<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">' \
'<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">' \
' <delegatePublic publicIdStartString="-//OASIS/ENTITIES DocBook XML" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DOCBOOK)"/>' \
' <delegatePublic publicIdStartString="-//OASIS/DTD DocBook XML" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DOCBOOK)"/>' \
' <delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DOCBOOK)"/>' \
' <delegateSystem systemIdStartString="http://docbook.org/" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DOCBOOK)"/>' \
' <delegateURI uriStartString="http://www.oasis-open.org/docbook/" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DOCBOOK)"/>' \
' <delegateURI uriStartString="http://docbook.org/" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DOCBOOK)"/>' \
' <delegatePublic publicIdStartString="-//OASIS/DTD DITA" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DITA)"/>' \
' <delegateSystem systemIdStartString="$(VBOX_PATH_MANUAL_SRC)/en_US/dita/bookmap.dtd" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DITA)"/>' \
' <delegateSystem systemIdStartString="$(VBOX_PATH_MANUAL_SRC)/en_US/dita/topics/topic.dtd" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_DITA)"/>' \
' <delegateSystem systemIdStartString="$(VBOX_PATH_MANUAL_SRC)" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_MANUAL)"/>' \
' <delegateSystem systemIdStartString="$(VBOX_PATH_MANUAL_OUTBASE)" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_MANUAL)"/>' \
' <delegateURI uriStartString="$(VBOX_PATH_MANUAL_SRC)" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_MANUAL)"/>' \
' <delegateURI uriStartString="$(VBOX_PATH_MANUAL_OUTBASE)" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_MANUAL)"/>' \
' <delegateURI uriStartString="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_SRC)" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_MANUAL)"/>' \
' <delegateURI uriStartString="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_OUTBASE)" catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG_MANUAL)"/>' \
'</catalog>'
# Create a docbook catalog file for xsltproc that points to the local docbook files.
$(VBOX_XML_CATALOG_DOCBOOK): $(VBOX_PATH_MANUAL_SRC)/Config.kmk | $$(dir $$@)
$(call MSG_L1,Creating catalog $@)
$(QUIET)$(APPEND) -tn "$@" \
'<?xml version="1.0"?>' \
'<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">' \
'<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">' \
' <public publicId="-//OASIS//ELEMENTS DocBook XML Information Pool V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/dbpoolx.mod"/>' \
' <public publicId="-//OASIS//DTD DocBook XML V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd"/>' \
' <public publicId="-//OASIS//ENTITIES DocBook XML Character Entities V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/dbcentx.mod"/>' \
' <public publicId="-//OASIS//ENTITIES DocBook XML Notations V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/dbnotnx.mod"/>' \
' <public publicId="-//OASIS//ENTITIES DocBook XML Additional General Entities V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/dbgenent.mod"/>' \
' <public publicId="-//OASIS//ELEMENTS DocBook XML Document Hierarchy V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/dbhierx.mod"/>' \
' <public publicId="-//OASIS//DTD XML Exchange Table Model 19990315//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/soextblx.dtd"/>' \
' <public publicId="-//OASIS//DTD DocBook XML CALS Table Model V4.5//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/calstblx.dtd"/>' \
' <rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.5" rewritePrefix="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)"/>' \
' <rewriteSystem systemIdStartString="http://docbook.org/xml/4.5" rewritePrefix="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)"/>' \
' <rewriteURI uriStartString="http://www.oasis-open.org/docbook/xml/4.5" rewritePrefix="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)"/>' \
' <rewriteURI uriStartString="http://docbook.org/xml/4.5" rewritePrefix="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsa.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Binary Operators//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsb.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Delimiters//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsc.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Negated Relations//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsn.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Ordinary//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amso.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Relations//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsr.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Box and Line Drawing//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-box.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Russian Cyrillic//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-cyr1.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Non-Russian Cyrillic//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-cyr2.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Diacritical Marks//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-dia.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Greek Letters//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-grk1.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Monotoniko Greek//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-grk2.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Greek Symbols//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-grk3.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Alternative Greek Symbols//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-grk4.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Added Latin 1//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-lat1.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Added Latin 2//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-lat2.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-num.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES Publishing//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-pub.ent"/>' \
' <public publicId="ISO 8879:1986//ENTITIES General Technical//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-tech.ent"/>' \
'</catalog>'
# Create a dita catalog file for xsltproc that points to the local dita files.
$(VBOX_XML_CATALOG_DITA): $(VBOX_PATH_MANUAL_SRC)/Config.kmk | $$(dir $$@)
$(call MSG_L1,Creating catalog $@)
$(QUIET)$(APPEND) -tn "$@" \
'<?xml version="1.0"?>' \
'<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">' \
'<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">' \
' <public publicId="-//OASIS//DTD DITA BookMap//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DITA_DTD)/bookmap.dtd"/>' \
' <public publicId="-//OASIS//DTD DITA Topic//EN" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DITA_DTD)/topic.dtd"/>' \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/dita/bookmap.dtd" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DITA_DTD)/bookmap.dtd"/>' \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/dita/topics/topic.dtd" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DITA_DTD)/topic.dtd"/>' \
'</catalog>'
# Create a docbook catalog file for xsltproc that points to the local manual files in non-default locations
$(VBOX_XML_CATALOG_MANUAL): $(VBOX_PATH_MANUAL_SRC)/Config.kmk | $$(dir $$@)
$(call MSG_L1,Creating catalog $@)
$(QUIET)$(APPEND) -tn "$@" \
'<?xml version="1.0"?>' \
'<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">' \
'<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">' \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/common/oracle-accessibility-ohc-en.xml" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_SRC)/en_US/oracle-accessibility-ohc-en.xml"/>' \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/common/oracle-legal-notices/oracle-diversity.xml" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_SRC)/en_US/oracle-diversity.xml"/>' \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/common/oracle-legal-notices/oracle-support-en.xml" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_SRC)/en_US/oracle-support-en.xml"/>' \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/user_ChangeLogImpl.xml" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml"/>' \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/titlepage-htmlhelp.xsl" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl"/>' \
$(foreach x,user_VBoxManage_CommandsOverview.xml user_isomakercmd-man.xml $(addprefix user_,$(VBOX_MANUAL_XML_REFENTRY_FILES) man_VBoxHeadless.xml man_vboximg-mount.xml)\
,' <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/$(x)" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_OUTBASE)/en_US/$(x)"/>' \$(NLTAB)$(TAB)) \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/SDKRef_apiref.xml" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef_apiref.xml"/>' \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/all-entities.ent" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_OUTBASE)/all-entities.ent"/>' \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/html/docbook.xsl" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK)/html/docbook.xsl"/>' \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/html/chunk.xsl" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK)/html/chunk.xsl"/>' \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/htmlhelp/htmlhelp.xsl" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK)/htmlhelp/htmlhelp.xsl"/>' \
' <system systemId="$(VBOX_PATH_MANUAL_SRC)/manpages/docbook.xsl" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_DOCBOOK)/manpages/docbook.xsl"/>' \
'</catalog>'
endif # VBOX_XML_CATALOG
ifdef VBOX_XML_ENTITIES
$(VBOX_XML_ENTITIES): $(VBOX_PATH_MANUAL_SRC)/Config.kmk $(VBOX_VERSION_STAMP) | $$(dir $$@)
$(call MSG_L1,Creating entities $@)
$(QUIET)$(APPEND) -tn "$@" \
'<!-- Entities for product names -->' \
'<!ENTITY product-version "$(VBOX_VERSION_STRING)">' \
'<!ENTITY product-name "Oracle VirtualBox">' \
'<!ENTITY extpack-name "Oracle VirtualBox Extension Pack">' \
'<!ENTITY vbox-mgr "VirtualBox Manager">' \
'<!ENTITY oci "Oracle Cloud Infrastructure">' \
'' \
'<!-- VBox placeholder entities -->' \
'<!ENTITY VBOX_VERSION_MAJOR "$(VBOX_VERSION_MAJOR)" >' \
'<!ENTITY VBOX_VERSION_MINOR "$(VBOX_VERSION_MINOR)" >' \
'<!ENTITY VBOX_VERSION_BUILD "$(VBOX_VERSION_BUILD)" >' \
'<!ENTITY VBOX_VERSION_STRING "$(VBOX_VERSION_STRING)" >' \
'<!ENTITY VBOX_VENDOR "$(VBOX_VENDOR)" >' \
'<!ENTITY VBOX_C_YEAR "$(VBOX_C_YEAR)" >' \
'<!ENTITY VBOX_PRODUCT '\''<trademark class="registered">Oracle</trademark> <trademark class="registered">VirtualBox</trademark>'\'' >' \
'' \
'<!-- Entities for Oracle Help Center -->' \
'<!ENTITY ohc-base-url "https://docs.oracle.com/en">' \
'<!ENTITY ohc-doc-page "&ohc-base-url;/virtualization/virtualbox/index.html">'
endif # VBOX_XML_ENTITIES
## Emit rules to produce a stylesheet for translating cross references (xref)
# to user manual chapters and sections in the man pages and --help output.
#
# Note! This is a bit hackish, as it only processes the checked in .dita files
# and not the processed result nor stuff we generated. Seems like all
# we generate is manpage related pages, so that's fine since these are
# all currently at the tail of one chapter in the manual.
#
# If it turns out we generate more stuff that this, we're in for lots of
# dependency fun with VBoxManage and the RTIsoMaker (+ derivatives).
#
# $(evalcall2 def_vbox_xref_to_text)
# @param 1 Language code.
define def_vbox_xref_to_text
$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT) \
+ $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT).cat: \
$$(VBOX_PATH_MANUAL_SRC)/$(1)/docbook-refentry-link-replacement-xsl-gen.xsl \
$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-link-replacement-xsl-gen.xsl \
$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita-refentry-link-replacement-xsl-gen.xsl \
$$(VBOX_PATH_MANUAL_SRC)/dita-refentry-link-replacement-xsl-gen.xsl \
$$(VBOX_PATH_MANUAL_SRC)/ditamap-to-single-xml.xsl \
$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/UserManual.ditamap \
$$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/topics/*.xml) \
$$(VBOX_MANUAL_XML_FILES_COMMON) \
$$(VBOX_XML_ALL_CATALOGS_DEP) $$(VBOX_XML_ENTITIES) \
| $$$$(dir $$$$@)
$$(call MSG_L1,Creating stylesheet $$@)
$$(QUIET)$$(APPEND) -nt "$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT).cat" \
'<?xml version="1.0"?>' \
'<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">' \
'<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">' \
$$(foreach x, vboxmanage-cmd-overview.dita \
,' <system systemId="$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/topics/$$(x)" uri="file://$$(VBOX_FILE_URL_MAYBE_SLASH)$$(VBOX_PATH_MANUAL_SRC)/dummy-topic.dita"/>' \$$(NLTAB)$$(TAB)) \
' <nextCatalog catalog="file://$$(VBOX_FILE_URL_MAYBE_SLASH)$$(VBOX_XML_CATALOG)"/>' \
'</catalog>'
$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT,,$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT).cat) \
--output "$$@.tmp.xml" "$$(VBOX_PATH_MANUAL_SRC)/ditamap-to-single-xml.xsl" $$(filter %.ditamap,$$^)
if 0 # Enable to see the full combined document.
$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT,,$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT).cat) \
--path "$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/topics/licensing/vbox-base" \
--path "$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/topics/licensing/vbox-ext" \
--path "$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/topics/licensing" \
--path "$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/topics" \
--output "$$@.tmp2.xml" "$$(VBOX_PATH_MANUAL_SRC)/ditamap-to-single-xml.xsl" "$$@.tmp.xml"
endif
$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT,,$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$$(VBOX_XML_XREF_TO_TEXT).cat) \
--path "$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/topics/licensing/vbox-base" \
--path "$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/topics/licensing/vbox-ext" \
--path "$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/topics/licensing" \
--path "$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita/topics" \
--stringparam 'g_sMode' 'first' \
--output "$$@" \
"$$(VBOX_PATH_MANUAL_SRC)/$(1)/dita-refentry-link-replacement-xsl-gen.xsl" \
"$$@.tmp.xml"
# Using en-US version as section and chapter names until user manual is translated as well
$$(foreach x, $$(VBOX_MANUAL_XML_REFENTRY_FILES)\
,$$(NLTAB)$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT, -ato "$$@") --stringparam 'g_sMode' 'append' \
"$$<" "$$(VBOX_PATH_MANUAL_SRC)/en_US/$$(x)")
$$(QUIET)$$(APPEND) -n "$$@" '' '</xsl:stylesheet>'
$$(QUIET)$$(RM) -f -- "$$@.tmp.xml"
BLDDIRS += $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/
endef
# generate rules for $(VBOX_XML_XREF_TO_TEXT)
$(evalcall2 def_vbox_xref_to_text,en_US)
#
# Generate rules for editing the refentry to C/H style sheets.
#
VBOX_DOCBOOK_REFENTRY_TO_C_HELP = $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-C-help.xsl
VBOX_DOCBOOK_REFENTRY_TO_H_HELP = $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-H-help.xsl
#
# Manual dependency.
#
$(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-C-help.xsl: $(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl
endif # !defined(VBOX_DOC_MANUAL_CONFIG_KMK_INCLUDED)
|
