VirtualBox

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

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

Docs: bugref:10705. Add ZIP containing generated DITA files for the DocBook changelog topics.

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