Changeset 68829 in vbox for trunk/doc

Timestamp:

Sep 22, 2017 2:18:44 PM (8 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

118083

Message:

manual: Added some mumblings about the VISO files and a dump of the RTIsoMaker options.

Location:

trunk/doc/manual

Files:

• Makefile.kmk (modified) (3 diffs)
• en_US/user_AdvancedTopics.xml (modified) (1 diff)

trunk/doc/manual/Makefile.kmk

@@ -342 +342 @@
         $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/overview_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \
         $(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml \
+        $(VBOX_PATH_MANUAL_OUTBASE)/user_AdvancedTopics_VISO_Options.xml \
         $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/UserManual_$(f).pdf) \
         $(foreach f,$(VBOX_MANUAL_ADD_LANGUAGES),$(PATH_STAGE_BIN)/VirtualBox_$(f).chm) \
@@ -519 +520 @@
         $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/user_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
         $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/overview_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
-        $(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml ))
+        $(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml \
+        $(VBOX_PATH_MANUAL_OUTBASE)/user_AdvancedTopics_VISO_Options.xml ))
 
 # Intermediate step to do some variable replacement in the document.
@@ -580 +582 @@
                 , '  <xi:include href="overview_$(refentry)" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />') \
                '  </remark>' \
+               '</sect1>'
+
+# Generate the VISO option listing.
+$(VBOX_PATH_MANUAL_OUTBASE)/user_AdvancedTopics_VISO_Options.xml: $(VBOX_RTISOMAKER) $(MAKEFILE_CURRENT) | $$(dir $$@)
+        $(call MSG_GENERATE,,$@,)
+        $(QUIET)$(RM) -f $@ [email protected]
+        $(QUIET)$(APPEND) -tn "$@" \
+                '<?xml version="1.0" encoding="UTF-8"?>' \
+               '<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">' \
+               '<sect1> <!-- this will be skipped via xpointer in the include. --> '
+        $(QUIET)$(REDIRECT) -wo [email protected] -E 'VBOX_LOG_FLAGS=disabled' -E 'VBOX_LOG_DEST=nofile' \
+                -- $(VBOX_RTISOMAKER) --help
+        $(QUIET)$(SED) \
+                -e ':a' \
+                -e 'N' \
+                -e '$(DOLLAR)!ba' \
+                -e 's/bldRTIsoMaker/RTIsoMaker/' \
+                -e 's/&/\&amp\;/g' \
+                -e 's/</\&lt\;/g' \
+                -e 's/>/\&gt\;/g' \
+                -e 's/\n*$(DOLLAR)/<\/screen>/' \
+                -e 's/^/<screen>/' \
+                --append $@ [email protected]
+        $(QUIET)$(RM) -f [email protected]
+        $(QUIET)$(APPEND) -n "$@" \
                '</sect1>'
 

trunk/doc/manual/en_US/user_AdvancedTopics.xml

@@ -4362 +4362 @@
   </sect1>
 
+  <sect1 id="viso">
+    <title>VISO file format</title>
+
+    <para>The VISO files was introduced with VirtualBox 5.2.  They are virtual ISO images,
+    i.e. constructed in memory from a bunch of files on the host.  A VISO is just the
+    recipe describing how to go about this using a syntax vaguely similar to mkisofs and
+    genisoimage.</para>
+
+    <para>One requirement, the VISO file must start with one of the
+    <option>--iprt-iso-maker-file-marker</option> options. Which of the options
+    you use will dicate the quoting and escaping rules used when reading the
+    file.  The option takes the image UUID as an argument.</para>
+
+    <para>The VISO files are treated as UTF-8 and must not contain any byte order
+    marker (BOM).  There is currently no way to comment out lines in a VISO file.</para>
+
+
+     <xi:include href="../user_AdvancedTopics_VISO_Options.xml" xpointer="xpointer(/sect1/*)"
+       xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+
+  </sect1>
+
 </chapter>
+