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 |
|
---|
40 | SUB_DEPTH = ../..
|
---|
41 | include $(KBUILD_PATH)/subheader.kmk
|
---|
42 |
|
---|
43 | ifndef VBOX_DOC_MANUAL_CONFIG_KMK_INCLUDED
|
---|
44 | include $(PATH_SUB_CURRENT)/Config.kmk
|
---|
45 | endif
|
---|
46 |
|
---|
47 | if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK)) # Whole file.
|
---|
48 |
|
---|
49 | #
|
---|
50 | # Globals
|
---|
51 | #
|
---|
52 |
|
---|
53 | ## Combines the VBOX_MANUAL_LANGUAGES and VBOX_MANUAL_ADD_LANGUAGES lists from
|
---|
54 | # /Config.kmk, as per the VBOX_WITH_DOCS_TRANSLATIONS setting.
|
---|
55 | ifdef VBOX_WITH_DOCS_TRANSLATIONS
|
---|
56 | VBOX_MANUAL_ALL_LANGUAGES := $(VBOX_MANUAL_LANGUAGES) $(VBOX_MANUAL_ADD_LANGUAGES)
|
---|
57 | else
|
---|
58 | VBOX_MANUAL_ALL_LANGUAGES := $(VBOX_MANUAL_LANGUAGES)
|
---|
59 | endif
|
---|
60 |
|
---|
61 | ## The files that should go into VBoxDocumentation.zip (must be immediately under PATH_STAGE_BIN).
|
---|
62 | VBOX_MANUAL_PACK =
|
---|
63 |
|
---|
64 | # Various file lists (mainly needed for OTHER_CLEAN).
|
---|
65 | VBOX_QHELP_OUTPUT_FILES := UserManual.qch UserManual.qhc
|
---|
66 | VBOX_ACCESSIBILITY_XML_FILES := Accessibility.xml
|
---|
67 | VBOX_MANUAL_LATEX_FILES_TARGET := $(addprefix UserManual.,aux log out toc tex)
|
---|
68 | VBOX_SDKREF_LATEX_FILES_TARGET := $(addprefix SDKRef.,aux log out toc tex)
|
---|
69 | VBOX_ACCESSIBILITY_LATEX_FILES_TARGET := $(addprefix Accessibility.,aux log out toc tex)
|
---|
70 |
|
---|
71 | VBOX_MANUAL_TEX_UNICODE_FILES = $(wildcard $(VBOX_PATH_MANUAL_SRC)/texfiles/unicode/*)
|
---|
72 |
|
---|
73 | # Wildcard the images path for every supported language
|
---|
74 | $(foreach lang,$(VBOX_MANUAL_ALL_LANGUAGES) \
|
---|
75 | ,$(eval VBOX_MANUAL_PNG_FILES_$$(lang) := $$(patsubst $$(VBOX_PATH_MANUAL_SRC)/$$(lang)/%,%, \
|
---|
76 | $$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$$(lang)/images/*.png))))
|
---|
77 |
|
---|
78 | # SDK related globals.
|
---|
79 | VBOX_MANUAL_APIREF_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef_apiref.xml
|
---|
80 | VBOX_DOC_XIDL_SRC = $(PATH_ROOT)/src/VBox/Main/idl/VirtualBox.xidl
|
---|
81 | VBOX_DOC_XIDL_SRC_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.xidl.tmp
|
---|
82 |
|
---|
83 |
|
---|
84 | #
|
---|
85 | # PDF LaTeX related globals.
|
---|
86 | #
|
---|
87 |
|
---|
88 | VBOX_PDFLATEX_INTERACTION ?= batchmode
|
---|
89 | # VBOX_PDFLATEX_INTERACTION = errorstopmode - Use this when you wants to figure out build failures
|
---|
90 | # without catting the log a million times.
|
---|
91 | ifeq ($(KBUILD_HOST),win)
|
---|
92 | ifndef VBOX_PDFLATEX
|
---|
93 | VBOX_PDFLATEX := $(firstword $(rsort $(wildcard $(KBUILD_DEVTOOLS)/win.x86/miktex-portable/*/miktex/bin/pdflatex.exe)))
|
---|
94 | ifneq ($(VBOX_PDFLATEX),)
|
---|
95 | VBOX_PDFLATEX_CMD = $(VBOX_PDFLATEX) -halt-on-error -interaction $(VBOX_PDFLATEX_INTERACTION)
|
---|
96 | endif
|
---|
97 | endif
|
---|
98 | ifndef VBOX_PDFLATEX
|
---|
99 | # Tell MiKTeX to automatically download packages if system wide install.
|
---|
100 | VBOX_PDFLATEX := pdflatex
|
---|
101 | VBOX_PDFLATEX_CMD = $(VBOX_PDFLATEX) -halt-on-error -interaction $(VBOX_PDFLATEX_INTERACTION) --enable-installer
|
---|
102 | endif
|
---|
103 | else
|
---|
104 | VBOX_PDFLATEX ?= pdflatex
|
---|
105 | VBOX_PDFLATEX_HALT = $(shell ( $(VBOX_PDFLATEX) -version | head -1 | grep 141592 > /dev/null ) && echo -halt-on-error )
|
---|
106 | VBOX_PDFLATEX_CMD = pdflatex $(VBOX_PDFLATEX_HALT) -interaction $(VBOX_PDFLATEX_INTERACTION)
|
---|
107 | endif
|
---|
108 |
|
---|
109 | #
|
---|
110 | # Java v17 or later (JAVA_HOME), used by DITA-OT.
|
---|
111 | #
|
---|
112 | ifeq ($(VBOX_JAVA17PLUS_HOME),)
|
---|
113 | if defined(VBOX_JAVA_VERSION) && $(VBOX_JAVA_VERSION) >= 170000 && "$(VBOX_JAVA_BIN_PATH)" != ""
|
---|
114 | VBOX_JAVA17PLUS_HOME := $(qabspath ,$(VBOX_JAVA_BIN_PATH)/..)
|
---|
115 | else
|
---|
116 | VBOX_JAVA17PLUS_HOME := $(firstfile \
|
---|
117 | $(rversortfiles $(qwildcard , $(KBUILD_DEVTOOLS_HST)/jdk/v1[789].* $(KBUILD_DEVTOOLS_HST)/jdk/v[2-9][0-9].* )) \
|
---|
118 | $(rversortfiles $(qwildcard ,$(KBUILD_DEVTOOLS_HST_ALT)/jdk/v1[789].* $(KBUILD_DEVTOOLS_HST_ALT)/jdk/v[2-9][0-9].* )) \
|
---|
119 | )
|
---|
120 | if "$(KBUILD_HOST)" == "darwin" && "$(VBOX_JAVA17PLUS_HOME)" != ""
|
---|
121 | VBOX_JAVA17PLUS_HOME := $(VBOX_JAVA17PLUS_HOME)/Contents/Home
|
---|
122 | endif
|
---|
123 | endif
|
---|
124 | endif
|
---|
125 |
|
---|
126 | #
|
---|
127 | # DITA-OT related globals.
|
---|
128 | #
|
---|
129 | VBOX_DITA_TECHNICAL_CONTENT_DTD_PATH = $(VBOX_DITA_OT_PATH)/plugins/org.oasis-open.dita.v1_2/dtd/technicalContent/dtd
|
---|
130 |
|
---|
131 | ##
|
---|
132 | # Runs the dost.jar.
|
---|
133 | #
|
---|
134 | # @param 1 Additional kmk_redirect options.
|
---|
135 | # @param 2 Parameters for the invoker.
|
---|
136 | #
|
---|
137 | VBOX_DITA_RUN_DOST = $(REDIRECT_EXT) \
|
---|
138 | -E 'ANT_HOME=$(VBOX_DITA_OT_PATH)' \
|
---|
139 | -E 'DITA_DIR=$(VBOX_DITA_OT_PATH)' \
|
---|
140 | -E 'JAVA_HOME=$(VBOX_JAVA17PLUS_HOME)' \
|
---|
141 | -E 'CLASSPATH=$(VBOX_DITA_CLASSPATH)' \
|
---|
142 | $1 \
|
---|
143 | -- \
|
---|
144 | "$(VBOX_JAVA17PLUS_HOME)/bin/java" \
|
---|
145 | "-Djava.awt.headless=true" \
|
---|
146 | "-Dsun.io.useCanonCaches=true" \
|
---|
147 | "-Dant.home=$(VBOX_DITA_OT_PATH)" \
|
---|
148 | "-Ddita.dir=$(VBOX_DITA_OT_PATH)" \
|
---|
149 | org.apache.tools.ant.launch.Launcher \
|
---|
150 | -cp "$(VBOX_DITA_CLASSPATH)" \
|
---|
151 | -buildfile "$(VBOX_DITA_OT_PATH)/build.xml" \
|
---|
152 | -main "org.dita.dost.invoker.Main" \
|
---|
153 | --args.grammar.cache=yes \
|
---|
154 | --verbose \
|
---|
155 | $(if-expr defined(VBOX_DITA_DEBUG),"--clean.temp=no" "--debug",) \
|
---|
156 | $2
|
---|
157 |
|
---|
158 | VBOX_DITA_CLASSPATH = \
|
---|
159 | $(subst $(SP),$(HOST_PATH_SEP),$(strip \
|
---|
160 | $(VBOX_DITA_OT_PATH)/lib/ant-launcher.jar \
|
---|
161 | $(VBOX_DITA_OT_PATH)/config \
|
---|
162 | $(VBOX_DITA_OT_PATH)/lib \
|
---|
163 | $(wildcard \
|
---|
164 | $(VBOX_DITA_OT_PATH)/lib/*.jar \
|
---|
165 | $(VBOX_DITA_OT_PATH)/plugins/*/lib/*.jar)))
|
---|
166 |
|
---|
167 |
|
---|
168 | #
|
---|
169 | # Targets
|
---|
170 | #
|
---|
171 |
|
---|
172 | BLDDIRS += $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/, $(VBOX_MANUAL_ALL_LANGUAGES))
|
---|
173 |
|
---|
174 | ifdef VBOX_ONLY_DOCS
|
---|
175 | PACKING += $(PATH_STAGE_BIN)/VBoxDocumentation.zip
|
---|
176 | endif
|
---|
177 |
|
---|
178 | BLDDIRS += \
|
---|
179 | $(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita \
|
---|
180 | $(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/topics \
|
---|
181 | $(VBOX_PATH_MANUAL_OUTBASE)/en_US/dita/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 |
|
---|
1120 | endif # if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK))
|
---|
1121 |
|
---|
1122 | include $(FILE_KBUILD_SUB_FOOTER)
|
---|
1123 |
|
---|