summaryrefslogtreecommitdiff
path: root/doc/manual/Makefile.kmk
blob: 4411d06715359ab6768fe30c04fb5fb498e30d75 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
# $Id: Makefile.kmk $
## @file
# Sub-Makefile for the VBox User Manual.
#

#
# Copyright (C) 2006-2012 Oracle Corporation
#
# This file is part of VirtualBox Open Source Edition (OSE), as
# available from http://www.virtualbox.org. This file is free software;
# you can redistribute it and/or modify it under the terms of the GNU
# General Public License (GPL) as published by the Free Software
# Foundation, in version 2 as it comes in the "COPYING" file of the
# VirtualBox OSE distribution. VirtualBox OSE is distributed in the
# hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
#

#
# This slightly messy makefile transforms the DocBook XML source for the
# user manual into presentation output. We support two targets:
#
#   -- UserManual.pdf, generated by LaTex
#
#   -- VirtualBox.chm
#
#   Both files end up in PATH_STAGE_BIN.
#
#   Both targets indirectly depend on the XML files in this directory;
#   "indirectly" because we first copy them to PATH_TARGET and hack them
#   up a bit for variable substitution and such (see below).
#   The toolchains are roughly like this:
#
#   -- PDF file via Apache FOP: pre-process the XML files in PATH_TARGET,
#      then create a .FO file (another XML format for "formatted objects")
#      via xsltproc, then feed the .FO file to Apache FOP to create the PDF.
#
#   -- PDF file via LaTeX: pre-process the XML files in PATH_TARGET, then
#      run our custom "dblatex" perl script on UserManual.xml, which parses
#      the XML (using the Perl SAX parsers) and dumps a matching latex file
#      to UserManual.tex. This is then regularly processed by pdflatex to
#      generate PDF.
#
#   -- CHM file: again, pre-process the XML files in PATH_TARGET, then use
#      xsltproc to create a .HHP file for the Microsoft Help Compiler, then
#      feed that file to it.
#

SUB_DEPTH = ../..
include $(KBUILD_PATH)/subheader.kmk


##########################################################################################
#
#  Globals
#
##########################################################################################
VBOX_PATH_MANUAL_SRC := $(PATH_SUB_CURRENT)
VBOX_PATH_MANUAL_OUTBASE := $(PATH_TARGET)/manual
BLDDIRS += $(VBOX_PATH_MANUAL_OUTBASE)


##########################################################################################
#
#  Main targets
#
##########################################################################################
ifdef VBOX_WITH_DOCS
 # Default language
 VBOX_MANUAL_LANGUAGES = en_US

 ifdef VBOX_WITH_DOCS_TRANSLATIONS
  VBOX_MANUAL_ADD_LANGUAGES = fr_FR
 endif

 if defined(VBOX_ONLY_SDK) || defined(VBOX_WITH_DOCS_SDKREF)
  ## @todo make this an install target, drop the BLDDIRS.
  OTHERS += \
  	$(VBOX_PATH_SDK)/docs/SDKRef.pdf
  BLDDIRS += \
  	$(VBOX_PATH_SDK)/docs
 endif

 ifdef VBOX_WITH_DOCS_CHM
  VBOX_PATH_BIN_CHM = $(PATH_STAGE_BIN)/VirtualBox.chm
 else
  VBOX_PATH_BIN_CHM =
        # do not build
 endif # !VBOX_WITH_DOCS_CHM

 ifndef VBOX_ONLY_SDK
  VBOX_MANUAL_PACK += \
  		$(PATH_STAGE_BIN)/UserManual.pdf \
  		$(VBOX_PATH_BIN_CHM)
  OTHERS += \
  	$(PATH_STAGE_BIN)/UserManual.pdf
  OTHERS.win += \
  	$(VBOX_PATH_BIN_CHM)
  OTHERS.linux += \
  	$(VBOX_PATH_BIN_CHM)

  ifdef VBOX_WITH_DOCS_TRANSLATIONS
   OTHERS += \
   	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf)
   ifdef VBOX_WITH_DOCS_CHM
   OTHERS.win += \
   	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm)
   OTHERS.linux += \
   	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm)
   endif
  endif
 endif # !VBOX_ONLY_SDK
 ifdef VBOX_ONLY_DOCS
  PACKING += $(PATH_STAGE_BIN)/VBoxDocumentation.zip
 endif

 ifdef VBOX_WITH_DOCS_TRANSLATIONS
  VBOX_MANUAL_LANGUAGES += $(VBOX_MANUAL_ADD_LANGUAGES)
 endif

 VBOX_MANUAL_XML_CHANGELOG = \
 	user_ChangeLogImpl.xml

 VBOX_MANUAL_XML_FILES = \
 	UserManual.xml \
 	user_AdvancedTopics.xml \
 	user_BasicConcepts.xml \
 	user_Glossary.xml \
 	user_Frontends.xml \
 	user_Installation.xml \
 	user_GuestAdditions.xml \
 	user_Introduction.xml \
 	user_KnownIssues.xml \
 	user_PrivacyPolicy.xml \
 	user_Security.xml \
 	user_Technical.xml \
 	user_ThirdParty.xml \
 	user_Troubleshooting.xml \
 	user_VBoxManage.xml \
 	user_VirtualBoxAPI.xml \
 	user_Storage.xml \
 	user_Networking.xml

 VBOX_MANUAL_XML_FILES_INCL_CHANGELOG = $(VBOX_MANUAL_XML_FILES) \
 	user_ChangeLog.xml

 VBOX_SDKREF_XML_FILES = \
 	SDKRef.xml

 # Wildcard the images path for every supported language
 $(foreach f,$(VBOX_MANUAL_LANGUAGES), \
 	$(eval VBOX_MANUAL_PNG_FILES_$$(f) := $$(patsubst $$(VBOX_PATH_MANUAL_SRC)/$$(f)/%,%,$$(wildcard $$(VBOX_PATH_MANUAL_SRC)/$$(f)/images/*.png))))

 VBOX_MANUAL_TEX_UNICODE_FILES = \
 	$(wildcard $(VBOX_PATH_MANUAL_SRC)/texfiles/unicode/*)

 VBOX_MANUAL_LATEX_FILES_TARGET = \
 	$(addprefix UserManual.,aux log out toc tex)

 VBOX_SDKREF_LATEX_FILES_TARGET = \
 	$(addprefix SDKRef.,aux log out toc tex)

 BLDDIRS += \
 	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/,\
 		$(VBOX_MANUAL_LANGUAGES) \
 		$(addsuffix /images, $(VBOX_MANUAL_LANGUAGES)) \
 		$(addsuffix /html-single, $(VBOX_MANUAL_LANGUAGES)) \
 		$(addsuffix /html-chunks, $(VBOX_MANUAL_LANGUAGES)) \
 		$(addsuffix /HTMLHelp, $(VBOX_MANUAL_LANGUAGES)) \
 		$(addsuffix /HTMLHelp/images, $(VBOX_MANUAL_LANGUAGES)) \
 	)

 ifdef VBOX_WITH_DOCS_CHM
 VBOX_MANUAL_PACK += \
 	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf $(PATH_STAGE_BIN)/VirtualBox_$(f).chm)
 endif

 OTHER_CLEAN += \
 	$(foreach f,$(VBOX_MANUAL_LANGUAGES), $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG))) \
 	$(foreach f,en_US,                    $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_SDKREF_XML_FILES))) \
 	$(foreach f,$(VBOX_MANUAL_LANGUAGES), $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_MANUAL_LATEX_FILES_TARGET))) \
 	$(foreach f,en_US,                    $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_SDKREF_LATEX_FILES_TARGET))) \
 	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/, \
 		catalog docbook \
 		UserManual.fo) \
 	$(foreach f,$(VBOX_MANUAL_LANGUAGES), $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/, \
 		docbook-htmlhelp-formatcfg.xsl \
		docbook-html-one-page-formatcfg.xsl \
		docbook-html-chunks-formatcfg.xsl \
 		titlepage-htmlhelp.xsl )) \
 	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_MANUAL_PNG_FILES_$(f)))) \
 	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/HTMLHelp/,$(VBOX_MANUAL_PNG_FILES_$(f)))) \
 	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/UserManual.pdf) \
 	$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/VirtualBox.chm) \
 	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf) \
 	$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm) \
 	$(PATH_STAGE_BIN)/UserManual.pdf \
 	$(PATH_STAGE_BIN)/VirtualBox.chm \
 	$(foreach f,en_US,$(VBOX_PATH_MANUAL_OUTBASE)/$f/SDKRef.pdf) \
 	$(PATH_STAGE_BIN)/sdk/docs/SDKRef.pdf \
 	$(wildcard $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/HTMLHelp/*.h*)) \
 	$(foreach f,$(VBOX_MANUAL_LANGUAGES),\
 		$(patsubst $(VBOX_PATH_MANUAL_SRC)/texfiles/unicode/%,$(VBOX_PATH_MANUAL_OUTBASE)/$f/%, \
 			$(VBOX_MANUAL_TEX_UNICODE_FILES))) \
 	$(VBOX_PATH_MANUAL_OUTBASE)/$(VBOX_MANUAL_XML_CHANGELOG)

endif # VBOX_WITH_DOCS



##########################################################################################
#
#  Options
#
##########################################################################################

HTMLHELPOPTS =


##########################################################################################
#
#  Preparations
#
##########################################################################################

# tool locations
ifndef VBOX_OSE
 # use docbook from our tools directory
 DOCBOOKPATH         ?= $(PATH_DEVTOOLS)/common/DocBook/v1.69.1
 DOCBOOKDTDPATH      ?= $(PATH_DEVTOOLS)/common/docbook-xml/v4.3
 XML_CATALOG         ?= $(VBOX_PATH_MANUAL_OUTBASE)/catalog
 XML_CATALOG_DOCBOOK ?= $(VBOX_PATH_MANUAL_OUTBASE)/docbook
else
 # use docbook of the build host
 DOCBOOKPATH         ?= http://docbook.sourceforge.net/release/xsl/current/
endif
VBOXMANAGEPATH       ?= $(PATH_STAGE_BIN)/VBoxManageHelp$(SUFF_EXE)

 # PDFLATEX_INTERACTION = errorstopmode - Use this when you wants to figure out build failures
 #                                        without catting the log a million times.
 PDFLATEX_INTERACTION ?= batchmode
ifeq ($(KBUILD_HOST),win)
 ifndef VBOX_PDFLATEX
  VBOX_PDFLATEX      := $(firstword $(rsort $(wildcard $(PATH_DEVTOOLS)/win.x86/miktex-portable/*/miktex/bin/pdflatex.exe)))
  ifneq ($(VBOX_PDFLATEX),)
   PDFLATEX           = $(VBOX_PDFLATEX) -halt-on-error -interaction $(PDFLATEX_INTERACTION)
  endif
 endif
 ifndef PDFLATEX
  # Tell MiKTeX to automatically download packages if system wide install.
  VBOX_PDFLATEX      := pdflatex
  PDFLATEX            = $(VBOX_PDFLATEX) -halt-on-error -interaction $(PDFLATEX_INTERACTION) --enable-installer
 endif
else
 PDFLATEX_HALT        = $(shell \
 	( pdflatex -version | head -1 | grep 141592 > /dev/null ) && echo -halt-on-error )
 PDFLATEX             = pdflatex $(PDFLATEX_HALT) -interaction $(PDFLATEX_INTERACTION)
endif

# Windows HTML Help Workshop compiler (stupid thing always returns an error!)
HHC = -$(EXEC_X86_WIN32) $(VBOX_PATH_HTML_HELP_WORKSHOP)/hhc.exe


##########################################################################################
#
#  Rules: Preprocess DocBook XML files
#  (preliminary step for both CHM and PDF generation)
#
##########################################################################################

#
# The following rules for $(VBOX_PATH_MANUAL_OUTBASE)/*.xml process the XML files
# in doc/manual to allow for some magic variable replacements. The PDF and CHM
# targets do not depend on the XML files in doc/manual, but those in
# $(VBOX_PATH_MANUAL_OUTBASE) instead, which we copy there from here, after that magic
# processing.
#
# So, before copying, the following steps are performed:
#
# -- $VBOX_VERSION_* strings are replaced with the actual current VBox version.
# -- $VBOX_MANAGE_OUTPUT (in VBoxManage.xml) is replaced with the current
#    output of the actual VBoxManage program, to save us from having to
#    update the manual all the time.
#

# Only one changelog for all languages
# $(VBOX_PATH_MANUAL_OUTBASE)/$(VBOX_MANUAL_XML_CHANGELOG): $(VBOX_PATH_MANUAL_SRC)/$(VBOX_MANUAL_XML_CHANGELOG) | $$(dir $$@)
# 	$(QUIET)$(INSTALL) -m 0644 $< $@

# intermediate step to do some variable replacement in the document
$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(filter-out user_VBoxManage.xml,$(VBOX_MANUAL_XML_FILES)))): \
		$(VBOX_PATH_MANUAL_OUTBASE)/% : $(VBOX_PATH_MANUAL_SRC)/% $(VBOX_VERSION_STAMP) | $$(dir $$@)
	$(call MSG_L1,Pre-processing [1] $(@F) to $@)
	$(QUIET)$(RM) -f $@ $@.tmp
	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
	               -e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
	               -e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
	               -e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
	               -e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
	               -e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
	               -e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
	               --output $@.tmp $<
	$(QUIET)$(MV) -f $@.tmp $@

$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/user_ChangeLog.xml): \
		$(VBOX_PATH_MANUAL_OUTBASE)/% : \
		$(VBOX_PATH_MANUAL_SRC)/% $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml | $$(dir $$@)
	$(call MSG_L1,Pre-processing [3] $(@F) to $@)
	$(QUIET)$(RM) -f $@ $@.tmp $@.tmp2
	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
	               -e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
	               -e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
	               -e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
	               -e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
	               -e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
	               -e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
	               --output $@.tmp $<
	$(QUIET)$(SED) -e '1,/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/!d' \
	               -e 's/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->//' \
	               --output $@ $@.tmp
	$(QUIET)var=`$(SED) -n '/!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/p' $<`; \
	               test -n "$${var}" && \
	               $(SED) -e 's/<?xml version=\"1.0\" encoding=\"UTF-8\"?>//g' \
	                       --append $@ $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml; \
                       true
	$(QUIET)$(SED) -e '/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->/,$$!d' \
	               -e 's/<!--\$$VIRTUALBOX_CHANGELOG_IMPL-->//' --append $@ $@.tmp

$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/user_VBoxManage.xml): \
		$(VBOX_PATH_MANUAL_OUTBASE)/% : \
		$(VBOX_PATH_MANUAL_SRC)/% \
		$(VBOXMANAGEPATH) | $$(dir $$@)
	$(call MSG_L1,Pre-processing [2] $(@F) to $@)
	$(QUIET)$(RM) -f $@ $@.tmp $@.tmp2
	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
	               -e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
	               -e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
	               -e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
	               -e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
	               -e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
	               -e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
	               --output $@.tmp $<
	$(QUIET)$(SED) -e '1,/\$$VBOX_MANAGE_OUTPUT/!d' \
	               -e 's/\$$VBOX_MANAGE_OUTPUT.*//' \
	               --output $@ $@.tmp
	$(QUIET)$(REDIRECT) -wo $@.tmp2 -E 'VBOX_LOG_FLAGS=disabled' -E 'VBOX_LOG_DEST=nofile' \
		$(if $(eq $(KBUILD_TARGET),darwin), -E 'DYLD_FALLBACK_LIBRARY_PATH=$(dir $(LIB_RUNTIME))') \
		-- \
		$(VBOXMANAGEPATH) --dumpopts
	$(QUIET)$(SED) -e 's/</\&lt;/g' -e 's/>/\&gt;/g' --append $@ $@.tmp2
	$(QUIET)$(SED) -e '/\$$VBOX_MANAGE_OUTPUT/,$$!d' \
	               -e 's/.*\$$VBOX_MANAGE_OUTPUT//' --append $@ $@.tmp
	$(QUIET)$(RM) -f $@.tmp $@.tmp2

VBOX_MANUAL_APIREF_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef_apiref.xml
VBOX_DOC_XIDL_SRC = $(PATH_ROOT)/src/VBox/Main/idl/VirtualBox.xidl
VBOX_DOC_XIDL_SRC_TMP = $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.xidl.tmp

$(VBOX_DOC_XIDL_SRC_TMP): $(VBOX_DOC_XIDL_SRC) $(MAKEFILE_CURRENT) | $$(dir $$@)
	$(call MSG_L1,Generating $@)
	$(QUIET)$(SED) -e 's|@a \+\(\w\+\)|<tt>\1</tt>|g' \
	       -e 's|@c \+\(\w\+\)|<tt>\1</tt>|g' \
	       --output $@ $<

# generate SDKRef_apiref.xml as a docbook file excerpt that will be referenced from the SDKRef.xml.
$(VBOX_MANUAL_APIREF_TMP): $(VBOX_DOC_XIDL_SRC_TMP) $(VBOX_PATH_MANUAL_SRC)/xidl2docbook.xsl
	$(call MSG_L1,Generating $@)
	$(QUIET)$(VBOX_XSLTPROC) --xinclude -o $@ $(VBOX_PATH_MANUAL_SRC)/xidl2docbook.xsl $(VBOX_DOC_XIDL_SRC_TMP)

$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.xml: \
		$(VBOX_PATH_MANUAL_SRC)/en_US/SDKRef.xml $(VBOX_MANUAL_APIREF_TMP) \
		| $$(dir $$@)
	$(call MSG_L1,Pre-processing [2] $(@F) to $@)
	$(QUIET)$(RM) -f $@ $@.tmp
	$(QUIET)$(SED) -e 's/\$$VBOX_VERSION_MAJOR/$(VBOX_VERSION_MAJOR)/g' \
	               -e 's/\$$VBOX_VERSION_MINOR/$(VBOX_VERSION_MINOR)/g' \
	               -e 's/\$$VBOX_VERSION_BUILD/$(VBOX_VERSION_BUILD)/g' \
	               -e 's/\$$VBOX_VERSION_STRING/$(VBOX_VERSION_STRING)/g' \
	               -e 's/\$$VBOX_VENDOR/$(VBOX_VENDOR)/g' \
	               -e 's/\$$VBOX_PRODUCT/$(VBOX_PRODUCT)/g' \
	               -e 's/\$$VBOX_C_YEAR/$(VBOX_C_YEAR)/g' \
	               --output $@.tmp $<
	$(QUIET)$(SED) -e '1,/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->/!d' \
	               -e 's/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->//' \
	               --output $@ $@.tmp
	$(QUIET)$(SED) -e 's/<?xml version=\"1.0\" encoding=\"utf-8\"?>//g' --append $@ $(VBOX_MANUAL_APIREF_TMP)
	$(QUIET)$(SED) -e '/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->/,$$!d' \
	               -e 's/<!--\$$VIRTUALBOX_MAIN_API_REFERENCE-->//' --append $@ $@.tmp
#	$(QUIET)$(MV) -f $@.tmp $@


##########################################################################################
#
#  Rules: Create or preprocess files for xsltproc
#  (preliminary step for both CHM and PDF generation)
#
##########################################################################################

# Create a catalog file for xsltproc that points to docbook catalog.
ifneq ($(XML_CATALOG),)
$(XML_CATALOG): $(MAKEFILE_CURRENT) | $$(dir $$@)
	$(call MSG_L1,Creating catalog $@)
	$(QUIET)$(RM) -f $@.tmp $@
	$(QUIET)$(APPEND) $@.tmp '<?xml version="1.0"?>'
	$(QUIET)$(APPEND) $@.tmp '<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">'
	$(QUIET)$(APPEND) $@.tmp '<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">'
	$(QUIET)$(APPEND) $@.tmp '  <delegatePublic publicIdStartString="-//OASIS/ENTITIES DocBook XML"      catalog="file:///$(XML_CATALOG_DOCBOOK)"/>'
	$(QUIET)$(APPEND) $@.tmp '  <delegatePublic publicIdStartString="-//OASIS/DTD DocBook XML"           catalog="file:///$(XML_CATALOG_DOCBOOK)"/>'
	$(QUIET)$(APPEND) $@.tmp '  <delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/" catalog="file:///$(XML_CATALOG_DOCBOOK)"/>'
	$(QUIET)$(APPEND) $@.tmp '  <delegateURI uriStartString="http://www.oasis-open.org/docbook/"         catalog="file:///$(XML_CATALOG_DOCBOOK)"/>'
	$(QUIET)$(APPEND) $@.tmp '</catalog>'
	$(QUIET)$(MV) -f $@.tmp $@

# Create a docbook catalog file for xsltproc that points to the local docbook files.
$(XML_CATALOG_DOCBOOK): $(MAKEFILE_CURRENT) | $$(dir $$@)
	$(call MSG_L1,Creating catalog $@)
	$(QUIET)$(RM) -f $@.tmp $@
	$(QUIET)$(APPEND) $@.tmp '<?xml version="1.0"?>'
	$(QUIET)$(APPEND) $@.tmp '<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">'
	$(QUIET)$(APPEND) $@.tmp '<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="-//OASIS//ELEMENTS DocBook XML Information Pool V4.3//EN"          uri="file:///$(DOCBOOKDTDPATH)/dbpoolx.mod"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="-//OASIS//DTD DocBook XML V4.3//EN"                                uri="file:///$(DOCBOOKDTDPATH)/docbookx.dtd"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="-//OASIS//DTD DocBook XML V4.4//EN"                                uri="file:///$(DOCBOOKDTDPATH)/docbookx.dtd"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="-//OASIS//ENTITIES DocBook XML Character Entities V4.3//EN"        uri="file:///$(DOCBOOKDTDPATH)/dbcentx.mod"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="-//OASIS//ENTITIES DocBook XML Notations V4.3//EN"                 uri="file:///$(DOCBOOKDTDPATH)/dbnotnx.mod"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="-//OASIS//ENTITIES DocBook XML Additional General Entities V4.3//EN" uri="file:///$(DOCBOOKDTDPATH)/dbgenent.mod"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="-//OASIS//ELEMENTS DocBook XML Document Hierarchy V4.3//EN"        uri="file:///$(DOCBOOKDTDPATH)/dbhierx.mod"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="-//OASIS//DTD XML Exchange Table Model 19990315//EN"               uri="file:///$(DOCBOOKDTDPATH)/soextblx.dtd"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="-//OASIS//DTD DocBook XML CALS Table Model V4.3//EN"               uri="file:///$(DOCBOOKDTDPATH)/calstblx.dtd"/>'
	$(QUIET)$(APPEND) $@.tmp '  <rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.3" rewritePrefix="file:///$(DOCBOOKDTDPATH)"/>'
	$(QUIET)$(APPEND) $@.tmp '  <rewriteURI         uriStartString="http://www.oasis-open.org/docbook/xml/4.3" rewritePrefix="file:///$(DOCBOOKDTDPATH)"/>'
	$(QUIET)$(APPEND) $@.tmp '  <rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.4" rewritePrefix="file:///$(DOCBOOKDTDPATH)"/>'
	$(QUIET)$(APPEND) $@.tmp '  <rewriteURI         uriStartString="http://www.oasis-open.org/docbook/xml/4.4" rewritePrefix="file:///$(DOCBOOKDTDPATH)"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN"   uri="file:///$(DOCBOOKDTDPATH)/ent/iso-amsa.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Binary Operators//EN"  uri="file:///$(DOCBOOKDTDPATH)/ent/iso-amsb.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Delimiters//EN"        uri="file:///$(DOCBOOKDTDPATH)/ent/iso-amsc.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Negated Relations//EN" uri="file:///$(DOCBOOKDTDPATH)/ent/iso-amsn.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Ordinary//EN"          uri="file:///$(DOCBOOKDTDPATH)/ent/iso-amso.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Relations//EN"         uri="file:///$(DOCBOOKDTDPATH)/ent/iso-amsr.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Box and Line Drawing//EN"                  uri="file:///$(DOCBOOKDTDPATH)/ent/iso-box.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Russian Cyrillic//EN"                      uri="file:///$(DOCBOOKDTDPATH)/ent/iso-cyr1.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Non-Russian Cyrillic//EN"                  uri="file:///$(DOCBOOKDTDPATH)/ent/iso-cyr2.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Diacritical Marks//EN"                     uri="file:///$(DOCBOOKDTDPATH)/ent/iso-dia.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Greek Letters//EN"                         uri="file:///$(DOCBOOKDTDPATH)/ent/iso-grk1.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Monotoniko Greek//EN"                      uri="file:///$(DOCBOOKDTDPATH)/ent/iso-grk2.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Greek Symbols//EN"                         uri="file:///$(DOCBOOKDTDPATH)/ent/iso-grk3.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Alternative Greek Symbols//EN"             uri="file:///$(DOCBOOKDTDPATH)/ent/iso-grk4.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Added Latin 1//EN"                         uri="file:///$(DOCBOOKDTDPATH)/ent/iso-lat1.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Added Latin 2//EN"                         uri="file:///$(DOCBOOKDTDPATH)/ent/iso-lat2.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN"           uri="file:///$(DOCBOOKDTDPATH)/ent/iso-num.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES Publishing//EN"                            uri="file:///$(DOCBOOKDTDPATH)/ent/iso-pub.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '  <public publicId="ISO 8879:1986//ENTITIES General Technical//EN"                     uri="file:///$(DOCBOOKDTDPATH)/ent/iso-tech.ent"/>'
	$(QUIET)$(APPEND) $@.tmp '</catalog>'
	$(QUIET)$(MV) -f $@.tmp $@
endif

# intermediate step to do some variable replacement in the XSL configuration
$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/docbook-htmlhelp-formatcfg.xsl): \
		$(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl $(MAKEFILE_CURRENT) | $$(dir $$@)
	$(call MSG_L1,Pre-processing $(@F) to $@)
	$(QUIET)$(RM) -f $@.tmp $@
	$(QUIET)$(SED) -e 's|\$$DOCBOOKPATH|$(DOCBOOKPATH)|g' \
	               -e 's|\$$CFGPATH|$(VBOX_PATH_MANUAL_SRC)|g' \
	               -e 's|\$$TARGETPATH|$(@D)|g' --output $@.tmp $<
	$(QUIET)$(MV) -f $@.tmp $@

# Prepare the XSL file for our title page, htmlhelp variant.
$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/titlepage-htmlhelp.xsl): \
		$(VBOX_PATH_MANUAL_SRC)/titlepage-htmlhelp.xml $(MAKEFILE_CURRENT) | $$(dir $$@)
	$(call MSG_L1,xsltproc $<)
	$(QUIET)$(RM) -f $@.tmp $@
	$(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet -o $@.tmp $(DOCBOOKPATH)/template/titlepage.xsl $<
	$(QUIET)$(MV) -f $@.tmp $@


##########################################################################################
#
#  Shared rules for PDF generation
#
##########################################################################################

ifndef VBOX_OSE
# copy ucs.sty and related files
$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/ucs.sty):
	$(call MSG_L1,Copying unicode support for LaTeX)
	$(QUIET)$(CP) $(VBOX_MANUAL_TEX_UNICODE_FILES) $(@D)
endif

# copy the PNG files.
# Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
define def_vbox_cp_images_pdf
local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)
$(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \
		$$(out_dir)/%: $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@)
	$$(call MSG_L1,Copying temporary $$< => $$@)
	$$(QUIET)$$(CP) -f $$< $$@
endef

$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(eval $(def_vbox_cp_images_pdf)))


##########################################################################################
#
#  UserManual.pdf
#
##########################################################################################

## @todo INSTALLS target for this!
$(PATH_STAGE_BIN)/UserManual.pdf: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.pdf | $$(dir $$@)
	$(QUIET)$(CP) $< $@
	$(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)

$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf): \
	$(PATH_STAGE_BIN)/UserManual_%.pdf : $(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.pdf
	$(QUIET)$(CP) $< $@
	$(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)

$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/UserManual.pdf): \
		$(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.pdf : \
		$(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.tex \
		$(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/%/ucs.sty) \
		$(foreach f,$(VBOX_MANUAL_LANGUAGES),\
		  $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_MANUAL_PNG_FILES_$(f)))) | $$(dir $$@)
# PDF generation via Latex: generate the .tex file
	$(call MSG_L1,pdflatex $< (four passes) -> $@)
	$(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(PDFLATEX) UserManual.tex
	$(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(PDFLATEX) UserManual.tex
	$(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(PDFLATEX) UserManual.tex
	$(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(PDFLATEX) UserManual.tex
	$(QUIET)$(SED) -n \
        -e '/Warning: There were \(undefined references\|multiply-defined labels\)/{p; q 1}' \
        $(basename $@).log

##@todo restore this when above has been converted to INSTALLS target.	$(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)

# generate temporary LaTeX source from processed XML
$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/UserManual.tex): \
				$(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.tex : \
				$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/%/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
				$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \
				$(MAKEFILE_CURRENT)
	$(call MSG_L1,Generating $@ from DocBook XML)
	$(QUIET)$(RM) -f $(addprefix $(@D)/,$(VBOX_MANUAL_LATEX_FILES_TARGET))
#   generate TeX source from processed docbook and store it in UserManual.tex.tmp;
#   pass current language to xsltproc in TARGETLANG variable (extract it from the
#   current directory, should become "de_DE" or the like)
	$(QUIET)$(VBOX_XSLTPROC) $(XSLTPROC_VERBOSE) --xinclude --nonet --stringparam TARGETLANG $(notdir $(@D)) -o $@.tmp $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $<
#   for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word;
#   the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections
	$(QUIET)$(SED) \
		-e 's|^\\QUOTE{}|\\OQ{}|g' \
		-e 's|\(\W\)\\QUOTE{}|\1\\OQ{}|g' \
		-e 's|\(\w\)\\QUOTE{}|\1\\CQ{}|g' \
		--output $@ $@.tmp
	$(QUIET)$(RM) -f $@.tmp


##########################################################################################
#
#  SDKRef.pdf
#
##########################################################################################

$(VBOX_PATH_SDK)/docs/SDKRef.pdf: \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex \
		$(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ucs.sty) \
		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) | $$(dir $$@)
# PDF generation via Latex: generate the .tex file
	$(QUIET)$(MKDIR) -p $(VBOX_PATH_SDK)/docs
	$(call MSG_L1,pdflatex $< (three passes))
	$(QUIET)$(REDIRECT) -C $(<D) -- $(PDFLATEX) SDKRef.tex
	$(QUIET)$(REDIRECT) -C $(<D) -- $(PDFLATEX) SDKRef.tex
	$(QUIET)$(REDIRECT) -C $(<D) -- $(PDFLATEX) SDKRef.tex
	$(QUIET)$(SED) -n \
        -e '/Warning: There were \(undefined references\|multiply-defined labels\)/{p; q 1}' \
        $(basename $<).log
	$(QUIET)$(CP) $(<D)/SDKRef.pdf $@
	$(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)

# generate temporary LaTeX source from processed XML
$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex: $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_SDKREF_XML_FILES)) $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $(MAKEFILE_CURRENT)
	$(call MSG_L1,Generating $@ from DocBook XML)
	$(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_SDKREF_LATEX_FILES_TARGET))
#	generate TeX source from processed docbook and store it in SDKRef.tex.tmp
	$(QUIET)$(VBOX_XSLTPROC) $(XSLTPROC_VERBOSE) --xinclude --nonet --stringparam TARGETLANG en_US -o $@.tmp $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $<
#	for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word;
#   the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections
	$(QUIET)$(SED) \
		-e 's|^\\QUOTE{}|\\OQ{}|g' \
		-e 's|\(\W\)\\QUOTE{}|\1\\OQ{}|g' \
		-e 's|\(\w\)\\QUOTE{}|\1\\CQ{}|g' \
		--output $@ $@.tmp
	$(QUIET)$(RM) -f $@.tmp


##########################################################################################
#
#  VirtualBox.chm
#
##########################################################################################

#
# Main rule for the .chm file (target of OTHERS at the top):
# We first generate a .hhp help source file from the preprocessed
# DocBook XML files, as defined above,  then feed that into the
# Microsoft Help Compiler.
#

ifdef VBOX_WITH_DOCS_CHM
$(PATH_STAGE_BIN)/VirtualBox.chm: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/VirtualBox.chm
	$(QUIET)$(CP) $< $@
	$(call MSG_L1,Fresh CHM is now at $@)

$(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm): \
	$(PATH_STAGE_BIN)/VirtualBox_%.chm : $(VBOX_PATH_MANUAL_OUTBASE)/%/VirtualBox.chm
	$(QUIET)$(CP) $< $@
	$(call MSG_L1,Fresh CHM is now at $@)

$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/VirtualBox.chm): \
		$(VBOX_PATH_MANUAL_OUTBASE)/%/VirtualBox.chm: \
		$(VBOX_PATH_MANUAL_OUTBASE)/%/HTMLHelp/htmlhelp.hhp \
		$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/HTMLHelp/,$(VBOX_MANUAL_PNG_FILES_$(f))))
	$(call MSG_L1,hhc $<,=> $@)
	$(QUIET)$(RM) -f $@
	$(QUIET)$(HHC) $(subst /,\\,$<)

$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/HTMLHelp/htmlhelp.hhp): \
		$(VBOX_PATH_MANUAL_OUTBASE)/%/HTMLHelp/htmlhelp.hhp: \
		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/%/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
		$(VBOX_PATH_MANUAL_OUTBASE)/%/docbook-htmlhelp-formatcfg.xsl \
		$(VBOX_PATH_MANUAL_OUTBASE)/%/titlepage-htmlhelp.xsl \
		$(XML_CATALOG) \
		$(XML_CATALOG_DOCBOOK)
	$(call MSG_L1,xsltproc $<,=> $@)
	$(QUIET)$(RM) -f $@
	$(QUIET)$(MKDIR) -p $(@D)
	$(QUIET)$(if $(XML_CATALOG),XML_CATALOG_FILES=$(XML_CATALOG)) \
		$(VBOX_XSLTPROC) --xinclude --nonet --output $(@D)/ \
		--stringparam htmlhelp.chm \
		$(subst /,\\,$(@D)/../VirtualBox.chm) \
		$(HTMLHELPOPTS) $(@D)/../docbook-htmlhelp-formatcfg.xsl \
		$<

# copy the PNG files.
# Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
define def_vbox_cp_images_html
local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/HTMLHelp
$$(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \
			$$(out_dir)/%: $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@)
	$$(call MSG_L1,Copying temporary $$< => $$@)
	$$(QUIET)$$(CP) -f $$< $$@
endef

$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(eval $(def_vbox_cp_images_html)))

# Packing the docs into a zip file
$(PATH_STAGE_BIN)/VBoxDocumentation.zip: $(VBOX_MANUAL_PACK)
	$(call MSG_L1,Packing documentation $@)
	$(QUIET)$(RM) -f $@
	$(QUIET)$(REDIRECT) -C $(PATH_STAGE_BIN) -- zip$(HOSTSUFF_EXE) -9 $@ $(notdir $^)
endif # VBOX_WITH_DOCS_CHM

##########################################################################################
#
#  UserManual.html
#
##########################################################################################

# intermediate step to do some variable replacement in the XSL configuration
$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl: \
		$(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-formatcfg.xsl $(MAKEFILE_CURRENT) | $$(dir $$@)
	$(call MSG_L1,Pre-processing $(@F) to $@)
	$(QUIET)$(RM) -f $@.tmp $@
	$(QUIET)$(SED) -e 's|\$$DOCBOOKPATH|$(DOCBOOKPATH)|g' \
	               -e 's|\$$CFGPATH|$(VBOX_PATH_MANUAL_SRC)|g' \
	               -e 's|\$$TARGETPATH|$(@D)|g' --output $@.tmp $<
	$(QUIET)$(MV) -f $@.tmp $@

$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl: \
		$(VBOX_PATH_MANUAL_SRC)/docbook-html-chunks-formatcfg.xsl $(MAKEFILE_CURRENT) | $$(dir $$@)
	$(call MSG_L1,Pre-processing $(@F) to $@)
	$(QUIET)$(RM) -f $@.tmp $@
	$(QUIET)$(SED) -e 's|\$$DOCBOOKPATH|$(DOCBOOKPATH)|g' \
	               -e 's|\$$CFGPATH|$(VBOX_PATH_MANUAL_SRC)|g' \
	               -e 's|\$$TARGETPATH|$(@D)|g' --output $@.tmp $<
	$(QUIET)$(MV) -f $@.tmp $@

$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html: \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.xml \
		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US))
	$(call MSG_L1,xsltproc $<)
	$(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet \
		--output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.xml

$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html: \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.xml \
		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US))
	$(call MSG_L1,xsltproc $<)
	$(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet \
		--output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html \
		--stringparam chunk.section.depth 0 \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.xml

$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip: \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html
	$(call MSG_L1,Packing documentation $@)
	$(QUIET)$(RM) -f $@
	$(QUIET)$(REDIRECT) -C $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ -- zip$(HOSTSUFF_EXE) \
		-9 -r $@ html-single html-chunks $(VBOX_MANUAL_PNG_FILES_en_US)

html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html

html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html

html-zip:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip

##########################################################################################
#
#  ChangeLog.html
#
##########################################################################################

# intermediate step to do some variable replacement in the XSL configuration
$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-changelog-formatcfg.xsl: \
		$(VBOX_PATH_MANUAL_SRC)/docbook-changelog-formatcfg.xsl $(MAKEFILE_CURRENT) | $$(dir $$@)
	$(call MSG_L1,Pre-processing $(@F) to $@)
	$(QUIET)$(RM) -f $@.tmp $@
	$(QUIET)$(SED) -e 's|\$$DOCBOOKPATH|$(DOCBOOKPATH)|g' \
	               -e 's|\$$CFGPATH|$(VBOX_PATH_MANUAL_SRC)|g' \
	               -e 's|\$$TARGETPATH|$(@D)|g' --output $@.tmp $<
	$(QUIET)$(MV) -f $@.tmp $@

# This XSLT rule depends on $(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml, which is build by the complex rule
#    $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/user_ChangeLog.xml): ...
# much further above. That rule takes en_US/user_ChangeLog.xml and replaces $VIRTUALBOX_CHANGELOG_IMPL
# with the actual change log contained in user_ChangeLogImpl.xml
$(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html: \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-changelog-formatcfg.xsl \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml
	$(QUIET)$(VBOX_XSLTPROC) --xinclude --nonet --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html \
		$(@D)/docbook-changelog-formatcfg.xsl \
		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml
	$(call MSG_L1,Fresh ChangeLog.html is now at $@)

cl-html: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html

include $(FILE_KBUILD_SUB_FOOTER)