Config.kmk@ 105564

Last change on this file since 105564 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: 27.7 KB

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

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

Download in other formats:

Original Format