VirtualBox

source: vbox/trunk/doc/manual/Makefile.kmk@ 103068

Last change on this file since 103068 was 101553, checked in by vboxsync, 12 months ago

doc/manual: bugref:10450: Get rid of Qt5 stuff.

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette